# index.html.md
# Ubuntu Pro Client
Whether you’re an enterprise customer deploying systems at scale or
want security patching for your personal Ubuntu LTS at home, the Ubuntu Pro
Client (`pro`) is the command-line tool that will help you manage your
[Ubuntu Pro](https://ubuntu.com/pro) services. If you’re not sure which services you need,
[check out our overview](https://ubuntu.com/pro-client/docs/latest/explanations/which_services.md#which-services).
The Ubuntu Pro Client comes pre-installed on every Ubuntu system. You can run
`pro help` in your terminal window to see a list of the `pro`
services and commands available, or get started
[with our hands-on tutorial](https://ubuntu.com/pro-client/docs/latest/tutorials/basic_commands.md#tutorial-commands) to try it out in
a virtual environment.
---
## In this documentation
Get started with our [hands-on introduction](https://ubuntu.com/pro-client/docs/latest/tutorials/basic_commands.md#tutorial-commands) and explore the ways Ubuntu Pro helps to [secure your system](https://ubuntu.com/pro-client/docs/latest/tutorials/security-with-pro.md#security-tutorial)
Step-by-step guides covering key operations and common tasks such as [attaching your machine](https://ubuntu.com/pro-client/docs/latest/howtoguides/attach_index.md#attach-index), [enabling services](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_index.md#enable-index) and [fixing vulnerabilities](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_index.md#fix-index)
Discussion and clarification of key topics like [how machines are counted](https://ubuntu.com/pro-client/docs/latest/explanations/pro_token_and_machine_usage.md#pro-token-and-machine-usage), [ESM-Apps and ESM-Infra](https://ubuntu.com/pro-client/docs/latest/explanations/about_esm.md#expl-esm), and [using Pro in airgapped](https://ubuntu.com/pro-client/docs/latest/explanations/using_pro_offline.md#pro-airgapped) environments
Technical information such as [network requirements](https://ubuntu.com/pro-client/docs/latest/references/network_requirements.md#network-requirements), [API reference](https://ubuntu.com/pro-client/docs/latest/references/api.md#api), and available [CLI commands](https://ubuntu.com/pro-client/docs/latest/references/commands.md#commands)
---
## Need help?
We’re keen to know about your experience of using Ubuntu Pro!
- **Have questions?**
You might find the answers [in our FAQ](https://discourse.ubuntu.com/t/ubuntu-pro-faq/34042).
- **Having trouble?**
We would like to help! To get help on a specific page in this documentation,
simply click on the “Give feedback” link at the top of that page. This
will open up an issue in GitHub where you can tell us more about the problem
you’re having or suggestion you’d like to make, and we will do our best to
resolve it for you.
- **Found a bug?**
You can [report bugs on Launchpad](https://bugs.launchpad.net/ubuntu/+source/ubuntu-advantage-tools/+filebug)!
- **Want to give feedback?**
If you have any comments, requests or suggestions that you’d like to share,
we’d be very happy to receive them! Please feel free to reach out on
[our Discourse forum](https://discourse.ubuntu.com/c/ubuntu-pro/116), or you can get in touch via the
`#ubuntu-server` IRC channel on Libera.
## Project and community
Ubuntu Pro Client is a member of the Ubuntu family. It’s an open source project
that warmly welcomes community projects, contributions, suggestions, fixes and
constructive feedback.
- Read our [code of conduct](https://ubuntu.com/community/ethos/code-of-conduct)
- Find out how to [contribute](https://github.com/canonical/ubuntu-pro-client/blob/-/CONTRIBUTING.md)
# index.html.md
# Explanation
Our explanatory and conceptual guides are written to provide a better
understanding of how the Ubuntu Pro Client (`pro`) works. They enable you
to expand your knowledge and become better at using and configuring `pro`.
## Pro services
Ubuntu Pro is a portal to many other services offered by Canonical. Here you
can discover more about the services available through Pro and how you can
manage them with the Pro Client.
* Find out [which services we recommend](https://ubuntu.com/pro-client/docs/latest/explanations/which_services.md#which-services) for different
situations
* Use the `pro status` command
[to monitor active services](https://ubuntu.com/pro-client/docs/latest/explanations/status_columns.md#pro-status-output) on your machine
* Learn [about ESM](https://ubuntu.com/pro-client/docs/latest/explanations/about_esm.md#expl-esm) security services (`esm-apps` and
`esm-infra`)
* [Disabling and purging services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge) explains how to disable services and remove them
from your machine
## Handling security vulnerabilities
Ubuntu Pro provides security fixes for vulnerabilities (CVEs and USNs). This
section explains what those are, how to find out if your machine is affected,
and the different uses of the `pro fix` command.
* [About CVEs and USNs](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn)
* [Understand the security coverage](https://ubuntu.com/pro-client/docs/latest/explanations/how_to_interpret_the_security_status_command.md#pro-security-status) on your
installed packages using `pro security-status`
* [Common scenarios](https://ubuntu.com/pro-client/docs/latest/explanations/fix_scenarios.md#pro-fix-howto) when using the `pro fix` command
## Ubuntu Pro policies
Here we explain our usage policies for features such as using Pro offline or
airgapped, how machines are counted against tokens, how we deprecate features
and what data is collected from active machines.
* [Using Ubuntu Pro airgapped or offline](https://ubuntu.com/pro-client/docs/latest/explanations/using_pro_offline.md#pro-airgapped)
* [How machines are counted](https://ubuntu.com/pro-client/docs/latest/explanations/pro_token_and_machine_usage.md#pro-token-and-machine-usage)
* [Feature deprecation policy](https://ubuntu.com/pro-client/docs/latest/explanations/deprecation_policy.md#deprecation-policy)
* [Data collection policy](https://ubuntu.com/pro-client/docs/latest/explanations/data_collection.md#what-data-is-collected)
## Messaging
Here you’ll find details about Ubuntu Pro Client-related APT and MOTD messages
– what they are, when they are used and how they work.
* [Ubuntu Pro-related APT messages](https://ubuntu.com/pro-client/docs/latest/explanations/apt_messages.md#apt-messages)
* [Ubuntu Pro-related MOTD messages](https://ubuntu.com/pro-client/docs/latest/explanations/motd_messages.md#motd-messages)
* [Timer jobs explained](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_the_timer_jobs.md#expl-timer-jobs)
## CVE commands
Here we’ll show information about CVE-related commands.
On any of the listed commands, we consider a CVE vulnerability as **fixable**,
if and only if, at least **one** affected installed package associated with it can
be fixed. That means that a vulnerability is unfixable if no affected installed packages
related to the vulnerability can be fixed at the moment.
* [How to interpret the output of CVE commands](https://ubuntu.com/pro-client/docs/latest/explanations/how_to_interpret_output_of_pro_cve_commands.md)
## Public Cloud Ubuntu Pro
Ubuntu Pro is supported on AWS, Azure and GCP through Public Cloud Ubuntu Pro
images. On Pro Cloud images, machines are automatically attached to a support
contract by the Ubuntu Pro daemon.
* [Public Cloud Ubuntu Pro images](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_ubuntu_pro_cloud_instances.md#expl-about-pro-cpc) and the auto-attach process
* [About the Pro daemon](https://ubuntu.com/pro-client/docs/latest/explanations/what_is_the_daemon.md#the-pro-daemon)
## API endpoints explained
Some of the commands in `pro` do more than you think. Here we’ll show some of
the API endpoint outputs and how to interpret them.
* [The unattended-upgrades endpoint](https://ubuntu.com/pro-client/docs/latest/explanations/how_to_interpret_output_of_unattended_upgrades.md)
* [The fix plan endpoint](https://ubuntu.com/pro-client/docs/latest/explanations/how_to_interpret_output_of_fix_plan_api.md)
# index.html.md
# Reference
Our reference section contains technical information for the Ubuntu Pro Client.
## Interacting with the Client
There are two main ways to interact with the Pro Client: on the command line
interface (CLI) in your terminal, or automatically via the API.
* [CLI reference guide](https://ubuntu.com/pro-client/docs/latest/references/commands.md#commands)
* [API reference guide](https://ubuntu.com/pro-client/docs/latest/references/api.md#api)
* [Error messages](https://ubuntu.com/pro-client/docs/latest/references/errors_explained.md#error-messages)
You may, in a staging or canary environment, want to test upcoming changes.
For this, you can use the available Pro Client Personal Package Archives (PPA).
* [Personal Package Archives (PPAs)](https://ubuntu.com/pro-client/docs/latest/references/ppas.md#ppas)
## Support and requirements
Some Ubuntu Pro services cannot be enabled at the same time. In this section,
you can check if your chosen release is supported, and whether the services you
want to use are compatible with each other.
* [Supported Ubuntu releases](https://ubuntu.com/pro-client/docs/latest/references/support_matrix.md#support-matrix)
* [Compatible Ubuntu Pro services](https://ubuntu.com/pro-client/docs/latest/references/compatibility_matrix.md#compatibility-matrix)
* [Network requirements](https://ubuntu.com/pro-client/docs/latest/references/network_requirements.md#network-requirements)
# index.html.md
# How-to guides
If you have a specific goal and are already familiar with the Ubuntu Pro Client
(`pro`), our how-to guides have more in-depth detail than our tutorials and
can be applied to a wider range of situations.
They will help you to achieve a particular end result, but may require you to
understand and adapt the steps to fit your specific requirements.
The Pro Client comes pre-installed on every Ubuntu release. To access your
Ubuntu Pro services, you first need to attach your machine to your subscription.
## Attaching machines
To access Ubuntu Pro services, you need to first attach your machine to a
subscription:
* [How to attach](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach)
You can also simulate attaching to a specific token, to check what will happen
without making changes to your machine:
* [How to simulate attaching](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_simulate_attach.md#simulate-attach)
It’s also possible to pass a specific token to your machine using a
configuration file:
* [Attach using a config file](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach_with_config_file.md#attach-with-config)
If you need to move, clone, rebuild, or delete an attached machine, see:
* [Move or clone an attached machine](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_migrate_attached_machines.md#how-to-migrate-attached-machines)
## Enabling services
Enable, disable or check the status of the following services with the Pro
Client:
* [Anbox Cloud](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_anbox.md#manage-anbox)
* [CC EAL](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cc.md#manage-cc)
* [CIS or USG](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cis.md#manage-cis)
* [ESM-Infra and ESM-Apps](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_esm_infra.md#manage-esm)
* [ESM-Infra Legacy on Trusty](https://ubuntu.com/pro-client/docs/latest/howtoguides/trusty_legacy_support.md#enable-trusty)
* [FIPS](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_fips.md#manage-fips)
* [Landscape](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_landscape.md#manage-landscape)
* [Livepatch](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_livepatch.md#manage-livepatch)
* [Real-Time Ubuntu](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_realtime_kernel.md#manage-realtime)
## Handling vulnerabilities
Using the Pro Client, you can handle individual vulnerabilities (both CVEs and
USNs) that may be affecting your machine. You can also preview what will happen
if you run the `pro fix` command on a specific vulnerability, and control
if related USNs are fixed.
* [Check if a system is affected](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_if_system_affected_by_cve.md#pro-fix-check-cve)
* [Use pro fix to resolve a CVE or USN](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_resolve_given_cve.md#pro-fix-resolve-cve)
* [Preview pro fix results](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_what_the_fix_command_would_change.md#pro-fix-dry-run)
* [Skip fixing related USNs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_not_fix_related_usns.md#pro-fix-skip-related)
You can also resolve multiple vulnerabilities at once using the API.
* [Check if your system is affected by multiple CVEs](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_know_if_system_affected_by_a_list_of_cves.md#pro-check-list-cves)
* [Preview result of fixing multiple CVEs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_better_visualize_fixing_multiple_cves.md#how-to-better-visualize-fixing-multiple-cves)
## Configuring messages
You can choose whether (and how) to display APT and MOTD messages, set timer
jobs, or use your own custom configuration.
* [Display or hide APT News](https://ubuntu.com/pro-client/docs/latest/howtoguides/disable_enable_apt_news.md#disable-enable-apt-news)
* [Use custom APT configuration](https://ubuntu.com/pro-client/docs/latest/howtoguides/use_custom_apt_config.md#custom-apt-config)
* [Refresh MOTD and APT messages](https://ubuntu.com/pro-client/docs/latest/howtoguides/update_motd_messages.md#update-motd-apt)
* [Configure a timer job](https://ubuntu.com/pro-client/docs/latest/howtoguides/configuring_timer_jobs.md#configuring-timer-jobs)
## Setting up proxies
The Ubuntu Pro Client supports proxy setups. These guides will help you to
configure your proxies correctly.
* [Configure a proxy](https://ubuntu.com/pro-client/docs/latest/howtoguides/configure_proxies.md)
* [Configure TLS-in-TLS proxy](https://ubuntu.com/pro-client/docs/latest/howtoguides/configure_tls_in_tls_proxy.md)
## Using Pro Client with Docker
There are several Ubuntu Pro services that may be useful in a Docker image.
* [Enable Ubuntu Pro services in a Dockerfile](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_in_dockerfile.md)
* [Create an Ubuntu FIPS Docker image](https://ubuntu.com/pro-client/docs/latest/howtoguides/create_a_fips_docker_image.md)
## Ubuntu Pro Client for Clouds
Ubuntu Pro is supported by AWS, Azure and GCP. For more details about this
support, see [our explanation](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_ubuntu_pro_cloud_instances.md#expl-about-pro-cpc). These how-to guides
will direct you in setting up your Public Cloud environment.
* [Create a customized Cloud Ubuntu Pro image](https://ubuntu.com/pro-client/docs/latest/howtoguides/create_pro_golden_image.md)
* [Cloud Ubuntu Pro images with FIPS updates](https://ubuntu.com/pro-client/docs/latest/howtoguides/create_a_fips_updates_pro_cloud_image.md)
## Ubuntu Pro Client LXD integration
* [How to set up the Ubuntu Pro LXD integration](https://ubuntu.com/pro-client/docs/latest/howtoguides/use_pro_lxd_guests.md)
## Troubleshooting
You may occasionally need to check the version of the Pro Client, collect logs
in order to report a bug, or release a corrupted lock on a file.
* [Check Pro Client version](https://ubuntu.com/pro-client/docs/latest/howtoguides/check_pro_version.md)
* [Collect data logs for bug reporting](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_collect_logs.md)
* [Get rid of corrupted locks](https://ubuntu.com/pro-client/docs/latest/howtoguides/get_rid_of_corrupt_lock.md)
# index.html.md
# Tutorial
This section contains step-by-step tutorials to show what the Ubuntu Pro Client
(`pro`) is capable of, while helping you to achieve specific aims.
We hope our tutorials make as few assumptions as possible and are accessible
to anyone with an interest in `pro`. They should be a great place to start!
## Getting started
These tutorials introduce you to the Pro Client, its main commands and how to
use them to manage Pro on your system. We will also take a look at Pro’s
security offerings and how they help to secure your system.
* [Part 1: Introduction to the main Pro Client commands](https://ubuntu.com/pro-client/docs/latest/tutorials/basic_commands.md#tutorial-commands)
* [Part 2: Explore your system’s security with Pro](https://ubuntu.com/pro-client/docs/latest/tutorials/security-with-pro.md#security-tutorial)
## Further tutorials
Once you are comfortable with the basics and want to start exploring other
things you can do with the Ubuntu Pro Client, you can work through our
additional tutorials.
They are not sequential, so you can approach them in any order you like!
* [Host your own APT news](https://ubuntu.com/pro-client/docs/latest/tutorials/host_apt_news.md#host-own-apt-news)
# index.html.md
# Compatibility matrix for Ubuntu Pro services
Some Ubuntu Pro services are compatible with each other. The following
matrix display the services that are compatible:
| | esm-infra | esm-apps | livepatch | cc-eal | cis | usg | fips | fips-updates | realtime-kernel | ros | ros-updates | anbox-cloud |
|-----------------|------------------------------------|-----------------------------------|------------------------------------|---------------------------------|------------------------------|------------------------------|--------------------------------|---------------------------------------|------------------------------------------|------------------------------|--------------------------------------|--------------------------------------|
| esm-infra | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| esm-apps | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| livepatch | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ |
| cc-eal | ✅ | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| cis | ✅ | ✅ | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| usg | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| fips | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | N/A | ❌ | ❌ | ✅ | ✅ | ✅ |
| fips-updates | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | N/A | ❌ | ✅ | ✅ | ✅ |
| realtime-kernel | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | N/A | ✅ | ✅ | ✅ |
| ros | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ✅ | ✅ |
| ros-updates | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ✅ |
| anbox-cloud | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
# index.html.md
# Support matrix for the Ubuntu Pro Client
Ubuntu Pro services are only available on Ubuntu Long Term Support (LTS)
releases.
On interim Ubuntu releases, `pro status` will report most of the services as
“n/a” (not applicable), and disallow enabling those services.
Here is a list of platforms and releases that Ubuntu Pro Client, through the
`ubuntu-pro-client` package, supports.
| Ubuntu Release | Build Architectures | Initial Release | Final Release |
|------------------|----------------------------------------------------|-------------------|----------------------------|
| Trusty | amd64, arm64, armhf, i386, powerpc, ppc64el | None | 19.6 \* |
| Xenial | amd64, arm64, armhf, i386, powerpc, ppc64el, s390x | None | Active SRU of all features |
| Bionic | amd64, arm64, armhf, i386, ppc64el, s390x | 17 | Active SRU of all features |
| Focal | amd64, arm64, armhf, ppc64el, riscv64, s390x | 20.3 | Active SRU of all features |
| Jammy | amd64, arm64, armhf, ppc64el, riscv64, s390x | 27.7 | Active SRU of all features |
| Kinetic | amd64, arm64, armhf, ppc64el, riscv64, s390x | 27.11.2 | Active SRU of all features |
| Lunar | amd64, arm64, armhf, ppc64el, riscv64, s390x | 27.14.4 | Active SRU of all features |
| Mantic | amd64, arm64, armhf, ppc64el, riscv64, s390x | TBD | Active SRU of all features |
\* Please note that, on Trusty, the package is called `ubuntu-advantage-tools`.
# index.html.md
# Errors you may encounter and their meaning
If you encounter an error or warning message from Pro Client that you don’t
understand and cannot find on this page, please click the “Give feedback”
button at the top of the page and let us know so that we can add it.
## User Configuration Migration in version 27.14
Version 27.14 of Ubuntu Pro Client changed how some user configuration settings
are stored on disk. It moved several settings out of
`/etc/ubuntu-advantage/uaclient.conf` and into a file managed solely by the
`pro config {set,unset,show}` subcommands.
Most settings should be automatically migrated to the new file when Pro Client
is upgraded. If something failed you may see one of the following messages:
### Migration error 1
* **Error message:**
```text
Warning: Failed to load /etc/ubuntu-advantage/uaclient.conf
No automatic migration will occur.
You may need to use "pro config set" to re-set your settings.
```
* **Where you’ll see it:**
During an `apt upgrade` or `apt install ubuntu-pro-client`.
* **What does it mean:**
This means that `/etc/ubuntu-advantage/uaclient.conf` could not be read or
parsed as YAML during the migration.
* **What you can do about it:**
Check the contents of `/etc/ubuntu-advantage/uaclient.conf` and ensure it
is valid YAML.
For any setting that is nested under `ua_config`:
* If you modified the value in the past, run
`pro config set field_name=your_custom_value`
* Delete the setting from `/etc/ubuntu-advantage/uaclient.conf`
* Delete the `ua_config:` line from `/etc/ubuntu-advantage/uaclient.conf`
### Migration error 2
* **Error message:**
```text
Warning: Failed to migrate user_config from /etc/ubuntu-advantage/uaclient.conf
Please run the following to keep your custom settings:
pro config set example=example
```
* **Where you’ll see it:**
During an `apt upgrade` or `apt install ubuntu-pro-client`
* **What does it mean:**
This means that `/var/lib/ubuntu-advantage/user-config.json` could not be
written, or a JSON serialization error occurred.
* **What you can do about it:**
Run each of the `pro config set` commands recommended in the warning
message.
### Migration error 3
* **Error message:**
```text
Warning: Failed to migrate /etc/ubuntu-advantage/uaclient.conf
Please add following to uaclient.conf to keep your config:
example: example
```
* **Where you’ll see it:**
During an `apt upgrade` or `apt install ubuntu-pro-client`
* **What does it mean:**
This means that `/etc/ubuntu-advantage/uaclient.conf` could not be
written, or a YAML serialization error occurred.
* **What you can do about it:**
Ensure that the settings listed in the warning output make it into your new
`uaclient.conf`.
### Warnings in versions >=27.14~
* **Error message:**
```text
legacy "ua_config" found in uaclient.conf
```
or
```text
Warning: uaclient.conf contains old ua_config field.
```
* **Where you’ll see it:**
In `/var/log/ubuntu-advantage.log` after using the `pro` CLI or during
an `apt upgrade` to a newer version of `ubuntu-pro-client`.
* **What does it mean:**
This means that there are still settings nested under `ua_config` in
`/etc/ubuntu-advantage/uaclient.conf`. These will still be honored, but
support may be removed in the future.
* **What you can do about it:**
Check the contents of `/etc/ubuntu-advantage/uaclient.conf`.
For any setting that is nested under `ua_config`:
* If you modified the value in the past, run
`pro config set field_name=your_custom_value`
* Delete the setting from `/etc/ubuntu-advantage/uaclient.conf`
* Delete the `ua_config:` line from `/etc/ubuntu-advantage/uaclient.conf`
# index.html.md
# The Ubuntu Pro API reference guide
The Ubuntu Pro Client has a Python-based API to be consumed by users who want
to integrate the Client’s functionality with their software.
The functions and objects are available through the `uaclient.api` module,
and all of the available endpoints return an object with specific data for the
calls.
Besides importing the Python code directly, consumers who are not writing
Python may use the command line interface (CLI) to call the same functionality,
using the `pro api` command. This command will always return a JSON with a
standard structure, as can be seen below:
```json
{
"_schema_version": "v1",
"data": {
"attributes": {
//
},
"meta": {
"environment_vars": []
},
"type": ""
},
"errors": [],
"result": "",
"version": "",
"warnings": []
}
```
## Version dependencies
The Ubuntu Pro Client is shipped as the `ubuntu-pro-client` package.
The documentation for each endpoint below states the first version to include
that endpoint.
If you depend on these endpoints, we recommend using a standard dependency
version requirement to ensure that a sufficiently up-to-date version of the Pro
Client is installed before trying to use it.
#### IMPORTANT
The `~` at the end of the version is important to ensure that `dpkg`
version comparison works as expected.
For example, if your software is packaged as a deb, then you can add the
following to your `Depends` list in your `control` file to ensure the
installed version is at least `27.11~`:
```default
ubuntu-pro-client (>= 27.11~)
```
### Runtime version detection
If you need to detect the current version at runtime, the most reliable way is
to query `dpkg`.
```bash
dpkg-query --showformat='${Version}' --show ubuntu-pro-client
```
If you need to compare versions at runtime, make sure you use the `dpkg`
version comparison algorithm. For example, the following will exit 0 if the
currently installed version of Pro Client is at least `27.11~`:
```bash
dpkg --compare-versions "$(dpkg-query --showformat='${Version}' --show ubuntu-pro-client)" ge "27.11~"
```
### Runtime feature detection
As an alternative to version detection, you can use feature detection. This is
easier to do when importing the API in python than it is when using the
`pro api` subcommand.
In python, try to import the desired endpoint. If an `ImportError` is raised,
then the currently installed version of Ubuntu Pro Client doesn’t support that
endpoint.
For example:
```python
try:
from uaclient.api.u.pro.version.v1 import version
pro_client_api_supported = True
except ImportError:
pro_client_api_supported = False
```
You could do something similar by catching certain errors when using the
`pro api` subcommand, but there are more cases that could indicate an old
version, and it generally isn’t recommended.
### *Errors* and *warnings* fields
When using the API through the CLI, we use two distinct fields to list issues
to the users; *errors* and *warnings*.
Both of these fields contain a list of JSON objects explaining unexpected
behavior during the execution of a command. For example, the *errors* field
will be populated like this if we have a connectivity issue when running a
`pro api` command:
```json
[
{
"title": "Failed to connect to authentication server",
"code": "connectivity-error",
"meta": {}
}
]
```
*Warnings* follow the exact same structure as *errors*. The only difference is
that *warnings* means that the command was able to complete although unexpected
scenarios happened when executing the command.
### CLI arguments
There are two ways to provide data to APIs that require arguments.
* `--args`: Use this to individually provide arguments to the CLI endpoint.
For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`
* `--data`: Use this to provide a JSON object containing all the data:
For example: `pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'`
## Available endpoints
The currently available endpoints are:
- [u.pro.version.v1]()
- [u.pro.attach.auto.configure_retry_service.v1]()
- [u.pro.attach.auto.full_auto_attach.v1]()
- [u.pro.attach.auto.should_auto_attach.v1]()
- [u.pro.attach.guest.get_guest_token.v1]()
- [u.pro.attach.magic.initiate.v1]()
- [u.pro.attach.magic.revoke.v1]()
- [u.pro.attach.magic.wait.v1]()
- [u.pro.attach.token.full_token_attach.v1]()
- [u.pro.detach.v1]()
- [u.pro.packages.summary.v1]()
- [u.pro.packages.updates.v1]()
- [u.pro.security.cves.v1]()
- [u.pro.security.fix.cve.execute.v1]()
- [u.pro.security.fix.cve.plan.v1]()
- [u.pro.security.fix.usn.execute.v1]()
- [u.pro.security.fix.usn.plan.v1]()
- [u.pro.security.status.livepatch_cves.v1]()
- [u.pro.security.status.reboot_required.v1]()
- [u.pro.services.dependencies.v1]()
- [u.pro.services.disable.v1]()
- [u.pro.services.enable.v1]()
- [u.pro.status.enabled_services.v1]()
- [u.pro.status.is_attached.v1]()
- [u.apt_news.current_news.v1]()
- [u.security.package_manifest.v1]()
- [u.unattended_upgrades.status.v1]()
## u.pro.version.v1
This endpoint shows the installed Pro Client version.
- Introduced in Ubuntu Pro Client Version: `27.11~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.version.v1 import version
result = version()
```
**Expected return object:**
- `uaclient.api.u.pro.version.v1.VersionResult`
| Field Name | Type | Description |
|---------------------|--------|-------------------------------|
| `installed_version` | `str` | The current installed version |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `VersionError`: Raised if the Client cannot determine the version.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.version.v1
```
**Expected attributes in JSON structure:**
```js
{
"installed_version": "32.3~24.04"
}
```
## u.pro.attach.auto.configure_retry_service.v1
This endpoint configures options for the retry auto-attach functionality,
and creates files that will activate the retry auto-attach functionality
if `ubuntu-advantage.service` runs.
Note that this does not start `ubuntu-advantage.service`. This makes it
useful for calling during the boot process
`Before: ubuntu-advantage.service` so that when
`ubuntu-advantage.service` starts, its `ConditionPathExists` check
passes and activates the retry auto-attach function.
If you call this function outside of the boot process and would like the
retry auto-attach functionality to actually start, you’ll need to call
something like `systemctl start ubuntu-advantage.service`.
- Introduced in Ubuntu Pro Client Version: `27.12~`
- Requires network access: No
Arguments:
| Field Name | Type | Description |
|------------------|-----------------------|----------------------------------------------------------------------|
| `enable` | `Optional[List[str]]` | Optional list of services to enable after auto-attaching. |
| `enable_beta` | `Optional[List[str]]` | Optional list of beta services to enable after auto-attaching. |
| `cloud_override` | `Optional[str]` | Ignore the result of `cloud-id` and act as if running on this cloud. |
#### NOTE
If none of the lists are set, the services will be enabled based on the
contract definitions.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.auto.configure_retry_service.v1 import configure_retry_service, ConfigureRetryServiceOptions
options = ConfigureRetryServiceOptions(enable=["", ""], enable_beta=[""])
result = configure_retry_service(options)
```
**Expected return object:**
- `uaclient.api.u.pro.attach.auto.configure_retry_service.v1.ConfigureRetryServiceResult`
- This object has no fields.
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.auto.configure_retry_service.v1 --data {"enable": ["esm-infra", "esm-apps"]}
```
**Expected attributes in JSON structure:**
```js
{}
```
## u.pro.attach.auto.full_auto_attach.v1
This endpoint runs the whole auto-attach process on the system.
- Introduced in Ubuntu Pro Client Version: `27.11~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|------------------|-----------------------|----------------------------------------------------------------------|
| `enable` | `Optional[List[str]]` | Optional list of services to enable after auto-attaching. |
| `enable_beta` | `Optional[List[str]]` | Optional list of beta services to enable after auto-attaching. |
| `cloud_override` | `Optional[str]` | Ignore the result of `cloud-id` and act as if running on this cloud. |
#### NOTE
If none of the lists are set, the services will be enabled based on the
contract definitions.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.auto.full_auto_attach.v1 import full_auto_attach, FullAutoAttachOptions
options = FullAutoAttachOptions(enable=["", ""], enable_beta=[""])
result = full_auto_attach(options)
```
**Expected return object:**
- `uaclient.api.u.pro.attach.auto.full_auto_attach.v1.FullAutoAttachResult`
- This object has no fields.
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `AlreadyAttachedError`: Raised if running on a machine which is already attached to a Pro subscription.
- `AutoAttachDisabledError`: Raised if `disable_auto_attach: true` in `uaclient.conf`.
- `ConnectivityError`: Raised if it is not possible to connect to the contracts service.
- `ContractAPIError`: Raised if there is an unexpected error in the contracts service interaction.
- `EntitlementsNotEnabledError`: Raised if the Client fails to enable any of the entitlements (whether present in any of the lists or listed in the contract).
- `LockHeldError`: Raised if another Client process is holding the lock on the machine.
- `NonAutoAttachImageError`: Raised if the cloud where the system is running does not support auto-attach.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.auto.full_auto_attach.v1 --data {"enable": ["esm-infra", "esm-apps"]}
```
**Expected attributes in JSON structure:**
```js
{}
```
## u.pro.attach.auto.should_auto_attach.v1
This endpoint checks if a given system should run auto-attach on boot.
- Introduced in Ubuntu Pro Client Version: `27.11~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.auto.should_auto_attach.v1 import should_auto_attach
result = should_auto_attach()
```
**Expected return object:**
- `uaclient.api.u.pro.attach.auto.should_auto_attach.v1.ShouldAutoAttachResult`
| Field Name | Type | Description |
|----------------------|--------|---------------------------------------------------|
| `should_auto_attach` | `bool` | True if the system should run auto-attach on boot |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.auto.should_auto_attach.v1
```
**Expected attributes in JSON structure:**
```js
{
"should_auto_attach": false
}
```
## u.pro.attach.guest.get_guest_token.v1
This endpoint fetches a guest token from the backend.
- Introduced in Ubuntu Pro Client Version: `35~`
- Requires network access: Yes
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.guest_token.get_guest_token.v1 import get_guest_token
get_guest_token()
```
**Expected return object:**
- `uaclient.api.u.pro.attach.guest.get_guest_token.v1.GetGuestTokenResult`
| Field Name | Type | Description |
|---------------|------------|----------------------------------------|
| `guest_token` | `str` | The guest token |
| `id` | `str` | The ID of the guest token |
| `expires` | `datetime` | The expiration time of the guest token |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `ConnectivityError`: Raised if it is not possible to connect to the contracts service.
- `ContractAPIError`: Raised if there is an unexpected error in the contracts service interaction.
- `NonRootUserError`: Raised if a non-root user executes this endpoint.
- `UnattachedError`: Raised if the machine is not attached
- `FeatureNotSupportedOldTokenError`: Raised if the machine needs to be re-attached first.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.guest_token.get_guest_token.v1
```
**Expected attributes in JSON structure:**
```js
{
"guest_token": "...",
"id": "...",
"expires": "..."
}
```
## u.pro.attach.magic.initiate.v1
This endpoint initiates the Magic Attach flow, retrieving the User Code to
confirm the operation and the Token used to proceed.
- Introduced in Ubuntu Pro Client Version: `27.11~`
- Requires network access: Yes
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.magic.initiate.v1 import initiate
result = initiate()
```
**Expected return object:**
- `uaclient.api.u.pro.attach.magic.initiate.v1.MagicAttachInitiateResult`
| Field Name | Type | Description |
|--------------|--------|-----------------------------------------------------------------------------------------------------------|
| `user_code` | `str` | Code the user will see in the UI when confirming the Magic Attach |
| `token` | `str` | Magic Token that can be used in either [u.pro.attach.magic.revoke.v1]() or [u.pro.attach.magic.wait.v1]() |
| `expires` | `str` | Timestamp of the Magic Attach process expiration |
| `expires_in` | `int` | Seconds before the Magic Attach process expires |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `ConnectivityError`: Raised if it is not possible to connect to the contracts service.
- `ContractAPIError`: Raised if there is an unexpected error in the contracts service interaction.
- `MagicAttachUnavailable`: Raised if the Magic Attach service is busy or unavailable at the moment.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.magic.initiate.v1
```
**Expected attributes in JSON structure:**
```js
{
"user_code":"",
"token":"",
"expires": "T.",
"expires_in": 600
}
```
## u.pro.attach.magic.revoke.v1
This endpoint revokes a Magic Attach Token.
- Introduced in Ubuntu Pro Client Version: `27.11~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|---------------|--------|----------------------------------------------|
| `magic_token` | `str` | The Token provided by the initiate endpoint. |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.magic.revoke.v1 import MagicAttachRevokeOptions, revoke
options = MagicAttachWaitOptions(magic_token="")
result = revoke(options)
```
**Expected return object:**
- `uaclient.api.u.pro.attach.magic.revoke.v1.MagicAttachRevokeResult`
- This object has no fields.
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `ConnectivityError`: Raised if it is not possible to connect to the contracts service.
- `ContractAPIError`: Raised if there is an unexpected error in the contracts service interaction.
- `MagicAttachTokenAlreadyActivated`: Raised when trying to revoke a Token which was already activated through the UI.
- `MagicAttachTokenError`: Raised when an invalid/expired Token is sent.
- `MagicAttachUnavailable`: Raised if the Magic Attach service is busy or unavailable at the moment.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.magic.revoke.v1 --args magic_token=
```
**Expected attributes in JSON structure:**
```js
{}
```
## u.pro.attach.magic.wait.v1
This endpoint polls the contracts service waiting for the user to confirm
the Magic Attach.
- Introduced in Ubuntu Pro Client Version: `27.11~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|---------------|--------|----------------------------------------------|
| `magic_token` | `str` | The Token provided by the initiate endpoint. |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.magic.wait.v1 import MagicAttachWaitOptions, wait
options = MagicAttachWaitOptions(magic_token="")
result = wait(options)
```
**Expected return object:**
- `uaclient.api.u.pro.attach.magic.wait.v1.MagicAttachWaitResult`
| Field Name | Type | Description |
|------------------|--------|-------------------------------------------------------------------|
| `user_code` | `str` | Code the user will see in the UI when confirming the Magic Attach |
| `token` | `str` | The same Magic Token that was sent as an argument |
| `expires` | `str` | Timestamp of the Magic Attach process expiration |
| `expires_in` | `int` | Seconds before the Magic Attach process expires |
| `contract_id` | `str` | ID of the contract the machine will be attached to |
| `contract_token` | `str` | The contract Token to attach the machine |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `ConnectivityError`: Raised if it is not possible to connect to the contracts service.
- `ContractAPIError`: Raised if there is an unexpected error in the contracts service interaction.
- `MagicAttachTokenError`: Raised when an invalid/expired Token is sent.
- `MagicAttachUnavailable`: Raised if the Magic Attach service is busy or unavailable at the moment.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.magic.wait.v1 --args magic_token=
```
**Expected attributes in JSON structure:**
```js
{
"user_code":"",
"token":"",
"expires": "T.",
"expires_in": 500,
"contract_id": "",
"contract_token": "",
}
```
## u.pro.attach.token.full_token_attach.v1
This endpoint allows the user to attach to a Pro subscription using a
token.
- Introduced in Ubuntu Pro Client Version: `32~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|------------------------|------------------|-------------------------------------------------------------------------------------------------|
| `token` | `str` | The token associated with a Pro subscription |
| `auto_enable_services` | `Optional[bool]` | If false, the attach operation will not enable any service during the operation (default: true) |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.attach.token.full_token_attach.v1 import full_token_attach, FullTokenAttachOptions
options = FullTokenAttachOptions(token="TOKEN")
result = full_token_attach(options)
```
**Expected return object:**
- `uaclient.api.u.pro.attach.token.full_token_attach.v1.FullTokenAttachResult`
| Field Name | Type | Description |
|-------------------|-------------|-----------------------------------------------------------------|
| `enabled` | `List[str]` | The services enabled during the attach operation |
| `reboot_required` | `bool` | True if the system requires a reboot after the attach operation |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `ConnectivityError`: Raised if it is not possible to connect to the contracts service.
- `ContractAPIError`: Raised if there is an unexpected error in the contracts service interaction.
- `LockHeldError`: Raised if another Client process is holding the lock on the machine.
- `NonRootUserError`: Raised if a non-root user executes this endpoint.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.attach.token.full_token_attach.v1 --data -
```
Note that it is generally not recommended to pass secrets such as the token on
the command line. The example uses the arguments `--data -` which causes
`pro` to read the input data from `stdin`. Then the arguments can be
written as JSON to `stdin` of the process.
For example, if we define a JSON file (i.e. `file.json`) with the same
attributes as the options for this endpoint:
```json
{
"token": "TOKEN",
"auto_enable_services": false
}
```
Then we can call the API like this:
```bash
cat file.json | pro api u.pro.attach.token.full_token_attach.v1 --data -
```
**Expected attributes in JSON structure:**
```js
{
"enabled": ["service1", "service2"],
"reboot_required": false
}
```
## u.pro.detach.v1
This endpoint allows the user to detach the machine from a Pro
subscription.
- Introduced in Ubuntu Pro Client Version: `32~`
- Requires network access: Yes
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.detach.v1 import detach
result = detach()
```
**Expected return object:**
- `uaclient.api.u.pro.detach.v1.DetachResult`
| Field Name | Type | Description |
|-------------------|-------------|-----------------------------------------------------------------|
| `disabled` | `List[str]` | The services disabled during the detach operation |
| `reboot_required` | `bool` | True if the system requires a reboot after the detach operation |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `NonRootUserError`: Raised if a non-root user executes this endpoint.
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.detach.v1
```
**Expected attributes in JSON structure:**
```js
{
"disabled": ["service1", "service2"],
"reboot_required": false
}
```
## u.pro.packages.summary.v1
This endpoint shows a summary of installed packages in the system,
categorized by origin.
- Introduced in Ubuntu Pro Client Version: `27.12~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.packages.summary.v1 import summary
result = summary()
```
**Expected return object:**
- `uaclient.api.u.pro.packages.summary.v1.PackageSummaryResult`
| Field Name | Type | Description |
|--------------|------------------|-----------------------------------|
| `summary` | `PackageSummary` | Summary of all installed packages |
- `uaclient.api.u.pro.packages.summary.v1.PackageSummary`
| Field Name | Type | Description |
|----------------------------|--------|------------------------------------------------------|
| `num_installed_packages` | `int` | Total count of installed packages |
| `num_esm_apps_packages` | `int` | Count of packages installed from `esm-apps` |
| `num_esm_infra_packages` | `int` | Count of packages installed from `esm-infra` |
| `num_main_packages` | `int` | Count of packages installed from `main` |
| `num_multiverse_packages` | `int` | Count of packages installed from `multiverse` |
| `num_restricted_packages` | `int` | Count of packages installed from `restricted` |
| `num_third_party_packages` | `int` | Count of packages installed from third party sources |
| `num_universe_packages` | `int` | Count of packages installed from `universe` |
| `num_unknown_packages` | `int` | Count of packages installed from unknown sources |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.packages.summary.v1
```
**Expected attributes in JSON structure:**
```js
{
"summary":{
"num_installed_packages": 1,
"num_esm_apps_packages": 2,
"num_esm_infra_packages": 3,
"num_main_packages": 4,
"num_multiverse_packages": 5,
"num_restricted_packages": 6,
"num_third_party_packages": 7,
"num_universe_packages": 8,
"num_unknown_packages": 9,
},
}
```
## u.pro.packages.updates.v1
This endpoint shows available updates for packages in a system, categorized
by where they can be obtained.
- Introduced in Ubuntu Pro Client Version: `27.12~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.packages.updates.v1 import updates
result = updates()
```
**Expected return object:**
- `uaclient.api.u.pro.packages.updates.v1.PackageUpdatesResult`
| Field Name | Type | Description |
|--------------|--------------------|----------------------------------------|
| `summary` | `UpdateSummary` | Summary of all available updates |
| `updates` | `List[UpdateInfo]` | Detailed list of all available updates |
- `uaclient.api.u.pro.packages.updates.v1.UpdateSummary`
| Field Name | Type | Description |
|---------------------------------|--------|--------------------------------------------------------|
| `num_updates` | `int` | Total count of available updates |
| `num_esm_apps_updates` | `int` | Count of available updates from `esm-apps` |
| `num_esm_infra_updates` | `int` | Count of available updates from `esm-infra` |
| `num_standard_security_updates` | `int` | Count of available updates from the `-security` pocket |
| `num_standard_updates` | `int` | Count of available updates from the `-updates` pocket |
- `uaclient.api.u.pro.packages.updates.v1.UpdateInfo`
| Field Name | Type | Description |
|-----------------|--------|--------------------------------------------------|
| `download_size` | `int` | Download size for the update in bytes |
| `origin` | `str` | Where the update is downloaded from |
| `package` | `str` | Name of the package to be updated |
| `provided_by` | `str` | Service which provides the update |
| `status` | `str` | Whether this update is ready for download or not |
| `version` | `str` | Version of the update |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.packages.updates.v1
```
**Expected attributes in JSON structure:**
```js
{
"summary": {
"num_updates": 1,
"num_esm_apps_updates": 2,
"num_esm_infra_updates": 3,
"num_standard_security_updates": 4,
"num_standard_updates": 5,
},
"updates": [
{
"download_size": 6,
"origin": "",
"package": "",
"provided_by": "",
"status": "",
"version": "",
},
]
}
```
## u.pro.security.cves.v1
This endpoint shows the CVE vulnerabilities in the system.
By default, this API will show all CVEs that affect the system.
- Introduced in Ubuntu Pro Client Version: `35~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|--------------|------------------|---------------------------|
| `unfixable` | `Optional[bool]` | Show only unfixable CVES. |
| `fixable` | `Optional[bool]` | Show only fixable CVES. |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.cves.v1 import cves, CVEsOptions
options = CVEsOptions()
result = cves(options)
```
**Expected return object:**
- `uaclient.api.u.pro.security.cves.v1.CVEsResult`
| Field Name | Type | Description |
|--------------|--------|-----------------------------------------------------------------------------------------------------|
| `packages` | `dict` | A dictionary where the keys are installed package names and the values are AffectedPackage objects. |
| `cves` | `dict` | A dictionary where the keys are CVE names and the values are CVEInfo objects. |
- `uaclient.api.u.pro.security.cves.v1.AffectedPackage`
| Field Name | Type | Description |
|-------------------|----------------------------|------------------------------------|
| `current_version` | `str` | The current version of the package |
| `cves` | `List[CVEAffectedPackage]` | The CVE that affects the package |
- `uaclient.api.u.pro.security.cves.v1.CVEAffectedPackage`
| Field Name | Type | Description |
|---------------|-----------------|------------------------------------------------|
| `name` | `Optional[str]` | The CVE name |
| `fix_version` | `Optional[str]` | The version that fixes the CVE for the package |
| `fix_status` | `Optional[str]` | The status of the CVE fix for the package |
| `fix_origin` | `str` | The pocket where the fix is available from |
- `uaclient.api.u.pro.security.cves.v1.CVEInfo`
| Field Name | Type | Description |
|-----------------|-----------------------|---------------------------------|
| `description` | `str` | The CVE description |
| `published_at` | `datetime` | The CVE published date |
| `priority` | `str` | The ubuntu priority for the CVE |
| `notes` | `Optional[List[str]]` | A list of notes for the CVE |
| `cvss_score` | `Optional[float]` | The CVE cvss score |
| `cvss_severity` | `Optional[str]` | The CVE cvss severity |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.cves.v1
```
**Expected attributes in JSON structure:**
```js
{
"cves": {
"CVE-2023-5678": {
"cvss_score": 8.1,
"cvss_severity": "high",
"description": "description example",
"notes": [
"note example",
],
"priority": "medium",
"published_at": ".*"
}
},
"packages": {
"accountsservice": {
"current_version": "0.6.40-2ubuntu11.6",
"cves": [
{
"fix_origin": "esm-infra",
"fix_status": "fixed",
"fix_version": "0.6.40-2ubuntu11.6+esm1",
"name": "CVE-2023-5678"
}
]
},
"libaccountsservice0": {
"current_version": "0.6.40-2ubuntu11.6",
"cves": [
{
"fix_origin": "esm-infra",
"fix_status": "fixed",
"fix_version": "0.6.40-2ubuntu11.6+esm1",
"name": "CVE-2023-5678"
}
]
}
},
}
```
## u.pro.security.fix.cve.execute.v1
This endpoint fixes the specified CVEs on the machine.
- Introduced in Ubuntu Pro Client Version: `30~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|--------------|-------------|-------------------------------------------|
| `cves` | `List[str]` | A list of CVE (i.e. CVE-2023-2650) titles |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.fix.cve.execute.v1 import execute, CVEFixExecuteOptions
options = CVEFixExecuteOptions(cves=["CVE-1234-1234", "CVE-1234-1235"])
result = execute(options)
```
**Expected return object:**
- `uaclient.api.u.pro.security.fix.cve.execute.v1.CVESAPIFixExecuteResult`
| Field Name | Type | Description |
|--------------|--------------------------|--------------------------------------------|
| `cves_data` | `CVEAPIFixExecuteResult` | A list of `CVEAPIFixExecuteResult` objects |
- `uaclient.api.u.pro.security.fix.cve.execute.v1.CVEAPIFixExecuteResult`
| Field Name | Type | Description |
|--------------|--------------------------|--------------------------------------|
| `status` | `str` | The status of fixing the CVEs |
| `cves` | `List[FixExecuteResult]` | A list of `FixExecuteResult` objects |
- `uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteResult`
| Field Name | Type | Description |
|---------------------|-----------------------------------|-------------------------------------|
| `title` | `str` | The title of the CVE |
| `description` | `Optional[str]` | The description of the CVE |
| `status` | `str` | The status of fixing the CVE |
| `upgraded_packages` | `Optional[List[UpgradedPackage]]` | A list of `UpgradedPackage` objects |
| `errors` | `Optional[List[FixExecuteError]]` | A list of `FixExecuteError` objects |
- `uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage`
| Field Name | Type | Description |
|--------------|--------|------------------------------------------------|
| `name` | `str` | The name of the package |
| `version` | `str` | The version that the package was upgraded to |
| `pocket` | `str` | The pocket which contained the package upgrade |
- `uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteError`
| Field Name | Type | Description |
|-------------------|---------------------------------|-----------------------------------|
| `error_type` | `str` | The type of the error |
| `reason` | `str` | The reason why the error occurred |
| `failed_upgrades` | `Optional[List[FailedUpgrade]]` | A list of `FailedUpgrade` objects |
- `uaclient.api.u.pro.security.fix._common.execute.v1.FailedUpgrade`
| Field Name | Type | Description |
|--------------|-----------------|------------------------------------------------|
| `name` | `str` | The name of the package |
| `pocket` | `Optional[str]` | The pocket which contained the package upgrade |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.fix.cve.execute.v1 --data '{"cves": ["CVE-1234-1234", "CVE-1234-1235"]}'
```
**Expected attributes in JSON structure:**
```js
{
"cves_data": {
"status": "fixed",
"cves": [
{
"title": "CVE-1234-56789",
"description": "..."
"status": "fixed",
"upgraded_packages": {
"name": "pkg1",
"version": "1.1",
"pocket": "standard-updates"
},
"errors": []
}
]
}
}
```
### Explanation
When using the CVE endpoint, the expected output is as follows:
```json
{
"_schema_version": "v1",
"data": {
"attributes": {
"cves_data": {
"cves": [
{
"description": "description",
"errors": null,
"status": "fixed",
"title": "CVE-2021-27135",
"upgraded_packages": [
{
"name": "xterm",
"pocket": "standard-updates",
"version": "VERSION"
}
]
}
],
"status": "fixed"
}
},
"meta": {
"environment_vars": []
},
"type": "CVEFixExecute"
},
"errors": [],
"result": "success",
"version": "30",
"warnings": []
}
```
From this output, we can see that the **cves_data** object contains two
attributes:
* **cves**: A list of CVE objects detailing what happened during the fix
operation.
* **status**: The status of the fix operation considering **all** CVEs.
This means that if one CVE cannot be fixed, this field will reflect that.
If we take a look at a CVE object, we will see the following structure:
* **title**: The title of the CVE.
* **description**: The CVE description.
* **error**: Any error captured when fixing the CVE will appear here. The
error object will be detailed in a following section.
* **status**: The expected status of the CVE after the fix operation.
There are three possible scenarios: **fixed**, **still-affected** and
**not-affected**. The system is considered **still-affected** if there
is something that prevents any required packages from being upgraded.
The system is considered **not-affected** if the CVE doesn’t affect the
system at all.
* **upgraded_packages**: A list of UpgradedPackage objects referencing each
package that was upgraded during the fix operation. The UpgradedPackage
object always contain the **name** of the package, the **version** it was
upgraded to and the **pocket** where the package upgrade came from.
**What errors can be generated?**
There some errors that can happen when executing this endpoint. For
example, the system might require the user to attach to a Pro subscription
to install the upgrades, or the user might run the command as non-root
when a package upgrade is needed.
In those situations, the error JSON error object will follow this
representation:
```json
{
"error_type": "error-type",
"reason": "reason",
"failed_upgrades": [
{
"name": "pkg1",
"pocket": "esm-infra"
}
]
}
```
We can see that the representation has the following fields:
* **error_type**: The error type
* **reason**: The explanation of why the error happened
* **failed_upgrade**: A list of objects that always contain the name of the
package that was not upgraded and the pocket where the upgrade would have
come from.
## u.pro.security.fix.cve.plan.v1
This endpoint shows the necessary steps required to fix CVEs in the system
without executing any of those steps.
- Introduced in Ubuntu Pro Client Version: `29~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|--------------|-------------|-------------------------------------------|
| `cves` | `List[str]` | A list of CVE (i.e. CVE-2023-2650) titles |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.fix.cve.plan.v1 import plan, CVEFixPlanOptions
options = CVEFixPlanOptions(cves=["CVE-1234-1234", "CVE-1234-1235"])
result = plan(options)
```
**Expected return object:**
- `uaclient.api.u.pro.security.fix.cve.plan.v1.CVESFixPlanResult`
| Field Name | Type | Description |
|--------------|--------------------|--------------------------------------|
| `cves_data` | `CVEFixPlanResult` | A list of `CVEFixPlanResult` objects |
- `uaclient.api.u.pro.security.fix.cve.plan.v1.CVEFixPlanResult`
| Field Name | Type | Description |
|-------------------|-----------------------|----------------------------------------|
| `expected_status` | `str` | The expected status of fixing the CVEs |
| `cves` | `List[FixPlanResult]` | A list of `FixPlanResult` objects |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanResult`
| Field Name | Type | Description |
|---------------------|----------------------------------|------------------------------------------------|
| `title` | `str` | The title of the issue |
| `description` | `Optional[str]` | The description of the issue |
| `current_status` | `Optional[str]` | The current status of the issue on the system |
| `expected_status` | `str` | The expected status of fixing the issue |
| `affected_packages` | `Optional[List[str]]` | A list of package names affected by the issue |
| `plan` | `List[FixPlanStep]` | A list of `FixPlanStep` objects |
| `warnings` | `Optional[List[FixPlanWarning]]` | A list of `FixPlanWarning` objects |
| `error` | `Optional[FixPlanError]` | A `FixPlanError` object, if an error occurred. |
| `additional_data` | `Optional[AdditionalData]` | Additional data for the issue |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanStep`
| Field Name | Type | Description |
|--------------|--------------|---------------------------------------------------------------------------------------------------------------------------|
| `operation` | `str` | The operation that would be performed to fix the issue. This can be either an attach, enable, apt-upgrade or a no-op type |
| `order` | `int` | The execution order of the operation |
| `data` | `DataObject` | A data object that can be either an `AptUpgradeData`, `AttachData`, `EnableData`, `NoOpData` |
- `uaclient.data_types.DataObject`
- This object has no fields.
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanWarning`
| Field Name | Type | Description |
|----------------|--------------|--------------------------------------------------------------------------------------------------------|
| `warning_type` | `str` | The type of warning |
| `order` | `int` | The execution order of the operation |
| `data` | `DataObject` | A data object that represents either a `PackageCannotBeInstalledData` or a `SecurityIssueNotFixedData` |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanError`
| Field Name | Type | Description |
|--------------|-----------------|-------------------|
| `msg` | `str` | The error message |
| `code` | `Optional[str]` | The message code |
- `uaclient.api.u.pro.security.fix._common.plan.v1.AdditionalData`
- This object has no fields.
- `uaclient.api.u.pro.security.fix._common.plan.v1.AptUpgradeData`
| Field Name | Type | Description |
|-------------------|-------------|------------------------------------------------------|
| `binary_packages` | `List[str]` | A list of binary packages that need to be upgraded |
| `source_packages` | `List[str]` | A list of source packages that need to be upgraded |
| `pocket` | `str` | The pocket where the packages will be installed from |
- `uaclient.api.u.pro.security.fix._common.plan.v1.AttachData`
| Field Name | Type | Description |
|--------------------|-------------|---------------------------------------------------------|
| `reason` | `str` | The reason why an attach operation is needed |
| `required_service` | `str` | The required service that requires the attach operation |
| `source_packages` | `List[str]` | The source packages that require the attach operation |
- `uaclient.api.u.pro.security.fix._common.plan.v1.EnableData`
| Field Name | Type | Description |
|-------------------|-------------|------------------------------------------------------------|
| `service` | `str` | The service that needs to be enabled |
| `source_packages` | `List[str]` | The source packages that require the service to be enabled |
- `uaclient.api.u.pro.security.fix._common.plan.v1.NoOpData`
| Field Name | Type | Description |
|--------------|--------|------------------------------------------------------------|
| `status` | `str` | The status of the issue when no operation can be performed |
- `uaclient.api.u.pro.security.fix._common.plan.v1.NoOpAlreadyFixedData`
| Field Name | Type | Description |
|-------------------|-------------|--------------------------------------------------------------|
| `status` | `str` | The status of the issue when no operation can be performed |
| `source_packages` | `List[str]` | The source packages that are already fixed |
| `pocket` | `str` | The pocket where the packages would have been installed from |
- `uaclient.api.u.pro.security.fix._common.plan.v1.NoOpLivepatchFixData`
| Field Name | Type | Description |
|-----------------|--------|----------------------------------------------------------|
| `status` | `str` | The status of the CVE when no operation can be performed |
| `patch_version` | `str` | Version of the patch from Livepatch that fixed the CVE |
- `uaclient.api.u.pro.security.fix._common.plan.v1.PackageCannotBeInstalledData`
| Field Name | Type | Description |
|---------------------------|-------------|----------------------------------------------------------------------------------|
| `binary_package` | `str` | The binary package that cannot be installed |
| `binary_package_version` | `str` | The version of the binary package that cannot be installed |
| `source_package` | `str` | The source package associated with the binary package |
| `related_source_packages` | `List[str]` | A list of source packages that come from the same pocket as the affected package |
| `pocket` | `str` | The pocket where the affected package should be installed from |
- `uaclient.api.u.pro.security.fix._common.plan.v1.SecurityIssueNotFixedData`
| Field Name | Type | Description |
|-------------------|-------------|--------------------------------------------------------------|
| `source_packages` | `List[str]` | A list of source packages that cannot be fixed at the moment |
| `status` | `str` | The status of the CVE regarding those packages |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-56789", "CVE-1234-1235"]}'
```
**Expected attributes in JSON structure:**
```js
{
"cves_data": {
"expected_status": "fixed",
"cves": [
{
"title": "CVE-1234-56789",
"expected_status": "fixed",
"plan": [
{
"operation": "apt-upgrade",
"order": 1,
"data": {
"binary_packages": ["pkg1"],
"source_packages": ["pkg1"],
"pocket": "standard-updates",
}
}
],
"warnings": [],
"error": null,
"additional_data": {}
}
]
}
}
```
## u.pro.security.fix.usn.execute.v1
This endpoint fixes the specified USNs on the machine.
- Introduced in Ubuntu Pro Client Version: `30~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|--------------|-------------|-----------------------------------------|
| `usns` | `List[str]` | A list of USNs (i.e. USN-6188-1) titles |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.fix.usn.execute.v1 import execute, USNFixExecuteOptions
options = USNFixExecuteOptions(usns=["USN-1234-1", "USN-1235-1"])
result = execute(options)
```
**Expected return object:**
- `uaclient.api.u.pro.security.fix.usn.execute.v1.USNSAPIFixExecuteResult`
| Field Name | Type | Description |
|--------------|--------------------------|--------------------------------------------|
| `usns_data` | `USNAPIFixExecuteResult` | A list of `USNAPIFixExecuteResult` objects |
- `uaclient.api.u.pro.security.fix.usn.execute.v1.USNAPIFixExecuteResult`
| Field Name | Type | Description |
|--------------|-----------------------------|-----------------------------------------|
| `status` | `str` | The status of fixing the USNs |
| `usns` | `List[FixExecuteUSNResult]` | A list of `FixExecuteUSNResult` objects |
- `uaclient.api.u.pro.security.fix.usn.execute.v1.FixExecuteUSNResult`
| Field Name | Type | Description |
|----------------|------------------------------------|-----------------------------------------------------------|
| `target_usn` | `FixExecuteResult` | The `FixExecuteResult` for the target USN |
| `related_usns` | `Optional[List[FixExecuteResult]]` | A list of `FixExecuteResult` objects for the related USNs |
- `uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteResult`
| Field Name | Type | Description |
|---------------------|-----------------------------------|-------------------------------------|
| `title` | `str` | The title of the CVE |
| `description` | `Optional[str]` | The description of the CVE |
| `status` | `str` | The status of fixing the CVE |
| `upgraded_packages` | `Optional[List[UpgradedPackage]]` | A list of `UpgradedPackage` objects |
| `errors` | `Optional[List[FixExecuteError]]` | A list of `FixExecuteError` objects |
- `uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage`
| Field Name | Type | Description |
|--------------|--------|------------------------------------------------|
| `name` | `str` | The name of the package |
| `version` | `str` | The version that the package was upgraded to |
| `pocket` | `str` | The pocket which contained the package upgrade |
- `uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteError`
| Field Name | Type | Description |
|-------------------|---------------------------------|-----------------------------------|
| `error_type` | `str` | The type of the error |
| `reason` | `str` | The reason why the error occurred |
| `failed_upgrades` | `Optional[List[FailedUpgrade]]` | A list of `FailedUpgrade` objects |
- `uaclient.api.u.pro.security.fix._common.execute.v1.FailedUpgrade`
| Field Name | Type | Description |
|--------------|-----------------|------------------------------------------------|
| `name` | `str` | The name of the package |
| `pocket` | `Optional[str]` | The pocket which contained the package upgrade |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.fix.usn.execute.v1 --data '{"usns": ["USN-1234-1", "USN-1235-1"]}'
```
**Expected attributes in JSON structure:**
```js
{
"usns_data": {
"status": "fixed",
"usns": [
{
"target_usn": {
"title": "CVE-1234-56789",
"status": "fixed",
"upgraded_packages": {
"name": "pkg1",
"version": "1.1",
"pocket": "standard-updates"
},
"error": null
},
"related_usns": []
}
]
}
}
```
### Explanation
When using the USN endpoint, the expected output is as follows:
```json
{
"usns_data": {
"status": "fixed",
"usns": [
{
"target_usn": {
"title": "CVE-1234-56789",
"status": "fixed",
"upgraded_packages": {
"name": "pkg1",
"version": "1.1",
"pocket": "standard-updates"
},
"error": null
},
"related_usns": []
}
]
}
}
```
From this output, we can see that the **usns_data** object contains two
attributes:
* **usns**: A list of USN objects detailing what happened during the fix
operation.
* **status**: The status of the fix operation considering **all** USNs.
This means that if one USN cannot be fixed, this field will reflect that.
Note that related USNs don’t interfere with this attribute, meaning that
a related USN can fail to be fixed without modifying the **status**
value.
Each **usn** object contains a reference for both **target_usn** and
**related_usns**. The target is the USN requested to be fixed by the user,
while related USNs are USNs that are related to the main USN and an
attempt to fix them will be performed by the endpoint too. To better
understand that distinction, please refer to
[our explanation of CVEs and USNs](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn).
With that said both **target_usn** object and any object from
**related_usns** follow this structure:
* **title**: The title of the USN.
* **description**: The USN description.
* **error**: Any error captured when fixing the USN will appear here. The
error object will be detailed in a following section.
* **status**: The expected status of the USN after the fix operation.
There are three possible scenarios: **fixed**, **still-affected** and
**not-affected**. The system is considered **still-affected** if there
is something that prevents any required packages from being upgraded.
The system is considered **not-affected** if the USN doesn’t affect the
system at all.
* **upgraded_packages**: A list of UpgradedPackage objects referencing each
package that was upgraded during the fix operation. The UpgradedPackage
object always contain the **name** of the package, the **version** it was
upgraded to and the **pocket** where the package upgrade came from.
**What errors can be generated?**
There some errors that can happen when executing this endpoint. For
example, the system might require the user to attach to a Pro subscription
to install the upgrades, or the user might run the command as non-root
when a package upgrade is needed.
In those situations, the error JSON error object will follow this
representation:
```json
{
"error_type": "error-type",
"reason": "reason",
"failed_upgrades": [
{
"name": "pkg1",
"pocket": "esm-infra"
}
]
}
```
We can see that the representation has the following fields:
* **error_type**: The error type
* **reason**: The explanation of why the error happened
* **failed_upgrade**: A list of objects that always contain the name of the
package that was not upgraded and the pocket where the upgrade would have
come from.
## u.pro.security.fix.usn.plan.v1
This endpoint shows the necessary steps required to fix USNs in the system
without executing any of those steps.
- Introduced in Ubuntu Pro Client Version: `29~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|--------------|-------------|-----------------------------------------|
| `usns` | `List[str]` | A list of USNs (i.e. USN-6119-1) titles |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.fix.usn.plan.v1 import plan, USNFixPlanOptions
options = USNFixPlanOptions(cves=["USN-1234-1", "USN-1235-1"])
result = plan(options)
```
**Expected return object:**
- `uaclient.api.u.pro.security.fix.usn.plan.v1.USNSFixPlanResult`
| Field Name | Type | Description |
|--------------|--------------------|--------------------------------------|
| `usns_data` | `USNFixPlanResult` | A list of `USNFixPlanResult` objects |
- `uaclient.api.u.pro.security.fix.usn.plan.v1.USNFixPlanResult`
| Field Name | Type | Description |
|-------------------|--------------------------|----------------------------------------|
| `expected_status` | `str` | The expected status of fixing the USNs |
| `usns` | `List[FixPlanUSNResult]` | A list of `FixPlanUSNResult` objects |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanUSNResult`
| Field Name | Type | Description |
|---------------------|---------------------------------|--------------------------------------------------------|
| `target_usn_plan` | `FixPlanResult` | A `FixPlanResult` object for the target USN |
| `related_usns_plan` | `Optional[List[FixPlanResult]]` | A list of `FixPlanResult` objects for the related USNs |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanResult`
| Field Name | Type | Description |
|---------------------|----------------------------------|------------------------------------------------|
| `title` | `str` | The title of the issue |
| `description` | `Optional[str]` | The description of the issue |
| `current_status` | `Optional[str]` | The current status of the issue on the system |
| `expected_status` | `str` | The expected status of fixing the issue |
| `affected_packages` | `Optional[List[str]]` | A list of package names affected by the issue |
| `plan` | `List[FixPlanStep]` | A list of `FixPlanStep` objects |
| `warnings` | `Optional[List[FixPlanWarning]]` | A list of `FixPlanWarning` objects |
| `error` | `Optional[FixPlanError]` | A `FixPlanError` object, if an error occurred. |
| `additional_data` | `Optional[AdditionalData]` | Additional data for the issue |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanStep`
| Field Name | Type | Description |
|--------------|--------------|---------------------------------------------------------------------------------------------------------------------------|
| `operation` | `str` | The operation that would be performed to fix the issue. This can be either an attach, enable, apt-upgrade or a no-op type |
| `order` | `int` | The execution order of the operation |
| `data` | `DataObject` | A data object that can be either an `AptUpgradeData`, `AttachData`, `EnableData`, `NoOpData` |
- `uaclient.data_types.DataObject`
- This object has no fields.
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanWarning`
| Field Name | Type | Description |
|----------------|--------------|--------------------------------------------------------------------------------------------------------|
| `warning_type` | `str` | The type of warning |
| `order` | `int` | The execution order of the operation |
| `data` | `DataObject` | A data object that represents either a `PackageCannotBeInstalledData` or a `SecurityIssueNotFixedData` |
- `uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanError`
| Field Name | Type | Description |
|--------------|-----------------|-------------------|
| `msg` | `str` | The error message |
| `code` | `Optional[str]` | The message code |
- `uaclient.api.u.pro.security.fix._common.plan.v1.AdditionalData`
- This object has no fields.
- `uaclient.api.u.pro.security.fix._common.plan.v1.USNAdditionalData`
| Field Name | Type | Description |
|-----------------------------|-------------|-------------------------------------------|
| `associated_cves` | `List[str]` | The associated CVEs for the USN |
| `associated_launchpad_bugs` | `List[str]` | The associated Launchpad bugs for the USN |
- `uaclient.api.u.pro.security.fix._common.plan.v1.AptUpgradeData`
| Field Name | Type | Description |
|-------------------|-------------|------------------------------------------------------|
| `binary_packages` | `List[str]` | A list of binary packages that need to be upgraded |
| `source_packages` | `List[str]` | A list of source packages that need to be upgraded |
| `pocket` | `str` | The pocket where the packages will be installed from |
- `uaclient.api.u.pro.security.fix._common.plan.v1.AttachData`
| Field Name | Type | Description |
|--------------------|-------------|---------------------------------------------------------|
| `reason` | `str` | The reason why an attach operation is needed |
| `required_service` | `str` | The required service that requires the attach operation |
| `source_packages` | `List[str]` | The source packages that require the attach operation |
- `uaclient.api.u.pro.security.fix._common.plan.v1.EnableData`
| Field Name | Type | Description |
|-------------------|-------------|------------------------------------------------------------|
| `service` | `str` | The service that needs to be enabled |
| `source_packages` | `List[str]` | The source packages that require the service to be enabled |
- `uaclient.api.u.pro.security.fix._common.plan.v1.NoOpData`
| Field Name | Type | Description |
|--------------|--------|------------------------------------------------------------|
| `status` | `str` | The status of the issue when no operation can be performed |
- `uaclient.api.u.pro.security.fix._common.plan.v1.NoOpAlreadyFixedData`
| Field Name | Type | Description |
|-------------------|-------------|--------------------------------------------------------------|
| `status` | `str` | The status of the issue when no operation can be performed |
| `source_packages` | `List[str]` | The source packages that are already fixed |
| `pocket` | `str` | The pocket where the packages would have been installed from |
- `uaclient.api.u.pro.security.fix._common.plan.v1.PackageCannotBeInstalledData`
| Field Name | Type | Description |
|---------------------------|-------------|----------------------------------------------------------------------------------|
| `binary_package` | `str` | The binary package that cannot be installed |
| `binary_package_version` | `str` | The version of the binary package that cannot be installed |
| `source_package` | `str` | The source package associated with the binary package |
| `related_source_packages` | `List[str]` | A list of source packages that come from the same pocket as the affected package |
| `pocket` | `str` | The pocket where the affected package should be installed from |
- `uaclient.api.u.pro.security.fix._common.plan.v1.SecurityIssueNotFixedData`
| Field Name | Type | Description |
|-------------------|-------------|--------------------------------------------------------------|
| `source_packages` | `List[str]` | A list of source packages that cannot be fixed at the moment |
| `status` | `str` | The status of the CVE regarding those packages |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.fix.usn.plan.v1 --data '{"usns": ["USN-1234-1", "USN-1235-1"]}'
```
**Expected attributes in JSON structure:**
```js
{
"usns_data": {
"expected_status": "fixed",
"usns": [
{
"related_usns_plan": [],
"target_usn_plan": {
"title": "USN-1234-5",
"expected_status": "fixed",
"plan": [
{
"operation": "apt-upgrade",
"order": 1,
"data": {
"binary_packages": ["pkg1"],
"source_packages": ["pkg1"],
"pocket": "standard-updates"
}
}
],
"warnings": [],
"error": null,
"additional_data": {
"associated_cves": [
"CVE-1234-56789"
],
"associated_launchpad_bus": [
"https://launchpad.net/bugs/BUG_ID"
]
}
},
}
]
}
}
```
## u.pro.security.status.livepatch_cves.v1
This endpoint lists Livepatch patches for the currently-running kernel.
- Introduced in Ubuntu Pro Client Version: `27.12~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.status.livepatch_cves.v1 import livepatch_cves
result = livepatch_cves()
```
**Expected return object:**
- `uaclient.api.u.pro.security.status.livepatch_cves.v1.LivepatchCVEsResult`
| Field Name | Type | Description |
|--------------|----------------------------|------------------------------------------------|
| `fixed_cves` | `List[LivepatchCVEObject]` | List of Livepatch patches for the given system |
- `uaclient.api.u.pro.security.status.livepatch_cves.v1.LivepatchCVEObject`
| Field Name | Type | Description |
|--------------|--------|-------------------------------|
| `name` | `str` | Name (ID) of the CVE |
| `patched` | `bool` | Livepatch has patched the CVE |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.status.livepatch_cves.v1
```
**Expected attributes in JSON structure:**
```js
{
"fixed_cves":[
{
"name": "",
"patched": true
},
{
"name": "",
"patched": false
},
]
}
```
## u.pro.security.status.reboot_required.v1
This endpoint informs if the system should be rebooted or not. Possible
outputs are:
1. `yes`: The system should be rebooted.
2. `no`: There is no known need to reboot the system.
3. `yes-kernel-livepatches-applied`: There are Livepatch patches applied
to the current kernel, but a reboot is required for an update to take
place. This reboot can wait until the next maintenance window.
- Introduced in Ubuntu Pro Client Version: `27.12~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.security.status.reboot_required.v1 import reboot_required
result = reboot_required()
```
**Expected return object:**
- `uaclient.api.u.pro.security.status.reboot_required.v1.RebootRequiredResult`
| Field Name | Type | Description |
|----------------------------------------|----------------------|------------------------------------------------------------|
| `reboot_required` | `str` | Either ‘yes’, ‘no’, or ‘yes-kernel-livepatches-applied’ |
| `reboot_required_packages` | `RebootRequiredPkgs` | The packages that require a reboot |
| `livepatch_enabled_and_kernel_patched` | `bool` | True if livepatch is enabled and working |
| `livepatch_enabled` | `bool` | True if livepatch is enabled |
| `livepatch_state` | `Optional[str]` | The state of livepatch as reported by the livepatch client |
| `livepatch_support` | `Optional[str]` | Whether livepatch covers the current kernel |
- `uaclient.api.u.pro.security.status.reboot_required.v1.RebootRequiredPkgs`
| Field Name | Type | Description |
|---------------------|-----------------------|-------------------------------------------|
| `standard_packages` | `Optional[List[str]]` | Non-kernel packages that require a reboot |
| `kernel_packages` | `Optional[List[str]]` | Kernel packages that require a reboot |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.security.status.reboot_required.v1
```
**Expected attributes in JSON structure:**
```js
{
"reboot_required": "yes|no|yes-kernel-livepatches-applied"
}
```
## u.pro.services.dependencies.v1
This endpoint will return a full list of all service dependencies,
regardless of the current system state. That means it will always return
the same thing until new services are added, or until we add/remove
dependencies between services.
- Introduced in Ubuntu Pro Client Version: `32~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.services.dependencies.v1 import dependencies
result = dependencies()
```
**Expected return object:**
- `uaclient.api.u.pro.services.dependencies.v1.DependenciesResult`
| Field Name | Type | Description |
|--------------|---------------------------------|--------------------------------------------|
| `services` | `List[ServiceWithDependencies]` | Each Pro service gets an item in this list |
- `uaclient.api.u.pro.services.dependencies.v1.ServiceWithDependencies`
| Field Name | Type | Description |
|---------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------|
| `name` | `str` | Name of the Pro service this item corresponds to |
| `incompatible_with` | `List[ServiceWithReason]` | List of Pro services this service is incompatible with. That means they cannot be enabled at the same time. |
| `depends_on` | `List[ServiceWithReason]` | List of Pro services this service depends on. The services in this list must be enabled for this service to be enabled. |
- `uaclient.api.u.pro.services.dependencies.v1.ServiceWithReason`
| Field Name | Type | Description |
|--------------|----------|--------------------------------------------------|
| `name` | `str` | Name of the Pro service this item corresponds to |
| `reason` | `Reason` | Reason that this service is in the list it is in |
- `uaclient.api.u.pro.services.dependencies.v1.Reason`
| Field Name | Type | Description |
|--------------|--------|-----------------------------------------------------------|
| `code` | `str` | Short string that represents the reason |
| `title` | `str` | Longer string describing the reason - possibly translated |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.services.dependencies.v1
```
**Expected attributes in JSON structure:**
```js
{
"services": [
{
"name": "one",
"depends_on": [
{
"name": "zero",
"reason": {
"code": "one-and-zero",
"title": "Service One requires service Zero."
}
},
...
],
"incompatible_with": [
{
"name": "two",
"reason": {
"code": "one-and-two",
"title": "Services One and Two are not compatible."
}
},
...
]
},
...
]
}
```
## u.pro.services.disable.v1
Disable a Pro service. This will automatically disable any services that
depend on the target service.
- Introduced in Ubuntu Pro Client Version: `32~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|--------------|------------------|-------------------------------------------------------------------------------------------------------------------|
| `service` | `str` | Pro service to disable |
| `purge` | `Optional[bool]` | Also remove all packages that were installed from this service. Only supported by some services. (default: false) |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.services.disable.v1 import disable, DisableOptions
result = disable(DisableOptions(service="usg"))
```
**Expected return object:**
- `uaclient.api.u.pro.services.disable.v1.DisableResult`
| Field Name | Type | Description |
|--------------|-------------|---------------------------|
| `disabled` | `List[str]` | List of services disabled |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `NonRootUserError`: When called as non-root user
- `UnattachedError`: When called on a machine that is not attached to a Pro subscription
- `EntitlementNotFoundError`: When the service argument is not a valid Pro service name
- `LockHeldError`: When another Ubuntu Pro related operation is in progress
- `EntitlementNotDisabledError`: When the service fails to disable
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.services.disable.v1 --args service=usg
```
**Expected attributes in JSON structure:**
```js
{
"disabled": [
"usg"
]
}
```
## u.pro.services.enable.v1
Enable a Pro service. This will automatically disable incompatible services
and enable required services that that target service depends on.
- Introduced in Ubuntu Pro Client Version: `32~`
- Requires network access: Yes
Arguments:
| Field Name | Type | Description |
|---------------|------------------|------------------------------------------------------------------------------------------------|
| `service` | `str` | Pro service to be enabled |
| `variant` | `Optional[str]` | Optional variant of the Pro service to be enabled. |
| `access_only` | `Optional[bool]` | If true and the target service supports it, only enable access to the service (default: false) |
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.services.enable.v1 import enable, EnableOptions
result = enable(EnableOptions(service="usg"))
```
**Expected return object:**
- `uaclient.api.u.pro.services.enable.v1.EnableResult`
| Field Name | Type | Description |
|-------------------|-------------|---------------------------------------------------------------------------------------------------|
| `enabled` | `List[str]` | List of services that were enabled. |
| `disabled` | `List[str]` | List of services that were disabled. |
| `reboot_required` | `bool` | True if one of the services that was enabled requires a reboot. |
| `messages` | `List[str]` | List of information message strings about the service that was just enabled. Possibly translated. |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `NonRootUserError`: When called as non-root user
- `UnattachedError`: When called on a machine that is not attached to a Pro subscription
- `NotSupported`: When called for a service that doesn’t support being enabled via API (currently only Landscape)
- `EntitlementNotFoundError`: When the service argument is not a valid Pro service name or if the variant is not a valid variant of the target service
- `LockHeldError`: When another Ubuntu Pro related operation is in progress
- `EntitlementNotEnabledError`: When the service fails to enable
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.services.enable.v1 --args service=usg
```
**Expected attributes in JSON structure:**
```js
{
"disabled": [],
"enabled": [
"usg"
],
"messages": [],
"reboot_required": false
}
```
## u.pro.status.enabled_services.v1
This endpoint shows the Pro services that are enabled on the machine.
- Introduced in Ubuntu Pro Client Version: `28~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.status.enabled_services.v1 import enabled_services
result = enabled_services()
```
**Expected return object:**
- `uaclient.api.u.pro.status.enabled_services.v1.EnabledServicesResult`
| Field Name | Type | Description |
|--------------------|------------------------|------------------------------------|
| `enabled_services` | `List[EnabledService]` | A list of `EnabledService` objects |
- `uaclient.api.u.pro.status.enabled_services.v1.EnabledService`
| Field Name | Type | Description |
|-------------------|-----------------|----------------------------------------------|
| `name` | `str` | Name of the service |
| `variant_enabled` | `bool` | If a variant of the service is enabled |
| `variant_name` | `Optional[str]` | Name of the variant, if a variant is enabled |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.status.enabled_services.v1
```
**Expected attributes in JSON structure:**
```js
{
"enabled_services": [
{
"name": "esm-apps",
"variant_enabled": false,
"variant_name": null
},
{
"name": "esm-infra",
"variant_enabled": false,
"variant_name": null
},
{
"name": "realtime-kernel",
"variant_enabled": true,
"variant_name": "raspi"
}
]
}
```
## u.pro.status.is_attached.v1
This endpoint shows if the machine is attached to a Pro subscription.
- Introduced in Ubuntu Pro Client Version: `28~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.pro.status.is_attached.v1 import is_attached
result = is_attached()
```
**Expected return object:**
- `uaclient.api.u.pro.status.is_attached.v1.IsAttachedResult`
| Field Name | Type | Description |
|----------------------------------|-----------------|----------------------------------------------------------------------------------------------------|
| `is_attached` | `bool` | True if the machine is attached to an Ubuntu Pro subscription |
| `contract_status` | `Optional[str]` | Status of the Ubuntu Pro subscription |
| `contract_remaining_days` | `int` | Number of days left in the Ubuntu Pro subscription |
| `is_attached_and_contract_valid` | `bool` | True if the machine is attached to an Ubuntu Pro subscription and that subscription is not expired |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.pro.status.is_attached.v1
```
**Expected attributes in JSON structure:**
```js
{
"contract_remaining_days": 360,
"contract_status": "active",
"is_attached": true,
"is_attached_and_contract_valid": true
}
```
### Explanation
The `contract_status` field can return 4 different states, they are:
* **active**: The contract is currently valid.
* **grace-period**: The contract is in the grace period. This means that
it is expired, but there are still some days where the contract will be
valid.
* **active-soon-to-expire**: The contract is almost expired, but still
valid.
* **expired**: The contract is expired and no longer valid.
## u.apt_news.current_news.v1
This endpoint returns the current APT News that gets displayed in
apt upgrade.
- Introduced in Ubuntu Pro Client Version: `29~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.apt_news.current_news.v1 import current_news
result = current_news().current_news
```
**Expected return object:**
- `uaclient.api.u.apt_news.current_news.v1.CurrentNewsResult`
| Field Name | Type | Description |
|----------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `current_news` | `Optional[str]` | The current APT News to be displayed for the system. This could be a str with up to three lines (i.e. up to two `\n` characters). If there is no APT News to be displayed, this will be `None`. |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.apt_news.current_news.v1
```
**Expected attributes in JSON structure:**
```js
{
"current_news":"This is a news message.\nThis is the second line of the message.\nAnd this is the third line."
}
```
## u.security.package_manifest.v1
This endpoint returns the status of installed packages (`apt` and
`snap`), formatted as a manifest file (i.e., `package_name\tversion`).
- Introduced in Ubuntu Pro Client Version: `27.12~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.security.package_manifest.v1 import package_manifest
result = package_manifest()
```
**Expected return object:**
- `uaclient.api.u.security.package_manifest.v1.PackageManifestResult`
| Field Name | Type | Description |
|-----------------|--------|---------------------------------------------------------------|
| `manifest_data` | `str` | Manifest of `apt` and `snap` packages installed on the system |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.security.package_manifest.v1
```
**Expected attributes in JSON structure:**
```js
{
"package_manifest":"package1\t1.0\npackage2\t2.3\n"
}
```
## u.unattended_upgrades.status.v1
This endpoint returns the status around `unattended-upgrades`. The focus
of the endpoint is to verify if the application is running and how it is
configured on the machine.
#### IMPORTANT
For this endpoint, we deliver a unique key under `meta` called
`raw_config`. This field contains all related `unattended-upgrades`
configurations, unparsed. This means that this field will maintain both
original name and values for those configurations.
- Introduced in Ubuntu Pro Client Version: `27.14~`
- Requires network access: No
Arguments:
- This endpoint takes no arguments.
### Python API interaction
**Calling from Python code:**
```python
from uaclient.api.u.unattended_upgrades.status.v1 import status
result = status()
```
**Expected return object:**
- `uaclient.api.u.unattended_upgrades.status.v1.UnattendedUpgradesStatusResult`
| Field Name | Type | Description |
|----------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `systemd_apt_timer_enabled` | `bool` | Indicate if the `apt-daily.timer` jobs are enabled |
| `apt_periodic_job_enabled` | `bool` | Indicate if the `APT::Periodic::Enabled` configuration is turned off |
| `package_lists_refresh_frequency_days` | `int` | The value of the `APT::Periodic::Update-Package-Lists` configuration |
| `unattended_upgrades_frequency_days` | `int` | The value of the `APT::Periodic::Unattended-Upgrade` configuration |
| `unattended_upgrades_allowed_origins` | `List[str]` | The value of the `Unattended-Upgrade::Allowed-Origins` configuration |
| `unattended_upgrades_running` | `bool` | Indicate if the `unattended-upgrade` service is correctly configured and running |
| `unattended_upgrades_disabled_reason` | `Optional[UnattendedUpgradesDisabledReason]` | Object that explains why `unattended-upgrades` is not running – if the application is running, the object will be null |
| `unattended_upgrades_last_run` | `Optional[datetime]` | The last time `unattended-upgrades` ran |
- `uaclient.api.u.unattended_upgrades.status.v1.UnattendedUpgradesDisabledReason`
| Field Name | Type | Description |
|--------------|--------|-----------------------|
| `msg` | `str` | Human readable reason |
| `code` | `str` | Reason code |
**Raised exceptions:**
- `UbuntuProError`: `UbuntuProError` is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from `UbuntuProError`, please report a bug).
- `UnattendedUpgradesError`: Raised if we cannot run a necessary command to show the status of `unattended-upgrades`
### CLI interaction
**Calling from the CLI:**
```bash
pro api u.unattended_upgrades.status.v1
```
**Expected attributes in JSON structure:**
```js
{
"apt_periodic_job_enabled": true,
"package_lists_refresh_frequency_days": 1,
"systemd_apt_timer_enabled": true,
"unattended_upgrades_allowed_origins": [
"${distro_id}:${distro_codename}",
"${distro_id}:${distro_codename}-security",
"${distro_id}ESMApps:${distro_codename}-apps-security",
"${distro_id}ESM:${distro_codename}-infra-security"
],
"unattended_upgrades_disabled_reason": null,
"unattended_upgrades_frequency_days": 1,
"unattended_upgrades_last_run": null,
"unattended_upgrades_running": true
}
```
- Possible attributes in JSON `meta` field:
```json
{
"meta": {
"environment_vars": [],
"raw_config": {
"APT::Periodic::Enable": "1",
"APT::Periodic::Unattended-Upgrade": "1",
"APT::Periodic::Update-Package-Lists": "1",
"Unattended-Upgrade::Allowed-Origins": [
"${distro_id}:${distro_codename}",
"${distro_id}:${distro_codename}-security",
"${distro_id}ESMApps:${distro_codename}-apps-security",
"${distro_id}ESM:${distro_codename}-infra-security"
]
}
}
}
```
# index.html.md
# The Ubuntu Pro CLI reference guide
This is a list of the commands and subcommands available in the Pro Client.
## Available commands
The currently available commands are:
- [pro api]()
- [pro attach]()
- [pro auto-attach]()
- [pro collect-logs]()
- [pro cve]()
- [pro cves]()
- [pro config]()
- [pro detach]()
- [pro disable]()
- [pro enable]()
- [pro fix]()
- [pro help]()
- [pro refresh]()
- [pro security-status]()
- [pro status]()
- [pro system]()
## pro api
**Usage:**
`pro api [-h] [--show-progress] [--args [OPTIONS ...]] [--data DATA] endpoint`
**Description:**
Calls the Client API endpoints.
For a list of all of the supported endpoints and their structure,
please refer to the Pro Client API reference guide:
[https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/)
## pro attach
**Usage:**
`pro attach [-h] [--no-auto-enable] [--attach-config ATTACH_CONFIG] [--format {cli,json}] [token]`
**Description:**
Attach this machine to an Ubuntu Pro subscription with a token obtained from:
[https://ubuntu.com/pro/dashboard](https://ubuntu.com/pro/dashboard)
When running this command without a token, it will generate a short code
and prompt you to attach the machine to your Ubuntu Pro account using
a web browser.
The “attach-config” option can be used to provide a file with the token
and optionally, a list of services to enable after attaching. To know more,
visit:
[https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/how_to_attach_with_config_file/](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/how_to_attach_with_config_file/)
The exit code will be:
> * 0: on successful attach
> * 1: in case of any error while trying to attach
> * 2: if the machine is already attached
## pro auto-attach
**Usage:**
`pro auto-attach [-h]`
**Description:**
Automatically attach on an Ubuntu Pro cloud instance.
## pro collect-logs
**Usage:**
`pro collect-logs [-h] [-o OUTPUT]`
**Description:**
Collect logs and relevant system information into a tarball.
This information can be later used for triaging/debugging issues.
## pro cve
**Usage:**
`pro cve [-h] cve`
**Description:**
Show all available information about a given CVE.
## pro cves
**Usage:**
`pro cves [-h] [--unfixable] [--fixable]`
**Description:**
List the CVE vulnerabilities that affects the system.
## pro config
**Usage:**
`pro config [-h] {show,set,unset} ...`
**Description:**
Manage Ubuntu Pro Client configuration on this machine.
### pro config show
**Usage:**
`pro config show [-h] [key]`
**Description:**
Show customizable configuration settings.
### pro config set
**Usage:**
`pro config set [-h] key_value_pair`
**Description:**
Set and apply Ubuntu Pro configuration settings.
### pro config unset
**Usage:**
`pro config unset [-h] key`
**Description:**
Unset an Ubuntu Pro configuration setting, restoring the default value.
## pro detach
**Usage:**
`pro detach [-h] [--assume-yes] [--format {cli,json}]`
**Description:**
Detach this machine from an Ubuntu Pro subscription.
## pro disable
**Usage:**
`pro disable [-h] [--assume-yes] [--format {cli,json}] [--purge] service [service ...]`
**Description:**
Disable one or more Ubuntu Pro services.
## pro enable
**Usage:**
`pro enable [-h] [--access-only] [--assume-yes] [--auto] [--beta] [--format {cli,json}] [--variant VARIANT] [service ...]`
**Description:**
Activate and configure this machine’s access to one or more Ubuntu Pro services.
## pro fix
**Usage:**
`pro fix [-h] [--dry-run] [--no-related] security_issue`
**Description:**
Inspect and resolve Common Vulnerabilities and Exposures (CVEs) and
Ubuntu Security Notices (USNs) on this machine.
The exit code will be:
> * 0: the fix was successfully applied or the system is not affected
> * 1: the fix cannot be applied
> * 2: the fix was applied but requires a reboot before it takes effect
## pro help
**Usage:**
`pro help [-h] [--format {tabular,json,yaml}] [--all] [service]`
**Description:**
Provide detailed information about Ubuntu Pro services.
## pro refresh
**Usage:**
`pro refresh [-h] [{contract,config,messages}]`
**Description:**
Refresh three distinct Ubuntu Pro related artifacts in the system:
> * contract: Update contract details from the server.
> * config: Reload the config file.
> * messages: Update APT and MOTD messages related to Pro.
You can individually target any of the three specific actions,
by passing the target name to the command. If no target
is specified, all targets are refreshed.
## pro security-status
**Usage:**
`pro security-status [-h] [--format {json,yaml,text}] [--thirdparty | --unavailable | --esm-infra | --esm-apps]`
**Description:**
Show security updates for packages in the system, including all
available Expanded Security Maintenance (ESM) related content.
Shows counts of how many packages are supported for security updates
in the system.
If the format is set to JSON or YAML it shows a summary of the
installed packages based on the origin:
> - main/restricted/universe/multiverse: Packages from the Ubuntu archive.
> - esm-infra/esm-apps: Packages from the ESM archive.
> - third-party: Packages installed from non-Ubuntu sources.
> - unknown: Packages which don’t have an installation source (like local
> deb packages or packages for which the source was removed).
The output contains basic information about Ubuntu Pro. For a
complete status on Ubuntu Pro services, run ‘pro status’.
## pro status
**Usage:**
`pro status [-h] [--wait] [--format {tabular,json,yaml}] [--simulate-with-token TOKEN] [--all]`
**Description:**
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:
> * 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. Possible
> values are: enabled, disabled, n/a (if your contract entitles
> 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
columns. 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.
## pro system
**Usage:**
`pro system [-h] {reboot-required} ...`
**Description:**
Output system-related information about Pro services.
### pro system reboot-required
**Usage:**
`pro system reboot-required [-h]`
**Description:**
Report the current reboot-required status for the machine.
This command will output one of the three following states
for the machine regarding reboot:
> * no: The machine doesn’t require a reboot.
> * yes: The machine requires a reboot.
> * yes-kernel-livepatches-applied: There are only kernel-related
> packages that require a reboot, but Livepatch has already provided
> patches for the current running kernel. The machine still needs a
> reboot, but you can assess if the reboot can be performed in the
> nearest maintenance window.
# index.html.md
# Ubuntu Pro Client network requirements
The Ubuntu Pro Client (`pro`) and Ubuntu Pro services need to make network
requests to certain services to function correctly.
#### NOTE
You can also refer to our
[proxy configuration guide](https://ubuntu.com/pro-client/docs/latest/howtoguides/configure_proxies.md#configure-proxies) to learn how to
inform Ubuntu Pro Client of HTTP(S)/APT proxies.
## Authentication
`pro` needs to authenticate with Canonical servers to provision the
credentials that will grant access to the individual Ubuntu Pro services.
Necessary endpoints:
- `contracts.canonical.com:443`
## APT package-based services
Many services are delivered via authenticated APT repositories. These include:
- `esm-infra` and `esm-apps`
- `esm-infra-legacy` and `esm-apps-legacy`
- `fips` and `fips-updates`
- `cis` and `usg`
- `cc-eal`
- `ros` and `ros-updates`
- `realtime-kernel`
Necessary endpoints:
- `esm.ubuntu.com:443`
## Livepatch
`livepatch` requires a snap-packaged client, so snap-related endpoints are
necessary. The Livepatch client itself also requires network access to download
the patches from the Livepatch server.
#### NOTE
The [snap documentation page](https://snapcraft.io/docs/network-requirements) may have more up-to-date information on
snap-related network requirements.
Necessary endpoints for `snap`
- `api.snapcraft.io:443`
- `dashboard.snapcraft.io:443`
- `login.ubuntu.com:443`
- `*.snapcraftcontent.com:443`
Necessary endpoints for `livepatch`:
- `livepatch.canonical.com:443`
- `livepatch-files.canonical.com:443`
## Fix
`pro fix` needs to fetch information about USNs and/or CVEs from the Ubuntu
Security APIs.
Necessary endpoints:
- `ubuntu.com/security:443`
# index.html.md
# Ubuntu Pro Client PPAs
There are two Personal Package Archives (PPAs) with different release
channels in the Ubuntu Pro Client: **Staging**, and **Daily**.
## Staging
This contains builds **under validation** for release to stable Ubuntu releases
and images. You can add it with:
```bash
sudo add-apt-repository ppa:ua-client/staging
```
## Daily
This PPA is updated every day with the latest changes. You can add it with:
```bash
sudo add-apt-repository ppa:ua-client/daily
```
# index.html.md
# Exploring your system’s security with Pro
Whether you’re running the latest Ubuntu LTS release, or a release at the end
of its standard support period, you are probably curious about the security
services that Ubuntu Pro provides.
In this tutorial, we will set up a virtual machine (VM) and use it to explore
some of the security-related services and commands available to all users, and
see how they can be used to keep your system safer and more secure.
## Install Multipass
To avoid making any modifications to your live system during the tutorial, we
will set up a virtual machine using [Multipass](https://multipass.run/). We are using Multipass
because it allows us to launch VMs without needing any complicated setup. To
install Multipass on your system, run the following command on your machine:
```bash
$ sudo snap install multipass
```
## Use Multipass to create a VM
We’re going to create our VM using the Ubuntu 18.04 LTS (Bionic Beaver). It is
the most recent LTS to reach the end of its standard support period (as of the
time of writing), so it has updates available through the Ubuntu Pro Expanded
Security Maintenance (ESM) services.
Let’s start by creating our VM by running the following command:
```bash
$ multipass launch bionic --name test-vm
```
This command will create (`launch`) a Bionic VM that we will label with the
name “`test-vm`”.
It will probably take a few minutes to fetch the Bionic image (depending on
your internet speed). Once Multipass has successfully set up the VM, you will
see a message like this in your terminal:
```text
Launched: test-vm
```
We can now enter our new VM with this command:
```bash
$ multipass shell test-vm
```
Notice that when we run this command, our terminal username and hostname
change to `ubuntu@test-vm`, which tells us we are now operating inside the
VM.
We then see a welcome message that looks similar to this (throughout this
tutorial, we will truncate the output for brevity – removed sections will be
indicated with `[...]`):
```text
Welcome to Ubuntu 18.04.6 LTS (GNU/Linux 4.15.0-212-generic x86_64)
[...]
System information as of Wed Jun 19 14:17:26 BST 2024
[...]
Expanded Security Maintenance for Infrastructure is not enabled.
16 updates can be applied immediately.
11 of these updates are standard security updates.
To see these additional updates run: apt list --upgradable
109 additional security updates can be applied with ESM Infra.
Learn more about enabling ESM Infra service for Ubuntu 18.04 at
https://ubuntu.com/18-04
[...]
```
We can see immediately that our virtual machine is not fully up-to-date, with
16 software updates that can be applied, and 103 additional security updates
(available with ESM-Infra). Let’s first see which software updates we can
apply by running the command that was suggested in the output:
```bash
$ apt list --upgradable
```
This will show us a list of all the packages with available updates, the
current version, and the version we can upgrade to:
```bash
Listing... Done
[...]
python3-update-manager/bionic-updates 1:18.04.12 all [upgradable from: 1:18.04.11.13]
shim-signed/bionic-updates 1.37~18.04.13+15.7-0ubuntu1 amd64 [upgradable from: 1.37~18.04.11+15.4-0ubuntu9]
ubuntu-pro-client/bionic-updates 32.3~18.04 amd64 [upgradable from: 27.14.4~18.04]
update-manager-core/bionic-updates 1:18.04.12 all [upgradable from: 1:18.04.11.13]
update-notifier-common/bionic-updates 3.192.1.21 all [upgradable from: 3.192.1.19]
```
One of the packages that needs updating is the `ubuntu-pro-client`
package, which provides the Pro Client, but it’s good practice to always keep
software up-to-date, so let’s upgrade all of these packages in our VM:
```default
$ sudo apt update && sudo apt upgrade -y
```
This will install the 16 pending software updates. In the next step, we’ll
tackle the 103 security updates.
## Check the machine’s security status
We know, since we just updated it, that the package providing the Pro Client
is already installed and up-to-date. So now, let’s check on the security status
of our machine:
```bash
$ pro security-status
```
After our update in the last section, we should see something that looks like
this in our terminal output:
```text
518 packages installed:
518 packages from Ubuntu Main/Restricted repository
[...]
This machine is NOT receiving security patches because the LTS period has ended
and esm-infra is not enabled.
This machine is NOT attached to an Ubuntu Pro subscription.
Ubuntu Pro with 'esm-infra' enabled provides security updates for
Main/Restricted packages until 2028. There are 110 pending security updates.
[...]
```
Let’s break this down a bit.
### The security-status output
```text
518 packages installed:
518 packages from Ubuntu Main/Restricted repository
```
Here, we learn that all 518 installed packages on our system come from the
Ubuntu Main or Restricted repositories. This is not surprising – we haven’t
installed any of our own packages yet! The only packages on the system are
those that shipped with the default Bionic image.
```text
This machine is NOT receiving security patches because the LTS period has ended
and esm-infra is not enabled.
This machine is NOT attached to an Ubuntu Pro subscription.
```
The message also lets us know that ‘esm-infra’ is not enabled. **ESM-Infra** is
the Ubuntu Pro service that provides security coverage for packages in Main
and Restricted **after** the initial 5 years of standard support for an LTS.
```text
Ubuntu Pro with 'esm-infra' enabled provides security updates for
Main/Restricted packages until 2028. There are 110 pending security updates.
```
With ESM-Infra, an LTS system gets a total of 10 years of security coverage for
packages in Main and Restricted. So, although LTS support for Bionic ended in
2023, `esm-infra` would cover us until 2028 on this machine – and we would
get 110 security updates as soon as we enabled it.
### What about packages in Universe?
It’s fair to assume that most people will go beyond the default distribution
and also install software from the Universe and Multiverse repositories. We
don’t have any of those yet, so let’s see what happens if we install a popular
package that comes from Universe, such as Ansible:
```bash
$ sudo apt install ansible -y
```
We can run `pro security-status` again to see what happened:
```text
555 packages installed:
550 packages from Ubuntu Main/Restricted repository
5 packages from Ubuntu Universe/Multiverse repository
[...]
Ubuntu Pro with 'esm-infra' enabled provides security updates for
Main/Restricted packages until 2028. There are 119 pending security updates.
Ubuntu Pro with 'esm-apps' enabled provides security updates for
Universe/Multiverse packages until 2028. There is 1 pending security update.
[...]
```
We now have 5 packages listed as coming from Universe/Multiverse – this is
the Ansible package and its dependencies. There are also now 119 security
updates available through `esm-infra`, so some of the Ansible dependencies
also had security updates.
We can see that `esm-apps` has 1 additional security update for Ansible
itself. **ESM-Apps** provides security updates from Canonical for packages in
Universe and Multiverse – even during the LTS period. This means that newer
Ubuntu releases like 24.04 Noble **also** benefit from Ubuntu Pro coverage.
The updates we get from `esm-apps` address critical and high severity
vulnerabilities, and this support is in addition to updates provided by the
Ubuntu Community.
So now we’ve seen that if we enabled `esm-infra` and `esm-apps`, we would
receive quite a few additional security updates. To enable these services, we
first need to attach to an Ubuntu Pro subscription.
## Attach to a subscription
To attach our VM to a subscription, let’s run the following command in our
terminal:
```bash
$ sudo pro attach
```
We should see output like this, giving us a link and a code:
```text
ubuntu@test-vm:~$ sudo pro attach
Initiating attach operation...
Please sign in to your Ubuntu Pro account at this link:
https://ubuntu.com/pro/attach
And provide the following code: H31JIV
```
Let’s first copy the code (`H31JIV` in this example, but yours will be
different), then open the link in our browser without closing the terminal
window. Paste or type the code into the “Enter your code” field.
By default, the “Free Personal Token” will be selected in the “Choose a
subscription to attach” field, and we can click on “Submit” to accept this.
#### NOTE
You can safely use one of your free personal tokens for this – after we
destroy this VM the token can be re-used.
The attach process will then continue in the terminal window, and after the
authentication is complete we will be presented with the following message:
```text
Attaching the machine...
Enabling default service esm-apps
Updating Ubuntu Pro: ESM Apps package lists
Ubuntu Pro: ESM Apps enabled
Enabling default service esm-infra
Updating Ubuntu Pro: ESM Infra package lists
Ubuntu Pro: ESM Infra enabled
Enabling default service livepatch
Installing snapd snap
Installing canonical-livepatch snap
Canonical Livepatch enabled
This machine is now attached to 'Ubuntu Pro - free personal subscription'
```
When the machine has successfully been attached, we also get a summary of
which services are enabled and information about our subscription. This
summary is the same result that you would get if you ran the `pro status`
command to check on the status of the different Ubuntu Pro services:
```text
SERVICE ENTITLED STATUS DESCRIPTION
cc-eal yes disabled Common Criteria EAL2 Provisioning Packages
cis yes disabled Security compliance and audit tools
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
fips yes disabled NIST-certified FIPS crypto packages
fips-updates yes disabled FIPS compliant crypto packages with stable security updates
livepatch yes warning Canonical Livepatch service
ros yes disabled Security Updates for the Robot Operating System
ros-updates yes disabled All Updates for the Robot Operating System
```
There are three services NOT disabled by default: `esm-apps`, `esm-infra`,
and `livepatch`. These three services are considered useful for everyone,
and so they are enabled by default when you attach your machine to a
subscription.
Enabling `esm-apps` and `esm-infra` provides us with access to the
repositories containing the additional security updates we saw earlier.
### What about Livepatch?
[Livepatch](https://ubuntu.com/security/livepatch) is a service that patches vulnerabilities in the Linux kernel
while the system runs, meaning that we don’t need to immediately reboot the
machine to apply these patches.
When Livepatch is enabled, the Livepatch client, `canonical-livepatch`, is
automatically installed, but what happens next depends on which kernel you are
running. You will either:
* Get all available patches applied to your system automatically, or
* Need to update your kernel before Livepatch can be fully activated.
In our case, the default Bionic image contains an old kernel, so we have a
warning beside `livepatch` and the following notice shown below the table:
```text
NOTICES
The running kernel has reached the end of its active livepatch window.
Please upgrade the kernel with apt and reboot for continued livepatch support.
```
We therefore need to update the kernel before we can feel the benefit of
Livepatch.
## Apply our new updates
Applying the newly available updates is as simple as running the `update`
and `upgrade` commands again:
```bash
sudo apt update && sudo apt upgrade -y
```
This may take a few minutes – we have quite a few updates to install!
Now we can run `pro security-status` once more to see a summary of the
results of attaching to our subscription and updating the software:
```text
559 packages installed:
554 packages from Ubuntu Main/Restricted repository
5 packages from Ubuntu Universe/Multiverse repository
[...]
This machine is attached to an Ubuntu Pro subscription.
Main/Restricted packages are receiving security updates from
Ubuntu Pro with 'esm-infra' enabled until 2028. You have received 121 security
updates.
Universe/Multiverse packages are receiving security updates from
Ubuntu Pro with 'esm-apps' enabled until 2028. You have received 1 security
update.
```
The update we did after attaching also updates our kernel to the newer version
(where Livepatch can be used). To boot into the new kernel, we need to restart
the VM.
To do this, press `Ctrl` + `D` together to exit the VM, and then
run:
```bash
multipass restart test-vm
```
After Multipass has restarted our VM, we can log back into it:
```bash
multipass shell test-vm
```
Now if we run `pro status` again, we will see that Livepatch no longer has a
warning, and its status is listed as `enabled`:
```text
SERVICE ENTITLED STATUS DESCRIPTION
cc-eal yes disabled Common Criteria EAL2 Provisioning Packages
cis yes disabled Security compliance and audit tools
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
fips yes disabled NIST-certified FIPS crypto packages
fips-updates yes disabled FIPS compliant crypto packages with stable security updates
livepatch yes enabled Canonical Livepatch service
ros yes disabled Security Updates for the Robot Operating System
ros-updates yes disabled All Updates for the Robot Operating System
```
When Livepatch is enabled, the Livepatch client automatically installs any
available fixes for high and critical severity vulnerabilities in the kernel
without us needing to specifically ask it to.
If we want to know which vulnerabilities have been patched by the Livepatch
client, we can run:
```bash
canonical-livepatch status --format yaml
```
If the kernel is very new, there may not be any patches to apply yet, but we
can always use this command to see what Livepatch has fixed for us.
So, we are now fully up-to-date with all of the software and security updates
for the packages on our VM. But what if we were not using a fresh VM? Let’s
consider a scenario that might affect us on our live system.
## Checking for vulnerabilities
There are two types of vulnerabilities that could affect a system:
[Common Vulnerabilities and Exposures](https://ubuntu.com/security/cves) (CVEs) and
[Ubuntu Security Notices](https://ubuntu.com/security/notices) (USNs).
CVEs are a way to publicly track and catalog security vulnerabilities in
software. Each is given a unique identifier in the format `CVE-XXXX-XXXX`.
To learn more about CVEs, check out our
[explanation of CVEs and USNs](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn).
We’ve seen how, just by attaching our Pro subscription and upgrading our
machine, the Pro Client services have taken care of applying the available
fixes for the CVEs that affected our VM. In fact, as long as we upgrade
our machine periodically, these fixes will always be applied after they are
released. The default configuration of `unattended-upgrades` runs upgrades
for you daily and includes Pro security updates.
However, there is always a period of time between a CVE or USN being reported
and the fix being released. In this case, we might reasonably want some way to
find out if a vulnerability is affecting our system.
In an upcoming release of the Pro Client, we will have a command that shows us
a list of all CVEs that affect our system, and their status. For now, we can
use the `pro fix` command to manually inspect and resolve both CVEs and USNs.
#### NOTE
This may be especially of interest to users who need more control over
their updates!
Now, we have a bit of a problem. We know that our machine is fully up-to-date
and all available fixes have been applied! But, using our VM we can simulate
having a package affected by a known CVE using the Ansible package we installed
earlier. [CVE-2023-5764](https://ubuntu.com/security/CVE-2023-5764) affected the LTS Bionic version of Ansible, so
let’s use this as our test case. We can run the `pro fix` command with the
`--dry-run` flag to inspect the CVE without actually fixing anything, so let
us do just that:
```bash
sudo pro fix cve-2023-5764 --dry-run
```
```text
WARNING: The option --dry-run is being used.
No packages will be installed when running this command.
CVE-2023-5764: Ansible vulnerabilities
- https://ubuntu.com/security/CVE-2023-5764
1 affected source package is installed: ansible
(1/1) ansible:
A fix is available in Ubuntu Pro: ESM Apps.
The update is already installed.
✔ CVE-2023-5764 is resolved.
```
As we can see, in the version of Ansible we are running (thanks to Pro) we are
not affected by this CVE. But what happens if we downgrade Ansible to an older
version that **was** affected by it:
```bash
sudo apt install ansible/bionic-updates -y
```
This command will install the last LTS update for Ansible in Bionic, which
doesn’t have the updates we got from Pro. Now, we can use this command again
to see what happened:
```bash
sudo pro fix cve-2023-5764 --dry-run
```
```text
WARNING: The option --dry-run is being used.
No packages will be installed when running this command.
CVE-2023-5764: Ansible vulnerabilities
- https://ubuntu.com/security/CVE-2023-5764
1 affected source package is installed: ansible
(1/1) ansible:
A fix is available in Ubuntu Pro: ESM Apps.
{ apt update && apt install --only-upgrade -y ansible }
✔ CVE-2023-5764 is resolved.
```
Now we can see that we **are** affected by a CVE in the Ansible package, and
that the CVE is resolved so we can apply the fix for it.
### The pro fix output
The output of the `pro fix` command has the same structure, whether we are
only inspecting a CVE using `--dry-run`, or resolving a CVE. It:
* describes the CVE/USN (with a link to its database entry);
* displays the affected package(s);
* the location of a fix (if one is available); and
* at the end, shows if the CVE/USN is fully fixed in the machine.
This is best demonstrated in a `pro fix` call that *does* fix a package.
### Manually resolve the CVE
Now that we’ve found a package that has a vulnerability, we can fix it using
the `pro fix` command on the CVE (without the `--dry-run` option):
```bash
$ sudo pro fix CVE-2023-5764
```
You will then see the following output:
```text
CVE-2023-5764: Ansible vulnerabilities
- https://ubuntu.com/security/CVE-2023-5764
1 affected source package is installed: ansible
(1/1) ansible:
A fix is available in Ubuntu Pro: ESM Apps.
{ apt update && apt install --only-upgrade -y ansible }
✔ CVE-2023-5764 is resolved.
```
#### NOTE
We need to run the command with `sudo` because it will be installing a
package on the system.
Also, at the end of the output you can see confirmation that the CVE was fixed
by the command. Just to confirm that the fix was successfully applied, let’s
run the `pro fix` command again, and we should now see the following:
```text
CVE-2023-5764: Ansible vulnerabilities
- https://ubuntu.com/security/CVE-2023-5764
1 affected source package is installed: ansible
(1/1) ansible:
A fix is available in Ubuntu Pro: ESM Apps.
The update is already installed.
✔ CVE-2023-5764 is resolved.
```
## Success!
In this tutorial, we have successfully run a Multipass VM and used it to:
- Check on the machine’s security status with `pro security-status`
- Update the software with `sudo apt update && sudo apt upgrade -y`
- Attach our subscription so we can access ESM-Apps, ESM-Infra, and Livepatch
using `sudo pro attach`
- Apply security updates by running `sudo apt update && sudo apt upgrade -y`
again (after attaching to our subscription)
- Check the status of the Pro services on the machine with `pro status`
- Check the fixes applied by Livepatch using
`canonical-livepatch status --format yaml`
- Check the status of a CVE using `pro fix --dry-run`
- And we used `pro fix` to resolve it.
### Close down the VM
When you are finished and want to leave the tutorial, you can shut down the VM
by first pressing `Ctrl` + `D` to exit it, and then running the
following commands to delete the VM completely:
```bash
multipass delete test-vm
multipass purge
```
We don’t need to detach our subscription first. When the VM is deleted and
purged, the token is released and can be used again.
### Further reading
* [ESM explained](https://ubuntu.com/pro-client/docs/latest/explanations/about_esm.md#expl-esm): to find out more about ESM-Infra, ESM-Apps
and the different repositories.
* [CVES/USNs explained](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn): to find out more about CVEs, USNs
and related USNs.
* [Which services are for me?](https://ubuntu.com/pro-client/docs/latest/explanations/which_services.md#which-services): Ubuntu Pro includes a
wide range of services. Although in this tutorial we’ve covered the three
services that are likely to be of interest to most people, you might be
curious about what else you might find useful.
### Get help
If you need more information about this, please feel free to reach out
to the Ubuntu Pro Client team on `#ubuntu-server` on
Libera IRC – we’re happy to help!
Alternatively, if you have a GitHub account, click on the “Give feedback”
link at the top of this page to leave us a message. We’d love to hear from you!
# index.html.md
# Host your own APT news
APT news is used to deliver messages related to APT updates. However, it can also be used to display custom messages within the `apt upgrade` command to your users.
In this tutorial, you will learn how to host your own APT news and how to
configure your Ubuntu machines to use it.
## Install Multipass
To avoid making any modifications to your live system during the tutorial, we
will set up a virtual machine using [Multipass](https://multipass.run/). We are using Multipass
because it allows us to launch VMs without needing any complicated setup. To
install Multipass on your system, run the following command on your machine:
```bash
$ sudo snap install multipass
```
#### NOTE
You will need at least 10 Gigabytes of free space on your machine to launch the Multipass VM used in this tutorial.
## Tutorial overview
To demonstrate how APT news works, we will create three containers inside a
Multipass VM. We will configure one of them to be the APT news server, and we
will configure the other two to consume APT news from that server. It will
look something like this:
Command snippets throughout this tutorial will include a shell prompt to make
it clear on which machine the command will be executed.
| Prompt | Machine |
|---------------------------|---------------------------------------|
| `you@yourcomputer:~$` | Your computer |
| `ubuntu@tutorial:~$` | Multipass VM named `tutorial` |
| `root@apt-news-server:~#` | LXD container named `apt-news-server` |
| `root@client-jammy:~#` | LXD container named `client-jammy` |
| `root@client-focal:~#` | LXD container named `client-focal` |
## Create the local VM and containers
Let’s begin by launching an Ubuntu 24.04 Multipass VM with the following command:
```console
you@yourcomputer:~$ multipass launch noble --disk 10G --name tutorial
```
Then we can access the VM using the `multipass shell` subcommand:
```console
you@yourcomputer:~$ multipass shell tutorial
```
When you see “Welcome to Ubuntu 24.04 LTS” and the shell prompt changes to the
following, you know that you’ve entered the VM.
```console
ubuntu@tutorial:~$
```
We’re going to use [LXD](https://documentation.ubuntu.com/lxd/) to set up our server and clients, so once we’re inside the VM, we can set up LXD with the default parameters:
```console
ubuntu@tutorial:~$ lxd init --minimal
```
Now we will launch three containers inside the VM with the following commands. This may
take a while since it will need to download the appropriate Ubuntu images.
```console
ubuntu@tutorial:~$ lxc launch ubuntu-daily:noble apt-news-server
ubuntu@tutorial:~$ lxc launch ubuntu-daily:jammy client-jammy
ubuntu@tutorial:~$ lxc launch ubuntu-daily:focal client-focal
```
## Configure the APT news server
Now, let’s set up the `apt-news-server` container to serve APT news content.
APT news content is formatted as a JSON file and served over HTTP(S). We can
accomplish this by installing and configuring [nginx](https://nginx.org/) to serve a properly
formatted JSON file.
First, enter the `apt-news-server` container:
```console
ubuntu@tutorial:~$ lxc shell apt-news-server
root@apt-news-server:~#
```
Inside `apt-news-server`, install `nginx` via `apt`. This will also start the HTTP server on port 80.
```console
root@apt-news-server:~# apt install -y nginx
```
With `nginx` installed and running, we can author an APT news JSON file. Open `/var/www/html/aptnews.json`:
```console
root@apt-news-server:~# nano /var/www/html/aptnews.json
```
and add the following content:
```json
{
"messages": [
{
"begin": "TODAY",
"selectors": {
"codenames": ["jammy"]
},
"lines": [
"Hello 22.04 users!",
"This is the APT news server."
]
},
{
"begin": "TODAY",
"lines": [
"Hello everyone else!",
"This is the APT news server."
]
}
]
}
```
In `nano`, use `Ctrl` + `S` and `Ctrl` + `X` to save and exit, respectively.
That apt news configuration will show one message to systems running Ubuntu
22.04 (codename “jammy”) and will show a different message to all other systems.
The value of `"begin"` actually needs to be an ISO8601 formatted datetime
string, and the message won’t be shown before the `begin` date or more than 30
days after the `begin` date. For the purposes of this tutorial you can
quickly replace “TODAY” with today’s date in `aptnews.json` with the
following command.
```console
root@apt-news-server:~# sed -i "s/TODAY/$(date --iso-8601=seconds)/" /var/www/html/aptnews.json
```
You can double check that the command worked by looking at the new contents of the file.
```console
root@apt-news-server:~# cat /var/www/html/aptnews.json
```
You should see that the `begin` field now has an appropriate value.
```json
{
"messages": [
{
"begin": "2024-07-30T16:35:19+00:00",
"selectors": {
"codenames": ["jammy"]
...
```
Now that our `apt-news-server` is configured, we can exit that container:
```console
root@apt-news-server:~# exit
ubuntu@tutorial:~$
```
## Configure the client machines to use the APT news server
We need to configure both client machines to use the APT news server we just
created. This is a single command on each container that we can run using
`lxc exec`:
```console
ubuntu@tutorial:~$ lxc exec client-jammy -- pro config set apt_news_url=http://apt-news-server/aptnews.json
ubuntu@tutorial:~$ lxc exec client-focal -- pro config set apt_news_url=http://apt-news-server/aptnews.json
```
That’s it! Now those containers will start displaying APT news in the output of `apt upgrade`.
Normally, the containers would fetch the latest APT news whenever an
`apt update` is run, but at most once per day. For this tutorial, we’ll use
`pro refresh messages` to force the containers to fetch the latest news
right away.
In the Jammy container we expect to see the special message we set up for systems on
Ubuntu 22.04. Let’s check this is working correctly by first entering the Jammy container:
```console
ubuntu@tutorial:~$ lxc shell client-jammy
```
Then we can run these commands to see the custom APT news message:
```console
root@client-jammy:~# pro refresh messages
root@client-jammy:~# apt upgrade
```
The output of `apt upgrade` should look like this.
```text
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
#
# Hello 22.04 users!
# This is the APT news server.
#
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
```
Since this is what we expected, we can now exit the container:
```console
root@client-jammy:~# exit
ubuntu@tutorial:~$
```
In the Focal client container we expect to see the other message. Let’s check that
by entering the Focal container:
```console
ubuntu@tutorial:~$ lxc shell client-focal
```
Then run these commands again to see the APT news message:
```console
root@client-focal:~# pro refresh messages
root@client-focal:~# apt upgrade
```
The output of `apt upgrade` should look like this.
```text
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
#
# Hello everyone else!
# This is the APT news server.
#
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
```
Once again, this is exactly what we expected to see, so everything is working correctly! Now we can exit this container:
```console
root@client-focal:~# exit
ubuntu@tutorial:~$
```
## Clean up
Congratulations! This tutorial demonstrated the basics of how an APT news server can be set up and used by other Ubuntu machines.
Now that the tutorial is over, you can exit out of the Multipass VM:
```console
ubuntu@tutorial:~$ exit
you@yourcomputer:~$
```
and delete it:
```console
you@yourcomputer:~$ multipass delete --purge tutorial
```
# index.html.md
# Get started with Ubuntu Pro Client
The Ubuntu Pro Client (`pro`) provides a simple mechanism for viewing,
enabling and disabling Canonical offerings on your system. In this tutorial, we
will cover the base `pro` commands that help you to successfully manage Pro
on your machine.
## Main `pro` commands
When dealing with `pro` through the command line, there are six commands that
cover the main functions of the tool. They are:
* `status`
* `attach`
* `refresh`
* `detach`
* `enable`
* `disable`
In this tutorial, we will go through each of these commands and learn how to
properly use them. To achieve this without making any modifications to your
machine, we will use a Xenial Multipass virtual machine (VM).
## Install Multipass
To avoid making any modifications to your live system during the tutorial, we
will set up a virtual machine using [Multipass](https://multipass.run/). We are using Multipass
because it allows us to launch VMs without needing any complicated setup. To
install Multipass on your system, run the following command on your machine:
```bash
$ sudo snap install multipass
```
## Create the Xenial Multipass VM
Now that we have installed Multipass, we can launch our Multipass VM by running
this command:
```bash
$ multipass launch xenial --name dev-x
```
Now we can access the VM by running the command:
```bash
$ multipass shell dev-x
```
Notice that when you run this command, your terminal username and hostname
change to:
```default
ubuntu@dev-x
```
This indicates that you are now inside the VM.
Finally, let’s run `apt update` and `apt upgrade` on the VM to make sure we
are operating on the correct version of Xenial:
```bash
$ sudo apt update && sudo apt install ubuntu-pro-client
```
From now on, every time we say: “run the command” our intention is for you to
run that command inside your VM.
## Base `pro` commands
### status
The `status` command of `pro` will show you the status of any Ubuntu Pro
service on your machine. It also helps you to easily verify that your machine
is attached to an Ubuntu Pro subscription.
Let’s run it on our VM:
```bash
$ pro status
```
You can expect to see an output similar to this:
```text
SERVICE AVAILABLE DESCRIPTION
cc-eal yes Common Criteria EAL2 Provisioning Packages
cis yes Security compliance and audit tools
esm-apps yes Expanded Security Maintenance for Applications
esm-infra yes Expanded Security Maintenance for Infrastructure
fips yes NIST-certified core packages
fips-updates yes NIST-certified core packages with priority security updates
livepatch yes Canonical Livepatch service
ros yes Security Updates for the Robot Operating System
ros-updates yes All Updates for the Robot Operating System
```
You can see that the `status` command shows the services available to your
machine, while also presenting a short description for each service.
If you also look at the last lines of the output, you can see that this machine
is not currently attached to an Ubuntu Pro subscription.
```text
This machine is not attached to an Ubuntu Pro subscription.
See https://ubuntu.com/pro
```
### attach
We have seen which service offerings are available to us, but to access them we
first need to attach an Ubuntu Pro subscription. We can do this by running the
`attach` command.
```bash
$ sudo pro attach
```
You should see output like this, giving you a link and a code:
```bash
ubuntu@test:~$ sudo pro attach
Initiating attach operation...
Please sign in to your Ubuntu Pro account at this link:
https://ubuntu.com/pro/attach
And provide the following code: H31JIV
```
Open the link without closing your terminal window.
In the field that asks you to enter your code, copy and paste the code shown
in the terminal. Then, choose which subscription you want to attach to.
By default, the Free Personal Token will be selected, which is fine for the
purposes of this tutorial.
Once you have pasted your code and chosen the subscription you want to attach
your machine to, click on the “Submit” button.
The attach process will then continue in the terminal window, and you should
eventually be presented with the following message:
```text
Enabling default service esm-apps
Updating package lists
Ubuntu Pro: ESM Apps enabled
Enabling default service esm-infra
Updating package lists
Ubuntu Pro: ESM Infra enabled
Enabling default service livepatch
Installing canonical-livepatch snap
Canonical livepatch enabled.
This machine is now attached to 'USER ACCOUNT'
SERVICE ENTITLED STATUS DESCRIPTION
cc-eal yes disabled Common Criteria EAL2 Provisioning Packages
cis yes disabled Security compliance and audit tools
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
fips yes disabled NIST-certified core packages
fips-updates yes disabled NIST-certified core packages with priority security updates
livepatch yes enabled Canonical Livepatch service
ros yes disabled Security Updates for the Robot Operating System
ros-updates yes disabled All Updates for the Robot Operating System
NOTICES
Operation in progress: pro attach
Enable services with: pro enable
Account: USER ACCOUNT
Subscription: USER SUBSCRIPTION
Valid until: 9999-12-31 00:00:00+00:00
Technical support level: essential
```
From this output, we can see that the `attach` command has introduced the
“status” column. This shows which services (specified by your user
subscription) have been enabled by default.
After the command ends, `pro` displays the new state of the machine. This
status output is exactly what you see if you run the `status` command. Let’s
confirm this by running the `status` command again:
```bash
$ pro status
```
#### NOTE
You may be wondering why the output of `status` is different depending on
whether `pro` is attached or unattached. For more information on why this
is, refer to our
[explanation on the different columns](https://ubuntu.com/pro-client/docs/latest/explanations/status_columns.md#pro-status-output).
Finally, another useful bit at the end of the output for both `attach` and
`status` is the contract expiration date:
```default
Account: USER ACCOUNT
Subscription: USER SUBSCRIPTION
Valid until: 9999-12-31 00:00:00+00:00
```
The `Valid until` field describes when your contract will expire, so you can
be aware of when it needs to be renewed. Note that if you are using a free
token, you will not see this part of the output since free tokens never expire.
### refresh
Although *free* tokens never expire, if you buy an Ubuntu Pro subscription and
later need to renew your contract, how can you make your machine aware of it?
This is where the `refresh` command comes in:
```bash
$ sudo pro refresh
```
This command will “refresh” the contract on your machine. It’s also really
useful if you want to change any definitions on your subscription.
For example, let’s assume that you now want `cis` to be enabled by default
when attaching. After you modify your subscription on the Ubuntu Pro website to
enable it by default, running the refresh command will process the changes you
made, and `cis` will then be enabled.
#### HINT
The `refresh` command does more than just update the contract in your
machine. If you would like more information about the command, take a look
at our [CLI reference page](https://ubuntu.com/pro-client/docs/latest/references/commands.md#commands).
### enable
There is another way to enable a service that wasn’t activated during
`attach` or `refresh`. Let us suppose that you now want to enable `cis`
on the machine manually. To achieve this, you can use the `enable` command.
Let’s try enabling `cis` on our VM by running:
```bash
$ sudo pro enable cis
```
After running the command, you should see output similar to this:
```text
One moment, checking your subscription first
Updating package lists
Installing CIS Audit packages
CIS Audit enabled
Visit https://ubuntu.com/security/cis to learn how to use CIS
```
We can then confirm that `cis` is now enabled by using the `status` command
again:
```bash
$ pro status
```
And you should see:
```text
SERVICE ENTITLED STATUS DESCRIPTION
cc-eal yes disabled Common Criteria EAL2 Provisioning Packages
cis yes enabled Security compliance and audit tools
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
fips yes disabled NIST-certified core packages
fips-updates yes disabled NIST-certified core packages with priority security updates
livepatch yes enabled Canonical Livepatch service
ros yes disabled Security Updates for the Robot Operating System
ros-updates yes disabled All Updates for the Robot Operating System
```
We can see now that `cis` is marked as `enabled` under “status”.
### disable
What happens if you don’t want a service anymore?
All you need to do is disable that service through `pro`. For example, let’s
say we changed our mind about `cis` after enabling it, and we now want to
disable it instead. We can turn it off by running `disable` on our VM:
```bash
$ sudo pro disable cis
```
Let’s now run `pro status` to see what happened to `cis`:
```text
SERVICE ENTITLED STATUS DESCRIPTION
cc-eal yes disabled Common Criteria EAL2 Provisioning Packages
cis yes disabled Security compliance and audit tools
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
fips yes disabled NIST-certified core packages
fips-updates yes disabled NIST-certified core packages with priority security updates
livepatch yes enabled Canonical Livepatch service
ros yes disabled Security Updates for the Robot Operating System
ros-updates yes disabled All Updates for the Robot Operating System
```
Now we can see that `cis` status has gone back to being disabled.
#### IMPORTANT
The `disable` command doesn’t uninstall any package that was installed by
the service, or undo any configuration that was applied to the machine –
it only removes the access you have to the service.
### detach
Finally, what if you decide you no longer want this machine to be attached to
an Ubuntu Pro subscription?
To disable all of the Ubuntu Pro services and remove the subscription you
stored on your machine during `attach`, you can use the `detach` command:
```bash
$ sudo pro detach
```
Just like the `disable` command, `detach` will not uninstall any packages
that were installed by any of the services enabled through `pro`.
## Success!
Congratulations! You successfully ran a Multipass VM and used it to try out the
six main commands of the Ubuntu Pro Client.
If you want to continue testing the different features and functions of `pro`,
you can run the command:
```bash
$ pro help
```
This will provide you with a full list of all the commands available, and
details of how to use them. Feel free to play around with them in your VM and
see what else `pro` can do for you!
### Close down the VM
When you are finished and want to leave the tutorial, you can shut down the VM
by first pressing `Ctrl` + `D` to exit it, and then running the
following commands to delete the VM completely:
```bash
$ multipass delete dev-x
$ multipass purge
```
### Next steps
If you would now like to see some more advanced options to configure `pro`,
we recommend taking a look at our
[how-to guides](https://ubuntu.com/pro-client/docs/latest/howtoguides.md#how-to).
If you have any questions or need some help, please feel free to reach out to
the `pro` team on #ubuntu-server on Libera IRC – we’re happy
to help!
Alternatively, if you have a GitHub account, click on the “Give feedback”
link at the top of this page to leave us a message. We’d love to hear from you!
# index.html.md
# The `pro status` output explained
When running `pro status` we can observe two different types of output, which
depend on whether the Ubuntu Pro subscription is attached or unattached.
## Pro subscription unattached
When unattached, users will see the following status table containing only
three columns (output truncated for brevity):
```text
SERVICE AVAILABLE DESCRIPTION
...
esm-apps yes Expanded Security Maintenance for Applications
esm-infra yes Expanded Security Maintenance for Infrastructure
fips yes NIST-certified core packages
fips-updates yes NIST-certified core packages with priority security updates
livepatch yes Canonical Livepatch service
...
```
Where:
* **SERVICE**: Is the name of service being offered.
* **AVAILABLE**: Shows if that service is available on that machine. To verify
if a service is available, we check the machine kernel version, architecture,
Ubuntu release being used and the machine type (i.e., lxd for LXD containers).
* **DESCRIPTION**: A short description of the service.
## With Pro subscription attached
However, if we run the same command when attached, we have an output with 4
columns (output truncated):
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
fips yes disabled NIST-certified core packages
fips-updates yes disabled NIST-certified core packages with priority security updates
livepatch yes enabled Canonical Livepatch service
...
```
You may notice that the column **AVAILABLE** is no longer shown, and instead we
see the following new columns:
* **ENTITLED**: Shows if the user subscription allows that service to be
enabled.
* **STATUS**: Reports the state of that service on the machine.
It is possible that a service could appear as “available” when the Pro status
is unattached, but then shows as “not entitled” if the subscription is later
attached. This happens because even if the service is available, if your Ubuntu
Pro subscription doesn’t allow you access to a service, `pro` cannot enable
it.
The **STATUS** column allows for three possible states:
* **enabled**: The service is enabled on the machine.
* **disabled**: The service is not currently running.
* **n/a**: This means “not applicable”. This will show if the service cannot be
enabled on the machine due to a non-contract restriction. For example, we
cannot enable `livepatch` on a container.
“Not applicable” rows are not shown by default. If you would like to see
the full output, use the `pro status --all` command.
## Notices
“Notices” are information regarding the Ubuntu Pro status which either require
some kind of action from the user, or may impact the experience with Ubuntu Pro.
For example, let’s say FIPS was just enabled, but the system wasn’t rebooted
yet (which is required for booting into the FIPS Kernel). The output of
`pro status` in this case will contain:
```text
NOTICES
FIPS support requires system reboot to complete configuration.
```
After the system is rebooted, the notice will go away.
Notices can always be resolved, and the instructions on how to resolve it will
be explicitly stated in the notice itself.
## Features
“Features” are extra configuration values that can be set and unset in
`uaclient.conf`. Most of these are meant for development/testing purposes,
but some can be used in application flows. For example, to always have beta
services with the same flow as the non-beta (for `enable`, `status`, etc.),
`uaclient.conf` may have:
```text
features:
allow_beta: true
```
In this case, the output of `pro status` will contain:
```text
FEATURES
allow_beta: True
```
It’s important to keep in mind that any feature defined like this will be
listed, even if it is invalid or typed the wrong way. Those appear in
`status` output for informational and debugging purposes.
## Machine-readable output
### Status API functions
Some status information can be obtained from API functions. These include:
* Is the machine currently attached to an Ubuntu Pro subscription? See
[u.pro.status.is_attached.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-status-is-attached-v1)
* Which Ubuntu Pro services are currently enabled on the machine? See
[u.pro.status.enabled_services.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-status-enabled-services-v1)
#### ATTENTION
Let us know what status information you need that is missing from the API
by clicking “Give feedback” at the top of this page.
# index.html.md
# Which services are for me?
Ubuntu Pro is a broad subscription designed to meet many different needs. You
are unlikely to want to use all of these tools and services at the same time,
so you are free to select the precise stream of updates and versions you want
to apply on any given machine covered by your Pro subscription.
To help you navigate the services offered through Ubuntu Pro, click on the tab
that best describes your needs for our suggestions on which services might be
of interest to you. For example, Pro includes a set of package versions that
are compliant with FIPS regulations. You will only want these versions on
machines that *need* to meet FIPS requirements, so you can choose to enable
that stream specifically on those machines.
### Commercial
* **Expanded Security Maintenance (ESM)**
If you’re using any Ubuntu LTS – Desktop or Server – in a commercial
setting and you rely on ‘Universe’ packages, or if you’re on an older
LTS and don’t want to upgrade yet, you can get additional security
support through [Expanded Security Maintenance (ESM)](https://ubuntu.com/security/esm). We recommend
it for everyone using Pro, and it’s enabled by default. It includes
two services:
* `esm-infra` provides security updates for packages in the Ubuntu
‘main’ repository (packages from Ubuntu) for five additional years
beyond the standard five years of security maintenance of ‘main’
packages.
* `esm-apps` covers packages in the ‘universe’ repository (which
are from Debian and the community) for ten years after the LTS
release.
* Whether you need one or both of these depends on your subscription.
If you’re not sure which services best support the needs of your
organization, contact us for [a security assessment](https://ubuntu.com/contact-us/form?product=pro).
* **Livepatch**
Ubuntu [Livepatch](https://ubuntu.com/security/livepatch) reduces costly unplanned maintenance by patching
vulnerabilities while the system runs. It removes the need to
immediately reboot after a kernel upgrade so that you can schedule
downtime when it’s convenient. This tooling is available through
`livepatch` and is one of the services we enable by default.
* Find out more about what Livepatch can do for your organization in
the [Livepatch documentation](https://ubuntu.com/security/livepatch/docs), or learn
[how to enable it](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_livepatch.md#manage-livepatch) with `pro`.
* **Landscape**
[Landscape](https://ubuntu.com/landscape) is the leading management and administration tool for
Ubuntu. It can manage up to 40,000 Ubuntu machines with a single
interface, and can automate security patching, as well as hardening
and compliance. Landscape can be [self-hosted](https://ubuntu.com/landscape/pricing) or you can use Canonical’s
[Landscape SaaS](https://ubuntu.com/landscape/pricing) offering.
* Find out more about
[registering a machine with Landscape](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_landscape.md#manage-landscape)
using `pro`.
Want more information?
### Security certification
Ubuntu provides security [compliance, certifications, and hardening](https://ubuntu.com/security/certifications):
* **FIPS 140-2**
* [FIPS 140-2 Certified Modules](https://ubuntu.com/security/fips) are available through `fips`.
* Compliant but non-certified patches are available through
`fips-updates`.
* Find out more [about managing FIPS](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_fips.md#manage-fips).
* **Ubuntu Security Guide (USG)**
* In the 20.04 LTS we introduced the [Ubuntu Security Guide](https://ubuntu.com/security/certifications/docs/usg), which
provides security tooling through `usg`. It bundles together
multiple key components, such as CIS benchmarking and DISA-STIG.
* Before USG, Center for Internet Security [(CIS) Benchmark](https://ubuntu.com/security/cis) tooling
was available as a separate service through `cis`. This can be
used up to (and including) 20.04 LTS, but on all later LTS releases
this functionality is provided through `usg`.
* Find out [how to manage USG (and CIS)](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cis.md#manage-cis)
with the Pro Client.
* **Common Criteria**
* [Common Criteria EAL2 (CC EAL)](https://ubuntu.com/security/cc) certification tooling is available
through `cc-eal`. The Ubuntu 18.04 LTS and 16.04 LTS have both
been certified.
* Find out [how to enable CC EAL](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cc.md#manage-cc) on your LTS.
Want more information?
### Personal user
* **Expanded Security Maintenance (ESM)**
If you’re using Pro on an LTS machine (Desktop or Server) you can get
additional security support through
[Expanded Security Maintenance (ESM)](https://ubuntu.com/security/esm). We recommend it for everyone
using Pro, and it’s enabled by default. It includes two services:
* `esm-infra` provides security updates for packages in the Ubuntu
‘main’ repository (packages from Ubuntu) for five additional years
beyond the standard five years of security maintenance of ‘main’
packages.
* `esm-apps` covers packages in the ‘universe’ repository (which
are from Debian and the community) for ten years after the LTS
release.
* Read more
[about ESM-Apps and ESM-Infra](https://ubuntu.com/pro-client/docs/latest/explanations/about_esm.md#expl-esm).
* **Livepatch**
Ubuntu [Livepatch](https://ubuntu.com/security/livepatch) removes the need to immediately reboot your
machine after a patch is applied to the kernel, so you can perform
device reboots when it’s convenient for you. Although it’s
lightweight, it may not be suitable on a very small system with
limited memory. Check our [list of supported kernels](https://ubuntu.com/security/livepatch/docs/livepatch/reference/kernels) if you’re
unsure.
* Find out
[how to enable Livepatch](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_livepatch.md#manage-livepatch).
Want more information?
### Specialty products
* **Anbox Cloud**
Canonical Anbox Cloud makes large-scale Android development easier by
running Android in secure, scalable containers or virtual machines.
Compared to other Android emulation solutions, Anbox Cloud can provide
at least twice the density and can serve up to 100 Android instances per
server.
Due to its highly scalable nature and performance optimization, Anbox Cloud
enables delivering device-agnostic mobile applications. Popular use cases
of Anbox Cloud include mobile game streaming services,
corporate application streaming, application automation and testing.
[Enabling the Anbox Cloud service](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_anbox.md#manage-anbox) lets you try out
the Anbox Cloud Appliance. Anbox Cloud also has a charm-based offering
for deployments in production. Find out more in the [official documentation](https://documentation.ubuntu.com/anbox-cloud/).
* **ROS ESM**
Our Robot Operating System Expanded Security Maintenance ([ROS ESM](https://ubuntu.com/robotics/ros-esm))
service provides security maintenance for ROS LTS releases, starting
with ROS Kinetic on Ubuntu 16.04 – including packages from the Ubuntu
‘universe’ repository.
* `ros` provides security updates to the 600+ packages for ROS 1
Kinetic and Melodic, and ROS 2 Foxy – in addition to the security
coverage already provided by ESM.
* `ros-updates` also gives you access to non-security updates.
* Want to know how to enable ROS ESM? Check out
[this introductory guide](https://discourse.ubuntu.com/t/ros-esm-user-introduction/26206) by the ROS team to get started.
* **Real-time kernel**
The Ubuntu 22.04 LTS brought the new, enterprise-grade
[real-time kernel](https://ubuntu.com/realtime-kernel), which reduces kernel latencies and ensures
predictable performance for time-sensitive task execution. It was
designed to deliver stable, ultra-low latency and security for
critical telco infrastructure, but has applications across a wide
variety of industries.
* Find out [more information about real-time Ubuntu](https://ubuntu.com/kernel/real-time/contact-us) and what it can
do for your organization.
* Or see our guide on
[how to enable the real-time kernel](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_realtime_kernel.md#manage-realtime).
Want more information?
# index.html.md
# Messaging
Here you’ll find details about Ubuntu Pro Client-related APT and MOTD messages
– what they are, when they are used and how they work.
* [Ubuntu Pro-related APT messages](https://ubuntu.com/pro-client/docs/latest/explanations/apt_messages.md#apt-messages)
* [Ubuntu Pro-related MOTD messages](https://ubuntu.com/pro-client/docs/latest/explanations/motd_messages.md#motd-messages)
* [Timer jobs explained](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_the_timer_jobs.md#expl-timer-jobs)
# index.html.md
# Pro services
Ubuntu Pro is a portal to many other services offered by Canonical. Here you
can discover more about the services available through Pro and how you can
manage them with the Pro Client.
* Find out [which services we recommend](https://ubuntu.com/pro-client/docs/latest/explanations/which_services.md#which-services) for different
situations
* Use the `pro status` command
[to monitor active services](https://ubuntu.com/pro-client/docs/latest/explanations/status_columns.md#pro-status-output) on your machine
* Learn [about ESM](https://ubuntu.com/pro-client/docs/latest/explanations/about_esm.md#expl-esm) security services (`esm-apps` and
`esm-infra`)
* [Disabling and purging services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge) explains how to disable services and remove them
from your machine
# index.html.md
# Handling security vulnerabilities
Ubuntu Pro provides security fixes for vulnerabilities (CVEs and USNs). This
section explains what those are, how to find out if your machine is affected,
and the different uses of the `pro fix` command.
* [About CVEs and USNs](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn)
* [Understand the security coverage](https://ubuntu.com/pro-client/docs/latest/explanations/how_to_interpret_the_security_status_command.md#pro-security-status) on your
installed packages using `pro security-status`
* [Common scenarios](https://ubuntu.com/pro-client/docs/latest/explanations/fix_scenarios.md#pro-fix-howto) when using the `pro fix` command
# index.html.md
# Timer jobs explained
Ubuntu Pro Client (`pro`) sets up a `systemd` timer to run jobs that need
to be carried out periodically. Every time the timer runs, it decides which
jobs need to be performed 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 `pro` runs periodically are `metering` and
`update_messaging`.
### The `update_messaging` job
`update_messaging` updates the MOTD and APT messages every 6 hours. It
ensures that the MOTD and APT messages displayed on the system match those
that are available/enabled. It finds updated information about available
packages or security updates and shows these to the user.
### The `metering` job
`metering` pings the Canonical servers for contract metering every 4 hours.
It informs Canonical which services are enabled on the machine.
#### NOTE
The `metering` job only runs when attached to an Ubuntu Pro subscription.
If you want to learn more about configuring the timer jobs, you can check our guide on [how to configure the timer jobs](https://ubuntu.com/pro-client/docs/latest/howtoguides/configuring_timer_jobs.md#configuring-timer-jobs).
# index.html.md
# Ubuntu Pro policies
Here we explain our usage policies for features such as using Pro offline or
airgapped, how machines are counted against tokens, how we deprecate features
and what data is collected from active machines.
* [Using Ubuntu Pro airgapped or offline](https://ubuntu.com/pro-client/docs/latest/explanations/using_pro_offline.md#pro-airgapped)
* [How machines are counted](https://ubuntu.com/pro-client/docs/latest/explanations/pro_token_and_machine_usage.md#pro-token-and-machine-usage)
* [Feature deprecation policy](https://ubuntu.com/pro-client/docs/latest/explanations/deprecation_policy.md#deprecation-policy)
* [Data collection policy](https://ubuntu.com/pro-client/docs/latest/explanations/data_collection.md#what-data-is-collected)
# index.html.md
# What is the Pro daemon?
Ubuntu Pro Client sets up a daemon for two types of machines:
* Azure and GCP generic cloud images
* Cloud Pro images
For the first type of images, the daemon is responsible
for detecting if an Ubuntu Pro license has been purchased for the machine.
If a Pro license is detected, then the machine is automatically attached.
For the Pro cloud images, the daemon is responsible for retrying the auto-attach
operation if it fails on first boot. When that happens, users will be notified in
MOTD or when they run `pro status` with a message like:
```text
Failed to automatically attach to an Ubuntu Pro subscription 1 time
The failure was due to: ERROR_MSG
The next attempt is scheduled for RETRY_DATE
You can try manually with `sudo pro auto-attach`.
```
The “retry auto-attach” operation will keep retrying for a **month**. If we
still cannot attach to the machine by then, we display the following message:
```text
Failed to automatically attach to an Ubuntu Pro subscription NUM times.
The most recent failure was due to: ERROR_MSG
Try re-launching the instance or report this issue by running `ubuntu-bug ubutu-advantage-tools`
You can try manually with `sudo pro auto-attach`.
```
## Disabling the daemon
If you are not interested in Ubuntu Pro services and don’t want your machine to
be automatically attached to your subscription, you can safely stop and disable
the daemon using `systemctl` as follows:
```bash
sudo systemctl stop ubuntu-advantage.service
sudo systemctl disable ubuntu-advantage.service
```
# index.html.md
# Machine counts and token usage for Ubuntu Pro
Ubuntu Pro tokens are used to authenticate your machine and enable access to the services you are entitled to. These tokens are unique and specific to your account, so you should treat them as a secret (as you would with a password).
In this page, we’ll discuss how Ubuntu Pro tokens work and how machines are counted against your subscription.
## About Ubuntu Pro tokens
- **Obtaining Pro tokens**:
After subscribing to Ubuntu Pro, you can access your subscriptions through the [Ubuntu Pro Dashboard](https://ubuntu.com/pro/dashboard). Each subscription includes an Ubuntu Pro token that can be used to attach as many machines as your subscription allows.
- **Attaching Pro tokens**:
You can use the `sudo pro attach` command to connect a machine to your Ubuntu Pro subscription.
- **Detaching Pro tokens**:
You can use the `sudo pro detach` command to remove a machine from the subscription. If you are attached on a VM you intend to delete, the token does not need to be detached before the VM is destroyed.
For guidance on moving, cloning, rebuilding, or deleting an attached machine,
see [How to manage Ubuntu Pro attachment when moving machines](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_migrate_attached_machines.md#how-to-migrate-attached-machines).
For more detailed information regarding Pro commands, refer to our [Getting started with Ubuntu Pro client](https://ubuntu.com/pro-client/docs/latest/tutorials/basic_commands.md#tutorial-commands) tutorial.
## Monitoring active machines
Active machines are counted based on the number of machines attached to your subscription at a given time. An active machine is defined as a machine that has been attached to a given subscription at any point within the past 24 hours.
Each subscription type has a limit on the number of machines it can cover. For personal subscriptions, this limit is 5 physical machines with unlimited VMs on these machines. Enterprise subscriptions will have a higher limit and may differentiate between physical and virtual machines.
The Ubuntu Pro dashboard can help track the number of active machines, ensuring compliance with subscription limits. It provides a comprehensive view of all active and attached machines. It helps track the number of active machines, ensuring that you remain within the subscription limits.
## Dealing with multiple VMs
In an IaaS environment where node control is limited, you can contact [Canonical’s sales team](https://ubuntu.com/contact-us/form?product=pro) to discuss purchasing licenses per single VM rather than per physical node.
## Handling overage of active machines
Canonical monitors the number of active machines associated with your Ubuntu Pro subscription. It’s important to ensure that the number of active machines does not exceed your subscription limit. However, occasional overages are generally acceptable and will not immediately impact your Ubuntu Pro subscription. If persistent overages occur, Canonical may reach out to address the issue.
To avoid any disruptions, you can monitor your active machines and detach any that are no longer in use.
If you have any additional questions, please visit the [Ubuntu Pro FAQ](https://discourse.ubuntu.com/t/ubuntu-pro-faq/34042) for further information.
# index.html.md
# Common scenarios when using `pro fix` to solve a CVE/USN
The Ubuntu Pro Client (`pro`) can be used to inspect and resolve
[Common Vulnerabilities and Exposures](https://ubuntu.com/security/cves) (CVEs) and
[Ubuntu Security Notices](https://ubuntu.com/security/notices) (USNs) on your machine.
Every CVE/USN is fixed by trying to upgrade all of the affected packages
described by the CVE or USN. Sometimes, the package fixes can only be applied
if an Ubuntu Pro service is already enabled on your machine.
In this article we will introduce the `pro fix` command, and then go into
more details about the different scenarios you may encounter when using
`pro fix` to resolve CVEs/USNs.
#### NOTE
If you want a simpler guide to get started with `pro fix`, start with
[our security features tutorial](https://ubuntu.com/pro-client/docs/latest/tutorials/security-with-pro.md#security-tutorial).
You can use the same VM-based environment created in that tutorial
to recreate the output shown below yourself. If you have already completed
the tutorial, you may want to [skip this section](#cve-no-fix).
## Use `pro fix`
First, let’s see what happens to your system when `pro fix` runs. We will
choose to fix a CVE that does not affect the system – for example if you
do not have `MariaDB` installed and want to fix [CVE-2020-15180](https://ubuntu.com/security/CVE-2020-15180).
Let’s first confirm that it doesn’t affect the system by running this command:
```bash
$ pro fix CVE-2020-15180
```
You should see an output like this:
```text
CVE-2020-15180: MariaDB vulnerabilities
- https://ubuntu.com/security/CVE-2020-15180
No affected source packages are installed.
✔ CVE-2020-15180 does not affect your system.
```
Every `pro fix` output has a similar output structure. It:
* describes the CVE/USN;
* displays the affected packages;
* fixes the affected packages; and
* at the end, shows if the CVE/USN is fully fixed in the machine.
This is best demonstrated in a `pro fix` call that *does* fix a package.
Therefore let us install an older package on the VM that we know is associated
with [CVE-2020-25686](https://ubuntu.com/security/CVE-2020-25686). You can install the package by running these commands:
```bash
$ sudo apt update
$ sudo apt install dnsmasq=2.75-1
```
Now, let’s run `pro fix` on the CVE:
```bash
$ sudo pro fix CVE-2020-25686
```
You will then see the following output:
```text
CVE-2020-25686: Dnsmasq vulnerabilities
- https://ubuntu.com/security/CVE-2020-25686
1 affected package is installed: dnsmasq
(1/1) dnsmasq:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y dnsmasq }
✔ CVE-2020-25686 is resolved.
```
#### NOTE
We need to run the command with `sudo` because it will be installing a
package on the system.
Whenever `pro fix` has a package to upgrade, it follows a consistent
structure and displays the following, in this order:
1. The affected package
2. The availability of a fix
3. The location of the fix, if one is available
4. The command that will fix the issue
Also, at the end of the output you can see confirmation that the CVE was fixed
by the command. Just to confirm that the fix was successfully applied, let’s
run the `pro fix` command again, and we should now see the following:
```text
CVE-2020-25686: Dnsmasq vulnerabilities
- https://ubuntu.com/security/CVE-2020-25686
1 affected package is installed: dnsmasq
(1/1) dnsmasq:
A fix is available in Ubuntu standard updates.
The update is already installed.
✔ CVE-2020-25686 is resolved.
```
## CVE/USN without a released fix
Some CVEs/USNs do not have a fix released yet. When that happens, `pro fix`
will let you know! This is example output created in the past, for which there
might be fixes later on. To create this scenario we installed a
known affected package with no fix (at the time) and then checked for an
available fix:
```bash
$ sudo apt-get install -y expat=2.1.0-7 swish-e matanza ghostscript
```
Now, we can confirm that there is no fix by running the following command:
```bash
$ pro fix CVE-2017-9233
```
You will see the following output:
```text
CVE-2017-9233: Coin3D vulnerability
- https://ubuntu.com/security/CVE-2017-9233
3 affected source packages are installed: expat, matanza, swish-e
(1/3, 2/3) matanza, swish-e:
Ubuntu security engineers are investigating this issue.
(3/3) expat:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y expat }
2 packages are still affected: matanza, swish-e
✘ CVE-2017-9233 is not resolved.
```
As we can see, we are informed by `pro fix` that some packages do not have a
fix available. In the last line, we can also see that the CVE is not resolved.
## CVE/USN that require an Ubuntu Pro subscription
Some package fixes can only be installed when the machine is attached to an
Ubuntu Pro subscription. When that happens, `pro fix` will tell you that.
To see an example of this scenario, you can run the following fix command:
```bash
$ sudo pro fix USN-5079-2
```
The command will prompt you for a response, like this:
```text
USN-5079-2: curl vulnerabilities
Associated CVEs:
- https://ubuntu.com/security/CVE-2021-22946
- https://ubuntu.com/security/CVE-2021-22947
Fixing requested USN-5079-2
1 affected package is installed: curl
(1/1) curl:
A fix is available in Ubuntu Pro: ESM Infra.
The update is not installed because this system is not attached to a
subscription.
Choose: [S]ubscribe at ubuntu.com [A]ttach existing token [C]ancel
>
```
We can see that the prompt is asking for an Ubuntu Pro subscription token. Any
user with a Ubuntu One account is entitled to a free personal token to use with
Ubuntu Pro.
If you choose the `Subscribe` option on the prompt, the command will ask you
to go to the [Ubuntu Pro portal](https://ubuntu.com/pro). In the portal, you can get a free
subscription token by logging in with your “Single Sign On” (SSO) credentials;
the same credentials you use to log into [https://login.ubuntu.com](https://login.ubuntu.com).
After getting your Ubuntu Pro token, you can hit `Enter` on the prompt
and it will ask you to provide the token you just obtained. After entering the
token you should now see the following output:
```text
USN-5079-2: curl vulnerabilities
Associated CVEs:
- https://ubuntu.com/security/CVE-2021-22946
- https://ubuntu.com/security/CVE-2021-22947
1 affected package is installed: curl
(1/1) curl:
A fix is available in Ubuntu Pro: ESM Infra.
The update is not installed because this system is not attached to a
subscription.
Choose: [S]ubscribe at ubuntu.com [A]ttach existing token [C]ancel
>A
Enter your token (from https://ubuntu.com/pro) to attach this system:
> TOKEN
{ pro attach TOKEN }
Updating Ubuntu Pro: ESM Apps package lists
Ubuntu Pro: ESM Apps enabled
Enabling default service esm-infra
Updating Ubuntu Pro: ESM Infra package lists
Ubuntu Pro: ESM Infra enabled
Enabling default service livepatch
Installing snapd snap
Installing canonical-livepatch snap
Canonical Livepatch enabled
{ apt update && apt install --only-upgrade -y curl libcurl3-gnutls }
✔ USN-5079-2 is resolved.
Found related USNs:
- USN-5079-1
Fixing related USNs:
- USN-5079-1
No affected source packages are installed.
✔ USN-5079-1 does not affect your system.
Summary:
✔ USN-5079-2 [requested] is resolved.
✔ USN-5079-1 [related] does not affect your system.
```
We can see that this command also fixed the related USN **USN-5079-1**.
If you want to learn more about related USNs, refer to
[our explanation guide](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#related-usns)
Finally, we can see that that the attach command was successful, which can be
verified by the status output we see when executing the command. Additionally,
we observe that the USN is indeed fixed, which you can confirm by running the
`pro fix` command again:
```text
USN-5079-2: curl vulnerabilities
Associated CVEs:
- https://ubuntu.com/security/CVE-2021-22946
- https://ubuntu.com/security/CVE-2021-22947
Fixing requested USN-5079-2
1 affected package is installed: curl
(1/1) curl:
A fix is available in Ubuntu Pro: ESM Infra.
The update is already installed.
✔ USN-5079-2 is resolved.
Found related USNs:
- USN-5079-1
Fixing related USNs:
- USN-5079-1
No affected source packages are installed.
✔ USN-5079-1 does not affect your system.
Summary:
✔ USN-5079-2 [requested] is resolved.
✔ USN-5079-1 [related] does not affect your system.
```
#### NOTE
Even though we are not covering this scenario here, if you have an expired
contract, `pro fix` will detect that and prompt you to attach a new token
for your machine.
## CVE/USN that require a Ubuntu Pro service
Now, let’s assume that you have attached to an Ubuntu Pro subscription, but
when running `pro fix`, the required service that fixes the issue is not
enabled. In that situation, `pro fix` will also prompt you to enable that
service.
To confirm that, run the following command to disable `esm-infra`:
```bash
$ sudo pro disable esm-infra
```
Now, you can run the following command:
```bash
$ sudo pro fix CVE-2023-1523
```
And you should see the following output (if you type `E` when prompted):
```text
CVE-2023-1523: snapd vulnerability
- https://ubuntu.com/security/CVE-2023-1523
1 affected source package is installed: snapd
(1/1) snapd:
A fix is available in Ubuntu Pro: ESM Infra.
The update is not installed because this system does not have
esm-infra enabled.
Choose: [E]nable esm-infra [C]ancel
> E
{ pro enable esm-infra }
Updating Ubuntu Pro: ESM Infra package lists
Ubuntu Pro: ESM Infra enabled
{ apt update && apt install --only-upgrade -y snapd ubuntu-core-launcher }
✔ CVE-2023-1523 is resolved.
```
We can observe that the required service was enabled and `pro fix` was able
to successfully upgrade the affected package.
## CVEs/USNs that require a reboot
When running the `pro fix` command, sometimes we can install a package that
requires a system reboot to complete. The `pro fix` command can detect that
and will inform you about it.
You can confirm this by running the following fix command:
```bash
$ sudo pro fix CVE-2023-3817
```
Then you will see the following output:
```text
CVE-2023-3817: OpenSSL vulnerabilities
- https://ubuntu.com/security/CVE-2023-3817
1 affected source package is installed: openssl
(1/1) openssl:
A fix is available in Ubuntu Pro: ESM Infra.
{ apt update && apt install --only-upgrade -y libssl1.0.0 openssl }
A reboot is required to complete fix operation.
✘ CVE-2023-3817 is not resolved.
```
If we reboot the machine and run the command again, you will see that it is
indeed fixed:
```text
CVE-2023-3817: OpenSSL vulnerabilities
- https://ubuntu.com/security/CVE-2023-3817
1 affected source package is installed: openssl
(1/1) openssl:
A fix is available in Ubuntu Pro: ESM Infra.
The update is already installed.
✔ CVE-2023-3817 is resolved.
```
## Partially resolved CVEs/USNs
Finally, you might run a `pro fix` command that only fixes some of the
affected packages. This happens when only a subset of the packages have
available updates to fix for that CVE/USN.
In this case, `pro fix` will tell you which package(s) it can or cannot fix.
In the example, we install a package so we can run `pro fix` against it to
demonstrate this scenario.
```bash
$ sudo apt-get install expat=2.1.0-7 swish-e matanza ghostscript
```
Now, you can run the following command:
```bash
$ sudo pro fix CVE-2017-9233
```
And you will see the following output:
```text
CVE-2017-9233: Expat vulnerability
- https://ubuntu.com/security/CVE-2017-9233
3 affected source packages are installed: expat, matanza, swish-e
(1/3, 2/3) matanza, swish-e:
Ubuntu security engineers are investigating this issue.
(3/3) expat:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y expat }
2 packages are still affected: matanza, swish-e
✘ CVE-2017-9233 is not resolved.
```
We can see that two packages, `matanza` and `swish-e`, don’t have any fixes
available, but there is one for `expat`. So, we install the fix for `expat`
and at the end of the report we can see that some packages are still affected.
As before, we can also observe that in this scenario we mark the CVE/USN as not
resolved.
## Success!
Congratulations! You have learned about the various scenarios that `pro fix`
might encounter to be ready to understand what is happening when using it in a
variety of situations.
### Next steps
There are further options to control what exactly will happen when
running `pro fix`, read about them in:
* [How to know what the fix command would change](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_what_the_fix_command_would_change.md#pro-fix-dry-run)
* [How to skip fixing related USNs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_not_fix_related_usns.md#pro-fix-skip-related)
If you need more information about this, please feel free to reach out
to the Ubuntu Pro Client team on `#ubuntu-server` on
Libera IRC – we’re happy to help!
Alternatively, if you have a GitHub account, click on the “Give feedback”
link at the top of this page to leave us a message. We’d love to hear from you!
# index.html.md
# Ubuntu Pro-related MOTD messages
When the Ubuntu Pro Client (`pro`) is installed on the system, it delivers
custom messages on [“Message of the Day”](https://wiki.debian.org/motd) (MOTD). Those messages are generated
directly by three different sources.
* [MOTD about available updates]()
* [MOTD about important subscription conditions]()
* [MOTD about ESM being available]()
## MOTD about available updates
The [update-notifier](https://wiki.ubuntu.com/UpdateNotifier) delivers a script via the `update-notifier-common`
package called `/usr/lib/update-notifier/apt_check.py`. With regards to
Ubuntu Pro, this script is responsible for:
* Informing the user about the status of one of the ESM services; `esm-apps`
if the machine is an LTS series, or `esm-infra` if the series is in ESM
mode.
* Showing the number of `esm-infra` or `esm-apps` packages that can be
upgraded on the machine.
`update-notifier` has always added information about potential updates to
MOTD to raise user awareness. With the advent of Ubuntu Pro they are
just more differentiated.
Note that if you run `apt_check.py` directly it might give you rather
unreadable output as it is meant for program use. You can add the
`--human-readable` flag to see the information as it would be presented in
MOTD.
### Machine is unattached
On a machine that runs an Ubuntu release for which the `esm-apps` service
is available, but not yet attached to an Ubuntu Pro subscription, there will
be a message notifying the user that there may be more security updates
available through ESM Apps.
```text
Expanded Security Maintenance for Applications is not enabled.
0 updates can be applied immediately.
Enable ESM Apps to receive additional future security updates.
See https://ubuntu.com/esm or run: sudo pro status
```
### Machine is fully attached
In the opposite situation, if an LTS machine has the `esm-infra` and
`esm-apps` services enabled then users will see the following output in MOTD:
```text
Expanded Security Maintenance for Applications is enabled.
11 updates can be applied immediately.
5 of these updates are ESM Apps security updates.
1 of these updates is a ESM Infra security update.
5 of these updates are standard security updates.
To see these additional updates run: apt list --upgradable
```
### Machine is fully attached, on an older release
Above, you have seen examples of recent (as in “still in their first 5
years of support”) Ubuntu releases, where the hint is about ESM Apps
extending the coverage to the ‘universe’ repositories.
However, if running on an Ubuntu release that is already past the initial
5 years of support and has thereby entered Expanded Security Maintenance
([ESM](https://ubuntu.com/security/esm)), we would instead see `esm-infra` (which provides coverage
for another 5 years) being shown:
```text
Expanded Security Maintenance Infrastructure is enabled.
11 updates can be applied immediately.
5 of these updates are ESM Apps security updates.
1 of these updates is a ESM Infra security update.
5 of these updates are standard security updates.
To see these additional updates run: apt list --upgradable
```
### Partial service enablement
Now let’s consider a scenario where one of these services is not enabled. For
example, if `esm-apps` was disabled, the output will be:
```text
Expanded Security Maintenance for Applications is not enabled.
6 updates can be applied immediately.
1 of these updates is a ESM Infra security update.
5 of these updates are standard security updates.
To see these additional updates run: apt list --upgradable
5 additional security updates can be applied with ESM Apps
Learn more about enabling ESM Apps for Ubuntu 16.04 at
https://ubuntu.com/16-04
```
At the end of the output we can see the number of packages that *could* be
upgraded if that service was enabled. Note that we would deliver the same
information for `esm-infra` if the service was disabled and the series
running on the machine is in ESM state.
## MOTD about important subscription conditions
One of the [timer jobs](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_the_timer_jobs.md#expl-timer-jobs) Ubuntu Pro uses can insert
additional messages into MOTD.
These messages will be always delivered next to the content created by
`update-notifier`. These additional messages are generated when `pro`
detects that certain conditions on the machine have been met. They are:
### Subscription expired
When the Ubuntu Pro subscription is expired, `pro` will deliver the following
message after the `update-notifier` message:
```text
*Your Ubuntu Pro subscription has EXPIRED*
2 additional security update(s) require Ubuntu Pro with 'esm-infra' enabled.
Renew your service at https://ubuntu.com/pro
```
### Subscription about to expire
When the Ubuntu Pro subscription is about to expire, we deliver the following
message after the `update-notifier` message:
```text
CAUTION: Your Ubuntu Pro subscription will expire in 2 days.
Renew your subscription at https://ubuntu.com/pro to ensure continued security
coverage for your applications.
```
### Subscription expired but within grace period
When the Ubuntu Pro subscription has expired, but is still within the grace
period, we deliver the following message after the `update-notifier` script:
```text
CAUTION: Your Ubuntu Pro subscription expired on 10 Sep 2021.
Renew your subscription at https://ubuntu.com/pro to ensure continued security
coverage for your applications.
Your grace period will expire in 9 days.
```
## MOTD about ESM being available
When Ubuntu Pro became generally available, a temporary announcement was made
through MOTD. This was intended to raise awareness of Pro now being available
and free for personal use, and was shown on systems that could be covered
by `esm-apps`.
It looked like:
```text
* Introducing Expanded Security Maintenance for Applications.
Receive updates to over 25,000 software packages with your
Ubuntu Pro subscription. Free for personal use.
https://ubuntu.com/pro
```
Since this message was intended as a limited-time announcement to coincide
with the release of Ubuntu Pro into general availability, it was removed in
version 27.14.
## How are these messages inserted into MOTD and how can I disable them?
Just as there are different purposes to the messages outlined above,
there are different sources producing these MOTD elements that one
sees at login.
Those messages are considered important to ensure user awareness about
the free additional security coverage provided by Ubuntu Pro and about
not-yet-applied potential updates in general. Therefore it is generally not
recommended to disable them. But still, you can selectively disable them
by removing the config files that add them, as outlined below.
Removing those files is considered a conffile change to customize a program
and they will stay removed even on future upgrades or re-installations of the
related packages.
If you realize that you actually need them back you need
to reinstall the related packages and tell `apt` / `dpkg` to offer you to
restore those files via:
```bash
sudo apt install --reinstall -o Dpkg::Options::="--force-confask" ubuntu-pro-client update-notifier-common
```
## Source: MOTD about available updates
1. `update-notifier-common` has a hook
(`/etc/apt/apt.conf.d/99update-notifier`) that runs after `apt update`.
2. That hook will update the information in
`/var/lib/update-notifier/updates-available` matching the new package
information that was just fetched by using
`/usr/lib/update-notifier/apt-check --human-readable`.
3. At MOTD generation time, the script located at
`/etc/update-motd.d/90-updates-available` checks if
`/var/lib/update-notifier/updates-available` exists and if it does,
inserts the message into the full MOTD.
If you want to remove the messages about Ubuntu Pro and ESM from the MOTD
output, but still want to keep the messages about the regular and security
updates, create a file named `/var/lib/update-notifier/hide-esm-in-motd`.
There is no need for any content in the file - its existence is enough to
tell update-notifier, and the Pro Client, to suppress the messages.
Keep in mind that the change in the MOTD message may take some time - if you
want to remove the ESM related messages immediately, create the file and run
the script which generates the messages using `--force`:
```bash
$ sudo /usr/lib/update-notifier/update-motd-updates-available --force
```
If you want to disable all messages from update-notifier (not just related to
Ubuntu Pro and ESM) about potentially available updates, just remove the
`/etc/update-motd.d/90-updates-available` file.
## Source: MOTD about important subscription conditions
1. The subscription status is checked periodically in the background when the
machine is attached to an Ubuntu Pro subscription.
2. If one of the above conditions applies to the subscription that the machine
is attached to (there are no messages generated by this for unattached
machines), then the message is stored in
`/var/lib/ubuntu-advantage/messages/motd-contract-status`.
3. At MOTD generation time, the script located at
`/etc/update-motd.d/91-contract-ua-esm-status` checks if
`/var/lib/ubuntu-advantage/messages/motd-contract-status` exists and if
it does, inserts the message into the full MOTD.
If you want to disable any message about important conditions of your
attached subscription, remove `/etc/update-motd.d/91-contract-ua-esm-status`.
## Source: MOTD about ESM being available
1. `pro` checks regularly if a system would have `esm-apps` available to
it, and if so, places a message in
`/var/lib/ubuntu-advantage/messages/motd-esm-announce`.
2. At MOTD generation time, the script located at
`/etc/update-motd.d/88-esm-announce` checks if
`/var/lib/ubuntu-advantage/messages/motd-esm-announce` exists and if it
does, inserts the message into the full MOTD.
If you want to disable the ESM announcement, remove
`/etc/update-motd.d/88-esm-announce` (or upgrade to `pro` version 27.14 or
later, which will remove it for you).
# index.html.md
# How to interpret the output of CVE commands
## pro cves
In the Pro Client version 35, we introduce the `pro cves` command.
This command will display all of installed packages that are affected
by a CVE. This can be better visualized in the following example:
```text
Package Priority Origin Vulnerability
firefox medium esm-infra CVE-2020-6852
openssh low standard CVE-2021-3188
openssh low standard CVE-2020-1288
openssh low standard CVE-2020-1290
openssh-client low esm-apps CVE-2021-3188
openssh-client low standard CVE-2020-1288
openssh-client low standard CVE-2020-1290
python3-apt medium esm-infra CVE-2020-6852
vim critical esm-infra CVE-2011-3374
vim high standard CVE-2011-3380
vim-tiny high - CVE-2011-3380
vim-tiny low - CVE-2011-3380
```
We can see that the table is oriented per-package. Additionally, we can see that
the table will have a line for each CVE that affects an installed package. For example,
**openssh** is affected by three distinct CVEs and because of that, it has three rows in
the table.
With that said, the table will always contain four headers:
* **Package**: The name of the package affected by a CVE
* **Priority**: The ubuntu priority for the CVE
* **Origin**: The ubuntu pocket where the fix can be found:
: * **esm-infra**: Fix is available on the esm-infra pocket. This means that user must have esm-infra service enabled through Pro in the machine to access it
* **esm-apps**: Fix is available on the esm-apps pocket. This means that user must have esm-apps service enabled through Pro in the machine to access it
* **fips**: Fix is available on the fips pocket. This means that user must have fips service enabled through Pro in the machine to access it
* **fips-updates**: Fix is available on the fips-updates pocket. This means that user must have fips-updates service enabled through Pro in the machine to access it
* **standard**: Fix is available on the ubuntu security or updates pocket
* **-**: No fix is available for this CVE
* **Vulnerability**: The name of the CVE
It is also important to say that the table is ordered by **Package** and **Priority**.
### What if no CVEs affect the system
If no CVEs affect the system, the command will display the following message:
```text
No CVES found that affect this system
```
### Supported flags
The command support two flags:
* **–unfixable**: Show only unfixable CVEs
* **–fixable**: Show only fixable CVEs
## pro cve
If you suspect that a CVE affects your system and wants to verify
if that is true, you can use the `pro cve` command for this.
This command will show you all the related information to a CVE **if** it affects
your Ubuntu release.
For example, let’s assume that `CVE-2022-2286` affects your system and you run:
```bash
pro cve CVE-2024-5480
```
You will see an output similar to this one:
```text
name: CVE-2024-5480
public-url: https://ubuntu.com/security/CVE-2024-5480
published-at: 2024-05-26
cve-cache-date: 2024-11-27
apt-cache-date: 2024-11-25
priority: critical
cvss-score: 9.8
cvss-severity: urgent
description: |
Systems with microprocessors utilizing speculative execution and indirect branch
prediction may allow unauthorized disclosure of information to an attacker with
local user access via a side-channel analysis of the data cache.
notes:
- mdeslaur> requires sourcing a vim commands file or similar
affected-packages:
firefox: available (esm-infra) 1.2.3~esm1
python3: available (standard) 1.5
vim: deferred
related-usns:
USN-6841-1: PHP vulnerability
USN-6839-1: MariaDB vulnerability
```
Let’s break it down the output of this command. We start by telling you some basic information for
the CVE:
* **name**: The CVE name
* **public-url**: The ubuntu dedicated CVE page
* **published-at**: The published date of the CVE
* **cve-cache-date**: The date of the local CVE data source cache
* **apt-cache-date**: The last time the APT state was updated in the system
(i.e. running an apt install operation)
* **priority**: The ubuntu priority for this CVE
* **cvss-score**: The CVSS score of the CVE
* **cvss-severity**: The CVSS severity of the CVE
* **description**: The CVE description
* **notes**: The CVE related notes
The next block is now displaying which installed packages in the machine are affected by the CVE,
in the format:
```text
affected-packages:
firefox: available (esm-infra) 1.2.3~esm1
python3: available (standard) 1.5
vim: deferred
```
If the package has a fix available, we will use the format:
```text
affected-packages:
firefox: available (esm-infra) 1.2.3~esm1
```
This line can be broke down into four distinct fields:
* **name**: The package name
* **status**: The CVE fix status for that package
* **origin**: The CVE fix origin
* **version**: The package version that will fix the CVE for that package
And if the package doesn’t have a fix available, we will use the format:
```text
affected-packages:
vim: deferred
```
Where the line will only contain the package name and the CVE status for it
Finally, we also display the related USNs to the CVE:
```text
related-usns:
USN-6841-1: PHP vulnerability
USN-6839-1: MariaDB vulnerability
```
### What if the CVE doesn’t affect my system ?
If the CVE doesn’t affect your system, The **affected-packages** field will be displayed like this:
```text
affected-packages: []
```
Which means that no installed packages are affected by the CVE.
### What if the CVE doesn’t affect my Ubuntu release ?
If the CVE doesn’t affect the Ubuntu release you are running own, that means
that our CVE source data will not contain any information about it. Therefore,
the command will display the following output:
```text
CVE-2025-26520 doesn't affect Ubuntu 16.04.
For more information, visit: https://ubuntu.com/security/CVE-2025-26520
```
In this example, the CVE-2025-26520 doesn’t affect the Xenial Ubuntu release (Ubuntu 16.04).
# index.html.md
# What data is collected from active Ubuntu Pro machines?
If a machine is attached to an Ubuntu Pro subscription, the following data is
collected and updated regularly (default: every 6 hours).
- Distribution (e.g. “Ubuntu”)
- Release codename (e.g. “Noble”)
- Kernel version (e.g. “6.8.0-38.38-generic”)
- Machine architecture (e.g. “amd64”)
- CPU Information (e.g.:
```default
{
cpuinfo_cpu_family='6',
cpuinfo_model='140',
cpuinfo_model_name='11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz',
cpuinfo_stepping='1',
cpuinfo_vendor_id='GenuineIntel'
}
```
- Is the machine a desktop? (e.g. “true”)
- Virtualization type (e.g. “Docker”)
- Services enabled (e.g. “ros” and “realtime-kernel generic variant”)
- When the machine was attached (e.g. “2024-07-24T13:54:07+00:00”)
- Version of `ubuntu-pro-client` (e.g. “33.2~24.04”)
These data elements are collected to ensure machines that are attached to a
particular Ubuntu Pro contract are compliant with the terms of that particular
contract.
## Data sent to provide service
The following data is not purposefully collected, but is sent to Canonical
servers in order to provide Ubuntu Pro services.
### APT package downloads
If you have any of the following services enabled, then the data collection
method described below will be in use whenever downloading packages for one of
these services.
- `anbox-cloud`
- `cc-eal`
- `cis`
- `esm-apps`
- `esm-apps-legacy`
- `esm-infra`
- `esm-infra-legacy`
- `fips`
- `fips-preview`
- `fips-updates`
- `realtime-kernel`
- `ros`
- `ros-updates`
- `usg`
Whenever you `apt install` a package from a Pro service (or `apt upgrade`
to a version of a package from a Pro service), `apt` will make a GET request
to `esm.ubuntu.com` that includes the package name and version, and HTTP
basic authentication credentials that are tied to the Ubuntu Pro subscription.
For example, installing the `hello` package from `esm-apps` will result in
a request that looks something like this:
```text
https://bearer:$resource_token@esm.ubuntu.com/apps/ubuntu/pool/main/h/hello/hello_2.10-2ubuntu4+esm1_amd64.deb
```
This request is necessary to download the Pro update and includes the
following data.
- Ubuntu codename (e.g. “Jammy”)
- Package name (e.g. “hello”)
- Package version (e.g. “2.10-2ubuntu4+esm1”)
- Package architecture (e.g. “amd64”)
Because this request needs to be authenticated and the authentication token is
tied to a particular Ubuntu Pro subscription, this data is inherently tied to
the Ubuntu Pro subscription that authenticated access to the package.
### Livepatch downloads
If you have `livepatch` enabled, then the following data is sent in order to
download the correct kernel patches:
- Kernel version (e.g. “6.8.0-38.38-generic”)
- Machine architecture (e.g. “amd64”)
Similarly to APT package downloads, because this request needs to be
authenticated and the authentication token is tied to a particular Ubuntu Pro
subscription, this data is inherently tied to the Ubuntu Pro subscription that
authenticated access to the package.
# index.html.md
# What does `security-status` do?
The `security-status` command provides an overview of all the packages
installed on your machine, and the security coverage that applies to those
packages.
The output of the `security-status` command varies, depending on the
configuration of the machine you run it on. In this article, we’ll take a look
at the different outputs of `security-status` and the situations in which
you might see them.
## Command output
If you run the `pro security-status` command, the first blocks of information
you see look like:
```text
2871 packages installed:
2337 packages from Ubuntu Main/Restricted repository
504 packages from Ubuntu Universe/Multiverse repository
8 packages from third parties
22 packages no longer available for download
To get more information about the packages, run
pro security-status --help
for a list of available options.
```
Those are counts for the `apt` packages installed in the system, sorted
between the packages in main, universe, third party packages, and packages
that are no longer available. You will also see a hint to run
`pro security-status --help` to get more information.
### `apt update` reminder
To get accurate package information, the `apt` caches must be up to date. If
your cache was not updated recently, you may see a message in the output with
a reminder to update.
```text
The system apt cache may be outdated. Make sure to run
sudo apt-get update
to get the latest package information from apt.
```
### LTS coverage
If `esm-infra` is disabled in your system, main/restricted packages will be
covered during the LTS period - this information is presented right after the
hints. A covered system will present this message:
```text
This machine is receiving security patching for Ubuntu Main/Restricted
repository until .
```
On a system where the LTS period ended, you’ll see:
```text
This machine is NOT receiving security patches because the LTS period has ended
and esm-infra is not enabled.
```
### Ubuntu Pro coverage
An Ubuntu Pro subscription provides more security coverage than a standard LTS.
The next blocks of information are related to Ubuntu Pro itself:
```text
This machine is attached to an Ubuntu Pro subscription.
Main/Restricted packages are receiving security updates from
Ubuntu Pro with 'esm-infra' enabled until 2032.
Universe/Multiverse packages are receiving security updates from
Ubuntu Pro with 'esm-apps' enabled until 2032. You have received 21 security
updates.
```
This system is already attached to Pro! It is a Jammy machine, which has
installed some updates from `esm-apps`. Running the same command on a Xenial
system without Pro enabled, the output looks like:
```text
This machine is NOT attached to an Ubuntu Pro subscription.
Ubuntu Pro with 'esm-infra' enabled provides security updates for
Main/Restricted packages until 2026. There are 170 pending security updates.
Ubuntu Pro with 'esm-apps' enabled provides security updates for
Universe/Multiverse packages until 2026. There is 1 pending security update.
Try Ubuntu Pro with a free personal subscription on up to 5 machines.
Learn more at https://ubuntu.com/pro
```
There are lots of `esm-infra` updates for this machine, and even an
`esm-apps` update. The hint in the end of the output has a link to the main
Pro website, so the user can learn more about Pro and get their subscription.
### Interim releases
If you are running an interim release, the output is slightly different because
there are no Ubuntu Pro services available. You will still see the package
counts and support period though - your main/restricted packages are supported
for 9 months from the release date.
```text
613 packages installed:
601 packages from Ubuntu Main/Restricted repository
12 packages from Ubuntu Universe/Multiverse repository
To get more information about the packages, run
pro security-status --help
for a list of available options.
Main/Restricted packages receive updates until 1/2024.
Ubuntu Pro is not available for non-LTS releases.
```
### Optional flags for specific package sets
Some flags can be passed to `security-status` to get information about
coverage of specific package sets. As an example, let’s look at the output of
`pro security-status --esm-infra`:
```text
442 packages installed:
441 packages from Ubuntu Main/Restricted repository
Main/Restricted packages are receiving security updates from
Ubuntu Pro with 'esm-infra' enabled until 2026. You have received 3 security
updates. There are 160 pending security updates.
Run 'pro help esm-infra' to learn more
Installed packages with an available esm-infra update:
( ... list of packages ... )
Installed packages with an esm-infra update applied:
( ... list of packages ... )
Further installed packages covered by esm-infra:
( ... list of packages ... )
For example, run:
apt-cache show tcpdump
to learn more about that package.
```
Besides the support information of main/restricted (which Ubuntu Pro with
`esm-infra` extends) there are lists of:
- Packages with an updated version available in ESM-infra repositories
- Packages with a version installed from the ESM-infra repositories
- Packages which are covered by ESM-infra
You will see a similar output when running `pro security-status --esm-apps`,
but with information regarding universe/multiverse packages.
You can also get a list of the third-party packages installed in the system:
```text
$ pro security-status --thirdparty
2871 packages installed:
8 packages from third parties
Packages from third parties are not provided by the official Ubuntu
archive, for example packages from Personal Package Archives in Launchpad.
Packages:
( ... list of packages ... )
For example, run:
apt-cache show
to learn more about that package.
```
And also a list of unavailable packages (which no longer have any installation
source):
```text
$ pro security-status --unavailable
2871 packages installed:
22 packages no longer available for download
Packages that are not available for download may be left over from a
previous release of Ubuntu, may have been installed directly from a
.deb file, or are from a source which has been disabled.
Packages:
( ... list of packages ... )
For example, run:
apt-cache show
to learn more about that package.
```
## Machine-readable output
If you need a machine readable version of `pro security-status`, you can use
these API endpoint to achieve that:
* [u.pro.packages.summary.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-packages-summary-v1)
* [u.pro.packages.updates.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-packages-updates-v1)
* [u.pro.status.is_attached.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-status-is-attached-v1)
* [u.pro.status.enabled_services.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-status-enabled-services-v1)
* [u.pro.security.status.livepatch_cves.v1](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-security-status-livepatch-cves-v1)
### `u.pro.packages.summary.v1`
This API is responsible for providing a summary of where all the installed packages
in the machine comes from.
When called through `pro api u.pro.packages.summary.v1`, it will produce a data output
with the following structure:
```js
{
"summary":{
"num_installed_packages": 1,
"num_esm_apps_packages": 2,
"num_esm_infra_packages": 3,
"num_main_packages": 4,
"num_multiverse_packages": 5,
"num_restricted_packages": 6,
"num_third_party_packages": 7,
"num_universe_packages": 8,
"num_unknown_packages": 9,
},
}
```
The summary object contains the following fields:
* **num_installed_packages**: The total number of installed packages on the
system.
* **num_esm_apps_packages**: The number of packages installed from
`esm-apps`.
* **num_esm_infra_packages**: The number of packages installed from
`esm-infra`.
* **num_main_packages**: The number of packages installed from the `main`
archive component.
* **num_multiverse_packages**: The number of packages installed from the
`multiverse` archive component.
* **num_restricted_packages**: The number of packages installed from the
`restricted` archive component.
* **num_third_party_packages** : The number of packages installed from
`third party` sources.
* **num_universe_packages**: The number of packages installed from the
`universe` archive component.
* **num_unknown_packages**: The number of packages installed from sources not
known to `apt` (e.g., those installed locally through `dpkg` or packages
without a remote reference).
### `u.pro.packages.updates.v1`
This API is responsible for listing the available package updates in the system.
When called through `pro api u.pro.packages.updates.v1`, it will produce a data output
with the following structure:
```js
{
"summary": {
"num_updates": 15,
"num_esm_apps_updates": 2,
"num_esm_infra_updates": 3,
"num_standard_security_updates": 5,
"num_standard_updates": 5,
},
"updates": [
{
"download_size": 6,
"origin": "",
"package": "",
"provided_by": "",
"status": "",
"version": "",
},
]
}
```
Note that there are two distinct object in the JSON response, **summary** and **updates**.
The summary object will contain the following attributes:
* **num_updates**: The total number of available updates to the system.
* **num_esm_apps_updates**: The number of `esm-apps` package updates
available to the system.
* **num_esm_infra_updates**: The number of `esm-infra` package updates
available to the system.
* **num_standard_security_updates**: The number of standard security updates
available to the system.
* **num_standard_updates**: The number of standard updates available to the system.
While the updates object will be a list of package updates, where each update object
will contain the following attributes:
* **download_size**: The number of bytes that would be downloaded in order to
install the update.
* **origin**: The host where the update comes from.
* **package**: The name of the package.
* **provided_by**: The service that provides the package update. It can be
one of: `esm-infra`, `esm-apps` or `standard-security`.
* **status**: The status for this update. It will be one of:
* **“upgrade_available”**: The package can be upgraded right now.
* **“upgrade_available_not_preferred”**: The package can be upgraded but the
upgrade will not automatically selected by APT or other tools due to
lower pinning or the existence of a higher-priority candidate.
* **“pending_attach”**: The package needs an Ubuntu Pro subscription attached
to be upgraded.
* **“pending_enable”**: The machine is attached to an Ubuntu Pro subscription,
but the service required to provide the upgrade is not enabled.
* **“upgrade_unavailable”**: The machine is attached, but the contract is not
entitled to the service which provides the upgrade.
* **version**: The update version.
### `u.pro.status.is_attached.v1`
This API is responsible for telling if the system is attached to a Pro subscription
When called through `pro api u.pro.status.is_attached.v1`, it will produce a data output
with the following structure:
```js
{
"contract_remaining_days": 360,
"contract_status": "active",
"is_attached": true,
"is_attached_and_contract_valid": true
}
```
The JSON response object will contain the following fields:
* **contract_remaining_days**: The number of days left in the Ubuntu Pro subscription
* **contract_status**: The status of the Ubuntu Pro subscription:
* **active**: The contract is currently valid.
* **grace-period**: The contract is in the grace period. This means that
it is expired, but there are still some days where the contract will be
valid.
* **active-soon-to-expire**: The contract is almost expired, but still
valid.
* **expired**: The contract is expired and no longer valid.
* **is_attached**: true if the machine is attached to an Ubuntu Pro subscription
* **is_attached_and_contract_valid**: true if the machine is attached to an Ubuntu
Pro subscription and that subscription is not expired
### `u.pro.status.enabled_services.v1`
This API is responsible for telling which services are enabled in the machine.
When called through `pro api u.pro.status.enabled_services.v1`, it will produce a data output
with the following structure:
```js
{
"enabled_services": [
{
"name": "esm-apps",
"variant_enabled": false,
"variant_name": null
},
{
"name": "esm-infra",
"variant_enabled": false,
"variant_name": null
},
{
"name": "realtime-kernel",
"variant_enabled": true,
"variant_name": "raspi"
}
]
}
```
You can see that the JSON response has an object named **enabled_services** that is a list
of services that are enabled in the machine. Each enabled service has these attributes:
* **name**: The name of the service.
* **variant_enabled**: true if a variant of the service was enable.
* **variant_name**: The variant name if **variant_enabled** is true, **null** otherwise.
### `u.pro.security.status.livepatch_cves.v1`
This endpoint lists Livepatch patches for the currently-running kernel.
When called through `pro api u.pro.security.status.livepatch_cves.v1`, it will
produce a data output with the following structure:
```js
{
"fixed_cves":[
{
"name": "",
"patched": true
},
{
"name": "",
"patched": false
},
]
}
```
You can see that the JSON response has an object named **fixed_cves** that is a list
of CVEs that are addressed by the current Livepatch patch. Each CVE object will have the
following attributes:
* **name**: The name of the CVE.
* **patched**: true if a CVE was patched by Livepatch patch, false otherwise.
# index.html.md
# How to interpret the output of the fix plan API endpoint
In the Pro Client version 29, we introduce two distinct endpoints:
* `u.pro.security.fix.cve.plan.v1`
* `u.pro.security.fix.usn.plan.v1`
These endpoints can be used to verify the needed steps for fixing a list of
[CVEs/USNs](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn). When using the CVE endpoint, the expected
output is as follows:
```json
{
"_schema_version": "v1",
"data": {
"attributes": {
"cves_data": {
"cves": [
{
"additional_data": {},
"error": null,
"expected_status": "EXPECTED_STATUS",
"plan": [
{
"data": {
"binary_packages": [
"package"
],
"source_packages": [
"package"
],
"pocket": "standard-updates"
},
"operation": "apt-upgrade",
"order": 1
}
],
"title": "CVE-2017-9233",
"warnings": []
}
],
"expected_status": "EXPECTED_STATUS"
}
},
"meta": {
"environment_vars": []
},
"type": "CVEFixPlan"
},
"errors": [],
"result": "success",
"version": "29",
"warnings": []
}
```
From this output, we can see that the **cves_data** object contains two
attributes:
* **cves**: A list of CVE objects containing the plan for fixing each of them.
* **expected_status**: The expected status of the fix operation considering
**all** CVEs. This means that if one CVE cannot be fixed, this field will
reflect that.
If we take a look at a CVE object, we will see the following structure:
* **title**: The title of the CVE.
* **error**: Any error captured when creating the CVE plan will appear here.
The error object will be detailed in a following section.
* **current_status**: The current status of the CVE showing if the system is
currently affected by the CVE before the plan is executed.
* **expected_status**: The expected status of the CVE if the plan was to be
executed. There are three possible scenarios: **fixed**, **still-affected**
and **not-affected**.
The system is considered **still-affected** if there is something that
prevents any required packages from being upgraded. The system is considered
**not-affected** if the CVE doesn’t affect the system at all.
* **plan**: The plan that would need to be executed to fix the CVE. We will
detail each possible plan step in a following section.
* **warnings**: Warnings that can happen when generating the plan. For example,
if the CVE doesn’t have a fix available for a given package, this will be
reflected here. We will detail the possible warnings in a following section.
* **additional_data**: Additional data for the CVE being fixed. Currently,
this field is only being used by USNs, where we deliver which CVEs and
Launchpad bugs are associated with the USN.
## What operations can appear in the plan array?
The plan array details all of the necessary operations that need to take place
to fix the CVE. Note that there are some situations where a CVE cannot be fully
fixed. If that happens, the **warnings** fields will be populated with objects
describing what prevents the CVE from fully being fixed.
Since the plan array is composed of operations, it is important to understand
each one of them. There are four distinct operations that can appear in the
plan array, they are:
### APT upgrade
This operation details which package (or packages) would need to be upgraded
to fix the CVE. The JSON representation for this step is:
```json
{
"data": {
"binary_packages": ["binary_package"],
"source_packages": ["source_package"],
"pocket": "standard-updates"
},
"operation": "apt-upgrade",
"order": 1
}
```
This step provides all the binary and source packages that need to be upgraded
through the **data** object.
### Attach
This operation informs that the user will need to attach to a Pro subscription.
The JSON representation for this step is:
```json
{
"data": {
"reason": "required-pro-service",
"source_packages": ["source_package"],
"required_service": "esm-infra"
},
"operation": "attach",
"order": 1
}
```
The `reason` field details why an attach is needed. This can be either
because the user has an expired subscription or the fix requires a specific Pro
service to upgrade an affected package.
### Enable
This operation details that the user needs to enable a specific Pro service.
The JSON representation for this step is:
```json
{
"data": {
"service": "esm-infra",
"source_packages": ["source_package"]
},
"operation": "enable",
"order": 1
}
```
The **data** object contains the name of the service that needs to be enabled.
### No-Op
This indicates that no operations need to be performed to address the CVE.
The JSON representation for this step is:
```json
{
"data": {
"status": "system-not-affected"
},
"operation": "no-op",
"order": 1
}
```
The **data** object will state why no operation is needed. This can either be
because the CVE doesn’t affect the system, or because the CVE is already fixed
in the machine.
#### NoOpAlreadyFixed
This is a sub-type of a No-Op step that indicates that the CVE is already
fixed in the machine. The JSON representation for this step is:
```json
{
"data": {
"status": "cve-already-fixed"
"pocket": "standard-updates",
"source_packages": ["source_package"]
},
"operation": "no-op",
"order": 1
}
```
The `data` object will state which packages are already fixed and which
pocket they come from.
#### NoOpLivepatchFixData
This is a sub-type of a No-Op step that indicates that the CVE is already
fixed by a patch from Livepatch. The JSON representation for this step is:
```json
{
"data": {
"status": "cve-fixed-by-livepatch",
"patch_version": "87.1"
},
"operation": "no-op",
"order": 1
}
```
The `data` object will state the patch version that fixed the CVE.
## What warnings can be generated?
There are two distinct warnings that can happen when executing the plan API:
### Package cannot be installed
This happens when the endpoint identifies that a given package cannot be
installed (i.e. the user lacks a required APT source in the machine). This can
be seen in the following JSON representation:
```json
{
"data": {
"binary_package": "binary_package",
"binary_package_version": "3.5.12-1ubuntu7.16",
"source_package": "source_package",
"pocket": "standard-updates"
},
"order": 1,
"warning_type": "package-cannot-be-installed"
}
```
The **data** object details the package that cannot be installed, the package
version, and the pocket it comes from.
### Security issue not fixed
This happens when the CVE doesn’t provide a fix for some of the affected
packages. This can be seen in the following JSON representation:
```json
{
"data": {
"source_packages": ["source_package"],
"status": "needs-triage"
},
"order": 1,
"warning_type": "security-issue-not-fixed"
}
```
## What errors can be generated?
There are two errors that can occur when running this API endpoint. These
errors happen either when a CVE has an invalid format, or if it doesn’t exist.
When an error happens, it will be described by the following JSON
representation:
```json
{
"code": "security-fix-not-found-issue",
"msg": "Error: CVE-XXXX-XXXXX not found."
}
```
## Why do we need the order attribute?
The order attribute is used to help the user to properly understand the exact
sequence of events that will happen when the fix is performed. This is
particularly true for situations where we have warnings that are held outside
the plan object.
## What about the USN endpoint?
The structure, as described for CVEs, works in exactly the same way for a USN.
The only difference for the USN endpoint is how the USN object is represented.
This can be seen here:
```json
{
"usns": [
{
"related_usns_plan": [],
"target_usn_plan": {}
}
]
}
```
We can see that there is a distinction between the **target** USN and the
**related** USNs. To better understand that distinction, please refer to
[our explanation of CVEs and USNs](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn).
Finally, for USNs, we don’t have the `NoOpLivepatchFixData` option, since
these should only occur for CVEs.
# index.html.md
# CVEs and USNs explained
## What is a CVE
Common Vulnerabilities and Exposures (CVEs) are a way to catalog and track
public security vulnerabilities for a given software. Every CVE is identified
through a unique identifier, for example [CVE-2023-0465](https://www.cve.org/CVERecord?id=CVE-2023-0465).
CVEs are maintained by the [MITRE Corporation](https://cve.mitre.org/) and the goal of the project is
to provide naming conventions for the public known security issues while also
maintaining a centralized repository for all of the security issues. This makes
it easier for an organization to submit a new security flaw though the CVE
convention while also analyzing any other existing CVEs in the database.
You can search for any existing CVE related to Ubuntu using
[the Ubuntu CVE page](https://ubuntu.com/security/cves).
## What is a USN?
An Ubuntu Security Notice (USN) is the way that Canonical publicly catalogs
and displays security vulnerabilities for Ubuntu packages. Usually, a USN is
composed of one or more CVEs and it also contains update instructions to fix
the issue, if a fix is already available.
USNs follow a naming convention of the format [USN-5963-1](https://ubuntu.com/security/notices/USN-5963-1).
You can search for any existing USN using
[the Ubuntu Security Notices page](https://ubuntu.com/security/notices).
## What are related USNs?
A USN is composed of different CVEs. If the same CVE appears on multiple USNs,
we say that those USNs are related.
In the following image, we can see a visual representation of that concept,
where USN-789 and USN-321 are related USNs because both are affected by CVE-2:
A real example can be seen in [USN-5573-1](https://ubuntu.com/security/notices/USN-5573-1). In the section **Related
notices**, it shows that both **USN-5570-1** and **USN-5570-2** are related to
**USN-5573-1**.
This information is useful for users that want to tackle all related USNs at
once, making sure that a CVE is fully fixed on their Ubuntu machine.
Find out how to fix only a single USN and
[avoid fixing related ones](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_not_fix_related_usns.md#pro-fix-skip-related).
# index.html.md
# About Public Cloud Ubuntu Pro images
Ubuntu Pro images are published to [AWS](https://ubuntu.com/aws/pro), [Azure](https://ubuntu.com/azure/pro)
and [GCP](https://ubuntu.com/gcp/pro). All of these come with Ubuntu Pro support and services
built in.
On first boot, Ubuntu Pro images will automatically attach to an Ubuntu Pro
support contract and enable all necessary Ubuntu Pro services 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**,
and **Ubuntu Pro FIPS**.
## Ubuntu Pro
These Ubuntu LTS images are provided already attached to Ubuntu Pro support,
with kernel Livepatch and ESM security access enabled. Ubuntu Pro images are
entitled to enable any additional Ubuntu Pro services (like
[FIPS](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_fips.md#manage-fips) or [USG](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cis.md#manage-cis)).
## Ubuntu Pro FIPS
These specialized Ubuntu Pro images for 16.04, 18.04 and 20.04 come pre-enabled
with the cloud-optimized FIPS-certified kernel, as well as all additional SSL
and security hardening enabled. These images are available as
[AWS Ubuntu Pro FIPS](https://ubuntu.com/aws/fips),
[Azure Ubuntu Pro FIPS](https://ubuntu.com/azure/fips) and [GCP Ubuntu Pro FIPS](https://ubuntu.com/gcp/fips).
## The `ubuntu-pro-auto-attach` package
The `ubuntu-pro-auto-attach` package is used by
[Public Cloud Ubuntu Pro](#expl-about-pro-cpc) machines to automate the
process of attaching a machine on boot. This package ships a `systemd` unit
that runs an auto-attach command on first boot.
# index.html.md
# Ubuntu Pro-related APT messages
When running some APT commands, you might see Ubuntu Pro-related messages in
the output of those commands. Currently, we deliver those messages when
running either `apt upgrade` or `apt dist-upgrade`. The scenarios
where we deliver those messages are as follows.
## ESM series with ESM-infra service disabled
When you run `apt upgrade` on an ESM release, like Xenial, we advertise
the `esm-infra` service if packages could be upgraded by enabling the
service:
```text
Reading package lists... Done
Building dependency tree
Reading state information... Done
Calculating upgrade... Done
The following package was automatically installed and is no longer required:
libfreetype6
Use 'apt autoremove' to remove it.
The following security updates require Ubuntu Pro with 'esm-infra' enabled:
libpam0g libpam-modules openssl ntfs-3g git-man libsystemd0 squashfs-tools git openssh-sftp-server udev libpam-runtime isc-dhcp-common libx11-6 libudev1 apport python3-apport systemd-sysv liblz4-1 libpam-systemd systemd libpam-modules-bin openssh-server libx11-data openssh-client libxml2 curl isc-dhcp-client python3-problem-report libcurl3-gnutls libssl1.0.0
Learn more about Ubuntu Pro for 16.04 at https://ubuntu.com/16-04
```
## LTS series with ESM-apps service disabled
When you are running `apt upgrade` on a LTS release, like Focal, we advertise
the `esm-apps` service if packages could be upgraded by enabling the service:
```text
Reading package lists... Done
Building dependency tree
Reading state information... Done
Calculating upgrade... Done
The following package was automatically installed and is no longer required:
libfreetype6
Use 'apt autoremove' to remove it.
Get more security updates through Ubuntu Pro with 'esm-apps' enabled:
adminer editorconfig ansible
Learn more about Ubuntu Pro at https://ubuntu.com/pro
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
```
## ESM package count
If both ESM services are enabled on the system, we deliver a package count
related to each service near the end of the `apt` command:
```text
1 standard LTS security update, 29 esm-infra security updates and 8 esm-apps security updates
```
We only deliver this message if the service is enabled *and* we upgraded
packages related to it. For example, if we had no `esm-infra` package
upgrades, the message would be:
```text
1 standard LTS security update and 8 esm-apps security updates
```
## Expired contract
If we detect that your contract is expired, we will deliver the following
message advertising `esm-infra` in the middle of the `apt upgrade` command:
```text
#
# *Your Ubuntu Pro subscription has EXPIRED*
# 10 additional security update(s) require Ubuntu Pro with '{service}' enabled.
# Renew your service at https://ubuntu.com/pro
#
```
If we don’t have any `esm-infra`-related packages to upgrade, we show the
following message instead:
```text
#
# *Your Ubuntu Pro subscription has EXPIRED*
# Renew your service at https://ubuntu.com/pro
#
```
## Contract will expire soon
Similarly, if we detect that your contract is about to expire, we deliver the
following message in the middle of the `apt` command:
```text
#
# CAUTION: Your Ubuntu Pro subscription will expire in 2 days.
# Renew your subscription at https://ubuntu.com/pro to ensure continued
# security coverage for your applications.
#
```
## Contract has expired, but still in grace period
Additionally, if we detect that the contract has expired, but is still in the
grace period, the following message will be seen in the middle of the `apt`
command output:
```text
#
# CAUTION: Your Ubuntu Pro subscription expired on 10 Sep 2021.
# Renew your subscription at https://ubuntu.com/pro to ensure continued
# security coverage for your applications.
# Your grace period will expire in 11 days.
#
```
## How are the APT messages generated?
We have two distinct `apt` hooks that allow us to deliver these messages when
you run `apt upgrade` or `apt dist-upgrade`. They are:
### `apt-esm-hook`
Responsible for populating templates with accurate package counts (i.e. the
package count we see on the “Expired contract” messages). However, the
messaging here is created by two distinct steps:
1. Our [update_messages](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_the_timer_jobs.md#expl-timer-jobs) timer job creates
templates for the APT messages this hook will deliver. We cannot create the
full message on the timer job, because we need the accurate package names
and count. This information can only be obtained when running the `apt`
command.
#### NOTE
These templates will only be produced if certain conditions are met. For
example, we only produce “expired contract” templates if the contracts
are indeed expired.
2. When you run either `apt upgrade` or `apt dist-upgrade`, the hook
searches for these templates and if they exist, they are populated with the
correct `apt` content and delivered to the user.
### `apt-esm-json-hook`
The JSON hook is responsible for delivering the rest of the message we have
presented here.
This hook is used to inject the message in the exact place we want, so we need
to use a specific `apt` [JSON hook](https://salsa.debian.org/apt-team/apt/-/blob/main/doc/json-hooks-protocol.md) to communicate with it.
#### NOTE
Those hooks are only delivered on LTS releases. This is because the hooks
will not deliver useful messages on non-LTS releases due to the lack of
support for ESM services.
## How is APT configured to deliver those messages?
We currently ship with the package the `20apt-esm-hook.conf` configuration
file that configures both the basic `apt` hooks to call our `apt-esm-hook`
binary, and also the `json` API of `apt` to call our `apt-esm-json-hook`
binary.
# index.html.md
# Using Ubuntu Pro airgapped
Airgapping (or air gapping) is a security measure that involves isolating a
machine or network from external/unsecured networks to protect sensitive data.
The term “air gapping” is often used to mean one of two things:
* **“True” airgapped**
This describes a system operating fully offline or “internetless”. These
systems are completely self-contained. Ubuntu Pro can still be used in a fully
offline environment via an airgapped contract server and local mirrors. This
allows Ubuntu Pro tokens to be distributed across the isolated network, and
provides the security support and other benefits of Pro even without internet
access.
* **Firewalled deployment**
Although not *truly* airgapped, this refers to systems where network
connectivity is heavily limited. On-prem setups tend to fall under this
method, for example, with Livepatch On-prem – where updates are fetched from
the Canonical servers to a local machine. This provides more control over
when, how, and which updates are deployed.
## How do I sync Pro packages in an airgapped system?
No matter whether you are running a truly airgapped (offline) system, or one
that is heavily firewalled, running Ubuntu Pro airgapped is an advanced
use-case. The steps to achieve this are detailed in this
[guide on our support portal](https://support-portal.canonical.com/knowledge-base/Get-Started-With-Ubuntu-Pro-in-an-Airgapped-Environment). However, it is important to note that you will
need to have a paid subscription to Ubuntu Pro.
## What tools will I need?
Updating Ubuntu systems in a truly offline environment requires mirroring
Ubuntu repositories. Since Ubuntu packages can be consumed via deb packages
and/or snaps, the tool needed to mirror Ubuntu repositories depends on where
you source your packages from.
### Mirror deb repositories with Landscape
Landscape is a management tool that can host a mirror of Ubuntu deb
repositories. It can be used in both kinds of airgapped environments.
For more information, see Landscape’s documentation on how to
[install Landscape](https://documentation.ubuntu.com/landscape/how-to-guides/landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment/) and [manage repositories](https://documentation.ubuntu.com/landscape/how-to-guides/repository-mirrors/manage-repositories-in-an-air-gapped-or-offline-environment/) in an airgapped environment.
### Mirror snaps with Snap store proxy
The Snap store proxy is the equivalent tool for hosting the snap packages that
your organization is consuming.
[Snap-store-proxy](https://snapcraft.io/snap-store-proxy) is a snap that provides an edge proxy to the Snap store, so
that after your device has been registered with the proxy, all communications
with the Snap store will be sent via the proxy. This is part of the “firewalled”
deployment. Although online mode is the default for the Snap Store Proxy, it
can also [operate in offline mode](https://docs.ubuntu.com/snap-store-proxy/en/airgap), for true airgapped deployments.
## Security patching with Livepatch on-prem
Livepatch is the tool that provides patching for critical and high security
vulnerabilities in the Ubuntu kernel. It can also be used in a firewalled
setup using Livepatch on-prem.
[Livepatch on-prem](https://ubuntu.com/security/livepatch/docs/livepatch_on_prem) creates a local deployment of the Canonical Livepatch
server, which retrieves patch updates from Canonical. This provides you with
greater control over when those patches roll out across your infrastructure.
# index.html.md
# Disabling and purging services
All services enabled using the Pro Client can be disabled using the command
line with a command that follows this structure:
```bash
$ sudo pro disable
```
When you disable a service, the Pro Client will remove all access to that
specific service’s packages and sources in your system. However, only the
access is removed – the packages (debs, snaps) installed when the service was
enabled will remain installed on your system.
For example, the command:
```bash
$ sudo pro disable esm-apps
```
will remove the `sources.list` entry for `esm-apps`, and also the
authentication information that granted access to the packages. It will **not**
remove the debs installed from the `esm-apps` repository.
In the same way, the command:
```bash
$ sudo pro disable livepatch
```
disables the Livepatch service, but the `canonical-livepatch` snap will
remain installed on the system (although inactive).
If there are other services which depend on the service being disabled, those
need to be disabled too. A prompt in the CLI will list those services and ask
to disable them. The `--assume-yes` flag can be used to automatically accept
this prompt.
## What does `purge` mean in this context?
Disabling and **purging** a service has a similar effect to what is done by
[ppa-purge](https://launchpad.net/ppa-purge): it removes access to the sources (from where the service packages
are obtained), and then makes a best-effort attempt to downgrade those packages
back to their Ubuntu versions (the ones published in the Ubuntu Archive).
If a package is specific to the given service (`ubuntu-fips` for the
FIPS-related services, for example) then that package will be removed during
the purge process, when possible.
#### WARNING
The operation of reverting or uninstalling packages may leave the system in
an undesired state, due to packages not meeting dependencies (partial or
broken system caches) or due to the removal of kernels when alternative
kernels are not working properly. Therefore, the `purge` feature is aimed
at users/administrators who understand the impacts.
## Using the CLI to disable and purge a service
First of all, it is important to note that this is an **experimental feature**,
so although it is available it should be used with caution.
To purge a service, use the CLI command:
```bash
$ sudo pro disable --purge
```
We recommend only using purge when you are able to monitor the screen. Since
the purge feature has the potential to do serious accidental damage to a
system if used unattended (for example, in a script), the `--assume-yes` flag
was made incompatible with the `--purge` flag.
Since packages are being uninstalled/reinstalled, the execution of the
`disable` command with `--purge` may take a while to complete.
## What happens when I purge…
### livepatch, realtime-kernel, landscape
These services do not currently support the `--purge` operation.
### anbox, cc-eal, cis/usg, esm-apps, esm-infra\*, ros (and ros-updates)
When these services are disabled with `--purge`, the sources and
authentication will be removed first. Then, packages that are only available
in the service-specific APT repository will be removed from the system.
The origin is detected based on the `origin` metadata defined in `apt` for
all packages in this repository.
Then, for the packages that are also present in the Ubuntu archives, there will
be a downgrade to the highest possible version in the archive. Downgrade
operations are the most common because the packages for specific services
usually have higher version strings than their counterparts in the archive.
Note that purging a service often results in the installation of newer
versions of packages than were originally present in the system (i.e., before
the given service was enabled). It is important to use the latest versions
available in the archive to guarantee that dependency chains are resolved –
in other words, that there are no broken dependencies between packages.
#### NOTE
\* Disabling `esm-infra` with `--purge` *may* involve removing a
kernel, see below for more information.
### FIPS (and fips-updates/fips-preview)
In the case of FIPS-related services (and in some cases, `esm-infra`), there
is an extra consideration when purging the packages: there may be Linux kernel
packages among the ones to be removed or downgraded.
In this case, the Pro Client will look for at least one more kernel installed
in the system. This check is performed while examining the installed `apt`
packages, and matching the version strings to `vmlinu[z|x]` files in
`/boot`.
If no other kernel is found in the system, then the current kernel cannot be
removed. The Client will warn the user and abort the operation.
Kernels which are manually compiled and installed, or that are not shipped in
Ubuntu as APT packages will *not* be considered and validated.
If another Ubuntu kernel is found in the system, `--purge` will proceed to
remove and downgrade packages normally. In the process, the user will be warned
that a kernel is being removed, and that it is their responsibility to make
sure the alternative kernels can be booted and are working.
A reboot is always needed when kernel packages are changed when purging a
service.
# index.html.md
# How to interpret the output of unattended-upgrades
In Pro Client version 27.14~, we introduced the
`u.pro.unattended_upgrades.status.v1` endpoint. This endpoint is designed to
provide users with an overview of the configuration and setup for
unattended upgrades on the machine. The expected output follows this JSON
example:
```json
{
"_schema_version": "v1",
"data": {
"attributes": {
"apt_periodic_job_enabled": true,
"package_lists_refresh_frequency_days": 1,
"systemd_apt_timer_enabled": true,
"unattended_upgrades_allowed_origins": [
"${distro_id}:${distro_codename}",
"${distro_id}:${distro_codename}-security",
"${distro_id}ESMApps:${distro_codename}-apps-security",
"${distro_id}ESM:${distro_codename}-infra-security"
],
"unattended_upgrades_disabled_reason": null,
"unattended_upgrades_frequency_days": 1,
"unattended_upgrades_last_run": null,
"unattended_upgrades_running": true
},
"meta": {
"environment_vars": [],
"raw_config": {
"APT::Periodic::Enable": "1",
"APT::Periodic::Unattended-Upgrade": "1",
"APT::Periodic::Update-Package-Lists": "1",
"Unattended-Upgrade::Allowed-Origins": [
"${distro_id}:${distro_codename}",
"${distro_id}:${distro_codename}-security",
"${distro_id}ESMApps:${distro_codename}-apps-security",
"${distro_id}ESM:${distro_codename}-infra-security"
]
}
},
"type": "UnattendedUpgradesStatus"
},
"errors": [],
"result": "success",
"version": "27.14~16.04.1",
"warnings": []
}
```
As we can see from this output, there is a variable named
`unattended_upgrades_running`. That variable indicates whether
`unattended-upgrades` is properly configured and running on the machine.
The value of this field will only be `true` if **ALL** of the following
prerequisites are also true:
* `apt_periodic_job_enable` is “true”:
This variable indicates whether the `APT::Periodic::Enable` configuration
variable is turned on. If it is turned off, `unattended-upgrades` will not
automatically run on the machine.
* `package_lists_refresh_frequency_days` is non-zero:
This variable shows the value of `APT::Periodic::Package-List-Frequency`.
This defines the daily frequency for updating package sources in the
background. If it has a zero value, this step will never happen and
`unattended-upgrades` might not be able to install new versions of the
packages.
* `systemd_apt_timer_enabled` is “true”:
This variable is true if both `apt-daily.timer` and
`apt-daily-upgrade.timer` are running on the machine. These timers are the
ones that control when `unattended-upgrades` runs. The first job,
`apt-daily.timer` is responsible for triggering the code that downloads the
latest package information on the system. The second job,
`apt-daily-upgrade.timer` is responsible for running
`unattended-upgrades` to download the latest version of the packages. If
one of these jobs is disabled, `unattended-upgrades` might not work as
expected.
* `unattended_upgrades_allowed_origins` is not empty:
This variable defines the origins that `unattended-upgrades` can use to
install a package. If that list is empty, no packages can be installed and
`unattended-upgrades` will not work as expected.
* `unattended_upgrades_frequency_days` is non-zero:
That variable shows the value of `APT::Periodic::Unattended-Upgrade`. This
configuration defines the daily frequency for running `unattended-upgrades`
in the background. Therefore, if it has a zero value, the command will never
run.
If *any* of these conditions are not met, the variable
`unattended_upgrades_disabled_reason` will contain an object explaining why
`unattended-upgrades` is not running. For example, if
`package_lists_refresh_frequency_days` has a zero value, we will see
the following value for `unattended_upgrades_disabled_reason`:
```json
{
"msg": "APT::Periodic::Update-Package-Lists is turned off",
"code": "unattended-upgrades-cfg-value-turned-off"
}
```
# index.html.md
# About ESM, esm-apps and esm-infra
## Expanded Security Maintenance (ESM)
In the earlier version of Ubuntu Pro, when security fixes were only guaranteed
for packages in the ‘main’ repository, ESM used to be known as *Extended
Security Maintenance*. At that time, it referred to the additional five years
of security coverage that Pro provided after the standard five years’ of
security coverage expired. It *extended* the security coverage to ten years.
This has since become known as `esm-infra` (more on that below!).
Since then, Pro has grown considerably in the size and scope of what it
provides. Where we originally only guaranteed security maintenance for
packages in the ‘main’ repository, we have now *expanded* the scope of our
security fixes to also include packages in the ‘universe’ repository. So, when
Pro went into General Availability in early 2023 and became available to all,
ESM became *Expanded Security Maintenance* to reflect the expanded scope of
our coverage.
## What are ‘main’ and ‘universe’?
There are tens of thousands of Ubuntu packages, all organized into sets in
*repositories*.
‘*Main*’ is the set of packages we identified as our focus when we launched
Ubuntu - they are packages that are either installed on every machine, or very
widely used for all kinds of deployments, from desktop to cloud. When we
launched Ubuntu LTS, we made a commitment to security-support these packages
and their dependencies in ‘main’ for five years, free of charge. There were
initially about 1,000 packages in ‘main’, and today that number has grown to
about 2,300 per Ubuntu release.
The ‘*universe*’ repository holds all of the other open source packages in
Ubuntu; from Debian and the Ubuntu community. ‘Universe’ is a much bigger
repository, with over 23,000 packages per release. Historically those packages
came with no security maintenance commitment from Canonical. Nevertheless,
Canonical and the Ubuntu community provided best-effort maintenance for those
packages. With the launch of Ubuntu Pro, all of the packages of Ubuntu
‘universe’ get the same security maintenance commitment from Canonical as
packages in Ubuntu ‘main’.
## What are ESM-infra and ESM-apps?
There are two streams of broad-based security updates for packages; we label
these ‘apps’ (for applications) and ‘infra’ (for infrastructure).
The `esm-apps` stream covers all ‘universe’ packages for ten years from the
release of the LTS.
The `esm-infra` stream covers ‘main’ packages for the period after the
standard five year security maintenance of ‘main’ packages ends. We call this
‘infra’ because it is commonly used to build our private cloud, storage and
Kubernetes clusters, where ‘universe’ packages are not typically deployed.
Commercial and enterprise customers can get a lower-cost Ubuntu Pro
(infra-only) subscription only the ‘infra’ components are needed, which equates
to our original ESM offering.
## How can I enable `esm-infra` and `esm-apps`?
You can manage `esm-infra` and `esm-apps` using `pro` on the command
line. To find out how, read our guide on
[enabling and disabling these services](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_esm_infra.md#manage-esm) on your machine.
## Are `esm-infra` and `esm-apps` packages preferred over regular updates?
Yes. The Pro Client will deliver the following configuration files to `apt`
to ensure the `esm` updates are preferred when running `apt upgrade`:
- `/etc/apt/preferences.d/ubuntu-pro-esm-infra`
- `/etc/apt/preferences.d/ubuntu-pro-esm-apps`
These files are *pinning* the packages coming from `esm` to give them a higher
priority than the standard priority defined in APT. This means that the version to be
installed by `apt` (in `apt install` or `apt upgrade`) or by unattended-upgrades will
always be the highest `esm` version available for a given package, even if a
higher version is theoretically available from a non-esm source.
This behavior guarantees that if you have `esm-infra` or `esm-apps` enabled,
your system will always have the `esm` patches installed for any package
available in the ESM repositories.
Although the preference files listed above will always be delivered by the
package, they will only take effect when the referenced sources are available, i.e. when the services are enabled. Otherwise, it
is safe to keep those files around.
check the [APT configuration article](https://wiki.debian.org/AptConfiguration#Using_pinning) in the Debian wiki to learn more about
pinning and priorities.
## Why do we set this preference for the ESM packages ?
Once you enable the ESM services you have immediate access to the security
updates provided by Canonical for your Ubuntu system. Setting the preference
guarantees that no automatically installed updates will ever revert a
previously applied security patch, unless some manual operation overrides the
default behavior set by the Pro Client.
## How does this preference affect PPAs ?
If you have any third party PPAs configured on your system, then the ESM
repositories will be preferred over these as well. That means if a
particular package has two different versions (one coming from the
PPA and the other from ESM) the ESM version will be chosen, even if the
PPA version is higher.
If you don’t want this behavior, and you want the the PPA version to be
automatically installed instead, you need to set at least the same preference
value used for ESM (510) for the PPA. To do that, please check the
[APT configuration article](https://wiki.debian.org/AptConfiguration#Using_pinning) in the Debian wiki to learn more about
pinning and priorities.
# index.html.md
# Ubuntu Pro Client feature deprecation policy
When the Pro Client introduces new features, particularly features designed for
other software to integrate with, we assume those features become relied-upon
in all Ubuntu releases we support. That includes the oldest and also the newest
(at time of writing, the oldest is 16.04 and the newest is 24.04). The newest
supported Ubuntu release typically has ~12 years of life left between LTS, ESM
and Legacy coverage. That means we need to support any given feature in a
backwards compatible-way for at least 12 years. This is particularly true for
any integration point with machine-readable output (e.g. our API functions, any
command with JSON-formatted output). It is also true for important features
that, even if lacking intentional machine-usability, are likely to be used in
automation (e.g. any form of `pro attach` or `pro enable` that doesn’t require
interaction).
## Removing features by release
We maintain the LTS promise of stability for every supported LTS. Therefore,
we cannot remove a given feature from any LTS that already has the
feature. Instead, we will remove features starting on a [devel](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/glossary/#term-Devel) Ubuntu release
onward. To make the transition more apparent to users and give them time to
adjust, we will only remove features in interim devel releases. We will not
remove a feature for the first time in an LTS devel release. When the given
feature is invoked on a release where it has been removed, the Pro Client will
return an error code and message describing what to do instead of using the
removed feature.
Features will only be per-release-removed once a better replacement is
available on all supported Ubuntu releases via [Stable Release Update](https://wiki.ubuntu.com/StableReleaseUpdates) (SRU).
The soonest allowed per-release-removal is the next new interim release after
the replacement is SRU’d to all Ubuntu releases.
## Deprecation warnings on releases that keep the feature
When a feature is removed in e.g. 24.10 onward, it will continue to exist in
all prior supported releases; however, features in `pro` are often expected to
work consistently across all supported Ubuntu releases. Any feature we remove
should either not apply to new Ubuntu releases, or should have a better
alternative available that does work consistently across all supported Ubuntu
releases. So when we remove a feature in future releases, all releases that
still support the feature should start showing a deprecation warning. This
warning will tell the user that this feature will not work on future Ubuntu
releases, and point them to the alternative.
## Documentation
For features that are removed per-release, we will add notices to the related
documentation noting which Ubuntu releases they are supported on, and also
directing the reader to the replacement.
# index.html.md
# How to disable or re-enable APT News
APT News is a feature that allows for timely package-related news to be
displayed during an `apt upgrade`. It is distinct from
[Ubuntu Pro ‘available update’ messages](https://ubuntu.com/pro-client/docs/latest/explanations/apt_messages.md)
that are also displayed during an `apt upgrade`. APT News messages are
fetched from [https://motd.ubuntu.com/aptnews.json](https://motd.ubuntu.com/aptnews.json) once per day (at most).
By default, APT News is turned on. In this guide, we show how to turn off and
on the APT News feature for a particular machine.
## Check current APT News configuration
```bash
pro config show apt_news
```
The default value is `True`, so if you haven’t yet modified this setting,
you will see:
```bash
apt_news True
```
## Disable APT News
```bash
pro config set apt_news=false
```
This should also clear any current APT News you may be seeing on your system
during `apt upgrade`.
You can double-check that the setting was changed successfully by running
`pro config show apt_news` again. This time, you should see:
```bash
apt_news False
```
## Re-enable APT News (optional)
If you change your mind and want APT News to start appearing again during
`apt upgrade`, run the following command:
```bash
pro config set apt_news=true
```
Once again, you can verify the setting worked with
the `pro config show apt_news` command.
# index.html.md
# How to configure a proxy
The Ubuntu Pro 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 Ubuntu Pro Client will automatically set up proxies for all
programs required for enabling Ubuntu Pro services. This includes APT, snaps,
and Livepatch.
#### NOTE
Throughout this guide, we will set the HTTPS proxy with an http prefix.
However, depending on your proxy setup, you might need to configure the
Pro HTTPS proxy with a https prefix.
## HTTP/HTTPS proxies
To configure standard HTTP and/or HTTPS proxies, run the following commands:
```bash
$ sudo pro config set http_proxy=http://host:port
$ sudo pro config set https_proxy=http://host:port
```
After running the above commands, Ubuntu Pro Client will:
1. Verify that the proxy is working by using it to reach `api.snapcraft.io`
2. Configure itself to use the given proxy for all future network requests
3. Configure `snapd` (if `snapd` is installed) to use the given proxy
4. Configure Livepatch (if Livepatch has already been enabled) to use the given
proxy:
1. If Livepatch is enabled after the `config` command, Ubuntu Pro Client
will configure Livepatch to use the given proxy at that time.
To remove HTTP/HTTPS proxy configuration, run the following:
```bash
$ sudo pro config unset http_proxy
$ sudo pro config unset https_proxy
```
After running the above commands, Ubuntu Pro Client will also remove proxy
configuration from `snapd` (if installed) and Livepatch (if enabled).
## APT proxies
APT proxy settings are configured separately. To have Ubuntu Pro Client manage
your global APT proxy configuration, run the following commands:
```bash
$ sudo pro config set global_apt_http_proxy=http://host:port
$ sudo pro config set global_apt_https_proxy=http://host:port
```
After running the above commands, Ubuntu Pro Client will:
1. Verify that the proxy works by using it to reach `archive.ubuntu.com` or
`esm.ubuntu.com`.
2. Configure APT to use the given proxy by writing an apt configuration file to
`/etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy`.
#### CAUTION
Any configuration file that comes later in the `apt.conf.d` directory
could override the proxy configured by the Ubuntu Pro Client.
To remove the APT proxy configuration, run the following:
```bash
$ sudo pro config unset global_apt_http_proxy
$ sudo pro config unset global_apt_https_proxy
```
#### NOTE
Starting in Pro Client version 27.9, APT proxy config options changed.
The old settings: `apt_http_proxy` and `apt_https_proxy` will still
work and will be treated the same as `global_apt_http_proxy` and
`global_apt_https_proxy`, respectively.
### Pro-service-only APT proxies
To set an APT proxy that will only be used for Ubuntu Pro services, use the
following commands instead:
```bash
$ sudo pro config set ua_apt_http_proxy=http://host:port
$ sudo pro config set ua_apt_https_proxy=http://host:port
```
## Authenticate your proxy server
If your proxy server requires authentication, you can pass the credentials
directly in the URL when setting the configuration, as in:
```bash
$ sudo pro config set https_proxy=https://username:password@host:port
```
## Check the configuration
To see which proxies Ubuntu Pro Client is currently configured to use, you can
use the `show` command.
```bash
$ sudo pro config show
```
The above will output something that looks like the following if there are
proxies set:
```text
http_proxy http://proxy
https_proxy http://proxy
global_apt_http_proxy http://aptproxy
global_apt_https_proxy http://aptproxy
```
Or it may look like this if there are no proxies set:
```text
http_proxy None
https_proxy None
global_apt_http_proxy None
global_apt_https_proxy None
```
# index.html.md
# How to preview the result of the `pro fix` command
As outlined in our explanation of the different scenarios encountered when
[using pro fix to solve a CVE/USN](https://ubuntu.com/pro-client/docs/latest/explanations/fix_scenarios.md#pro-fix-howto),
`pro fix` can encounter many conditions
and running it might or might not lead to upgrades of packages on your system.
If you are unsure and want to check what changes will happen to your system
when you run `pro fix` to address a CVE/USN, you can simulate a run using the
`--dry-run` flag to see which packages will be installed on the system. For
example, this is the output of running `pro fix USN-5079-2 --dry-run`:
```text
WARNING: The option --dry-run is being used.
No packages will be installed when running this command.
USN-5079-2: curl vulnerabilities
Associated CVEs:
- https://ubuntu.com/security/CVE-2021-22946
- https://ubuntu.com/security/CVE-2021-22947
Fixing requested USN-5079-2
1 affected source package is installed: curl
(1/1) curl:
A fix is available in Ubuntu Pro: ESM Infra.
The machine is not attached to an Ubuntu Pro subscription.
To proceed with the fix, a prompt would ask for a valid Ubuntu Pro token.
{ pro attach TOKEN }
Ubuntu Pro service: esm-infra is not enabled.
To proceed with the fix, a prompt would ask permission to automatically enable
this service.
{ pro enable esm-infra }
{ apt update && apt install --only-upgrade -y curl libcurl3-gnutls }
✔ USN-5079-2 is resolved.
Found related USNs:
- USN-5079-1
Fixing related USNs:
- USN-5079-1
No affected source packages are installed.
✔ USN-5079-1 does not affect your system.
Summary:
✔ USN-5079-2 [requested] is resolved.
✔ USN-5079-1 [related] does not affect your system.
```
You can see that using `--dry-run` will also indicate which actions would
need to happen to completely address the USN/CVE. Here we can see that the
package fix can only be accessed through the `esm-infra` service. Therefore,
we need an Ubuntu Pro subscription, as can be seen in this part of the output:
```text
The machine is not attached to an Ubuntu Pro subscription.
To proceed with the fix, a prompt would ask for a valid Ubuntu Pro token.
{ pro attach TOKEN }
```
Additionally, it informs you that even with a subscription, we need the
specific `esm-infra` service to be enabled:
```text
Ubuntu Pro service: esm-infra is not enabled.
To proceed with the fix, a prompt would ask permission to automatically enable
this service.
{ pro enable esm-infra }
```
#### NOTE
After performing these steps during a `fix` command without
`--dry-run`, your machine should no longer be affected by the USN we
used as an example.
# index.html.md
# How to get Ubuntu Pro on LXD guests
Pro client v35 allows LXD guests to get Ubuntu Pro during boot. For the integration to
work properly you need to:
* Have a version of LXD which supports the feature installed in your system:
* version 5.21.4 or later (if running from `5/stable`)
* version 6.3 or later (if running from `6/stable`)
* the `latest/stable` version (recommended)
* Have the host machine attached to Ubuntu Pro, running the Client version
`35.1` or later
Once that is done, you can control the LXD integration
with the lxd_guest_attach configuration. This configuration has three possible values:
* **off**: This turns off the LXD integration with Ubuntu Pro. This is also the default value for
this feature
* **available**: This value will allow LXD guests to attach to Pro, but it won’t perform that action
automatically. You will need to run the pro auto-attach command in the guest for it to attach to
the Ubuntu Pro license
* **on**: This value will attach the LXD guest to Pro automatically during the boot stage
To set any of those values, you can use the following command:
```bash
$ pro config set lxd_guest_attach=(off|available|on)
```
# index.html.md
# How to simulate the `attach` operation
If you are unsure what the state of your machine will be after running
`attach` with a specific token, you can simulate running the `attach`
operation.
## Get an Ubuntu Pro token
You first need to retrieve the Ubuntu Pro token you want to test from the
[Ubuntu Pro portal](https://ubuntu.com/pro). Log in with your “Single Sign On” credentials,
the same credentials you use for [https://login.ubuntu.com](https://login.ubuntu.com).
After you have logged in you can go to the
[Ubuntu Pro Dashboard](https://ubuntu.com/pro/dashboard) associated with your user account. It
will show you all subscriptions currently available to you and for each
associated token.
Note that even without buying anything you can always obtain a free personal
token that way, which provides you with access to several of the Ubuntu Pro
services.
## Simulate the attach process
Once you have your token, you can run the following command (replacing
YOUR_TOKEN with the token you retrieved from the dashboard):
```bash
$ pro status --simulate-with-token YOUR_TOKEN
```
After running the command, you should see a modified status table, similar to
this one:
```text
SERVICE AVAILABLE ENTITLED AUTO_ENABLED DESCRIPTION
cc-eal yes yes no Common Criteria EAL2 Provisioning Packages
cis yes yes no Security compliance and audit tools
esm-infra yes yes yes Expanded Security Maintenance for Infrastructure
fips yes yes no NIST-certified core packages
fips-updates yes yes no NIST-certified core packages with priority security updates
livepatch yes yes yes Canonical Livepatch service
```
Here, you can see which services that token is entitled to, while also
verifying which services will be enabled by default through the
**AUTO_ENABLED** column. The services marked as “yes” here will be
automatically enabled when running an `attach` operation.
#### NOTE
If you want more information about the **AVAILABLE** and **ENTITLED**
columns, please refer to [this explanation](https://ubuntu.com/pro-client/docs/latest/explanations/status_columns.md#pro-status-output).
If there are services that will be auto-enabled that you don’t want to enable,
or you only want to enable specific services, you may want to run `attach`
[using a config file](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach_with_config_file.md#attach-with-config) instead of the usual attach
process. Otherwise, you can run:
```bash
$ sudo pro attach --no-auto-enable
```
This will prevent the auto-enabling of any services while attaching a
particular machine.
# index.html.md
# How to enable Ubuntu Pro Services in a Dockerfile
Ubuntu Pro comes with several services, some of which can be useful in Docker.
For example, Expanded Security Maintenance (ESM) of packages and FIPS-certified
packages may be desirable in a Docker image. In this how-to guide, we show how
you can use the `pro` tool to take advantage of these services in your
Dockerfile.
## Pre-requisites
You should be running the latest version of Ubuntu Pro Client. You can
ensure that it is up to date by running:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
You should also build your Docker image on a host machine with an active Ubuntu
Pro subscription. If you are running an auto-attached cloud instance, then you
are already good to go. (See [How to attach](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) and
[About Public Cloud Ubuntu Pro images](https://ubuntu.com/pro-client/docs/latest/explanations/what_are_ubuntu_pro_cloud_instances.md#expl-about-pro-cpc) for more
details).
```bash
sudo pro attach
```
## Create an Ubuntu Pro Attach Config file
#### ATTENTION
The Ubuntu Pro Attach Config file will contain your Ubuntu Pro Contract
token and should be treated as a secret file.
An Attach Config file for `pro` is a YAML file that specifies some options
you want to invoke when running `pro attach`. The file has two fields,
`token` and `enable_services` and looks something like this:
```yaml
token: TOKEN
enable_services:
- service1
- service2
- service3
```
* **`token`:**
The `token` field is required and must be set to an Ubuntu Pro token.
You can retrieve a guest token on your Ubuntu Pro host by running the
following command:
```bash
sudo pro api u.pro.attach.guest.get_guest_token.v1
```
That command will output JSON that includes a guest token that is usable only once and valid for a
short time, during which you can use it in your Docker build.
#### TIP
If you have `jq` installed, you can use the following command to extract the token:
```bash
sudo pro api u.pro.attach.guest.get_guest_token.v1 | jq -r '.data.attributes.guest_token'
```
* **`enable_services`:**
The `enable_services` field value is a list of Ubuntu Pro service names. When
it is set, then the services specified will be automatically enabled after
attaching with your Ubuntu Pro token.
Service names that you may be interested in enabling in your Docker builds
include:
- `esm-infra`
- `esm-apps`
- `fips`
- `fips-updates`
You can see a full list of the service names available by using the
`pro status --all` command. You can then find out more about any of these
services by running `pro help service-name` on any Ubuntu machine.
## Create a Dockerfile to use `pro` and your Attach Config file
Your Dockerfile is going to look something like the following – there are
inline comments explaining each line:
```dockerfile
# Base on the LTS of your choice
FROM ubuntu:focal
# We mount a BuildKit secret here to access the attach config file which should
# be kept separate from the Dockerfile and managed in a secure fashion since it
# needs to contain your Ubuntu Pro token.
# In the next step, we demonstrate how to pass the file as a secret when
# running docker build.
RUN --mount=type=secret,id=pro-attach-config \
#
# First we update apt so we install the correct versions of packages in
# the next step
apt-get update \
#
# Here we install `pro` (ubuntu-pro-client) as well as ca-certificates,
# which is required to talk to the Ubuntu Pro authentication server securely.
&& apt-get install --no-install-recommends -y ubuntu-pro-client ca-certificates \
#
# With pro installed, we attach using our attach config file from the
# previous step
&& pro attach --attach-config /run/secrets/pro-attach-config \
#
###########################################################################
# At this point, the container has access to all Ubuntu Pro services
# specified in the attach config file.
###########################################################################
#
# Always upgrade all packages to the latest available version with the Ubuntu Pro
# services enabled.
&& apt-get upgrade -y \
#
# Then, you can install any specific packages you need for your docker
# container.
# Install them here, while Ubuntu Pro is enabled, so that you get the appropriate
# versions.
# Any `apt-get install ...` commands you have in an existing Dockerfile
# that you may be migrating to use Ubuntu Pro should probably be moved here.
&& apt-get install -y openssl \
#
###########################################################################
# Now that we have upgraded and installed any packages from the Ubuntu Pro
# services, we can clean up.
###########################################################################
#
# This detaches and purges ubuntu-pro-client, including all Ubuntu Pro
# related secrets from the system.
###########################################################################
# IMPORTANT: As written here, this command assumes your container does not
# need ca-certificates so it is purged as well.
# If your container needs ca-certificates, then do not purge it from the
# system here.
###########################################################################
&& pro detach --assume-yes \
&& apt-get purge --auto-remove -y ubuntu-pro-client ca-certificates \
#
# Finally, we clean up the apt lists which should not be needed anymore
# because any `apt-get install`s should have happened above. Cleaning these
# lists keeps your image smaller.
&& rm -rf /var/lib/apt/lists/*
# Now, with all of your Ubuntu apt packages installed, including all those
# from Ubuntu Pro services, you can continue the rest of your app-specific Dockerfile.
```
An important point to note about the above Dockerfile is that all of the
`apt` and `pro` commands happen inside one Dockerfile `RUN` instruction.
This is **critical** and must not be changed. Keeping everything as written
inside of one `RUN` instruction has two key benefits:
1. It prevents any Ubuntu Pro Subscription-related tokens and secrets from
being leaked in an image layer.
2. It keeps the image as small as possible by cleaning up extra packages and
files before the layer is finished.
#### NOTE
These benefits could also be attained by squashing the image.
## Build the Docker image
Now, with our Attach Config file and Dockerfile created, we can build the image
with a command like the following:
```bash
DOCKER_BUILDKIT=1 docker build . --secret id=pro-attach-config,src=pro-attach-config.yaml -t ubuntu-focal-pro
```
There are two important pieces to this command.
1. We enable BuildKit with `DOCKER_BUILDKIT=1`. This is necessary to support
the secret mount feature.
2. We use the secret mount feature of BuildKit with
`--secret id=pro-attach-config,src=pro-attach-config.yaml`. This is what
passes our Attach Config file in to be securely used by the
`RUN --mount=type=secret,id=pro-attach-config` command in the Dockerfile.
## Success
Congratulations! At this point, you should have a Docker image that has been
built with Ubuntu Pro packages installed from whichever Ubuntu Pro service you
required.
# index.html.md
# How to manage Expanded Security Maintenance (ESM) services
For Ubuntu LTS releases, ESM for Infrastructure (`esm-infra`) and ESM for
Applications (`esm-apps`) are automatically enabled after you attach the
Ubuntu Pro Client subscription to your account. However, if you chose to
disable them initially, you can enable them at any time from the command line
using the Ubuntu Pro Client (`pro`).
## Make sure `pro` is up-to-date
All systems come with `pro` pre-installed through the
`ubuntu-pro-client` package. To make sure that you’re running the latest
version of `pro`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
## Check the status of the services
After you have [attached your subscription](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) and
updated the `ubuntu-pro-client` package, you can check which services
are enabled by running the following command:
```bash
pro status
```
This will show you which services are enabled or disabled on your machine
(output truncated for brevity):
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
livepatch yes enabled Canonical Livepatch service
realtime-kernel yes disabled Ubuntu kernel with PREEMPT_RT patches integrated
```
## Enable `esm-apps` and `esm-infra`
If either of the `esm-apps` or `esm-infra` services are disabled and you
want to enable them, run the following command to enable ESM-Infra:
```bash
sudo pro enable esm-infra
```
Or the following for ESM-Apps:
```bash
sudo pro enable esm-apps
```
## Update your packages
When you enable the ESM-Infra and/or ESM-Apps repositories, especially on
Ubuntu 14.04 and 16.04, you may see a number of package updates available that
were not available previously.
Even if your system indicated that it was up to date before enabling
`esm-infra` or `esm-apps`, make sure to check for new package updates after
you enable them:
```bash
sudo 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 packages being
updated with the `esm-infra` and `esm-apps` content.
Running `apt upgrade` will apply all available package updates, including
the ones in `esm-infra` and `esm-apps`.
## Disable the services
If you wish to disable the services, you can use the following command to
disable ESM-Infra:
```bash
sudo pro disable esm-infra
```
Or the following command to disable ESM-Apps:
```bash
sudo pro disable esm-apps
```
Note that this command will only remove the APT sources, but not uninstall the
packages installed with the services.
To purge the services, removing the APT packages installed with them, see
[how to disable and purge services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge).
## Notes
- For more information about ESM-Apps and ESM-Infra, see
[our explanatory guide](https://ubuntu.com/pro-client/docs/latest/explanations/about_esm.md#expl-esm).
# index.html.md
# How to check if a system is affected by a CVE/USN?
The Ubuntu Pro Client (`pro`) can be used to inspect and resolve
[Common Vulnerabilities and Exposures](https://ubuntu.com/security/cves) (CVEs) and
[Ubuntu Security Notices](https://ubuntu.com/security/notices) (USNs) on your machine.
Every CVE/USN is fixed by trying to upgrade all of the affected packages
described by the CVE or USN. Sometimes, the package fixes can only be applied
if an Ubuntu Pro service is already enabled on your machine.
If you’ve found a [Common Vulnerabilities and Exposure](https://ubuntu.com/security/cves) (CVEs) and [Ubuntu Security Notice](https://ubuntu.com/security/notices) (USNs) and want to check if your Ubuntu system is affected by it, you can check using the `pro fix` command as we’ll show you in this guide.
#### NOTE
The `pro fix` command is part of the Ubuntu Pro Client (`pro`), which is a security tool for Ubuntu systems. The Ubuntu Pro Client comes pre-installed on every Ubuntu system. You can run `pro help` in your terminal window to see a list of the `pro` services and commands available.
## Perform a “dry run”
A “dry run” lets you simulate running the `pro fix` command without actually making any changes to your system. This is useful for checking if a CVE affects your system and whether a fix is available.
Let’s see what happens when we perform a dry run with the `pro fix` command.
Every `pro fix` output has a similar output structure. It:
* describes the CVE/USN;
* displays the affected packages;
* fixes the affected packages; and
* at the end, shows if the CVE/USN is fully fixed in the machine.
To perform a dry run, use the `--dry-run` option with the `pro fix` command followed by the CVE identifier:
```bash
pro fix --dry-run CVE-XXXX-XXXX
```
Replace `CVE-XXXX-XXXX` with the actual CVE identifier you want to check.
## Output of a “dry run”
The output of the dry run will indicate whether your system is affected by the CVE and if a fix is available. Here are some possible scenarios:
### CVE does not affect your system
Here, for example, We will choose to fix a CVE that does not affect the system – for example if you do not have `MariaDB` installed and want to check [CVE-2020-15180](https://ubuntu.com/security/CVE-2020-15180).
```bash
pro fix --dry-run CVE-2020-15180
```
You should see an output like this:
```text
CVE-2020-15180: MariaDB vulnerabilities
- https://ubuntu.com/security/CVE-2020-15180
No affected source packages are installed.
✔ CVE-2020-15180 does not affect your system.
```
### CVE affects your system, and a fix is available
Let’s simulate a scenario where an older package associated with [CVE-2020-25686](https://ubuntu.com/security/CVE-2020-25686) is installed on the machine.
```bash
sudo pro fix --dry-run CVE-2020-25686
```
The output will indicate that the system is affected and a fix is available:
```text
CVE-2020-25686: Dnsmasq vulnerabilities
- https://ubuntu.com/security/CVE-2020-25686
1 affected package is installed: dnsmasq
(1/1) dnsmasq:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y dnsmasq }
✔ CVE-2020-25686 is resolved.
```
### CVE affects your system, but no fix is available
Some CVEs/USNs do not have a fix released yet. When that happens, the dry run output will let you know.
This is example output created in the past, for which there
might be fixes later on. To create this scenario we installed a
known affected package with no fix (at the time) and then checked for an
available fix:
```bash
sudo apt-get install -y expat=2.1.0-7 swish-e matanza ghostscript
```
Now, we can confirm that there is no fix by running the following command:
```bash
pro fix --dry-run CVE-2017-9233
```
You will see the following output:
```text
CVE-2017-9233: Coin3D vulnerability
- https://ubuntu.com/security/CVE-2017-9233
3 affected source packages are installed: expat, matanza, swish-e
(1/3, 2/3) matanza, swish-e:
Ubuntu security engineers are investigating this issue.
(3/3) expat:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y expat }
2 packages are still affected: matanza, swish-e
✘ CVE-2017-9233 is not resolved.
```
### CVE that requires a Pro service
Assuming you have attached to a Pro subscription, when running the `pro fix` command
you may see that the service required to fix the issue is not enabled. In this situation,
`pro fix` will also prompt you to enable that service.
For example, if you want to fix the issue CVE-2023-1523 which requires the Pro service `esm-infra`
and you run the following command:
```bash
sudo pro fix --dry-run CVE-2023-1523
```
You will see the following output (if you type `E` to enable the service when prompted):
```text
CVE-2023-1523: snapd vulnerability
- https://ubuntu.com/security/CVE-2023-1523
1 affected source package is installed: snapd
(1/1) snapd:
A fix is available in Ubuntu Pro: ESM Infra.
The update is not installed because this system does not have
esm-infra enabled.
Choose: [E]nable esm-infra [C]ancel
> E
{ pro enable esm-infra }
Updating Ubuntu Pro: ESM Infra package lists
Ubuntu Pro: ESM Infra enabled
{ apt update && apt install --only-upgrade -y snapd ubuntu-core-launcher }
✔ CVE-2023-1523 is resolved.
```
We can observe that the required service was enabled and `pro fix` was able
to successfully upgrade the affected package.
Here we see how performing a dry run with the `pro fix` command is a quick and safe way to check if your system is affected by a specific CVE and also see if a fix is available.
## Success!
Here we see how performing a dry run with the `pro fix` command is a quick and safe way to check if your system is affected by a specific CVE and also see if a fix is available. If a fix is available, you can apply the fix by running the command provided in the output.
To learn how to resolve a CVE using the `pro fix` command, refer to the guide on [How to resolve a CVE/USN](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_resolve_given_cve.md#pro-fix-resolve-cve).
### Additional resources
This is not the only scenario where you might want to use `pro fix`. To find out about the other situations where it can be useful, as well as which options can be used to give you greater control over the command, you can refer to the following guides:
* In [Understanding scenarios encountered when using pro fix to solve a CVE/USN](https://ubuntu.com/pro-client/docs/latest/explanations/fix_scenarios.md#pro-fix-howto) you can continue learning more about the different scenarios you might encounter and understand the different outputs you will find.
* [How do I know what the pro fix command would change?](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_what_the_fix_command_would_change.md#pro-fix-dry-run) will show you how to use `pro fix` in `--dry-run` mode to safely simulate the changes before they’re applied.
* [How to skip fixing related USNs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_not_fix_related_usns.md#pro-fix-skip-related) will show you how to only fix a single USN, even if other fixes are available.
If you need more information about this, please feel free to reach out
to the Ubuntu Pro Client team on `#ubuntu-server` on
Libera IRC – we’re happy to help!
Alternatively, if you have a GitHub account, click on the “Give feedback”
link at the top of this page to leave us a message. We’d love to hear from you!
# index.html.md
# How to manage Livepatch
For Ubuntu LTS releases, [Livepatch](https://ubuntu.com/security/livepatch) is automatically enabled after you attach
your Ubuntu Pro subscription. However, you can choose to disable it initially
via the dashboard, and then enable it at a later time from the command line
using the Ubuntu Pro Client (`pro`).
## Make sure `pro` is up-to-date
All systems come with `pro` pre-installed through the
`ubuntu-pro-client` package. To make sure that you’re running the latest
version of `pro`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
## Check the status of the services
After you have [attached your subscription](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) and
updated the `ubuntu-pro-client` package, you can check which services
are enabled by running the following command:
```bash
pro status
```
This will show you which services are enabled or disabled on your machine
(output truncated for brevity):
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
livepatch yes enabled Canonical Livepatch service
realtime-kernel yes disabled Ubuntu kernel with PREEMPT_RT patches integrated
```
## How to enable Livepatch
#### IMPORTANT
Once you enable Livepatch, enabling some Pro services will not be possible
until Livepatch is disabled again. For a complete view of which services
are compatible with Livepatch, refer to the
[services compatibility matrix](https://ubuntu.com/pro-client/docs/latest/references/compatibility_matrix.md).
If Livepatch is disabled and you want to enable it, run the following command:
```bash
$ sudo pro enable livepatch
```
You should see output like the following, indicating that the Livepatch snap
package has been installed successfully:
```text
One moment, checking your subscription first
Installing snapd
Updating package lists
Installing canonical-livepatch snap
Canonical livepatch enabled.
```
## Check Livepatch status after installation
If you’re interested in the detailed status of the Livepatch client once it has
been installed, use the following command:
```bash
$ sudo canonical-livepatch status
```
### Unsupported kernels
Although you can enable Livepatch on an unsupported kernel, since patches are
kernel-specific, you will not receive any updates from Livepatch if your kernel
is not supported.
The `pro status` command will warn you in its output if Livepatch is not
supported:
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
livepatch yes warning Current kernel is not supported
realtime-kernel yes disabled Ubuntu kernel with PREEMPT_RT patches integrated
NOTICES
The current kernel (5.19.0-46-generic, amd64) is not supported by livepatch.
Supported kernels are listed here: https://ubuntu.com/security/livepatch/docs/kernels
Either switch to a supported kernel or `pro disable livepatch` to dismiss this warning.
```
The `canonical-livepatch status` command will also warn you if your kernel is
unsupported (output truncated for brevity):
```bash
...
server check-in: succeeded
kernel state: ✗ kernel not supported by Canonical
patch state: ✓ no livepatches needed for this kernel yet
...
```
You can also check
[the kernel support matrix](https://ubuntu.com/security/livepatch/docs/livepatch/reference/kernels)
to see if your kernel is supported by Livepatch. To find out more, refer to
this explanation of [how Livepatch works](https://ubuntu.com/security/livepatch/docs/livepatch/explanation/howitworks).
## How to disable Livepatch
Enabling Livepatch installs the Livepatch client as a snap package, and there
are a few possible ways to disable it. The simplest is to use the Pro Client:
```bash
sudo pro disable livepatch
```
If you also want to remove the Livepatch client from your machine, you can
then use the following command:
```bash
snap remove canonical-livepatch
```
For other options, you can also refer to [the Livepatch documentation](https://ubuntu.com/security/livepatch/docs/livepatch/how-to/disable).
## Notes
- For more information about the Livepatch client and how to use it, refer to
the [official Livepatch client documentation](https://ubuntu.com/security/livepatch/docs).
- Livepatch is not compatible with FIPS-certified kernels or with the
[real-time kernel](https://ubuntu.com/realtime-kernel), and should not be enabled if you wish to
use those services. If Livepatch is enabled and you try to enable an
incompatible service, `pro` will notify you and offer to disable Livepatch
first.
# index.html.md
# How to manage Landscape
You can register a machine with Landscape via the `pro enable landscape`
command. You can register interactively for convenience, or non-interactively
which is useful for hands-off automation.
To register a machine, you’ll need (as a minimum) your Landscape Account Name
and a name for the machine you are registering. If you’re not using
[Landscape SaaS](https://landscape.canonical.com), then you’ll also need the URL of your
hosted Landscape server.
## Enable interactively
To register your machine by interactively providing your Landscape account
details at the CLI, run:
```bash
sudo pro enable landscape
```
This command will install `landscape-client` and start up an interactive
wizard to complete the Landscape registration for the machine.
## Enable non-interactively
If you know the details of your Landscape setup then you can register a
machine without using the wizard. Under the hood, `pro` installs and executes
`landscape-config`, so you can pass any [parameters supported by](https://manpages.ubuntu.com/manpages/noble/en/man1/landscape-config.1.html)
`landscape-config` to `pro enable landscape` after a `--`.
You should also use the `--assume-yes` flag to automatically accept the
defaults for any un-provided parameters.
The command to enable Landscape takes the following format:
```bash
sudo pro enable landscape \
\
-- \
```
Which, when the parameters are added, should look something like this:
```bash
sudo pro enable landscape \
--assume-yes \
-- \
--account-name \
--computer-title
```
That command will install `landscape-client` and pass the provided parameters
after `--` to the `landscape-config` tool to automatically register the
machine.
## What next?
After successfully running `pro enable landscape`, either interactively
or non-interactively, an administrator of your Landscape account will need to
go to the “Pending Computers” page in Landscape to accept the machine you just
registered.
And that’s it! The machine should now appear in the Landscape dashboard for
management.
# index.html.md
# How to get rid of a corrupt lock
Some Pro Client commands (`attach`, `enable`, `detach` and `disable`)
can potentially change the internal state of your system. Since those commands
can run in parallel, we have a lock file mechanism to guarantee that only one
of these commands can run at the same time. The lock follows this pattern:
```default
PROCESS_PID:LOCK_HOLDER_NAME
```
Where:
* **PROCESS_PID**: The PID of the process that is running the `pro` command
* **LOCK_HOLDER_NAME**: The name of the command that is using the lock (i.e.
`pro disable`
If the lock file doesn’t follow that pattern, we say that it is corrupted. This
might happen if we have any type of disk failures in the system. Once we detect
a corrupted lock file, any of the mentioned `pro` commands will generate the
following output:
```text
There is a corrupted lock file in the system. To continue, please remove it
from the system by running:
$ sudo rm /var/lib/ubuntu-advantage/lock
```
You can follow the instructions presented on the output to get rid of the
corrupted lock. After that, running the command should generate a correct lock
file and continue as expected.
# index.html.md
# How to configure a TLS-in-TLS proxy
If you need to set `https_proxy` to a proxy that uses `https://` (a
practice commonly referred to as “TLS-in-TLS”), you need to follow a few extra
steps to ensure all Ubuntu Pro actions work correctly.
Support for TLS-in-TLS proxying was added in version 28.1 of the Ubuntu Pro
Client, and is supported by the Ubuntu Pro Client on Ubuntu 18.04 and later.
## Install the pycurl dependency
For TLS-in-TLS proxying, `pro` switches to using `pycurl` – but
`pycurl` may not be installed by default on your machine. To install it, run:
```bash
sudo apt install python3-pycurl
```
If you don’t do this and try to set the TLS-in-TLS proxy anyway, you will get
an error that looks like this:
```text
To use an HTTPS proxy for HTTPS connections, please install pycurl with
``apt install python3-pycurl``
```
## Ensure the proxy’s HTTPS certificate will be trusted by Livepatch
#### TIP
You can skip this step if you don’t plan to use Livepatch.
Livepatch requires configuration separate from the rest of the Ubuntu system
for trusting certificates. Even if your proxy’s certificate is signed by a well
known certificate authority (CA), it may not be trusted by Livepatch by
default.
To ensure Livepatch will trust your proxy’s certificate, first pre-install the
`livepatch-client`:
```bash
sudo snap install canonical-livepatch
```
Then download the certificate of your proxy (or of the CA) in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format and
configure `livepatch-client` to trust it:
```bash
sudo canonical-livepatch config ca-certs=@stdin < /path/to/certificate.pem
```
Verify the PEM contents are present and accurate under the `ca-certs` field
by running:
```bash
sudo canonical-livepatch config
```
## Set the HTTPS proxy via the `pro config` command
Now that everything else is set up, you can configure the Ubuntu Pro Client to
use the TLS-in-TLS proxy:
```bash
sudo pro config https_proxy=https://your.proxy.here:1234
```
## Success!
Now with the TLS-in-TLS proxy configured, you can
[configure any other proxies you need](https://ubuntu.com/pro-client/docs/latest/howtoguides/configure_proxies.md#configure-proxies) and then use
your Ubuntu Pro token to [attach your machine](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach).
# index.html.md
# How to manage FIPS
#### NOTE
The latest FedRAMP policy on the use of cryptographic modules relaxes some
of the past restrictions that prevented organizations from applying
critical security updates. Because of that, we don’t recommend enabling
`fips` anymore - please use `fips-updates` instead. Read more in
[our blog post](https://ubuntu.com/blog/the-role-of-fips-140-3-in-the-latest-fedramp-guidance). Jammy Jellyfish (22.04) and later releases will not
have the legacy `fips` service available.
#### NOTE
Check [the FIPS documentation](https://ubuntu.com/security/certifications/docs/fips) to verify which Ubuntu releases have FIPS
available.
#### CAUTION
**Disabling FIPS is not recommended**: only enable FIPS on machines
intended expressly to be used for FIPS.
To use FIPS, one can either launch existing Ubuntu premium support images which
already have the FIPS kernel and security pre-enabled on first boot at
[AWS Ubuntu Pro FIPS images](https://ubuntu.com/aws/fips),
[Azure Pro FIPS images](https://ubuntu.com/azure/fips), and GCP Pro FIPS images.
Alternatively, you can enable FIPS using the Ubuntu Pro Client, which will
install a FIPS-certified kernel and core security-related packages such as
`openssh-server/client` and `libssl`.
To enable FIPS, run:
```bash
$ sudo pro enable fips-updates
```
You should see output like the following, indicating that the FIPS packages
have been installed:
```text
Installing FIPS Updates packages
FIPS Updates enabled
A reboot is required to complete install.
```
Enabling FIPS should be performed during a system maintenance window since
this operation makes changes to underlying SSL-related libraries and requires
a reboot into the FIPS-certified kernel.
#### CAUTION
Once you enable FIPS, enabling some Pro services may not be possible. For
a complete view of which services are incompatible with FIPS, refer to the
[services compatibility matrix](https://ubuntu.com/pro-client/docs/latest/references/compatibility_matrix.md)
## How to disable FIPS
If you wish to disable FIPS, you can use the following command:
```bash
sudo pro disable fips-updates
```
Note that this command will only remove the APT sources, but not uninstall the
packages installed with the service. Your system will **still have the FIPS
packages installed** after FIPS is disabled.
To purge the service, removing the APT packages installed with it, potentially
removing also the FIPS kernel, see
[how to disable and purge services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge).
# index.html.md
# Create an Ubuntu FIPS Docker image
#### NOTE
This tutorial requires at least Ubuntu Pro Client version 27.7 – to check
which version of the Pro Client you are using, run `pro version`.
## Acquire your Ubuntu Pro token
You can acquire an Ubuntu Pro token one of two ways, either by logging in to
your Ubuntu Pro account or by using the Ubuntu Pro Client on an already
attached machine.
### Logging in to your Ubuntu Pro account
Your Ubuntu Pro token can be found on your Ubuntu Pro dashboard. To access your
dashboard, you need an [Ubuntu One](https://login.ubuntu.com/) account. If you purchased an Ubuntu Pro
subscription and don’t yet have an Ubuntu One account, be sure to use the same
email address you used to purchase your subscription. If you haven’t purchased
an Ubuntu Pro subscription, don’t worry! Everyone gets a free token for
personal use with their Ubuntu One account – no purchase necessary.
The Ubuntu One account functions as a Single Sign On (SSO), so after you log in
we can go straight to the [Ubuntu Pro dashboard](https://ubuntu.com/pro). Here, you should see
a list of your subscriptions (including the “free for personal use”
subscription) in the left-hand column.
Click on the subscription that you wish to use for this tutorial, if it is not
already selected. On the right you will now see the details of your
subscription, including your secret token (under the “Subscription” header and
next to the “🔗” symbol).
### Ubuntu Pro Client on an already attached machine
If you will be building this Docker image on a machine that is already attached
to an Ubuntu Pro subscription, you can use the Ubuntu Pro Client to get a guest
token for the Docker build.
```bash
sudo pro api u.pro.attach.guest.get_guest_token.v1
```
That command will output JSON that includes a guest token that is valid for a
short time, during which you can use it in your Docker build.
#### TIP
If you have `jq` installed, you can use the following command to extract the token:
```bash
sudo pro api u.pro.attach.guest.get_guest_token.v1 | jq -r '.data.attributes.guest_token'
```
## Create an Ubuntu Pro Client attach config file
First, let’s create a directory for this tutorial and navigate there.
```bash
mkdir pro_fips_tutorial
cd pro_fips_tutorial
```
Now we need to create our config file called `pro-attach-config.yaml`:
```bash
touch pro-attach-config.yaml
```
Edit the file, add the following contents, and save it:
```yaml
token: YOUR_TOKEN
enable_services:
- fips
```
Replace `YOUR_TOKEN` with the Ubuntu Pro token we got from the Ubuntu Pro
[dashboard](https://ubuntu.com/pro) earlier.
## Create a Dockerfile
Next, let us create a file named `Dockerfile` by running the following
command:
```bash
touch Dockerfile
```
This file will later enable FIPS in the container, upgrade all the packages,
and install the FIPS version of `openssl`.
Edit the file and add the following contents:
```dockerfile
FROM ubuntu:focal
RUN --mount=type=secret,id=pro-attach-config \
apt-get update \
&& apt-get install --no-install-recommends -y ubuntu-pro-client ca-certificates \
&& pro attach --attach-config /run/secrets/pro-attach-config \
&& apt-get upgrade -y \
&& apt-get install -y openssl libssl1.1 libssl1.1-hmac libgcrypt20 libgcrypt20-hmac strongswan strongswan-hmac openssh-client openssh-server \
&& pro detach --assume-yes \
&& apt-get purge --auto-remove -y ubuntu-pro-client ca-certificates \
&& rm -rf /var/lib/apt/lists/*
```
#### HINT
For more details on how this works, see our how-to guide on enabling
[Ubuntu Pro Services in a Dockerfile](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_in_dockerfile.md#enable-in-dockerfile).
## Build the Docker image
Now let’s build the docker image by running the following command:
```bash
DOCKER_BUILDKIT=1 docker build . --secret id=pro-attach-config,src=pro-attach-config.yaml -t ubuntu-focal-fips
```
This will pass the `pro-attach-config.yaml` file we created earlier as a
[BuildKit Secret](https://docs.docker.com/engine/reference/builder/#run---mounttypesecret) so that the finished Docker image will not contain your
Ubuntu Pro token.
## Test the Docker image
#### IMPORTANT
The Docker image isn’t considered fully FIPS compliant unless it is running
on a host Ubuntu machine that is also FIPS compliant.
Let’s check to make sure the FIPS version of `openssl` is installed in the
container. First, let us run:
```bash
docker run -it ubuntu-focal-fips dpkg-query --show openssl
```
This should show something like: `openssl 1.1.1f-1ubuntu2.fips.2.8` (notice
“fips” in the version name).
We can now use the build Docker image’s FIPS compliant `openssl` to connect
to `https://ubuntu.com`:
```bash
docker run -it ubuntu-focal-fips sh -c "echo | openssl s_client -connect ubuntu.com:443"
```
This should print information about the certificates of ubuntu.com and the
algorithms used during the TLS handshake.
## Success
That’s it! You could now push this image to a private registry and use it as
the base of other Docker images using `FROM`.
If you want to learn more about how the steps in this tutorial work, take a
look at the more general how-to guide on enabling
[Ubuntu Pro services in a Dockerfile](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_in_dockerfile.md#enable-in-dockerfile).
# index.html.md
# How to update MOTD and APT messages
Since `ubuntu-pro-client` is responsible for enabling ESM services, we
advertise them on different applications through the system, such as MOTD and
APT commands like `upgrade`.
To verify that the APT and MOTD message is advertising the ESM packages, ensure
that we have ESM source list files in the system. If that is the case, please
run the following command to update the state of MOTD and APT messages:
```bash
sudo pro refresh messages
```
# index.html.md
# How to enable esm-infra-legacy on Trusty
The `esm-infra-legacy` service can be enabled with the Legacy Support add-on to grant an additional two years of
extended security coverage. This service is only available on 14.04 LTS (Trusty), since the release has reached
the end of its support period for `esm-infra`. Check out this article to [learn more about the expansion of Long Term Support for Trusty](https://canonical.com/blog/canonical-expands-long-term-support-to-12-years-starting-with-ubuntu-14-04-lts) and how to contact Canonical to purchase this additional support.
## Make sure `ua` is up-to-date
All Trusty systems come with `ua` pre-installed through the
`ubuntu-advantage-tools` package.
#### IMPORTANT
If you are running Trusty on a public cloud instance, you must install the updated
package from this [PPA](https://launchpad.net/~ua-client/+archive/ubuntu/legacy-trusty).
Follow the instructions to add the PPA to your machine, then continue with
this guide.
To make sure that you’re running the latest version of `ua`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-advantage-tools
```
Note that on Trusty, Ubuntu Pro is referred to by its previous name: “Ubuntu Advantage” (or `ua`).
## Check the status of the services
After you have attached to a Pro subscription and
updated the `ubuntu-advantage-tools` package, you can check which services
are enabled by running the following command:
```bash
sudo ua status
```
This will show you which services are enabled or disabled on your machine,
(output truncated for brevity). With the addition of Legacy Support, it will
now show the esm-infra-legacy service on Trusty:
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
esm-infra-legacy yes disabled Expanded Security Maintenance for Infrastructure on Legacy Instances
livepatch yes enabled Canonical Livepatch service
```
## Enabling esm-infra-legacy
If you are entitled to the `esm-infra-legacy` service as shown above, you can enable it by running:
```bash
sudo ua enable esm-infra-legacy
```
## What if `esm-infra-legacy` is not entitled?
If `ua status` shows that you are not entitled to the service, you
will first need to buy access to the service, as mentioned at the top of this page.
Once you have purchased the Legacy Support add-on, run the following command
on your machine to refresh the contract definitions:
```bash
sudo ua refresh
```
After refreshing the contract data, you can confirm that the service is now entitled by running:
```bash
sudo ua status
```
The output should now show that you are entitled to the `esm-infra-legacy` service, and you can now enable the service as outlined [in the enablement section](#enable-legacy).
## Trusty caveats
There are some known caveats for the Trusty version of ubuntu-advantage-tools:
### Disabling `esm-infra` also disables `esm-infra-legacy`
If you disable `esm-infra`, this will (due to internal dependencies) also disable
`esm-infra-legacy`. Although updates will **only** be applied via `esm-infra-legacy`,
we recommend keeping both services enabled. This is not true in reverse: if you want
to disable `esm-infra-legacy`, doing so will not disable `esm-infra`.
### `do-release-upgrade` fails if packages are installed from `esm-infra`
If `esm-infra` is enabled **and** packages are installed from that source, the
`do-release-upgrade` operation will fail since there will be an APT dependency issue
when performing the operation.
You can address this issue by running `do-release-upgrade` with the following command:
```bash
sudo RELEASE_UPGRADER_ALLOW_THIRD_PARTY=1 do-release-upgrade
```
It is important to note that you will need to re-enable the Ubuntu Pro services again
once you have upgraded to Xenial, since Trusty lacks the correct mechanisms to re-enable
the Pro services automatically after a `do-release-upgrade`.
Note that this is only the case when upgrading from Trusty to Xenial. The Ubuntu Pro
Client is fully supported from Xenial onward, where these issues have already been fixed.
### Why 14.04 (Trusty) no longer receives new Ubuntu Pro Client features
For a further reduced risk of regressions on 14.04 (Trusty) the Pro client package is almost frozen.
Hence it is not receiving regular new features like newer Ubuntu LTS releases do. Beyond
version 19.7 there won’t be updates except any critical CVE maintenance or features explicitly
targeted for Trusty (like `esm-infra-legacy` in 2024).
Version 19.7 has full-featured support of the applicable Ubuntu Pro
service offerings `esm-infra`, `esm-infra-legacy` and `livepatch`.
# index.html.md
# How to enable Real-time Ubuntu
[Real-time Ubuntu](https://ubuntu.com/realtime-kernel) is supported on specific Ubuntu releases. To
find out more about the supported Ubuntu versions and what kernel variants
are available, refer to [the supported releases page](https://canonical-real-time-ubuntu-documentation.readthedocs-hosted.com/en/latest/reference/releases/).
## Attach your subscription
If you have not yet attached your machine to an Ubuntu Pro subscription, you
will need to do so in order to enable Real-time Ubuntu. You can do so by
running the following command:
```bash
sudo pro attach
```
And follow the instructions in your terminal window. For a more complete guide
to the attach process, refer to our [how to attach](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) guide.
## Make sure `pro` is up-to-date
All systems come with `pro` pre-installed through the
`ubuntu-pro-client` package. To make sure that you’re running the latest
version of `pro`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
#### IMPORTANT
Once you enable Real-time Ubuntu, enabling some Pro services will not be
possible. To see which services are compatible with the
real-time kernel, refer to the
[services compatibility matrix](https://ubuntu.com/pro-client/docs/latest/references/compatibility_matrix.md).
If you try to enable Real-time Ubuntu while an incompatible service is
already enabled, the Pro Client will inform you and offer to disable that
service.
## Enable and install automatically
The Real-time Ubuntu kernel package is installed using the APT package manager
when you enable `realtime-kernel` through the Pro Client.
If you want to access the repository but not install the package immediately,
skip to [Install and enable manually]().
Otherwise, [select the correct version](https://canonical-real-time-ubuntu-documentation.readthedocs-hosted.com/en/latest/reference/releases/) for your OS
and processor, and use the corresponding command below:
### Generic
```bash
sudo pro enable realtime-kernel
```
#### CAUTION
The generic Real-time kernel is not intended for Raspberry Pi.
Using the Pro Client to install it on these platforms will make your
system unusable.
### Raspberry Pi
For Raspberry Pi 4 and 5:
```bash
sudo pro enable realtime-kernel --variant=raspi
```
### Intel IOTG
For 12th Gen Intel® Core™ processors:
```bash
sudo pro enable realtime-kernel --variant=intel-iotg
```
You will need to acknowledge a warning, then you will see a confirmation
message like the following that the Real-time Ubuntu package has been
installed:
```text
One moment, checking your subscription first
Real-time kernel cannot be enabled with Livepatch.
Disable Livepatch and proceed to enable Real-time kernel? (y/N) y
Disabling incompatible service: Livepatch
The Real-time kernel is an Ubuntu kernel with PREEMPT_RT patches integrated.
This will change your kernel. To revert to your original kernel, you will need
to make the change manually.
Do you want to continue? [ default = Yes ]: (Y/n) Y
Updating Real-time kernel package lists
Updating standard Ubuntu package lists
Installing Real-time kernel packages
Real-time kernel enabled
A reboot is required to complete install.
```
You will now need to reboot your machine to complete the process. After
rebooting, you will be running Real-time Ubuntu.
## Install and enable manually
To access the Real-time Ubuntu repository but not install the package
immediately, you can use the `--access-only` flag, which was introduced in
Pro Client version 27.11:
```bash
$ sudo pro enable realtime-kernel --access-only
One moment, checking your subscription first
Real-time kernel cannot be enabled with Livepatch.
Disable Livepatch and proceed to enable Real-time kernel? (y/N) y
Disabling incompatible service: Livepatch
Updating Real-time kernel package lists
Skipping installing packages: ubuntu-realtime
Real-time kernel access enabled
```
Now that Real-time Ubuntu is accessible, you can install and enable it whenever
you wish. For example, to install the generic Real-time kernel (not suitable
for Raspberry Pi):
```bash
sudo apt install ubuntu-realtime
```
After rebooting, you’ll be running Real-time Ubuntu.
## Install the hardware enablement (HWE) real-time kernel
Once you have Real-time Ubuntu enabled, you can install the HWE real-time
kernel to get support for newer hardware. To learn more about what kernel
versions and variants are supported by the HWE real-time kernel, refer to
[the supported releases page](https://canonical-real-time-ubuntu-documentation.readthedocs-hosted.com/en/latest/reference/releases/).
#### CAUTION
The HWE real-time kernel only supports generic Real-time Ubuntu,
not Real-time Ubuntu for Raspberry Pi or Intel IOTG.
### Ubuntu 22.04 LTS
```bash
sudo apt install linux-realtime-hwe-22.04
```
#### NOTE
The HWE real-time kernel for Ubuntu 22.04 LTS is based on the 6.8
kernel.
### Ubuntu 24.04 LTS
```bash
sudo apt install linux-realtime-hwe-24.04
```
#### NOTE
The HWE real-time kernel for Ubuntu 24.04 LTS is based on the 6.17
kernel.
After rebooting, you’ll be running the HWE kernel for Real-time Ubuntu.
## Next steps
For more information about Real-time Ubuntu and how it can help you, refer
to the [official Real-time Ubuntu](https://canonical-real-time-ubuntu-documentation.readthedocs-hosted.com/en/latest/) documentation.
# index.html.md
# How to resolve a specific CVE or USN
In this guide, we will introduce the `pro fix` command and show how you can use it to resolve CVEs/USNs.
#### NOTE
If you want a simpler guide to get started with `pro fix`, start with
[our security features tutorial](https://ubuntu.com/pro-client/docs/latest/tutorials/security-with-pro.md#security-tutorial).
You can use the same VM-based environment created in that tutorial
to recreate the output shown below yourself.
Before you begin, you will need to update the Pro Client to the most recent
version:
```bash
$ sudo apt update && sudo apt install ubuntu-pro-client
```
## Use `pro fix`
First, let’s see what happens to your system when `pro fix` runs.
Every `pro fix` output has a similar output structure. It:
* describes the CVE/USN;
* displays the affected packages;
* fixes the affected packages; and
* at the end, shows if the CVE/USN is fully fixed in the machine.
This is best demonstrated in a `pro fix` call that *does* fix a package.
Therefore let us install an older package on the VM that we know is associated
with [CVE-2020-25686](https://ubuntu.com/security/CVE-2020-25686). You can install the package by running these commands:
```bash
$ sudo apt update
$ sudo apt install dnsmasq=2.75-1
```
Now, let’s run `pro fix` on the CVE:
```bash
$ sudo pro fix CVE-2020-25686
```
You will then see the following output:
```text
CVE-2020-25686: Dnsmasq vulnerabilities
- https://ubuntu.com/security/CVE-2020-25686
1 affected package is installed: dnsmasq
(1/1) dnsmasq:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y dnsmasq }
✔ CVE-2020-25686 is resolved.
```
#### NOTE
We need to run the command with `sudo` because it will be installing a
package on the system.
Whenever `pro fix` has a package to upgrade, it follows a consistent
structure and displays the following, in this order:
1. The affected package
2. The availability of a fix
3. The location of the fix, if one is available
4. The command that will fix the issue
Also, at the end of the output you can see confirmation that the CVE was fixed
by the command. Just to confirm that the fix was successfully applied, let’s
run the `pro fix` command again, and we should now see the following:
```text
CVE-2020-25686: Dnsmasq vulnerabilities
- https://ubuntu.com/security/CVE-2020-25686
1 affected package is installed: dnsmasq
(1/1) dnsmasq:
A fix is available in Ubuntu standard updates.
The update is already installed.
✔ CVE-2020-25686 is resolved.
```
There might be other cases which you might encounter when using `pro fix` to resolve a CVE/USN. You can learn more about these cases in the guide detailing [Common scenarios encountered when using pro fix to solve a CVE/USN](https://ubuntu.com/pro-client/docs/latest/explanations/fix_scenarios.md#pro-fix-howto).
### Additional resources
This is not the only scenario where you might want to use `pro fix` . To find out about the other situations where it can be useful, as well as which options can be used to give you greater control over the command, you can refer to the following guides:
* [How do I know what the pro fix command would change?](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_what_the_fix_command_would_change.md#pro-fix-dry-run) will show you how to use `pro fix` in `--dry-run` mode to safely simulate the changes before they’re applied.
* [How to skip fixing related USNs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_not_fix_related_usns.md#pro-fix-skip-related) will show you how to only fix a single USN, even if other fixes are available.
If you need more information about this, please feel free to reach out
to the Ubuntu Pro Client team on `#ubuntu-server` on
Libera IRC – we’re happy to help!
Alternatively, if you have a GitHub account, click on the “Give feedback”
link at the top of this page to leave us a message. We’d love to hear from you!
# index.html.md
# How to preview the results when fixing multiple CVEs
To fix multiple CVEs, you need to use the `u.pro.security.fix.cve.execute.v1`
endpoint, as the CLI `pro fix` command doesn’t support multiple CVEs. However,
as can be seen in the
[endpoint documentation](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-security-fix-cve-execute-v1),
this command will output a JSON blob containing the results of the `fix`
operation for each CVE.
This doesn’t allow for a quick visualization of the `fix` status of each
requested CVE. To address that, you can use a `jq` filter. The `jq` command
is mainly used to parse JSON data directly in the terminal. To learn more about
it, refer to the `jq` [manpage](https://manpages.ubuntu.com/manpages/xenial/man1/jq.1.html).
Before proceeding, you need to ensure that `jq` is installed on your machine.
This can be achieved by running the following command:
```bash
$ sudo apt update && sudo apt install jq -y
```
Now that `jq` is installed, you can properly parse the JSON data delivered
from the `execute` API endpoint. As an example, let’s try to fix these three
CVEs: **CVE-2020-28196**, **CVE-2020-15180** and **CVE-2017-9233**.
To do that, run the following command:
```bash
pro api u.pro.security.fix.cve.execute.v1 --data '{"cves": ["CVE-2020-28196", "CVE-2020-15180", "CVE-2017-9233"]}' \
| jq -r '.data.attributes.cves_data.cves[] | "\(.title) (\(.description)) - \(.status)"'
```
We can see that the command output will be something that follows this
structure here:
```bash
CVE-2020-28196 (Kerberos vulnerability) - fixed
CVE-2020-15180 (MariaDB vulnerabilities) - not-affected
CVE-2017-9233 (Coin3D vulnerability) - fixed
```
Note that each entry in this output consists of three fields:
* **CVE NAME**: The name of the CVE
* **CVE DESCRIPTION**: The description of the CVE
* **CVE STATUS**: The status of the CVE which can be one of: **fixed, still-affected, not-affected**
and **affected-until-reboot**.
If you want to change the output format, you can tweak the `jq` filter. For
example, to only show the CVE title and status, you can change the `jq`
filter to:
```bash
jq -r '.data.attributes.cves_data.cves[] | "\(.title) - \(.status)"'
```
Finally, if you want to have the same visualization when fixing USNs, change
the `jq` filter to:
```bash
jq -r '.data.attributes.usns_data.usns[] | "\(.title) (\(.description)) - \(.status)"'
```
# index.html.md
# How to skip fixing related USNs
The general scenarios you might encounter when running `pro fix` are
outlined in our explanation of
[using pro fix to solve a CVE/USN](https://ubuntu.com/pro-client/docs/latest/explanations/fix_scenarios.md#pro-fix-howto).
When running the `pro fix` command for a USN, by default we also try to fix
any related USNs as well. To better understand the concept of related USNs,
you can refer to our [related USNs guide](https://ubuntu.com/pro-client/docs/latest/explanations/cves_and_usns_explained.md#expl-cve-usn).
To make this clear, let’s take a look into the following example:
```text
USN-5573-1: rsync vulnerability
Associated CVEs:
- https://ubuntu.com/security/CVE-2022-37434
Fixing requested USN-5573-1
1 affected source package is installed: rsync
(1/1) rsync:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y rsync }
✔ USN-5573-1 is resolved.
Found related USNs:
- USN-5570-1
- USN-5570-2
Fixing related USNs:
- USN-5570-1
No affected source packages are installed.
✔ USN-5570-1 does not affect your system.
- USN-5570-2
1 affected source package is installed: zlib
(1/1) zlib:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y zlib1g }
✔ USN-5570-2 is resolved.
Summary:
✔ USN-5573-1 [requested] is resolved.
✔ USN-5570-1 [related] does not affect your system.
✔ USN-5570-2 [related] is resolved.
```
We can see here that the `pro fix` command fixed the requested
**USN-5573-1** while also handling both **USN-5570-1** and **USN-5570-2**,
which are related to the requested USN.
If you don’t want to fix any related USNs during the `fix` operation, you
can use the `--no-related` flag. By running the command
`pro fix USN-5573-1 --no-related` we would get the following output instead:
```text
USN-5573-1: rsync vulnerability
Associated CVEs:
- https://ubuntu.com/security/CVE-2022-37434
Fixing requested USN-5573-1
1 affected source package is installed: rsync
(1/1) rsync:
A fix is available in Ubuntu standard updates.
{ apt update && apt install --only-upgrade -y rsync }
✔ USN-5573-1 is resolved.
```
Comparing this output to the previous one, we can see that we have not analyzed
or tried to fix any related USNs.
# index.html.md
# How to enable CIS or USG
On Ubuntu 20.04 LTS (Focal) and later releases, CIS was
[replaced by USG](https://ubuntu.com/security/certifications/docs/usg). If you are running Focal (or a later release) and
want to enable `usg`, then select the **USG** tab below.
## Make sure `pro` is up-to-date
All systems come with `pro` pre-installed through the
`ubuntu-pro-client` package. To make sure that you’re running the latest
version of `pro`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
## Check the status of the services
After you have [attached your subscription](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) and
updated the `ubuntu-pro-client` package, you can check which services
are enabled by running the following command:
```bash
pro status
```
This will show you which services are enabled or disabled on your machine
(output truncated for brevity):
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
livepatch yes enabled Canonical Livepatch service
realtime-kernel yes disabled Ubuntu kernel with PREEMPT_RT patches integrated
```
## Enable the service
To access the tooling, first enable the software repository as follows:
### CIS
> ```bash
> $ sudo pro enable cis
> ```
### USG
> ```bash
> $ sudo pro enable usg
> ```
You should see output like the following, indicating that the package has been
installed:
### CIS
> ```text
> Updating CIS Audit package lists
> Updating standard Ubuntu package lists
> Installing CIS Audit packages
> CIS Audit enabled
> Visit https://ubuntu.com/security/cis to learn how to use CIS
> ```
### USG
> ```text
> Updating Ubuntu Security Guide package lists
> Ubuntu Security Guide enabled
> Visit https://ubuntu.com/security/certifications/docs/usg for the next steps
> ```
Once the feature is enabled you can [follow the documentation](https://ubuntu.com/security/certifications/docs/usg/cis)
for both the CIS and USG tooling, to run the provided hardening audit scripts.
## Disable the service
If you wish to disable the service, you can use the following command:
### CIS
> ```bash
> $ sudo pro disable cis
> ```
### USG
```bash
$ sudo pro disable usg
```
You can verify that the service has been correctly disabled by once again
running the `pro status` command.
Note that this command will only remove the APT sources, but not uninstall any
of the packages installed with the service.
To purge the service, removing all APT packages installed with it, see
[how to disable and purge services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge). This does not
remove any of your configuration, it only removes the packages.
# index.html.md
# How to check your Ubuntu Pro Client version
There are two ways to check the current version of the Ubuntu Pro Client you
are running. You can use the command:
```bash
pro version
```
Or the alternative:
```bash
pro --version
```
# index.html.md
# How to manage Ubuntu Pro attachment when moving machines
This guide explains what happens to your Ubuntu Pro attachment when you move,
clone, rebuild, or delete a machine, and what actions (if any) you need to
take in each case.
Ubuntu Pro attachment information is stored locally on the machine. The
subscription’s active machine count is based on activity. If a machine is
stopped or deleted, it will eventually be removed from the active count
automatically. No manual detach is required.
#### NOTE
Run `sudo pro status` or `sudo pro refresh` at any time to verify the
current attachment state of a machine.
## Moving a VM to another host or hypervisor
When you move an attached VM to a different host, hypervisor, or virtual
environment (for example, a live migration or export/import), the Pro
attachment travels with it. The attachment data is part of the filesystem,
so no re-attachment is needed after the move.
1. Move the VM using your platform’s standard tooling.
2. After the move, verify the attachment is intact:
```bash
sudo pro status
```
No further action is required. The machine continues to be counted as one
active machine on your subscription, as it was before.
## Cloning an attached VM
When you clone an attached VM, the clone inherits the attachment from the
original. Both the original and the clone will be counted as separate active
machines on your subscription.
If you intend to **replace** the original with the clone (for example, for
testing or migration), stop or delete the original. It will eventually be
removed from the active count automatically.
#### NOTE
If you are creating a **reusable template or golden image** from an attached
VM, you should not leave the image in an attached state. See
[How to create a customized Cloud Ubuntu Pro image](https://ubuntu.com/pro-client/docs/latest/howtoguides/create_pro_golden_image.md#create-pro-golden-image) for the recommended approach to creating
Ubuntu Pro golden images.
1. Clone the VM using your platform’s standard tooling.
2. Verify the attachment on the new clone:
```bash
sudo pro status
```
3. If you no longer need the original, stop or delete it. No detach is needed
before deletion.
## Rebuilding a machine with a fresh Ubuntu installation
If you reinstall a fresh Ubuntu image, the new installation does not carry over the previous Pro attachment.
You will need to attach the rebuilt machine to your subscription:
```bash
sudo pro attach
```
Your Pro token is available from the [Ubuntu Pro Dashboard](https://ubuntu.com/pro/dashboard).
If the previous machine is no longer in use, there is no need to detach it
first. It will eventually be removed from the active count automatically.
## Decommissioning or deleting a machine
You do not need to detach a machine before decommissioning or deleting it. Once
the machine is gone and no longer communicates with the Ubuntu Pro service, it
will eventually be removed from the active count automatically.
You can detach before deleting, but this is optional:
```bash
sudo pro detach
```
## Verifying the result
After any migration operation, use the following commands to confirm the state
of your attachment:
- Check the current attachment status and enabled services:
```bash
sudo pro status
```
- Force a refresh to sync with the Ubuntu Pro service:
```bash
sudo pro refresh
```
# index.html.md
# How to collect Ubuntu Pro Client logs
When reporting a bug it is helpful to include your logs. To collect all of the
necessary logs for Ubuntu Pro Client (`pro`), run the following command:
```bash
$ sudo pro collect-logs
```
This command creates a tarball with all relevant data for debugging possible
problems with `pro`.
It puts together:
* The Ubuntu Pro Client configuration file (the default is
`/etc/ubuntu-advantage/uaclient.conf`)
* The Ubuntu Pro Client log files (the default is `/var/log/ubuntu-advantage*`)
* The files in `/etc/apt/sources.list.d/*` related to Ubuntu Pro
* Output of `systemctl status` for the Ubuntu Pro Client-related services
* Status of the timer jobs, `canonical-livepatch`, and the `systemd` timers
* Output of `cloud-id`, `dmesg` and `journalctl`
Sensitive data is redacted from all files included in the tarball. As of now,
the command must be run as root.
Running the command creates a `pro_logs.tar.gz` file in the current directory.
The output file path/name can be changed using the `-o` option.
You can then attach these logs when
[reporting a bug on Launchpad](https://bugs.launchpad.net/ubuntu/+source/ubuntu-advantage-tools/+filebug).
# index.html.md
# Handle vulnerabilities
Using the Pro Client, you can handle individual vulnerabilities (both CVEs and
USNs) that may be affecting your machine. You can also preview what will happen
if you run the `pro fix` command on a specific vulnerability, and control
if related USNs are fixed.
* [Check if a system is affected](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_if_system_affected_by_cve.md#pro-fix-check-cve)
* [Use pro fix to resolve a CVE or USN](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_resolve_given_cve.md#pro-fix-resolve-cve)
* [Preview pro fix results](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_know_what_the_fix_command_would_change.md#pro-fix-dry-run)
* [Skip fixing related USNs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_not_fix_related_usns.md#pro-fix-skip-related)
You can also resolve multiple vulnerabilities at once using the API.
* [Check if your system is affected by multiple CVEs](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_know_if_system_affected_by_a_list_of_cves.md#pro-check-list-cves)
* [Preview result of fixing multiple CVEs](https://ubuntu.com/pro-client/docs/latest/howtoguides/fix_how_to_better_visualize_fixing_multiple_cves.md#how-to-better-visualize-fixing-multiple-cves)
# index.html.md
# How to configure a timer job
All timer jobs can be configured through the `pro config set` command.
We will show how you can properly use this command to interact with timer jobs.
## Check a timer job’s configuration
To see each job’s running interval, use the `show` command:
```bash
$ sudo pro config show
```
You should see output which includes the timer jobs:
```text
update_messaging_timer 21600
metering_timer 14400
```
## Change a timer job interval
Each job has a configuration option of the form `_timer`,
which can be set with `pro config`. The expected value is a positive
integer for the number of seconds in the interval. For example, to
change the `update_messaging job` timer interval to run every 24 hours, run:
```bash
$ sudo pro config set update_messaging_timer=86400
```
## Disable a timer job
To disable a job, set its interval to zero. For instance, to disable
the `update_messaging` job, run:
```bash
$ sudo pro config set update_messaging_timer=0
```
# index.html.md
# Configure messages
You can choose whether (and how) to display APT and MOTD messages, set timer
jobs, or use your own custom configuration.
* [Display or hide APT News](https://ubuntu.com/pro-client/docs/latest/howtoguides/disable_enable_apt_news.md#disable-enable-apt-news)
* [Use custom APT configuration](https://ubuntu.com/pro-client/docs/latest/howtoguides/use_custom_apt_config.md#custom-apt-config)
* [Refresh MOTD and APT messages](https://ubuntu.com/pro-client/docs/latest/howtoguides/update_motd_messages.md#update-motd-apt)
* [Configure a timer job](https://ubuntu.com/pro-client/docs/latest/howtoguides/configuring_timer_jobs.md#configuring-timer-jobs)
# index.html.md
# How to create a customized Cloud Ubuntu Pro image
* Launch an Ubuntu Pro instance on your cloud of choice
* customize the instance as you see fit
* Run the command: `sudo truncate -s 0 /etc/machine-id`
* Use your cloud platform to clone or snapshot this VM as a **golden image**
For more detailed instructions on creating customized Cloud Ubuntu Pro images, refer to the following guides:
* [AWS guide](https://documentation.ubuntu.com/aws/en/latest/aws-how-to/instances/build-pro-ami-using-packer/)
* [Azure guide](https://documentation.ubuntu.com/azure/en/latest/azure-how-to/instances/create-pro-fips-golden-image/)
* [GCP guide](https://documentation.ubuntu.com/gcp/en/latest/google-how-to/gce/build-ubuntu-pro-golden-image/)
#### TIP
Prior to Pro Client version 27.11, when launching instances based on this
instance, you will need to re-enable any non-standard Ubuntu Pro services
that you enabled on the image. This will be faster on the new instance
because it was already enabled on the image. You will not need to reboot
for e.g. `fips` or `fips-updates`.
# index.html.md
# How to attach with a configuration file
To attach with a configuration file, you can run `pro attach` with the
`--attach-config` flag, passing the path of the configuration file you intend
to use.
When using `--attach-config` the token must be passed in the file rather than
on the command line. This is useful in situations where it is preferred to keep
the secret token in a file.
Optionally, the attached config file can be used to override the services that
are automatically enabled as a part of the attach process.
## Get an Ubuntu Pro token
Retrieve your Ubuntu Pro token from the [Ubuntu Pro portal](https://ubuntu.com/pro). Log in
with your “Single Sign On” credentials, the same credentials you use for
[https://login.ubuntu.com](https://login.ubuntu.com).
After you have logged in you can go to the
[Ubuntu Pro Dashboard](https://ubuntu.com/pro/dashboard) associated with your user account. It
will show you all subscriptions currently available to you and for each
associated token.
Note that even without buying anything you can always obtain a free personal
token that way, which provides you with access to several of the Ubuntu Pro
services.
## The attach config file
An attach config file looks like this:
```yaml
token: YOUR_TOKEN_HERE # required
enable_services: # optional list of service names to auto-enable
- esm-infra
- esm-apps
- cis
```
And can be passed via the CLI with the following command:
```bash
sudo pro attach --attach-config /path/to/file.yaml
```
# index.html.md
# Attaching machines
To access Ubuntu Pro services, you need to first attach your machine to a
subscription:
* [How to attach](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach)
You can also simulate attaching to a specific token, to check what will happen
without making changes to your machine:
* [How to simulate attaching](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_simulate_attach.md#simulate-attach)
It’s also possible to pass a specific token to your machine using a
configuration file:
* [Attach using a config file](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach_with_config_file.md#attach-with-config)
If you need to move, clone, rebuild, or delete an attached machine, see:
* [Move or clone an attached machine](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_migrate_attached_machines.md#how-to-migrate-attached-machines)
# index.html.md
# How to manage CC EAL
[Common Criteria](https://ubuntu.com/security/cc) is supported only on Ubuntu 16.04 (Xenial) and 18.04
(Bionic). This means that CC EAL2 can be enabled on both Xenial and Bionic LTS
releases, but the installed scripts that configure CC EAL2 on those machines
will only run on Xenial 16.04.4 and Bionic 18.04.4 point releases.
## Make sure `pro` is up-to-date
All systems come with `pro` pre-installed through the
`ubuntu-pro-client` package. To make sure that you’re running the latest
version of `pro`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
## Check the status of the services
After you have [attached your subscription](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) and
updated the `ubuntu-pro-client` package, you can check which services
are enabled by running the following command:
```bash
pro status
```
This will show you which services are enabled or disabled on your machine
(output truncated for brevity):
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
livepatch yes enabled Canonical Livepatch service
realtime-kernel yes disabled Ubuntu kernel with PREEMPT_RT patches integrated
```
## Enable and auto-install
To enable CC EAL2 using the Ubuntu Pro Client, run the following command:
```bash
$ sudo pro enable cc-eal
```
You should see output like this:
```text
Updating package lists
(This will download more than 500MB of packages, so may take some time.)
Installing CC EAL2 packages
CC EAL2 enabled
Please follow instructions in /usr/share/doc/ubuntu-commoncriteria/README to configure EAL2
```
This indicates that the CC EAL2 package has been successfully installed.
## Enable and manually install
#### HINT
The `--access-only` flag was introduced in Pro Client version 27.11.
If you would like to enable access to the CC EAL2 `apt` repository but not
install the packages immediately, use the `--access-only` flag while
enabling:
```bash
$ sudo pro enable cc-eal --access-only
```
With that extra flag you’ll see output like the following:
```text
One moment, checking your subscription first
Updating package lists
Skipping installing packages: ubuntu-commoncriteria
CC EAL2 access enabled
```
To install the packages at a later time, you can then run:
```bash
$ sudo apt install ubuntu-commoncriteria
```
## Disable the service
If you wish to disable `cc-eal`, you can use the following command:
```bash
sudo pro disable cc-eal
```
Note that this command will only remove the APT source, but not uninstall any
of the packages installed with the service.
To purge the service, removing the APT packages installed with it, see
[how to disable and purge services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge). This will not
remove any configuration, but will remove the packages.
# index.html.md
# How to attach a machine to your Ubuntu Pro subscription
To attach your machine to a subscription, run the following command in your
terminal:
```bash
$ sudo pro attach
```
You should see output like this, giving you a link and a code:
```bash
ubuntu@test:~$ sudo pro attach
Initiating attach operation...
Please sign in to your Ubuntu Pro account at this link:
https://ubuntu.com/pro/attach
And provide the following code: H31JIV
```
Open the link without closing your terminal window.
In the field that asks you to enter your code, copy and paste the code shown
in the terminal. Then, choose which subscription you want to attach to.
By default, the Free Personal Token will be selected.
If you have a paid subscription and want to attach to a different token, you
may want to log in first so that your additional tokens will appear.
Once you have pasted your code and chosen the subscription you want to attach
your machine to, click on the “Submit” button.
The attach process will then continue in the terminal window, and you should
eventually be presented with the following message:
```bash
Attaching the machine...
Enabling default service esm-apps
Updating Ubuntu Pro: ESM Apps package lists
Ubuntu Pro: ESM Apps enabled
Enabling default service esm-infra
Updating Ubuntu Pro: ESM Infra package lists
Ubuntu Pro: ESM Infra enabled
Enabling default service livepatch
Installing snapd snap
Installing canonical-livepatch snap
Canonical Livepatch enabled
This machine is now attached to 'Ubuntu Pro - free personal subscription'
```
When the machine has successfully been attached, you will also see a summary of
which services are enabled and information about your subscription.
Once the Ubuntu Pro Client is attached to your Ubuntu Pro 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.
## Control of auto-enabled services
Your subscription controls which services are available to you and which ones
you can manage via the Ubuntu Pro Dashboard.
Recommended services are auto-enabled by default when attaching a machine.
You can choose which of the available services will be automatically
enabled or disabled when you attach by toggling them “on” or “off” in the
[Ubuntu Pro Dashboard](https://ubuntu.com/pro/dashboard).
Available services can always be enabled or disabled on the command line
with `pro enable` and `pro disable` after attaching.
If your subscription does not permit you to change the default enabled services
via the Dashboard, or if you want to keep the defaults but do not want to
auto-enable any services while attaching a particular machine, you can pass
the `--no-auto-enable` flag to `attach` in the following way:
```bash
$ sudo pro attach --no-auto-enable
```
#### NOTE
If you want to control which services are enabled during attach, you can
[attach with a configuration file](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach_with_config_file.md#attach-with-config) instead.
# index.html.md
# Enable services
Enable, disable or check the status of the following services with the Pro
Client:
* [Anbox Cloud](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_anbox.md#manage-anbox)
* [CC EAL](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cc.md#manage-cc)
* [CIS or USG](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_cis.md#manage-cis)
* [ESM-Infra and ESM-Apps](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_esm_infra.md#manage-esm)
* [ESM-Infra Legacy on Trusty](https://ubuntu.com/pro-client/docs/latest/howtoguides/trusty_legacy_support.md#enable-trusty)
* [FIPS](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_fips.md#manage-fips)
* [Landscape](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_landscape.md#manage-landscape)
* [Livepatch](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_livepatch.md#manage-livepatch)
* [Real-Time Ubuntu](https://ubuntu.com/pro-client/docs/latest/howtoguides/enable_realtime_kernel.md#manage-realtime)
# index.html.md
# How to customize a cloud Ubuntu Pro image with FIPS updates
## Launch an Ubuntu Pro instance on your cloud
See the following links for up to date information about Pro for each supported
cloud:
* [AWS](https://ubuntu.com/aws/pro)
* [Azure](https://ubuntu.com/azure/pro)
* [GCP](https://ubuntu.com/gcp/pro)
## Enable FIPS updates
Wait for the standard Ubuntu Pro services to be set up:
```bash
sudo pro status --wait
```
Use the enable command to set up FIPS updates:
```bash
sudo pro enable fips-updates --assume-yes
```
Now, reboot the instance:
```bash
sudo reboot
```
And verify that `fips-updates` is enabled in the output of `pro status`:
```bash
sudo pro status
```
Also remove the `machine-id` so that it is regenerated for each instance
launched from the snapshot.
```bash
sudo rm /etc/machine-id
```
## Snapshot the instance as a Cloud image
Cloud-specific instructions are here:
* [AWS](https://ubuntu.com/aws/pro)
* [Azure](https://ubuntu.com/azure/pro)
* [GCP](https://ubuntu.com/gcp/pro)
## Launch your custom image
Use your specific cloud to launch a new instance from the custom image.
#### NOTE
For versions of the Ubuntu Pro Client prior to 27.11, you will need to
re-enable `fips-updates` on each instance launched from the custom image.
This won’t require a reboot and is only necessary to ensure the instance
gets updates to FIPS packages when they become available.
```bash
sudo pro enable fips-updates --assume-yes
```
This can be scripted using [cloud-init user data](https://cloudinit.readthedocs.io/en/latest/reference/modules.html#runcmd) at launch time:
```yaml
#cloud-config
# Enable fips-updates after pro auto-attach and reboot after cloud-init completes
runcmd:
- 'pro status --wait'
- 'pro enable fips-updates --assume-yes'
```
# index.html.md
# How to use custom APT configuration
The Pro Client CLI is able, through the security-status command, to show
information about installed packages in the system, their origins, and
potential updates that may be available for them. This information is also
available through the
[packages updates API](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-packages-updates-v1) and the
[packages summary API](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-packages-summary-v1) calls,
for example.
The information presented on the outputs mentioned above is taken directly
from the local APT caches. Packages, origins, versions, and candidates are all
calculated using the `python3-apt` library, which in turn relies on the
knowledge APT has about in a particular machine.
You may need to configure APT to have some specific behavior. An example could
be to pass custom `.list` or `.sources` files to APT, whether to limit or
to increase knowledge about different package sources.
The Pro Client will respect the [configuration set directly on APT](https://manpages.ubuntu.com/apt.conf), at
execution time. If system level configuration is present, it will be used by
default. To configure APT without changing the system, there is the option of
passing the config file as an environment variable.
## Use an APT config file
For example, consider that the `/etc/apt/apt.conf.d/50-custom` file exists,
and has this content:
```bash
$ cat /etc/apt/apt.conf.d/50-custom
# setting custom sources.list and unsetting the parts directory
Dir::Etc::Sourcelist "/my/personal/configured/sources.list";
Dir::Etc::Sourceparts "nonexisting-dir";
```
APT will use this configuration by default when running all operations.
The Pro Client will do the same - all outputs will take the custom `.list`
file into consideration, and no `parts` directory will be loaded (unless the
directory set there actually exists).
## Use an environment variable
Now, if the user does not want to change their system, the `APT_CONFIG`
environment variable can be set when running APT commands, pointing to the
desired configuration file.
For example, let’s say that instead of `apt.conf.d`, the config file is
created in `/tmp`:
```bash
$ cat /tmp/custom-config
# setting custom sources.list and unsetting the parts directory
Dir::Etc::Sourcelist "/my/personal/configured/sources.list";
Dir::Etc::Sourceparts "nonexisting-dir";
```
APT will respect this configuration if found in the aforementioned environment
variable:
```bash
$ APT_CONFIG=/tmp/custom-config apt list --installed
$ APT_CONFIG=/tmp/custom-config sudo apt update
```
If the variable is set when executing the Pro Client commands that depend on
APT, it will also be respected:
```bash
$ APT_CONFIG=/tmp/custom-config pro security-status
$ APT_CONFIG=/tmp/custom-config pro api u.pro.packages.updates.v1
```
## In the python API integration
Changing the environment also works for the integration with the Pro Client’s
APIs. Even after import time, it is just a matter of setting the value in
`os.environ` before calling the function.
```python3
import os
from uaclient.api.u.pro.packages.updates.v1 import updates
# call updates using the system APT configuration
updates()
# set the custom configuration, so updates will respect it, then set it
# back to the original value so it respects the system config again
try:
old_env_apt_config = os.getenv("APT_CONFIG")
os.environ["APT_CONFIG"] = "/tmp/custom-config"
updates()
# (...)
finally:
os.environ["APT_CONFIG"] = old_env_apt_config
```
# index.html.md
# How to manage Anbox Cloud
To use [Anbox Cloud](https://anbox-cloud.io/), you will need to enable it directly through the
Ubuntu Pro Client (`pro`), which will install all the necessary snaps and set
up the APT sources needed for the service.
#### NOTE
Anbox Cloud is supported on all recent Ubuntu LTS releases (from 20.04 LTS
onward). Refer to the [Anbox Cloud requirements page](https://documentation.ubuntu.com/anbox-cloud/reference/requirements/) for more details.
## Make sure `pro` is up-to-date
All systems come with `pro` pre-installed through the
`ubuntu-pro-client` package. To make sure that you’re running the latest
version of `pro`, run the following commands:
```bash
sudo apt update && sudo apt install ubuntu-pro-client
```
## Check the status of the services
After you have [attached your subscription](https://ubuntu.com/pro-client/docs/latest/howtoguides/how_to_attach.md#attach) and
updated the `ubuntu-pro-client` package, you can check which services
are enabled by running the following command:
```bash
pro status
```
This will show you which services are enabled or disabled on your machine
(output truncated for brevity):
```text
SERVICE ENTITLED STATUS DESCRIPTION
esm-apps yes enabled Expanded Security Maintenance for Applications
esm-infra yes enabled Expanded Security Maintenance for Infrastructure
livepatch yes enabled Canonical Livepatch service
realtime-kernel yes disabled Ubuntu kernel with PREEMPT_RT patches integrated
```
## Enable Anbox
To enable Anbox Cloud, run:
```bash
$ sudo pro enable anbox-cloud
```
#### IMPORTANT
The Anbox Cloud service can only be installed on **containers** using the
`--access-only` flag. This option will only set up the APT sources for
Anbox, but not install any of the snaps.
You should see output like the following, indicating that Anbox Cloud
was correctly enabled on your system:
```text
One moment, checking your subscription first
Installing required snaps
Installing required snap: anbox-cloud-appliance
Configuring APT access to Anbox Cloud
Updating Anbox Cloud package lists
Anbox Cloud enabled
To finish setting up the Anbox Cloud Appliance, run the following commands
sequentially:
The `prepare-node-script` command lets you preview a script that installs some
additional packages, kernel modules and GPU driver packages, if a GPU is
available:
$ anbox-cloud-appliance prepare-node-script > prepare.sh
Preview the script and when ready, apply it to complete the installation:
$ sudo bash -ex prepare.sh
Once installed, to initialize Anbox Cloud, run:
$ sudo anbox-cloud-appliance init
You can accept the default answers if you do not have any specific
configuration changes.
For more information, see https://anbox-cloud.io/docs/tutorial/installing-appliance/#initialize-the-appliance
```
You have probably noticed that the output states an **additional step** is
required to complete the Anbox Cloud setup. Let us run the required command:
```bash
$ anbox-cloud-appliance prepare-node-script > prepare.sh
$ sudo bash -ex prepare.sh
$ sudo anbox-cloud-appliance init
```
You can now confirm that the service is enabled by running the `pro status`
command again. It should contain the following line for `anbox-cloud`:
```text
SERVICE ENTITLED STATUS DESCRIPTION
anbox-cloud yes enabled Scalable Android in the cloud
```
## Disable the service
If you wish to disable Anbox, you can use the following command to
disable it:
```bash
sudo pro disable anbox-cloud
```
Note that this command will only remove the APT sources, but will not uninstall
the snaps.
To also purge the service, removing all the APT packages installed with it, see
[how to disable and purge services](https://ubuntu.com/pro-client/docs/latest/explanations/purging_services.md#disable-and-purge).
# index.html.md
# Check if a system is affected by a list of CVEs
The Ubuntu Pro Client (`pro`) can be used to inspect and resolve
[Common Vulnerabilities and Exposures](https://ubuntu.com/security/cves) (CVEs) and
[Ubuntu Security Notices](https://ubuntu.com/security/notices) (USNs) on your machine.
Every CVE/USN is fixed by trying to upgrade all of the affected packages
described by the CVE or USN. Sometimes, the package fixes can only be applied
if an Ubuntu Pro service is already enabled on your machine.
If you have a list of CVEs and/or USNs and want to check if your Ubuntu
system is affected by them, you can check using the
`u.pro.security.fix.cve.plan.v1` API endpoint as we’ll show you in this guide.
#### NOTE
The `u.pro.security.fix.cve.plan` API endpoint is provided as part of the
Ubuntu Pro Client (`pro`), which is a security tool for Ubuntu systems.
The Ubuntu Pro Client comes pre-installed on every Ubuntu system. You can
run `pro help` in your terminal window to see a list of the `pro`
services and commands available.
## Using the `pro.fix.cve.plan` API
To check if your system is affected by a list of CVEs, you need to use the
`u.pro.security.fix.cve.plan.v1` API endpoint, since the
`pro fix --dry-run` CLI command is only used to check individual CVEs. The
API endpoint will output a JSON blob containing the current status of each CVE,
as can be seen [in the endpoint documentation](https://ubuntu.com/pro-client/docs/latest/references/api.md#u-pro-security-fix-cve-execute-v1).
To better visualize the current status of each CVE from the JSON output we can
use a `jq` filter. The `jq` command can parse JSON data directly in the
terminal, creating a more readable output. For more details about `jq`, refer
to [the manual page](https://manpages.ubuntu.com/manpages/xenial/man1/jq.1.html)
First, we need to install `jq` by running the following command:
```bash
sudo apt update & sudo apt install jq -y
```
Once `jq` is installed, we can parse the JSON data returned from the plan API.
For example, if we want to see if our system is affected by the CVEs:
* **CVE-2020-28196**
* **CVE-2020-15180**
* **CVE-2017-9233**
We make use of the plan API by running the following command:
```bash
pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-2020-28196", "CVE-2020-15180", "CVE-2017-9233"]}' \
| jq -r '.data.attributes.cves_data.cves[] | "\(.title) (\(.description)) - Current Status: \(.current_status)"'
```
This command returns output with the following structure:
```bash
CVE-2020-28196 (Kerberos vulnerability) - Current Status: not-affected
CVE-2020-15180 (MariaDB vulnerabilities) - Current Status: not-affected
CVE-2017-9233 (Coin3D vulnerability) - Current Status: not-affected
```
Note that each entry in this output consists of three fields:
* **CVE NAME**: The name of the CVE
* **CVE DESCRIPTION**: The description of the CVE
* **CVE STATUS**: The current status of the CVE