Ubuntu Advantage Client

Documentation Server Guide
1

Note: The Ubuntu Advantage Client or UA Client has been renamed to the Ubuntu Pro Client in line with the rebranding of Ubuntu Advantage to Ubuntu Pro. Specific commands have also been updated to refer to Ubuntu Pro rather than Ubuntu Advantage.

For the most up-to-date information about the Ubuntu Pro Client and how to use it, please refer to our documentation.

The Ubuntu Advantage (UA) client is a tool designed to automate access to UA services like Extended Security Maintenance (ESM), CIS, FIPS, Livepatch and more. The client is available for all Ubuntu LTS releases as well as premium Ubuntu PRO cloud images on AWS, Azure and GCP. Features supported depend on the specific LTS release as they do or do not apply. The UA client provides users a command-line interface with a single point to access all UA services. This simplifies access to UA Services and allows access to UA services for all users of Ubuntu with a free tier of service. See Ubuntu Pro | Ubuntu for more details on the various UA services.

Ubuntu PRO

Ubuntu PRO premium images are published to AWS, Azure and GCP which come with Ubuntu Advantage support and services built in. On first boot, Ubuntu PRO images will automatically attach to an Ubuntu Advantage support contract and enable necessary security and support out of the box so that no extra setup is required to ensure a secure and supported Ubuntu machine.

There are two primary flavors of Ubuntu PRO images in clouds:

  • Ubuntu PRO: Ubuntu LTS images with attached Ubuntu Advantage support with kernel Livepatch and ESM security access already enabled. Ubuntu PRO images are entitled to enable any additional UA services.
  • Ubuntu PRO FIPS: Specialized Ubuntu PRO images for 16.04 and 18.04 which come pre-enabled with the cloud-optimized FIPS-certified kernel and all additional SSL and security hardening enabled are available in AWS Ubuntu PRO FIPS and Azure Ubuntu PRO FIPS.

Network requirements

Using the UA client to enable support services will rely on network access to obtain updated service credentials, add APT repositories to install deb packages and install snap packages when Livepatch is enabled. Also see the Proxy Configuration section to inform UA client of HTTP(S)/APT proxies.

Ensure the managed system has access the folloowing port:urls if in a network-limited environment:

Enabling kernel Livepatch require additional network egress:

  • 443:api.snapcraft.io
  • 443:dashboard.snapcraft.io
  • 443:login.ubuntu.com
  • 443:*.snapcraftcontent.com - Download CDNs

Working with specific services

Extended Security Maintenance (ESM)

To access ESM, either attach your existing Ubuntu 16.04 LTS machine via the UA client command line or launch an Ubuntu PRO 16.04 image which already has ESM enabled.

Keep reading if you want more detailed instructions, or have questions

Installing the UA client

The UA client is installed through apt and is present on all Ubuntu Server images. Confirm you have the latest Ubuntu Advantage client which is equal to or greater than version 27.

$ sudo apt update
$ sudo apt install ubuntu-advantage-tools
$ ua --version

Once you have verified your client, you will need to attach it to your UA account.

Attach the UA client (not needed for Ubuntu PRO)

Retrieve your UA token from Ubuntu Pro | Ubuntu. You will log in with your SSO credentials, the same credentials you use for https://login.ubuntu.com.

$ sudo ua attach YOUR_TOKEN

You should see output like the following, indicating that you have successfully associated this machine with your account.

Enabling default service esm-infra
Updating package lists
ESM Infra enabled
This machine is now attached to 'UA Infra - Essential (Virtual)'

SERVICE       ENTITLED  STATUS    DESCRIPTION
cis           yes       disabled  Center for Internet Security Audit Tools
esm-infra     yes       enabled   UA Infra: Extended Security Maintenance (ESM)
fips          yes       n/a       NIST-certified FIPS modules
fips-updates  yes       n/a       Uncertified security updates to FIPS modules
livepatch     yes       n/a       Canonical Livepatch service

NOTICES
Operation in progress: ua attach

Enable services with: ua enable <service>

