ubuntu-advantage.1

.TH "UBUNTU-PRO" "1" "21 February 2020" "Canonical Ltd." "Ubuntu Pro"


.SH NAME
pro \- Manage Ubuntu Pro services from Canonical


.SH SYNOPSIS
.BR "pro" " <command> [<args>]"
.br
.BR "ua" " <command> [<args>]"
.br
.BR "ubuntu-advantage" " <command> [<args>]"


.SH DESCRIPTION
Ubuntu Pro is a collection of services offered by Canonical to
Ubuntu users. The Ubuntu Pro command line tool is used to attach
a system to an Ubuntu Pro contract to then enable and disable
services from Canonical. The available commands and services are
described in more detail below.


.SH COMMANDS
.TP
.BR "attach" " [--no-auto-enable] [--attach-config=/path/to/file.yaml] <token>"
Connect an Ubuntu Pro support contract to this machine.

The \fItoken\fR parameter can be obtained from
https://auth.contracts.canonical.com/.

The \fI--attach-config\fR option can be used to provide a file with the token
and optionally, a list of services to enable after attaching. The \fItoken\fR
parameter should not be used if this option is provided. An attach config file
looks like the following:
    token: YOUR_TOKEN_HERE  # required
    enable_services:        # optional list of service names to auto-enable
        - esm-infra
        - esm-apps
        - cis

The optional \fI--no-auto-enable\fR flag will disable the automatic
enablement of recommended entitlements which usually happens immediately
after a successful attach.

The exit code can be:
    0: on successful attach
    1: in case of any error while trying to attach
    2: if the machine is already attached

.TP
.B collect-logs [-o <file>| --output <file>]
Create a tarball with all relevant logs and debug data.

The \fI--output\fR parameter defines the path to the tarball. If not
provided, the file is saved as \fBua_logs.tar.gz\fP in the current
directory.

.TP
.B detach
Remove the Ubuntu Pro support contract from this machine. This
also disables all enabled services that can be.

.TP
.BR "disable" " [cc-eal|cis|esm|fips|fips-updates|livepatch|ros|ros-updates]"
Disable this machine's access to an Ubuntu Pro service.

.TP
.BR "enable" " [cc-eal|cis|esm|fips|fips-updates|livepatch|ros|ros-updates]"
Activate and configure this machine's access to an Ubuntu Pro
service.

.TP
.BR "fix" " <security_issue>"
Fix a CVE or USN on the system by upgrading the appropriate package(s).

<security_issue> can be any of the following formats: CVE-yyyy-nnnn,
CVE-yyyy-nnnnnnn, or USN-nnnn-dd.

The exit code can be 0, 1, or 2.
    0: the fix was successfully applied
    1: the fix cannot be applied
    2: the fix was applied but requires a reboot before it takes effect

.TP
.B refresh
Refresh contract and service details from Canonical.

.TP
.B security-status
Show security updates for packages in the system, including all
available ESM related content.

.TP
.BR "status" " [--format=tabular|json|yaml] [--simulate-with-token TOKEN] [--all]"
Report current status of Ubuntu Pro services on system.

This shows whether this machine is attached to an Ubuntu Pro
support contract. When attached, the report includes the specific
support contract details including contract name, expiry dates, and the
status of each service on this system.

The attached status output has four columns:

.BR "SERVICE" ":"
name of the service

.BR "ENTITLED" ":"
whether the contract to which this machine is attached entitles use of
this service. Possible values are: \fIyes\fR or \fIno\fR

