ubuntu-advantage

UBUNTU-ADVANTAGE(1)            Ubuntu Advantage            UBUNTU-ADVANTAGE(1)

NAME
       ubuntu-advantage - Manage Ubuntu Advantage services from Canonical

SYNOPSIS
       ua <command> [<args>]
       ubuntu-advantage <command> [<args>]

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

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

              The  token  parameter  can  be  obtained  from https://auth.con-
              tracts.canonical.com/.

              The --attach-config option can be used to provide  a  file  with
              the  token  and  optionally,  a list of services to enable after
              attaching. The token 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 --no-auto-enable 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

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

              The --output parameter defines the path to the tarball.  If  not
              provided,  the  file  is  saved as ua_logs.tar.gz in the current
              directory.

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

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

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

       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

       refresh
              Refresh contract and service details from Canonical.

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

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

              This  shows whether this machine is attached to an Ubuntu Advan-
              tage 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:

              SERVICE: name of the service

              ENTITLED: whether the contract to which this machine is attached
              entitles use of this service. Possible values are: yes or no

              STATUS:  whether the service is enabled on this machine.  Possi-
              ble values are: enabled, disabled, n/a (if your  contract  enti-
              tles  you  to  the  service,  but  it  isn't  available for this
              machine) or -- (if you aren't entitled to this service)

              DESCRIPTION: a brief description of the service

              The unattached status output instead has three columns.  SERVICE
              and DESCRIPTION are the same as above, and there is the addition
              of:

              AVAILABLE: whether this  service  would  be  available  if  this
              machine were attached.  The possible values are yes or no.

              If  --simulate-with-token is used, then the output has five col-
              umns.  SERVICE, AVAILABLE, ENTITLED and DESCRIPTION are the same
              as  mentioned  above, and AUTO_ENABLED 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.

       version
              Show version of the Ubuntu Advantage package.

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

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

TIMER JOBS
       UA 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  desynchro-
       nize  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:

       update_messaging
              Makes sure that the MOTD  and  APT  messages  match  the  avail-
              able/enabled  services  on the system, showing information about
              available packages or security updates.

       update_status
              Makes sure the `ua status` command will have the latest informa-
              tion  even  when  executed  by  a  non-root  user,  updating the
              /var/lib/ubuntu-advantage/status.json file.

CONFIGURATION
       By default, Ubuntu Advantage client configuration options are read from
       /etc/ubuntu-advantage/uaclient.conf.

       The following configuration options are available:

       contract_url
              The ubuntu advantage contract server URL

       security_url
              The ubuntu advantage security server URL

       data_dir
              Where Ubuntu Advantage client stores its data files

       log_level
              The logging level used when writing to log_file

       log_file
              The log file for the Ubuntu Advantage client

       timer_log_file
              The log file for the Ubuntu Advantage timer and timer jobs

       daemon_log_file
              The log file for the Ubuntu Advantage daemon

       The following options must be nested under the "ua_config" key:

       http_proxy
              If  set,  ua  will  use the specified http proxy when making any
              http requests

       https_proxy
              If set, ua will use the specified https proxy  when  making  any
              https requests

       apt_http_proxy
              If set, ua will configure apt to use the specified http proxy by
              writing a apt config file to /etc/apt/apt.conf.d/90ubuntu-advan-
              tage-aptproxy

       apt_https_proxy
              If  set,  ua will configure apt to use the specified https proxy
              by writing a apt config  file  to  /etc/apt/apt.conf.d/90ubuntu-
              advantage-aptproxy

       <job_name>_timer
              Sets the timer running interval for a specific job. Those inter-
              vals are checked every time the systemd timer runs.

       If needed, authentication to the proxy server can be performed by  set-
       ting username and password in the URL itself, as in:

         http_proxy: http://<username>:<password>@<fqdn>:<port>

       Additionally, some configuration options can be overridden in the envi-
       ronment   by   setting   an   environment    variable    prefaced    by
       UA_<option_name>.  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:

         UA_LOG_LEVEL=info ua attach

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

              The artifacts include a configure script, a tarball  with  addi-
              tional 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.

       CIS Audit (cis)
              Enables and installs the CIS Audit artifacts.

       Extended Security Maintenance (esm)
              Extended Security Maintenance ensures the ongoing  security  and
              integrity  of  systems  running  Ubuntu  Long Term Support (LTS)
              releases through Ubuntu Advantage for Infrastructure.

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

       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.

       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.

       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.

       ROS ESM Security Updates (ros)
              Robot Operating System Extended  Security  Maintenance  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.

       ROS ESM All Updates (ros-updates)
              Robot Operating System Extended Security Maintenance All Updates
              provides  additional bug fixes in addition to security fixes for
              ROS packages to ensure the ongoing integrity of ROS based appli-
              cations.

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

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

COPYRIGHT
       Copyright (C) 2019-2020 Canonical Ltd.

Canonical Ltd.                 21 February 2020            UBUNTU-ADVANTAGE(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2022 Hurricane Electric. All Rights Reserved.