Once the UA client is attached to your UA account, you can use it to activate various services, including: access to ESM packages, Livepatch, FIPS, and CIS. Some features are specific to certain LTS releases

UA Status

Users can use the status subcommand to get the current status and see what services are enabled or disabled:

$ sudo ua status

SERVICE       ENTITLED  STATUS    DESCRIPTION
cis           yes       disabled  Center for Internet Security Audit Tools
esm-infra     yes       enabled   UA Infra: Extended Security Maintenance (ESM)
fips          yes       n/a       NIST-certified FIPS modules
fips-updates  yes       n/a       Uncertified security updates to FIPS modules
livepatch     yes       n/a       Canonical Livepatch service

Enable services with: ua enable <service>

                Account: 
           Subscription: UA Applications - Essential (Virtual)
            Valid until: 2022-12-31 00:00:00
Technical support level: essential

Extended Security Maintenance (ESM)

For Ubuntu 14.04 LTS and 16.04 LTS as shown above, ESM will be automatically enabled after attaching the UA client to your account. After ubuntu-advantage-tools is installed and your machine is attached, ESM should be enabled. If ESM is not enabled, you can enable it with the following command:

$ sudo ua enable esm-infra

With the ESM repository enabled, you may see a number of additional package updates available that were not available previously. Even if your system had indicated that it was up to date before installing the ubuntu-advantage-tools and attaching, make sure to check for new package updates after ESM is enabled using apt upgrade. If you have cron jobs set to install updates, or other unattended upgrades configured, be aware that this will likely result in a number of package updates with the ESM content.

Running apt upgrade will now apply all of package updates available, including the ones in ESM.

$ sudo apt upgrade

More information: https://ubuntu.com/security/esm

Livepatch

Livepatch requires:

To enable run:

$ sudo ua enable livepatch

You should see output like the following, indicating that the Livepatch snap package has been installed.

One moment, checking your subscription first
Installing snapd
Updating package lists
Installing canonical-livepatch snap
Canonical livepatch enabled.

To check the status of Livepatch once it has been installed use this command

$ sudo canonical-livepatch status

More information: Ubuntu Livepatch Service | Security | Ubuntu

CIS Audit Tools

To access the CIS tooling first enable the software repository.

$ sudo ua enable cis
Installing CIS Audit packages
CIS Audit enabled
Visit https://security-certs.docs.ubuntu.com/en/cis to learn how to use CIS

Once the feature is enabled please follow the documentation for the CIS tooling to run the provided hardening audit scripts.

Security Certifications: FIPS

FIPS is supported on 16.04, 18.04 and 20.04 releases.

To use FIPS, one can either launch existing Ubuntu premium support images which already have FIPS kernel and security pre-enabled on first boot at AWS Ubuntu PRO FIPS images or Azure PRO FIPS images.

- OR -
Enable FIPS using the UA client will install a FIPS-certified kernel and core security-related packages such as openssh-server/client and libssl. Note: disabling FIPS on an image is not yet syupport

Warning: Enabling FIPS should be performed during a system maintenance window because this operation makes changes to underlying SSL related libraries and requires a reboot into the FIPS certified kernel.

Note: Disabling FIPS is not currently supported, only use it on machines intended expressly for this purpose.

$ sudo ua enable fips
Installing FIPS packages
FIPS enabled
A reboot is required to complete installl

Security Certifications: Common Criteria

Common Criteria is supported on 16.04 and 18.04, please see Common Criteria | Ubuntu for details and installation instructions. The UA client will be updated at a later date to add support for enabling this service directly.

Proxy Configuration

The UA client can be configured to use an HTTP/HTTPS proxy as needed for network requests. It will also honor the no_proxy environment variable if set to avoid using local proxies for certain outbound traffic. In addition, the UA client will automatically set up proxies for all programs required for enabling Ubuntu Advantage services. This includes APT, Snaps, and Livepatch.

HTTP/HTTPS Proxies

To configure standard HTTP and/or HTTPS proxies, run the following commands:

$ sudo ua config set http_proxy=http://host:port
$ sudo ua config set https_proxy=https://host:port