.BR "STATUS" ":"
whether the service is enabled on this machine.
Possible values are: \fIenabled\fR, \fIdisabled\fR, \fIn/a\fR (if your
contract entitles you to the service, but it isn't available for this
machine) or \fI—\fR (if you aren't entitled to this service)

.BR "DESCRIPTION" ":"
a brief description of the service

The unattached status output instead has three columns. \fBSERVICE\fR
and \fBDESCRIPTION\fR are the same as above, and there is the addition
of:

.BR "AVAILABLE" ":"
whether this service would be available if this machine were attached.
The possible values are \fIyes\fR or \fIno\fR.

If --simulate-with-token is used, then the output has five columns.
\fBSERVICE\fR, \fBAVAILABLE\fR, \fBENTITLED\fR and \fBDESCRIPTION\fR are the
same as mentioned above, and \fBAUTO_ENABLED\fR shows whether the service is
set to be enabled when that token is attached.

If the --all flag is set, beta and unavailable services are also listed in the
output.

.TP
.B version
Show version of the Ubuntu Pro package.

.SH PRO UPGRADE DAEMON
Ubuntu Pro client sets up a daemon on supported platforms (currently GCP only) to
detect if an Ubuntu Pro license is purchased for the machine. If an Ubuntu Pro license
is detected, then the machine is automatically attached.
If you are uninterested in Ubuntu Pro services, you can safely stop and disable the
daemon using systemctl:

sudo systemctl stop ubuntu-advantage.service
sudo systemctl disable ubuntu-advantage.service

.SH TIMER JOBS
Ubuntu Pro client sets up a systemd timer to run jobs that need to be executed
recurrently. The timer itself ticks every 5 minutes on average, and decides
which jobs need to be executed based on their intervals.

Jobs are executed by the timer script if the script has not yet run
successfully, or their interval since last successful run is already exceeded.
There is a random delay applied to the timer, to desynchronize job execution
time on machines spinned at the same time, avoiding multiple synchronized
calls to the same service.

Current jobs being checked and executed are:
.TP
.B
\fBupdate_messaging\fP
Makes sure that the MOTD and APT messages match the available/enabled services
on the system, showing information about available packages or security
updates.


.SH CONFIGURATION
By default, Ubuntu Pro client configuration options are read from
\fB/etc/ubuntu-advantage/uaclient.conf\fB.

The following configuration options are available:
.TP
.B
\fBcontract_url\fP
The Ubuntu Pro contract server URL
.TP
.B
\fBsecurity_url\fP
The Ubuntu Pro security server URL
.TP
.B
\fBdata_dir\fP
Where Ubuntu Pro client stores its data files
.TP
.B
\fBlog_level\fP
The logging level used when writing to \fBlog_file\fP
.TP
.B
\fBlog_file\fP
The log file for the Ubuntu Pro client cli
.TP
.B
\fBtimer_log_file\fP
The log file for the Ubuntu Pro timer and timer jobs
.TP
.B
\fBdaemon_log_file\fP
The log file for the Ubuntu Pro daemon

.P
\fBThe following options must be nested under the "ua_config" key:\fP

.TP
.B
\fBhttp_proxy\fP
If set, pro will use the specified http proxy when making any http requests
.TP
.B
\fBhttps_proxy\fP
If set, pro will use the specified https proxy when making any https requests
.TP
.B
\fBapt_http_proxy\fP
\fB[DEPRECATED]\fP If set, pro will configure apt to use the specified http proxy by writing a apt
config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. (Please use \fBglobal_apt_http_proxy\fP)
.TP
.B
\fBapt_https_proxy\fP
\fB[DEPRECATED]\fP If set, pro will configure apt to use the specified https proxy by writing a apt
config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. (Please use \fBglobal_apt_https_proxy\fP)
.TP
.B
\fBglobal_apt_http_proxy\fP
If set, pro will configure apt to use the specified http proxy by writing a apt
config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. Set this if you
prefer a global proxy for all resources, not just the ones from \fIesm.ubuntu.com\fB
.TP
.B
\fBglobal_apt_https_proxy\fP
If set, pro will configure apt to use the specified https proxy by writing a apt
config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. Set this if you
prefer a global proxy for all resources, not just the ones from \fIesm.ubuntu.com\fB
.TP
.B
\fBua_apt_http_proxy\fP
If set, pro will configure apt to use the specified http proxy by writing a apt
config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. This proxy is limited
to accessing resources from \fIesm.ubuntu.com\fB
.TP
.B
\fBua_apt_https_proxy\fP
If set, pro will configure apt to use the specified https proxy by writing a apt
config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. This proxy is limited
to accessing resources from \fIesm.ubuntu.com\fB
.TP
.B
\fB<job_name>_timer\fP
Sets the timer running interval for a specific job. Those intervals are checked
every time the systemd timer runs.

.P
If needed, authentication to the proxy server can be performed by setting
username and password in the URL itself, as in:
.PP
.nf
.fam C
  http_proxy: http://<username>:<password>@<fqdn>:<port>
.fam T
.fi

.P
Additionally, some configuration options can be overridden in the environment
by setting an environment variable prefaced by \fBUA_<option_name>\fP. Both
uppercase and lowercase environment variables are allowed. The configuration
options that support this are: data_dir, log_file, timer_log_file,
daemon_log_file, log_level, and security_url.

For example, the following overrides the log_level found in uaclient.conf:
.PP
.nf
.fam C
  UA_LOG_LEVEL=info pro attach
.fam T
.fi


.SH SERVICES
.TP
.B "Common Criteria EAL2 Provisioning (cc-eal)"
Enables and install the Common Criteria artifacts.

The artifacts include a configure script, a tarball with additional
packages, and post install scripts. The artifacts will be installed in
/usr/lib/common-criteria directory and the README and configuration
guide are available in /usr/share/doc/ubuntu-commoncriteria directory.

.TP
.B "CIS Audit (cis)"
Enables and installs the CIS Audit artifacts.

.TP
.B "Expanded Security Maintenance (esm)"
Expanded Security Maintenance ensures the ongoing security and
integrity of systems running Ubuntu Long Term Support (LTS) releases
through Ubuntu Pro for Infrastructure.

See https://ubuntu.com/esm for more information.

.TP
.B "FIPS 140-2 certified modules (fips)"
Install, configure, and enable FIPS 140-2 certified modules.

After successfully enabling FIPS, the system MUST be rebooted. Failing
to reboot will result in the system not running the updated FIPS
kernel.

Disabling FIPS is not currently supported.

.TP
.B "FIPS 140-2 certified modules with updates (fips-updates)"
Install, configure, and enable FIPS 140-2 certified modules with
updates. Enabling FIPS with updates will take the system out of FIPS
compliance as the updated modules are not FIPS certified.

After successfully enabling FIPS with updates, the system MUST be
rebooted. Failing to reboot will result in the system not running the
updated FIPS kernel.

Disabling FIPS with updates is not currently supported.

.TP
.B "Livepatch Service (livepatch)"
Automatically apply critical kernel patches without rebooting. Reduces
downtime, keeping your Ubuntu LTS systems secure and compliant.

See https://ubuntu.com/livepatch for more information.

.TP
.B "ROS ESM Security Updates (ros)"
Robot Operating System Expanded Security Maintenance - Only Security Updates
provides security fixes for ROS packages to ensure the ongoing integrity
of ROS based applications.

See https://ubuntu.com/robotics/ros-esm for more information.

.TP
.B "ROS ESM All Updates (ros-updates)"
Robot Operating System Expanded Security Maintenance - All Updates
provides additional bug fixes in addition to security fixes for
ROS packages to ensure the ongoing integrity of ROS based applications.

See https://ubuntu.com/robotics/ros-esm for more information.

.SH REPORTING BUGS
Please report bugs either by running `ubuntu-bug ubuntu-advantage-tools` or
login to Launchpad and navigate to
https://bugs.launchpad.net/ubuntu/+source/ubuntu-advantage-tools/+filebug

.SH COPYRIGHT
Copyright (C) 2019-2020 Canonical Ltd.