After running the above commands, UA client:

  1. Verifies that the proxy is working by using it to reach api.snapcraft.io
  2. Configures itself to use the given proxy for all future network requests
  3. If snapd is installed, configures snapd to use the given proxy
  4. If Livepatch has already been enabled, configures Livepatch to use the given proxy
    1. If Livepatch is enabled after this command, UA client will configure Livepatch to use the given proxy at that time.

To remove HTTP/HTTPS proxy configuration, run the following:

$ sudo ua config unset http_proxy
$ sudo ua config unset https_proxy

After running the above commands, UA client will also remove proxy configuration from snapd (if installed) and Livepatch (if enabled).

APT Proxies

APT proxy settings are configured separately. To have UA client manage your APT proxy configuration, run the following commands:

$ sudo ua config set apt_http_proxy=http://host:port
$ sudo ua config set apt_https_proxy=https://host:port

After running the above commands, UA client:

  1. Verifies that the proxy works by using it to reach archive.ubuntu.com or esm.ubuntu.com.
  2. Configures APT to use the given proxy by writing an apt configuration file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy.

Note: Any configuration file that comes later in the apt.conf.d directory could override the proxy configured by the UA client.

Note: On cloud Ubuntu PRO images in network-limited environments with UA client older than version 27.4, ensure to set a no_proxy=metadata,169.254.169.254 to ensure the launched image doesn’t attempt to use a proxy to talk to cloud-specific link-local metadata services.

To remove the APT proxy configuration, run the following:

$ sudo ua config unset apt_http_proxy
$ sudo ua config unset apt_https_proxy

Authenticating

If your proxy server requires authentication, you can pass the credentials directly in the URL when setting the configuration, as in:

$ sudo ua config set https_proxy=https://username:password@host:port

Checking the configuration

To see what proxies UA client is currently configured to use, you can use the show command.

$ sudo ua config show

The above will output something that looks like the following if there are proxies set:

http_proxy      http://proxy
https_proxy     https://proxy
apt_http_proxy  http://aptproxy
apt_https_proxy https://aptproxy

Or it may look like this if there aren’t any proxies set:

http_proxy      None
https_proxy     None
apt_http_proxy  None
apt_https_proxy None

Timer intervals for recurrent jobs

UA client sets up a systemd timer to run jobs that need to be executed recurrently. Everytime the timer runs, it decides which jobs need to be executed based on their intervals. When a job runs successfully, its next run is determined by the interval defined for that job.

Current jobs

The jobs that UA client runs periodically are:

  • update_messaging (Every 6 hours): Updates the MOTD and APT messages to reflect ESM package availability.
  • update_status: (Every 12 hours): Updates the UA status for available/enabled services.
  • gcp_auto_attach (Every 30 minutes): Tries to auto-attach on a GCP Ubuntu instance. A generic Ubuntu instance can be promoted to PRO, via the Google Platform, and acquire a license. This job checks for this scenario and auto-attaches the VM.

Changing the job interval

Each job has a configuration option of the form <job_name>_timer, which can be set with ua config. The expected value is a positive integer for the number of seconds in the interval. For example, to change the update_status job timer interval to run every 24 hours, run:

$ sudo ua config set update_status_timer=86400

Disabling a job

To disable a job, set its interval to zero. For instance, to disable the GCP auto-attach job, run:

$ sudo ua config set gcp_auto_attach_timer=0

Checking the timers

To see each job’s running interval, use the show command:

$ sudo ua config show
update_messaging_timer=21600
update_status_timer=43200
gcp_auto_attach_timer=1800

FAQ

General

Why are we updating the client?

The updated client provides users a command-line interface with a single point to access all UA services. This reduces the number of tokens a customer has to manage as the old mechanism was one token per service.

Will the old ESM system stay in place for the entire Ubuntu 14.04 LTS ESM lifetime?

Yes. If you have ESM provisioned using the old client or manually you do not have to change.

Ubuntu Pro | Ubuntu shows I have 0? Why? I have more licenses.

The number is showing 0 attached to the subscription - not your total license amount.

Attach

How do I attach/login/activate?

You have to obtain your token and run: ua attach <token>

Where do I get a token?

How do I use SSO?

SSO is available from a user’s Ubuntu One account and can be created at https://login.ubuntu.com/.

What services get enabled by default?

ESM would be enabled by default where possible. Livepatch will not be auto-enabled on Ubuntu 14.04 LTS, but is enabled by default on later series. If a service is not applicable on the platform or release then the service will be skipped

I already have UA, and use Landscape to manage my devices, can I attach and manage UA from Landscape?

Not at this time. That said, you can automate the rollout using Landscape’s ability to execute commands on systems under management.

Status

What does ‘’‘entitled’‘’ mean?

Entitled shows whether your contract with us includes this Ubuntu Advantage service or not.

Why does the STATUS column say ‘’‘n/a’‘’ if I am ‘’‘entitled’‘’ to the service?

This service may not be applicable to the system you are currently on. Here are some examples:

  • FIPS is currently only supported on Xenial and Bionic and Focal. If you are on any other release, FIPS would show up as ‘’‘n/a’‘’.
  • Bug ubuntu-advantage v. 27.2: On cloud images for AWS and Azure enabling FIPS is currently not recommended as the kernel this is installed a generic Linux FIPS kernel and not a cloud-optimized kernel. This can lead to issues rebooting your Focal (20.04) VM for certain instance types LP: #1939932 A fix will be provided in ubuntu-advantage-tools 27.3 to prevent enabling FIPS on AWS/Azure Focal cloud images
  • On Ubuntu 14.04 LTS, Livepatch is only available if you have the HWE kernel installed and are booted into it. Otherwise it shows ‘’‘n/a’‘’.
  • If you are on a container, you cannot install Livepatch.

Issues/Bugs/Debug

Where can I file bugs?

https://bugs.launchpad.net/ubuntu/+source/ubuntu-advantage-tools/+filebug

Things are failing, what logs are useful?

First, consider using the --debug option to see what might be failing. Otherwise, checkout /var/log/ubuntu-advantage.log. If including this log file in a bug report, please sanitize it first, as it will likely contain secrets!

I’m attaching successfully, but not showing entitled to anything? I have a commercial contract.

Please open a https://support.canonical.com/ with the output of sudo ua status --format json

I upgraded from Trusty with ESM to Xenial and now it does not show I have ESM enabled any longer
This is a known issue and can be resolved by re-enabling ESM using sudo ua enable esm-infra after rebooting the system into Xenial. See https://github.com/canonical/ubuntu-advantage-client/issues/1590

My cloud-init cloud-config is no longer working to enable UA products
Customers using the following cloud-config userdata will have to update to use the new cmdline client ‘ua attach’, ‘ua enable’ commands.

   #cloud-config
     ubuntu_advantage:
         commands: XXX
     runcmd:
         ubuntu-advantage enable-fips
10

I find customers also like to know that running <canonical-livepatch status --format yaml> and <canonical-livepatch status --verbose> will tell you which livepatch is currently enabled and which CVEs it’s protecting you from (otherwise some people can end up updating and rebooting every time their sys mgmt tool alerts them to a vulnerability)

12

I would repeat this question for Livepatch, especially because at some point we will recommend that users move from the Livepatch-specific token to the UA client.

13

Can we please tweak this to be more applicable to Pro users on the clouds? Specifically I am thinking, for example, of a statement upfront that, if you are running Ubuntu Pro on Azure/AWS/GCE, you should already have a recent version of the ua-client installed and it should already be attached, so you can likely go straight to the sudo ua status step.

We could also add a reference to Ubuntu Pro in the “Where do I get a token?” FAQ. Something along the lines that “Our recommended approach to obtain services like Livepatch and ESM on the Public Clouds is to use Ubuntu Pro. For other use cases you can purchase Ubuntu Advantage directly from Canonical: [existing link].”

I am not sure about having this part at the beginning:

I think you have done a great job summarising the value of ua client and how to install and configure it. I wonder if specific guidance on enabling ESM to 14.04 or 16.04 belongs somewhere else separately (e.g. on our 16.04 page). That would also give us greater flexibility to tailor the advice to, for example, Public Cloud users, who in some cases have better options.

Should we add in a ua version so that people who do have the latest version aren’t adding a ppa etc? I wonder if we should just tell people to run ua version and check it is at least 26.3 (and follow your steps if not) – if they have a version >= 26.3 do they need the very latest from a ppa?

16

I can appreciate the nice to know information but I’d leave those details to the livepatch documentation vs this specific to enabling UA services. We do reference them to the livepatch content for more information.

We’ll see if we get more questions/feedback there and balance how much detail about each service best serves users here.

17

I just purchased an Ubuntu Advantage package t get ESM for 16.04 LTS.

My server has unattended-upgrades and my /etc/apt/apt.conf.d/50unattended-upgrades file currently looks like this:

Unattended-Upgrade::Allowed-Origins {
        "${distro_id}:${distro_codename}";
        "${distro_id}:${distro_codename}-security";
        // Extended Security Maintenance; doesn't necessarily exist for
        // every release and this system may not have it installed, but if
        // available, the policy for updates is such that unattended-upgrades
        // should also install from here by default.
        "${distro_id}ESM:${distro_codename}";
//      "${distro_id}:${distro_codename}-updates";
//      "${distro_id}:${distro_codename}-proposed";
//      "${distro_id}:${distro_codename}-backports";
};

I am confused about what should actually be present in there to only get security updates including the ESM updates, because I have also seen these lines (which are different from what seems to be present in my configuration):

"${distro_id}ESMApps:${distro_codename}-apps-security";
"${distro_id}ESM:${distro_codename}-infra-security";

So: to enable ESM security updates for 16.04 LTS, which line(s) should I actually add in my 50unattended-upgrades file?

I’m now also wondering if that very first line ( “${distro_id}:${distro_codename}”, so without the “-security” suffix) is actually needed…

Thanks for any clarifications!

18

The key line I’d expect for 16.04 esm is the one for the -infra-security like:

"${distro_id}ESM:${distro_codename}-infra-security";

That said, if there are system issues so bad, or issues that prevent a system from enabling ESM there could be required updates in the original repositories

    "${distro_id}:${distro_codename}";
    "${distro_id}:${distro_codename}-security";

So I’d suggest having those three enabled.

1 Like
19

Thanks so much for your fast reply!
All sounds reasonable, so I will do as you suggest.

Do you have any idea, why my configuration line would look like this instead of the suggested one:

Is there a place where I can read up on what these various origins (ESM-related or otherwise) mean/imply?

20

https://ubuntu.com/advantage says that UA Essential includes Landscape support. However, landscape does not show up as one of the UA services that can be enabled, even after I’ve attached my token and enabled esm-infra, in sudo ua status. The Landscape dashboard says that I am not a member of any Landscape account and I can sign up for a trial account, but I don’t want a trial account (because its credit runs out in 60 days). Have I misunderstood whether UA and the ua client should give me access to Landscape? (This may be a question for Landscape support, not UA, of course!)

1 Like
21

I have a similar question. I my case I signed up for Landscape first, then added UA for a subset of servers.

I had Landscape on my all servers already and now I have added UA on three production servers. How do I let Landscape know those three production servers are covered bu UA and should not be charged separately for Landscape?

22

I want to have ESM support for Ubuntu 14.04 Trusty.
So I installed the package ubuntu-advantage-tools from the trusty-updates repository on the Ubuntu 14 host.
That package has version 19.6~ubuntu14.04.4.
It’s ua command lacks the --version switch.
It seems, that it does not know of proxy setting in /etc/uaclient.conf, too.
→ OK proxy is used when set environmant variable http(s)_proxy in the shell.

Looks like I got it running now with Trusty. Documentation for UA client with Trusty would be nice, though.

23

Is there a way to attach a client that is totally disconnected from the internet ? I deal with some environments where servers will never reach the outside and packages are generally copied over to the local apt server. Thanks.