diff --git a/custom_wordlist.txt b/custom_wordlist.txt index a6b3df6e54..a1948ae84a 100644 --- a/custom_wordlist.txt +++ b/custom_wordlist.txt @@ -1,14 +1,11 @@ -AdditionalData airgapped Airgapping amd anbox Anbox aptnews -AptUpgradeData Args armhf -AttachData aws backport benchmarking @@ -27,7 +24,6 @@ CTRL cve CVE CVEAPIFixExecuteResult -CVEFixPlanResult cves CVEs DISA @@ -36,8 +32,6 @@ dpkg eal EAL el -EnableData -EnabledService enablement esm ESM @@ -48,9 +42,7 @@ firewalled Firewalled FixExecuteError FixExecuteResult -FixExecuteUSNResult FixPlanError -FixPlanResult FixPlanStep FixPlanUSNResult FixPlanWarning @@ -70,7 +62,6 @@ latencies Libera livepatch Livepatch -LivepatchCVEObject Livepatches LTS lxd @@ -79,13 +70,10 @@ Mantic motd MOTD Multipass -NoOp NoOpAlreadyFixed -NoOpData NoOpLivepatchFixData num PackageCannotBeInstalledData -PackageSummary PEM PID powerpc @@ -121,15 +109,12 @@ uaclient ubuntu un unparsed -UpdateInfo -UpdateSummary UpgradedPackage usg USG usn usns USNAPIFixExecuteResult -USNFixPlanResult USNs usr VMs diff --git a/dev-docs/howtoguides/troubleshoot_security_confinement.md b/dev-docs/howtoguides/troubleshoot_security_confinement.md new file mode 100644 index 0000000000..67c336bd7b --- /dev/null +++ b/dev-docs/howtoguides/troubleshoot_security_confinement.md @@ -0,0 +1,260 @@ +# How to troubleshoot security confinement + +The Ubuntu Pro client ships some services with these special security confinement features: + - [systemd sandboxing features](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#Sandboxing) + - [AppArmor profile](https://ubuntu.com/server/docs/security-apparmor) + +In the git repository, these are located at: + - [apt-news.service](https://github.com/canonical/ubuntu-pro-client/blob/main/systemd/apt-news.service) + - [esm-cache.service](https://github.com/canonical/ubuntu-pro-client/blob/main/systemd/esm-cache.service) + - `debian/apparmor/ubuntu_pro_apt_news.jinja2` + - `debian/apparmor/ubuntu_pro_esm_cache.jinja2` + +These security features restrict what the service can do on the system, and it's quite common that an application faced with unexpected "permission denied" errors, or unavailability of resources, will either crash or behave unexpectedly. + +If you suspect the security confinement might be impacting these services, here are some troubleshooting tips. + +## Panic: disable everything + +To completely remove the security features and verify if they are the cause of the problem you are troubleshooting, we have to disable the AppArmor confinement for that service, and remove the systemd security sandboxing features. + +Do the following: + +1. Edit the systemd service unit file in `/lib/systemd/system/.service` and remove or comment the `AppArmorProfile` line, and the security isolation lines. + +For example, for `apt-news.service`, this is what the minimal version of that file should look like: +``` + [Unit] + Description=Update APT News + + [Service] + Type=oneshot + ExecStart=/usr/bin/python3 /usr/lib/ubuntu-advantage/apt_news.py +``` + +For `esm-cache.service`, we would have: +``` + [Unit] + Description=Update the local ESM caches + + [Service] + Type=oneshot + ExecStart=/usr/bin/python3 /usr/lib/ubuntu-advantage/esm_cache.py +``` + +An alternative to removing `AppArmorProfile` from the unit file is to just disable it on the system, or put it in complain mode. See "Troubleshooting Apparmor" below for details. + +2. Reload the systemd units: + +``` + sudo systemctl daemon-reload +``` + +3. Use the service and observe if the problem you are troubleshooting is still there. If it's still there, then the security features are not the cause. + + + +## Troubleshooting Apparmor + +The Apparmor profile for the confined service is loaded via the `AppArmorProfile` directive in the unit file `/lib/systemd/system/.service`. For example, for `apt-news.service`: +``` + [Service] + ... + AppArmorProfile=-ubuntu_pro_apt_news +``` + +This will apply the specified AppArmor profile on service startup. If the profile does not exist, the service startup will fail in Pro client versions older than 31.2.2. In newer versions, that failure will be masked (see [LP: #2057937](https://bugs.launchpad.net/ubuntu/+source/ubuntu-advantage-tools/+bug/2057937) for details) and the service will run unconfined, i.e., without AppArmor protection. + +The AppArmor profiles are located in the `/etc/apparmor.d` directory, and are loaded into the kernel at package install/upgrade time, or when the system boots. While the filename of the profile is an indication about its name, that's not mandatory: the actual name of the profile is defined inside the file. + +To verify if the Apparmor profile is causing the issues you are observing, the first troubleshooting attempt should be to put it in "complain" mode. In that mode, it will allow everything, but log if something would have been blocked had the profile been in "enforce" mode. + +To place the profile in complain mode, first install the `apparmor-utils` package, if it's not installed already: +``` + sudo apt install apparmor-utils +``` + +Then run this command to place the `ubuntu_pro_apt_news` profile in complain mode: +``` + sudo aa-complain /etc/apparmor.d/ubuntu_pro_apt_news +``` + +For `ubuntu_pro_esm_cache`, the command is: +``` + sudo aa-complain /etc/apparmor.d/ubuntu_pro_esm_cache +``` + +This will both change the profile file to include the `complain` flag, and reload it into the kernel. + +Next, keep an eye on the `dmesg` output with something like this: +``` +sudo dmesg -wT | grep -E 'apparmor=\".*(profile=\"ubuntu_pro_|name=\"ubuntu_pro_)' +``` + +And exercise the service. To make sure the service will run, and this applies to both `apt-news` and `esm-cache`, you should remove these files and directories: +``` +sudo rm -rf /var/lib/apt/periodic/update-success-stamp /run/ubuntu-advantage /var/lib/ubuntu-advantage/messages/* +``` + +And then start the service: +``` + sudo systemctl start apt-news.service +``` + +or, for `esm-cache`: +``` + sudo systemctl start esm-cache.service +``` + +If you see any logs with `ALLOWED` in them, then that action is something that would have been blocked by the AppArmor profile had it not been in "complain" mode, and is something you should add to the AppArmor profile. + +To make changes to the AppArmor profile, edit the respective profile file in the `/etc/apparmor.d` directory, save, and reload the profile with the following command: +``` +sudo apparmor_parser -r -W -T /etc/apparmor.d/ +``` + +Explaining the full syntax of the AppArmor profiles is out of scope for this document. You can find more information in the [apparmor.d manpage](https://manpages.ubuntu.com/manpages/noble/man5/apparmor.d.5.html). The Ubuntu Server Guide also has a good introduction on the topic in the [Security - AppArmor](https://ubuntu.com/server/docs/security-apparmor) page. + +ATTENTION: be mindful of the differences in Ubuntu Releases regarding the AppArmor profile syntax! + +## `esm-cache` specific AppArmor notes +The `esm-cache` service has an AppArmor profile that is a bit more involved than the one for `apt-news`. Instead of just one profile, there are multiple profiles, all defined in the same `/etc/apparmor.d/ubuntu_pro_esm_cache` file: + +``` +profile ubuntu_pro_esm_cache flags=(attach_disconnected) { + profile ps flags=(attach_disconnected) { + profile cloud_id flags=(attach_disconnected) { + profile dpkg flags=(attach_disconnected) { + profile ubuntu_distro_info flags=(attach_disconnected) { + profile apt_methods flags=(attach_disconnected) { + profile apt_methods_gpgv flags=(attach_disconnected) { +profile ubuntu_pro_esm_cache_systemctl flags=(attach_disconnected) { +profile ubuntu_pro_esm_cache_systemd_detect_virt flags=(attach_disconnected) { +``` + +This was done to avoid having to give the main profile (`ubuntu_pro_esm_cache`) too many privileges. Therefore, whenever other specific binaries are executed, the main profile switches to another one, which will have different rules just for that new execution. + + +## Troubleshooting systemd sandboxing + +Troubleshooting systemd sandboxing is not as straightforward as with AppArmor, because there are no specific logs telling you that a certain action was blocked. It will just be blocked, and it's up to the application to handle the situation. There is no "system" log to help with troubleshooting the sandbox rules. + +The only way to troubleshoot this sandboxing is to methodically disable rule by rule in the unit file for the service, and test it. + +For example, let's take the `/lib/systemd/system/apt-news.service` unit file as below: +``` +[Unit] +Description=Update APT News + +[Service] +Type=oneshot +ExecStart=/usr/bin/python3 /usr/lib/ubuntu-advantage/apt_news.py +AppArmorProfile=-ubuntu_pro_apt_news +CapabilityBoundingSet=~CAP_SYS_ADMIN +CapabilityBoundingSet=~CAP_NET_ADMIN +CapabilityBoundingSet=~CAP_NET_BIND_SERVICE +CapabilityBoundingSet=~CAP_SYS_PTRACE +CapabilityBoundingSet=~CAP_NET_RAW +PrivateTmp=true +RestrictAddressFamilies=~AF_NETLINK +RestrictAddressFamilies=~AF_PACKET +``` + +If you suspect that the `PrivateTmp` restriction is causing problems, comment it: +``` +... +CapabilityBoundingSet=~CAP_NET_RAW +#PrivateTmp=true +RestrictAddressFamilies=~AF_NETLINK +... +``` + +Then reload the unit files: +``` +sudo systemctl daemon-reload +``` + +And try the service again: +``` +sudo rm -rf /var/lib/apt/periodic/update-success-stamp /run/ubuntu-advantage /var/lib/ubuntu-advantage/messages/* +sudo systemctl start apt-news.service +``` + +If whatever incorrect behavior that you were observing is now gone, then it's likely that that restriction was causing it. + +The exact meaning of each sandboxing feature is well documented upstream, in the [systemd.exec sandboxing](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#Sandboxing) section of the manpage. But as with AppArmor, be mindful of differences between Ubuntu Releases: not all features from the latest releases will be available in, say, Ubuntu Xenial, for example. + +There is one additional troubleshooting tip that can be helpful, and that is to run any command with specific sandboxing features enabled. + +For example, let's try the `PrivateTmp` feature. First, let's create a file in `/tmp`: +``` +touch /tmp/my-file +``` + +It should be visible to you. Let's check with `ls -la /tmp/my-file`: +``` +-rw-r--r-- 1 root root 0 jan 3 16:31 /tmp/my-file +``` + +Now let's try it with the `PrivateTmp` restriction disabled, first. The command is: +``` +systemd-run -qt -p PrivateTmp=no ls -la /tmp/my-file +``` + +And the output will be: +``` +-rw-r--r-- 1 root root 0 jan 3 16:31 /tmp/my-file +``` + +What happens if we enable the restriction? The command now is: +``` +systemd-run -qt -p PrivateTmp=yes ls -la /tmp/my-file +``` + +And we get: +``` +/usr/bin/ls: cannot access '/tmp/my-file': No such file or directory +``` + +Interesting! What if we create a file in `/tmp` with the restriction enabled, will it still be there once the command finishes? Let's try: +``` +systemd-run -qt -p PrivateTmp=yes touch /tmp/other-file +``` + +And when we check with `ls -la /tmp/other-file`: +``` +ls: cannot access '/tmp/other-file': No such file or directory +``` + +That's what `PrivateTmp=yes` means: the service will get a fresh and empty `/tmp` directory when it starts, and that will be gone when it finishes. + +These restrictions can be specified multiple times in the `systemd-run` command line with the `-p` parameter. + +Here is another example: let's block the `CAP_NET_RAW` capability, and try the `ping` command: +``` +systemd-run -qt -p CapabilityBoundingSet=~CAP_NET_RAW ping -c 1 1.1.1.1 +``` + +That will show nothing, but the exit status `$?` is `203`, so something failed. If we check the journal, we will see: +``` +jan 03 16:36:31 nsnx2 systemd[1]: Started run-u3002.service - /usr/bin/ping -c 1 1.1.1.1. +jan 03 16:36:31 nsnx2 (ping)[575067]: run-u3002.service: Failed to execute /usr/bin/ping: Operation not permitted +jan 03 16:36:31 nsnx2 (ping)[575067]: run-u3002.service: Failed at step EXEC spawning /usr/bin/ping: Operation not permitted +jan 03 16:36:31 nsnx2 systemd[1]: run-u3002.service: Main process exited, code=exited, status=203/EXEC +jan 03 16:36:31 nsnx2 systemd[1]: run-u3002.service: Failed with result 'exit-code'. +``` + + +## Cheat sheet + +Here are a few handful AppArmor and systemd tips. + +| What | How | +|-----------------------------------------|----------------------------------------| +| Reload an AppArmor profile from disk | `sudo apparmor_parser -r -W -T ` | +| Place a profile in complain mode | `sudo aa-complain ` | +| Place a profile in enforce mode | `sudo aa-enforce ` | +| List loaded profiles | `sudo aa-status` | +| Check AppArmor logs | `sudo dmesg -wT \| grep apparmor=` | +| Run a command under an AppArmor profile | `sudo aa-exec -p ` | +| Run a command with a systemd sanboxing property | `sudo systemd-run -qt -p ` | diff --git a/docs/explanations/motd_messages.rst b/docs/explanations/motd_messages.rst index 5911feff79..9a79ce8bbc 100644 --- a/docs/explanations/motd_messages.rst +++ b/docs/explanations/motd_messages.rst @@ -218,9 +218,23 @@ Source: MOTD about available updates ``/var/lib/update-notifier/updates-available`` exists and if it does, inserts the message into the full MOTD. -If you want to disable any message of ``update-notifier`` (not just related to -Ubuntu Pro and ESM) about potentially available updates, remove -``/etc/update-motd.d/90-updates-available``. +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``: + +.. code-block:: 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 ==================================================== diff --git a/docs/howtoguides/how_to_better_visualise_fixing_multiple_cves.rst b/docs/howtoguides/how_to_better_visualise_fixing_multiple_cves.rst index aa718da11b..10c2a99a55 100644 --- a/docs/howtoguides/how_to_better_visualise_fixing_multiple_cves.rst +++ b/docs/howtoguides/how_to_better_visualise_fixing_multiple_cves.rst @@ -3,22 +3,22 @@ How to better visualise the result 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 :ref:`in the endpoint documentation `, +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 :ref:`in the endpoint documentation`, this command will output a JSON blob containing the results of the fix operation for each CVE. This doesn't allow for a quick visualisation of the fix status of each requested CVE. -To address that, we can use a ``jq`` filter. The ``jq`` command is mainly used to parse JSON data directly in +To address that, we can use a `jq` filter. The `jq` command is mainly used to parse JSON data directly in the terminal. To know more about it, please refer to `the jq manpage `_ -Before proceeding, we need to guarantee that ``jq`` is installed in your machine. This can be achieved +Before proceeding, we need to guarantee that `jq` is installed in your machine. This can be achieved by running the following command: .. code-block:: bash $ apt update & apt install jq -y -Now that ``jq`` is installed, we can properly parse the JSON data delivered from the execute API. +Now that `jq` is installed, we can properly parse the JSON data delivered from the execute API. As an example, let's assume we want to fix these three CVEs: **CVE-2020-28196, CVE-2020-15180** and **CVE-2017-9233**. @@ -44,14 +44,14 @@ Note that each entry in this output consists of three fields: * **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: +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: .. code-block:: bash jq -r '.data.attributes.cves_data.cves[] | "\(.title) - \(.status)"' -Finally, if you want to have the same visualisation when fixing USNs, just change the ``jq`` filter +Finally, if you want to have the same visualisation when fixing USNs, just change the `jq` filter to: .. code-block:: bash diff --git a/docs/howtoguides/how_to_collect_logs.rst b/docs/howtoguides/how_to_collect_logs.rst index b4c5002de6..c7b554d624 100644 --- a/docs/howtoguides/how_to_collect_logs.rst +++ b/docs/howtoguides/how_to_collect_logs.rst @@ -24,5 +24,5 @@ It puts together: 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 ``ua_logs.tar.gz`` file in the current directory. +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. diff --git a/docs/includes/pro-fix-simple-case.txt b/docs/includes/pro-fix-simple-case.txt index fdbb785d6b..5909946db8 100644 --- a/docs/includes/pro-fix-simple-case.txt +++ b/docs/includes/pro-fix-simple-case.txt @@ -19,7 +19,7 @@ You will then see the following output: .. code-block:: text CVE-2020-25686: Dnsmasq vulnerabilities - https://ubuntu.com/security/CVE-2020-25686 + - https://ubuntu.com/security/CVE-2020-25686 1 affected package is installed: dnsmasq (1/1) dnsmasq: @@ -48,7 +48,7 @@ run the ``pro fix`` command again, and we should now see the following: .. code-block:: text CVE-2020-25686: Dnsmasq vulnerabilities - https://ubuntu.com/security/CVE-2020-25686 + - https://ubuntu.com/security/CVE-2020-25686 1 affected package is installed: dnsmasq (1/1) dnsmasq: diff --git a/docs/references/api.rst b/docs/references/api.rst index 60fe3dce27..5bfe236f75 100644 --- a/docs/references/api.rst +++ b/docs/references/api.rst @@ -147,22 +147,27 @@ 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.magic.initiate.v1`_ -- `u.pro.attach.magic.wait.v1`_ - `u.pro.attach.magic.revoke.v1`_ -- `u.pro.attach.auto.should_auto_attach.v1`_ -- `u.pro.attach.auto.full_auto_attach.v1`_ -- `u.pro.attach.auto.configure_retry_service.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.fix.cve.execute.v1`_ -- `u.pro.security.fix.usn.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.packages.summary.v1`_ -- `u.pro.packages.updates.v1`_ -- `u.pro.status.is_attached.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`_ @@ -201,7 +206,7 @@ This endpoint shows the installed Pro Client version. - Type - Description * - ``installed_version`` - - *str* + - ``str`` - The current installed version - Raised exceptions: @@ -225,11 +230,137 @@ This endpoint shows the installed Pro Client version. "installed_version":"" } -u.pro.attach.magic.initiate.v1 -============================== +u.pro.attach.auto.configure_retry_service.v1 +============================================ -This endpoint initiates the Magic Attach flow, retrieving the User Code to -confirm the operation and the Token used to proceed. +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~`` +- Args: + + - ``enable``: Optional list of services to enable after auto-attaching. + - ``enable_beta``: Optional list of beta services to enable after + auto-attaching. + +.. note:: + + If none of the lists are set, the services will be enabled based on the + contract definitions. + +.. tab-set:: + + .. tab-item:: Python API interaction + :sync: python + + - Calling from Python code: + + .. code-block:: 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`` + + No data present in the result. + + - Raised exceptions: + + - No exceptions raised by this endpoint. + + .. tab-item:: CLI interaction + :sync: CLI + + - Calling from the CLI: + + - This endpoint currently has no CLI support. Only the Python-based + version is available. + +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~`` +- Args: + + - ``enable``: Optional list of services to enable after auto-attaching. + - ``enable_beta``: Optional list of beta services to enable after auto-attaching. + +.. note:: + + If none of the lists are set, the services will be enabled based on the + contract definitions. + +.. tab-set:: + + .. tab-item:: Python API interaction + :sync: python + + - Calling from Python code: + + .. code-block:: 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`` + + No data present in the result. + + - Raised exceptions + + - ``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. + - ``UserFacingError``: Raised if: + + - The Client is unable to determine which cloud the system is running + on. + - The image where the Client is running does not support auto-attach. + + .. tab-item:: CLI interaction + :sync: CLI + + - Calling from the CLI: + + This endpoint currently has no CLI support. Only the Python-based + version is available. + +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~`` - Args: @@ -245,13 +376,13 @@ confirm the operation and the Token used to proceed. .. code-block:: python - from uaclient.api.u.pro.attach.magic.initiate.v1 import initiate + from uaclient.api.u.pro.attach.auto.should_auto_attach.v1 import should_auto_attach - result = initiate() + result = should_auto_attach() - Expected return object: - - ``uaclient.api.u.pro.attach.magic.initiate.v1.MagicAttachInitiateResult`` + - ``uaclient.api.u.pro.attach.auto.should_auto_attach.v1.ShouldAutoAttachResult`` .. list-table:: :header-rows: 1 @@ -259,27 +390,13 @@ confirm the operation and the Token used to proceed. * - Field Name - Type - Description - * - ``user_code`` - - *str* - - Code the user will see in the UI when confirming the Magic Attach - * - ``token`` - - *str* - - Magic Token used by the tooling to continue the operation - * - ``expires`` - - *str* - - Timestamp of the Magic Attach process expiration - * - ``expires_in`` - - *int* - - Seconds before the Magic Attach process expires + * - ``should_auto_attach`` + - ``bool`` + - True if the system should run auto-attach on boot - Raised exceptions: - - ``ConnectivityError``: Raised if it is not possible to connect to the - Contracts Server. - - ``ContractAPIError``: Raised if there is an unexpected error in the - Contracts Server interaction. - - ``MagicAttachUnavailable``: Raised if the Magic Attach service is - busy or unavailable at the moment. + - No exceptions raised by this endpoint. .. tab-item:: CLI interaction :sync: CLI @@ -288,29 +405,26 @@ confirm the operation and the Token used to proceed. .. code-block:: bash - pro api u.pro.attach.magic.initiate.v1 + pro api u.pro.attach.auto.should_auto_attach.v1 - Expected attributes in JSON structure: .. code-block:: json { - "user_code":"", - "token":"", - "expires": "T.", - "expires_in": 600 + "should_auto_attach": false } -u.pro.attach.magic.wait.v1 -========================== +u.pro.attach.magic.initiate.v1 +============================== -This endpoint polls the Contract Server waiting for the user to confirm the -Magic Attach. +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~`` - Args: - - ``magic_token``: The Token provided by the initiate endpoint. + - This endpoint takes no arguments. .. tab-set:: @@ -321,14 +435,13 @@ Magic Attach. .. code-block:: python - from uaclient.api.u.pro.attach.magic.wait.v1 import MagicAttachWaitOptions, wait + from uaclient.api.u.pro.attach.magic.initiate.v1 import initiate - options = MagicAttachWaitOptions(magic_token="") - result = wait(options) + result = initiate() - Expected return object: - - ``uaclient.api.u.pro.attach.magic.wait.v1.MagicAttachWaitResult`` + - ``uaclient.api.u.pro.attach.magic.initiate.v1.MagicAttachInitiateResult`` .. list-table:: :header-rows: 1 @@ -337,32 +450,24 @@ Magic Attach. - Type - Description * - ``user_code`` - - *str* + - ``str`` - Code the user will see in the UI when confirming the Magic Attach * - ``token`` - - *str* - - Magic Token used by the tooling to continue the operation + - ``str`` + - Magic Token that can be used in either `u.pro.attach.magic.revoke.v1`_ or `u.pro.attach.magic.wait.v1`_ * - ``expires`` - - *str* + - ``str`` - Timestamp of the Magic Attach process expiration * - ``expires_in`` - - *int* + - ``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: - ``ConnectivityError``: Raised if it is not possible to connect to the - Contracts Server. + contracts service. - ``ContractAPIError``: Raised if there is an unexpected error in the - Contracts Server interaction. - - ``MagicAttachTokenError``: Raised when an invalid/expired Token is - sent. + contracts service interaction. - ``MagicAttachUnavailable``: Raised if the Magic Attach service is busy or unavailable at the moment. @@ -373,21 +478,20 @@ Magic Attach. .. code-block:: bash - pro api u.pro.attach.magic.wait.v1 --args magic_token= + pro api u.pro.attach.magic.initiate.v1 - Expected attributes in JSON structure: .. code-block:: json { - "user_code":"", - "token":"", - "expires": "T.", - "expires_in": 500, - "contract_id": "", - "contract_token": "", + "user_code":"", + "token":"", + "expires": "T.", + "expires_in": 600 } + u.pro.attach.magic.revoke.v1 ============================ @@ -421,9 +525,9 @@ This endpoint revokes a Magic Attach Token. - Raised exceptions: - ``ConnectivityError``: Raised if it is not possible to connect to the - Contracts Server. + contracts service. - ``ContractAPIError``: Raised if there is an unexpected error in the - Contracts Server interaction. + 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 @@ -446,15 +550,16 @@ This endpoint revokes a Magic Attach Token. {} -u.pro.attach.auto.should_auto_attach.v1 -======================================= +u.pro.attach.magic.wait.v1 +========================== -This endpoint checks if a given system should run auto-attach on boot. +This endpoint polls the contracts service waiting for the user to confirm the +Magic Attach. - Introduced in Ubuntu Pro Client Version: ``27.11~`` - Args: - - This endpoint takes no arguments. + - ``magic_token``: The Token provided by the initiate endpoint. .. tab-set:: @@ -465,13 +570,14 @@ This endpoint checks if a given system should run auto-attach on boot. .. code-block:: python - from uaclient.api.u.pro.attach.auto.should_auto_attach.v1 import should_auto_attach + from uaclient.api.u.pro.attach.magic.wait.v1 import MagicAttachWaitOptions, wait - result = should_auto_attach() + options = MagicAttachWaitOptions(magic_token="") + result = wait(options) - Expected return object: - - ``uaclient.api.u.pro.attach.auto.should_auto_attach.v1.ShouldAutoAttachResult`` + - ``uaclient.api.u.pro.attach.magic.wait.v1.MagicAttachWaitResult`` .. list-table:: :header-rows: 1 @@ -479,13 +585,35 @@ This endpoint checks if a given system should run auto-attach on boot. * - Field Name - Type - Description - * - ``should_auto_attach`` - - *bool* - - True if the system should run auto-attach on boot + * - ``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: - - No exceptions raised by this endpoint. + - ``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. .. tab-item:: CLI interaction :sync: CLI @@ -494,31 +622,33 @@ This endpoint checks if a given system should run auto-attach on boot. .. code-block:: bash - pro api u.pro.attach.auto.should_auto_attach.v1 + pro api u.pro.attach.magic.wait.v1 --args magic_token= - Expected attributes in JSON structure: .. code-block:: json { - "should_auto_attach": false + "user_code":"", + "token":"", + "expires": "T.", + "expires_in": 500, + "contract_id": "", + "contract_token": "", } -u.pro.attach.auto.full_auto_attach.v1 -===================================== +u.pro.attach.token.full_token_attach.v1 +============================================ -This endpoint runs the whole auto-attach process on the system. +This endpoint allow the user to attach to a Pro subscription using +a token. -- Introduced in Ubuntu Pro Client Version: ``27.11~`` +- Introduced in Ubuntu Pro Client Version: ``32~`` - Args: - - ``enable``: Optional list of services to enable after auto-attaching. - - ``enable_beta``: Optional list of beta services to enable after auto-attaching. - -.. note:: - - If none of the lists are set, the services will be enabled based on the - contract definitions. + - ``token``: The token associated with a Pro subscription + - ``auto_enable_services``: If false, the attach operation will not enable any service during the + operation .. tab-set:: @@ -529,75 +659,72 @@ This endpoint runs the whole auto-attach process on the system. .. code-block:: python - from uaclient.api.u.pro.attach.auto.full_auto_attach.v1 import full_auto_attach, FullAutoAttachOptions + from uaclient.api.u.pro.attach.token.full_token_attach.v1 import full_token_attach, FullTokenAttachOptions - options = FullAutoAttachOptions(enable=["", ""], enable_beta=[""]) - result = full_auto_attach(options) + options = FullTokenAttachOptions(token="TOKEN") + result = full_token_attach(options) - Expected return object: - - ``uaclient.api.u.pro.attach.auto.full_auto_attach.v1.FullAutoAttachResult`` + - ``uaclient.api.u.pro.attach.token.full_token_attach.v1.FullTokenAttachResult`` - No data present in the result. + .. list-table:: + :header-rows: 1 - - Raised exceptions + * - 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 - - ``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 Server. - - ``ContractAPIError``: Raised if there is an unexpected error in the - Contracts Server 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. - - ``UserFacingError``: Raised if: + - Raised exceptions: - - The Client is unable to determine which cloud the system is running - on. - - The image where the Client is running does not support auto-attach. + - ``NonRootUserError``: Raised if a non-root user executes this endpoint .. tab-item:: CLI interaction :sync: CLI - Calling from the CLI: - This endpoint currently has no CLI support. Only the Python-based - version is available. + .. code-block:: bash -u.pro.attach.auto.configure_retry_service.v1 -============================================ + pro api u.pro.attach.token.full_token_attach.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 we don't need to explicitly pass the token when calling the CLI command. + If we define a JSON file (i.e. ``file.json``) with the same attributes as the options for this endpoint: -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. + .. code-block:: json -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``. + { + "token": "TOKEN", + "auto_enable_services": false + } -- Introduced in Ubuntu Pro Client Version: ``27.12~`` -- Args: + Then we can call the API like this: - - ``enable``: Optional list of services to enable after auto-attaching. - - ``enable_beta``: Optional list of beta services to enable after - auto-attaching. + .. code-block:: bash -.. note:: + cat file.json | pro api u.pro.attach.token.full_token_attach.v1 --data - - If none of the lists are set, the services will be enabled based on the - contract definitions. + - Expected attributes in JSON structure: + + .. code-block:: json + + { + "enabled": ["service1", "service2"], + "reboot_required": false + } + +u.pro.detach.v1 +============================================ + +This endpoint allow the user to detach the machine from a Pro subscription. + +- Introduced in Ubuntu Pro Client Version: ``32~`` .. tab-set:: @@ -608,40 +735,59 @@ like ``systemctl start ubuntu-advantage.service``. .. code-block:: python - from uaclient.api.u.pro.attach.auto.configure_retry_service.v1 import configure_retry_service, ConfigureRetryServiceOptions + from uaclient.api.u.pro.detach.v1 import detach - options = ConfigureRetryServiceOptions(enable=["", ""], enable_beta=[""]) - result = configure_retry_service(options) + result = detach() - Expected return object: - - ``uaclient.api.u.pro.attach.auto.configure_retry_service.v1.ConfigureRetryServiceResult`` + - ``uaclient.api.u.pro.detach.v1.DetachResult`` - No data present in the result. + .. list-table:: + :header-rows: 1 + + * - 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: - - No exceptions raised by this endpoint. + - ``NonRootUserError``: Raised if a non-root user executes this endpoint .. tab-item:: CLI interaction :sync: CLI - Calling from the CLI: - - This endpoint currently has no CLI support. Only the Python-based - version is available. + .. code-block:: bash -.. _cve-execute-api-v1: + pro api u.pro.detach.v1 -u.pro.security.fix.cve.execute.v1 -=================================== + - Expected attributes in JSON structure: -This endpoint fixes the specified CVEs on the machine. + .. code-block:: json -- Introduced in Ubuntu Pro Client Version: ``30~`` + { + "disabled": ["service1", "service2"], + "reboot_required": false + } + +u.pro.packages.summary.v1 +========================= + +This endpoint shows a summary of installed packages in the system, categorised +by origin. + +- Introduced in Ubuntu Pro Client Version: ``27.12~`` - Args: - - ``cves``: A list of CVE (i.e. CVE-2023-2650) titles + - This endpoint takes no arguments. .. tab-set:: @@ -652,14 +798,13 @@ This endpoint fixes the specified CVEs on the machine. .. code-block:: python - from uaclient.api.u.pro.security.fix.cve.execute.v1 import execute, CVEFixExecuteOptions + from uaclient.api.u.pro.packages.summary.v1 import summary - options = CVEFixExecuteOptions(cves=["CVE-1234-1234", "CVE-1234-1235"]) - result = execute(options) + result = summary() - Expected return object: - - ``uaclient.api.u.pro.security.fix.cve.execute.v1.CVESAPIFixExecuteResult`` + - ``uaclient.api.u.pro.packages.summary.v1.PackageSummaryResult`` .. list-table:: :header-rows: 1 @@ -667,11 +812,11 @@ This endpoint fixes the specified CVEs on the machine. * - Field Name - Type - Description - * - ``cves_data`` - - *List[CVEAPIFixExecuteResult]* - - A list of CVEAPIFixExecuteResult objects + * - ``summary`` + - ``PackageSummary`` + - Summary of all installed packages - - ``uaclient.api.u.pro.security.fix.cve.execute.v1.CVEAPIFixExecuteResult`` + - ``uaclient.api.u.pro.packages.summary.v1.PackageSummary`` .. list-table:: :header-rows: 1 @@ -679,35 +824,92 @@ This endpoint fixes the specified CVEs on the machine. * - Field Name - Type - Description - * - ``status`` - - *str* - - The status of fixing the CVEs - * - ``cves`` - - *List[FixExecuteResult]* - - A list of FixExecuteResult objects + * - ``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 - - ``uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteResult`` + - Raised exceptions: - .. list-table:: - :header-rows: 1 + - No exceptions raised by this endpoint. - * - Field Name - - Type - - Description - * - ``title`` - - *str* - - The title of the CVE - * - ``expected_status`` - - *str* - - The status of fixing the CVE - * - ``upgraded_packages`` - - *List[UpgradedPackage]* - - A list of UpgradedPackage objects - * - ``error`` - - *Optional[FixExecuteError]* - - A FixExecuteError object + .. tab-item:: CLI interaction + :sync: CLI - - ``uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage`` + - Calling from the CLI: + + .. code-block:: bash + + pro api u.pro.packages.summary.v1 + + - Expected attributes in JSON structure: + + .. code-block:: json + + { + "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, categorised by +where they can be obtained. + +- Introduced in Ubuntu Pro Client Version: ``27.12~`` +- Args: + + - This endpoint takes no arguments. + +.. tab-set:: + + .. tab-item:: Python API interaction + :sync: python + + - Calling from Python code: + + .. code-block:: python + + from uaclient.api.u.pro.packages.updates.v1 import updates + + result = updates() + + - Expected return object: + + - ``uaclient.api.u.pro.packages.updates.v1.PackageUpdatesResult`` .. list-table:: :header-rows: 1 @@ -715,17 +917,14 @@ This endpoint fixes the specified CVEs on the machine. * - 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 + * - ``summary`` + - ``UpdateSummary`` + - Summary of all available updates + * - ``updates`` + - ``List[UpdateInfo]`` + - Detailed list of all available updates - - ``uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteError`` + - ``uaclient.api.u.pro.packages.updates.v1.UpdateSummary`` .. list-table:: :header-rows: 1 @@ -733,17 +932,23 @@ This endpoint fixes the specified CVEs on the machine. * - 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 + * - ``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.security.fix._common.execute.v1.FailedUpgrade`` + - ``uaclient.api.u.pro.packages.updates.v1.UpdateInfo`` .. list-table:: :header-rows: 1 @@ -751,17 +956,193 @@ This endpoint fixes the specified CVEs on the machine. * - Field Name - Type - Description - * - ``name`` - - *str* - - The name of the package - * - ``pocket`` - - *str* - - The pocket which contained the package upgrade - - - Raised exceptions: - - - No exceptions raised by this endpoint. - + * - ``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: + + - No exceptions raised by this endpoint. + + .. tab-item:: CLI interaction + :sync: CLI + + - Calling from the CLI: + + .. code-block:: bash + + pro api u.pro.packages.updates.v1 + + - Expected attributes in JSON structure: + + .. code-block:: json + + { + "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": "", + }, + ] + } + +.. _cve-execute-api-v1: + +u.pro.security.fix.cve.execute.v1 +=================================== + +This endpoint fixes the specified CVEs on the machine. + +- Introduced in Ubuntu Pro Client Version: ``30~`` +- Args: + + - ``cves``: A list of CVE (i.e. CVE-2023-2650) titles + +.. tab-set:: + + .. tab-item:: Python API interaction + :sync: python + + - Calling from Python code: + + .. code-block:: 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`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``cves_data`` + - ``List[CVEAPIFixExecuteResult]`` + - A list of CVEAPIFixExecuteResult objects + + - ``uaclient.api.u.pro.security.fix.cve.execute.v1.CVEAPIFixExecuteResult`` + + .. list-table:: + :header-rows: 1 + + * - 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`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``title`` + - ``str`` + - The title of the CVE + * - ``expected_status`` + - ``str`` + - The status of fixing the CVE + * - ``upgraded_packages`` + - ``List[UpgradedPackage]`` + - A list of UpgradedPackage objects + * - ``error`` + - ``Optional[FixExecuteError]`` + - A FixExecuteError object + + - ``uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage`` + + .. list-table:: + :header-rows: 1 + + * - 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`` + + .. list-table:: + :header-rows: 1 + + * - 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`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``name`` + - ``str`` + - The name of the package + * - ``pocket`` + - ``str`` + - The pocket which contained the package upgrade + + - Raised exceptions: + + - No exceptions raised by this endpoint. + .. tab-item:: CLI interaction :sync: CLI @@ -884,6 +1265,320 @@ This endpoint fixes the specified CVEs on the machine. * **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~`` +- Args: + + - ``cves``: A list of CVE (i.e. CVE-2023-2650) titles + +.. tab-set:: + + .. tab-item:: Python API interaction + :sync: python + + - Calling from Python code: + + .. code-block:: 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`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``cves_data`` + - ``List[CVEFixPlanResult]`` + - A list of ``CVEFixPlanResult`` objects + + - ``uaclient.api.u.pro.security.fix.cve.plan.v1.CVEFixPlanResult`` + + .. list-table:: + :header-rows: 1 + + * - 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.FixPlanResult`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``title`` + - ``str`` + - The title of the CVE + * - ``expected_status`` + - ``str`` + - The expected status of fixing the CVE + * - ``plan`` + - ``List[FixPlanStep]`` + - A list of FixPlanStep objects + * - ``warnings`` + - ``List[FixPlanWarning]`` + - A list of FixPlanWarning objects + * - ``error`` + - ``Optional[FixPlanError]`` + - A list of FixPlanError objects + * - ``additional_data`` + - ``AdditionalData`` + - Additional data for the CVE + + - ``uaclient.api.u.pro.security.fix.FixPlanStep`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``operation`` + - ``str`` + - The operation that would be performed to fix the CVE. This can be either an attach, enable, apt-upgrade or a no-op type + * - ``order`` + - ``int`` + - The execution order of the operation + * - ``data`` + - ``object`` + - A data object that can be either an ``AptUpgradeData``, ``AttachData``, ``EnableData``, ``NoOpData`` + + - ``uaclient.api.u.pro.security.fix.FixPlanWarning`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``warning_type`` + - ``str`` + - The type of warning + * - ``order`` + - ``int`` + - The execution order of the operation + * - ``data`` + - ``object`` + - A data object that represents either an PackageCannotBeInstalledData or a SecurityIssueNotFixedData + + - ``uaclient.api.u.pro.security.fix.FixPlanError`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``msg`` + - ``str`` + - The error message + * - ``code`` + - ``str`` + - The message code + + - ``uaclient.api.u.pro.security.fix.AdditionalData`` + + For a CVE, we don't expect any additional data at the moment + + - ``uaclient.api.u.pro.security.fix.AptUpgradeData`` + + .. list-table:: + :header-rows: 1 + + * - 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.AttachData`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``reason`` + - ``str`` + - The reason why an attach operation is needed + * - ``source_packages`` + - ``List[str]`` + - The source packages that require the attach operation + * - ``required_service`` + - ``str`` + - The required service that requires the attach operation + + - ``uaclient.api.u.pro.security.fix.EnableData`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``service`` + - ``str`` + - The Pro client service that needs to be enabled + * - ``source_packages`` + - ``str`` + - The source packages that require the service to be enabled + + - ``uaclient.api.u.pro.security.fix.NoOpData`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``status`` + - ``str`` + - The status of the CVE when no operation can be performed + + - ``uaclient.api.u.pro.security.fix.NoOpAlreadyFixedData`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``status`` + - ``str`` + - The status of the CVE when no operation can be performed + * - ``source_packages`` + - ``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.NoOpLivepatchFixData`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``status`` + - ``str`` + - The status of the CVE when no operation can be performed + * - ``patch_version`` + - ``str`` + - Version of the path from Livepatch that fixed the CVE + + - ``uaclient.api.u.pro.security.fix.PackageCannotBeInstalledData`` + + .. list-table:: + :header-rows: 1 + + * - 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 comes 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.SecurityIssueNotFixedData`` + + .. list-table:: + :header-rows: 1 + + * - 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: + + - No exceptions raised by this endpoint. + + .. tab-item:: CLI interaction + :sync: CLI + + - Calling from the CLI: + + .. code-block:: bash + + pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-56789", "CVE-1234-1235"]}' + + - Expected attributes in JSON structure: + + .. code-block:: json + + { + "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 =================================== @@ -919,7 +1614,7 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``usns_data`` - - *List[USNAPIFixExecuteResult]* + - ``List[USNAPIFixExecuteResult]`` - A list of USNAPIFixExecuteResult objects - ``uaclient.api.u.pro.security.fix.usn.execute.v1.USNAPIFixExecuteResult`` @@ -931,10 +1626,10 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``status`` - - *str* + - ``str`` - The status of fixing the USNs * - ``cves`` - - *List[FixExecuteUSNResult]* + - ``List[FixExecuteUSNResult]`` - A list of FixExecuteResult objects - ``uaclient.api.u.pro.security.fix.usn.execute.v1.FixExecuteUSNResult`` @@ -946,10 +1641,10 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``target_usn`` - - *str* + - ``str`` - The FixExecuteResult for the target USN * - ``related_usns`` - - *List[FixExecuteResult]* + - ``List[FixExecuteResult]`` - A list of FixExecuteResult objects for the related USNs - ``uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteResult`` @@ -961,16 +1656,16 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``title`` - - *str* + - ``str`` - The title of the USN * - ``expected_status`` - - *str* + - ``str`` - The status of fixing the USN * - ``upgraded_packages`` - - *List[UpgradedPackage]* + - ``List[UpgradedPackage]`` - A list of UpgradedPackage objects * - ``error`` - - *Optional[FixExecuteError]* + - ``Optional[FixExecuteError]`` - A FixExecuteError object - ``uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage`` @@ -982,13 +1677,13 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``name`` - - *str* + - ``str`` - The name of the package * - ``version`` - - *str* + - ``str`` - The version that the package was upgraded to * - ``pocket`` - - *str* + - ``str`` - The pocket which contained the package upgrade - ``uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteError`` @@ -1000,13 +1695,13 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``error_type`` - - *str* + - ``str`` - The type of the error * - ``reason`` - - *str* + - ``str`` - The reason why the error occurred * - ``failed_upgrades`` - - *Optional[List[FailedUpgrade]]* + - ``Optional[List[FailedUpgrade]]`` - A list of FailedUpgrade objects - ``uaclient.api.u.pro.security.fix._common.execute.v1.FailedUpgrade`` @@ -1018,10 +1713,10 @@ This endpoint fixes the specified USNs on the machine. - Type - Description * - ``name`` - - *str* + - ``str`` - The name of the package * - ``pocket`` - - *str* + - ``str`` - The pocket which contained the package upgrade - Raised exceptions: @@ -1143,327 +1838,12 @@ This endpoint fixes the specified USNs on the machine. ] } - 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~`` -- Args: - - - ``cves``: A list of CVE (i.e. CVE-2023-2650) titles - -.. tab-set:: - - .. tab-item:: Python API interaction - :sync: python - - - Calling from Python code: - - .. code-block:: 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`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``cves_data`` - - *List[CVEFixPlanResult]* - - A list of CVEFixPlanResult objects - - - ``uaclient.api.u.pro.security.fix.cve.plan.v1.CVEFixPlanResult`` - - .. list-table:: - :header-rows: 1 - - * - 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.FixPlanResult`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``title`` - - *str* - - The title of the CVE - * - ``expected_status`` - - *str* - - The expected status of fixing the CVE - * - ``plan`` - - *List[FixPlanStep]* - - A list of FixPlanStep objects - * - ``warnings`` - - *List[FixPlanWarning]* - - A list of FixPlanWarning objects - * - ``error`` - - *Optional[FixPlanError]* - - A list of FixPlanError objects - * - ``additional_data`` - - *AdditionalData* - - Additional data for the CVE - - - ``uaclient.api.u.pro.security.fix.FixPlanStep`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``operation`` - - *str* - - The operation that would be performed to fix the CVE. This can be either an attach, enable, apt-upgrade or a no-op type - * - ``order`` - - *int* - - The execution order of the operation - * - ``data`` - - *object* - - A data object that can be either an AptUpgradeData, AttachData, EnableData, NoOpData - - - ``uaclient.api.u.pro.security.fix.FixPlanWarning`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``warning_type`` - - *str* - - The type of warning - * - ``order`` - - *int* - - The execution order of the operation - * - ``data`` - - *object* - - A data object that represents either an PackageCannotBeInstalledData or a SecurityIssueNotFixedData - - - ``uaclient.api.u.pro.security.fix.FixPlanError`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``msg`` - - *str* - - The error message - * - ``code`` - - *str* - - The message code - - - ``uaclient.api.u.pro.security.fix.AdditionalData`` - - For a CVE, we don't expect any additional data at the moment - - - ``uaclient.api.u.pro.security.fix.AptUpgradeData`` - - .. list-table:: - :header-rows: 1 - - * - 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.AttachData`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``reason`` - - *str* - - The reason why an attach operation is needed - * - ``source_packages`` - - *List[str]* - - The source packages that require the attach operation - * - ``required_service`` - - *str* - - The required service that requires the attach operation - - - ``uaclient.api.u.pro.security.fix.EnableData`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``service`` - - *str* - - The Pro client service that needs to be enabled - * - ``source_packages`` - - *str* - - The source packages that require the service to be enabled - - - ``uaclient.api.u.pro.security.fix.NoOpData`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``status`` - - *str* - - The status of the CVE when no operation can be performed - - - ``uaclient.api.u.pro.security.fix.NoOpAlreadyFixedData`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``status`` - - *str* - - The status of the CVE when no operation can be performed - * - ``source_packages`` - - *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.NoOpLivepatchFixData`` - - .. list-table:: - :header-rows: 1 - - * - Field Name - - Type - - Description - * - ``status`` - - *str* - - The status of the CVE when no operation can be performed - * - ``patch_version`` - - *str* - - Version of the path from Livepatch that fixed the CVE - - - ``uaclient.api.u.pro.security.fix.PackageCannotBeInstalledData`` - - .. list-table:: - :header-rows: 1 - - * - 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 comes 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.SecurityIssueNotFixedData`` - - .. list-table:: - :header-rows: 1 - - * - 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: - - - No exceptions raised by this endpoint. - - .. tab-item:: CLI interaction - :sync: CLI - - - Calling from the CLI: - - .. code-block:: bash - - pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-56789", "CVE-1234-1235"]}' - - - Expected attributes in JSON structure: - - .. code-block:: json + We can see that the representation has the following fields: - { - "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": {} - } - ] - } - } + * **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 =============================== @@ -1501,8 +1881,8 @@ executing any of those steps. - Type - Description * - ``usns_data`` - - *List[USNFixPlanResult]* - - A list of USNFixPlanResult objects + - ``List[USNFixPlanResult]`` + - A list of ``USNFixPlanResult`` objects - ``uaclient.api.u.pro.security.fix.cve.plan.v1.USNFixPlanResult`` @@ -1513,10 +1893,10 @@ executing any of those steps. - Type - Description * - ``expected_status`` - - *str* + - ``str`` - The expected status of fixing the USNs * - ``cves`` - - *List[FixPlanUSNResult]* + - ``List[FixPlanUSNResult]`` - A list of FixPlanUSNResult objects - ``uaclient.api.u.pro.security.fix.FixPlanUSNResult`` @@ -1528,11 +1908,11 @@ executing any of those steps. - Type - Description * - ``target_usn_plan`` - - *FixPlanResult* - - A FixPlanResult object for the target USN + - ``FixPlanResult`` + - A ``FixPlanResult`` object for the target USN * - ``related_usns_plan`` - - *List[FixPlanResult]* - - A list of FixPlanResult objects for the related USNs + - ``List[FixPlanResult]`` + - A list of ``FixPlanResult`` objects for the related USNs - ``uaclient.api.u.pro.security.fix.FixPlanResult`` @@ -1543,22 +1923,22 @@ executing any of those steps. - Type - Description * - ``title`` - - *str* + - ``str`` - The title of the USN * - ``expected_status`` - - *str* + - ``str`` - The expected status of fixing the USN * - ``plan`` - - *List[FixPlanStep]* + - ``List[FixPlanStep]`` - A list of FixPlanStep objects * - ``warnings`` - - *List[FixPlanWarning]* + - ``List[FixPlanWarning]`` - A list of FixPlanWarning objects * - ``error`` - - *Optional[FixPlanError]* + - ``Optional[FixPlanError]`` - A list of FixPlanError objects * - ``additional_data`` - - *AdditionalData* + - ``AdditionalData`` - Additional data for the USN - ``uaclient.api.u.pro.security.fix import FixPlanStep`` @@ -1570,14 +1950,14 @@ executing any of those steps. - Type - Description * - ``operation`` - - *str* + - ``str`` - The operation that would be performed to fix the USN * - ``order`` - - *int* + - ``int`` - The execution order of the operation * - ``data`` - - *object* - - A data object that can be either an AptUpgradeData, AttachData, EnableData, NoOpData + - ``object`` + - A data object that can be either an ``AptUpgradeData``, ``AttachData``, ``EnableData``, ``NoOpData`` - ``uaclient.api.u.pro.security.fix import FixPlanWarning`` @@ -1588,13 +1968,13 @@ executing any of those steps. - Type - Description * - ``warning_type`` - - *str* + - ``str`` - The type of warning * - ``order`` - - *int* + - ``int`` - The execution order of the operation * - ``data`` - - *object* + - ``object`` - A data object that represents either an PackageCannotBeInstalledData or a SecurityIssueNotFixedData - ``uaclient.api.u.pro.security.fix import FixPlanError`` @@ -1606,10 +1986,10 @@ executing any of those steps. - Type - Description * - ``msg`` - - *str* + - ``str`` - The error message * - ``code`` - - *str* + - ``str`` - The message code - ``uaclient.api.u.pro.security.fix.AdditionalData`` @@ -1621,10 +2001,10 @@ executing any of those steps. - Type - Description * - ``associated_cves`` - - *List[str]* + - ``List[str]`` - The associated CVEs for the USN * - ``associated_launchpad_bugs`` - - *List[str]* + - ``List[str]`` - The associated Launchpad bugs for the USN @@ -1637,13 +2017,13 @@ executing any of those steps. - Type - Description * - ``binary_packages`` - - *List[str]* + - ``List[str]`` - A list of binary packages that need to be upgraded * - ``source_packages`` - - *List[str]* + - ``List[str]`` - A list of source packages that need to be upgraded * - ``pocket`` - - *str* + - ``str`` - The pocket where the packages will be installed from - ``uaclient.api.u.pro.security.fix import AttachData`` @@ -1655,13 +2035,13 @@ executing any of those steps. - Type - Description * - ``reason`` - - *str* + - ``str`` - The reason why an attach operation is needed * - ``source_packages`` - - *List[str]* + - ``List[str]`` - The source packages that require the attach operation * - ``required_service`` - - *str* + - ``str`` - The required service that requires the attach operation - ``uaclient.api.u.pro.security.fix import EnableData`` @@ -1673,10 +2053,10 @@ executing any of those steps. - Type - Description * - ``service`` - - *str* + - ``str`` - The Pro client service that needs to be enabled * - ``source_packages`` - - *str* + - ``str`` - The source packages that require the service to be enabled - ``uaclient.api.u.pro.security.fix import NoOpData`` @@ -1688,7 +2068,7 @@ executing any of those steps. - Type - Description * - ``status`` - - *str* + - ``str`` - The status of the USN when no operation can be performed - ``uaclient.api.u.pro.security.fix.NoOpAlreadyFixedData`` @@ -1700,13 +2080,13 @@ executing any of those steps. - Type - Description * - ``status`` - - *str* + - ``str`` - The status of the CVE when no operation can be performed * - ``source_packages`` - - *str* + - ``str`` - The source packages that are already fixed * - ``pocket`` - - *str* + - ``str`` - The pocket where the packages would have been installed from - ``uaclient.api.u.pro.security.fix import PackageCannotBeInstalledData`` @@ -1718,19 +2098,19 @@ executing any of those steps. - Type - Description * - ``binary_package`` - - *str* + - ``str`` - The binary package that cannot be installed * - ``binary_package_version`` - - *str* + - ``str`` - The version of the binary package that cannot be installed * - ``source_package`` - - *str* + - ``str`` - The source package associated with the binary package * - ``related_source_packages`` - - *List[str]* + - ``List[str]`` - A list of source packages that comes from the same pocket as the affected package * - ``pocket`` - - *str* + - ``str`` - The pocket where the affected package should be installed from - ``uaclient.api.u.pro.security.fix import SecurityIssueNotFixedData`` @@ -1742,10 +2122,10 @@ executing any of those steps. - Type - Description * - ``source_packages`` - - *List[str]* + - ``List[str]`` - A list of source packages that cannot be fixed at the moment * - ``status`` - - *str* + - ``str`` - The status of the USN regarding those packages - Raised exceptions: @@ -1835,7 +2215,7 @@ This endpoint lists Livepatch patches for the currently-running kernel. - Type - Description * - ``fixed_cves`` - - *list(LivepatchCVEObject)* + - ``list(LivepatchCVEObject)`` - List of Livepatch patches for the given system - ``uaclient.api.u.pro.security.status.livepatch_cves.v1.LivepatchCVEObject`` @@ -1847,10 +2227,10 @@ This endpoint lists Livepatch patches for the currently-running kernel. - Type - Description * - ``name`` - - *str* + - ``str`` - Name (ID) of the CVE * - ``patched`` - - *bool* + - ``bool`` - Livepatch has patched the CVE - Raised exceptions: @@ -1924,7 +2304,7 @@ are: - Type - Description * - ``reboot_required`` - - *str* + - ``str`` - One of the descriptive strings indicating if the system should be rebooted @@ -1949,13 +2329,15 @@ are: "reboot_required": "yes|no|yes-kernel-livepatches-applied" } -u.pro.packages.summary.v1 -========================= +u.pro.services.dependencies.v1 +======================================== -This endpoint shows a summary of installed packages in the system, categorised -by origin. +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: ``27.12~`` +- Introduced in Ubuntu Pro Client Version: ``32~`` - Args: - This endpoint takes no arguments. @@ -1969,13 +2351,12 @@ by origin. .. code-block:: python - from uaclient.api.u.pro.packages.summary.v1 import summary - - result = summary() + from uaclient.api.u.pro.services.dependencies.v1 import dependencies + result = dependencies() - Expected return object: - - ``uaclient.api.u.pro.packages.summary.v1.PackageSummaryResult`` + - ``uaclient.api.u.pro.services.dependencies.v1.DependenciesResult`` .. list-table:: :header-rows: 1 @@ -1983,11 +2364,11 @@ by origin. * - Field Name - Type - Description - * - ``summary`` - - *PackageSummary* - - Summary of all installed packages + * - ``services`` + - ``List[ServiceWithDependencies]`` + - Each Pro service gets an item in this list - - ``uaclient.api.u.pro.packages.summary.v1.PackageSummary`` + - ``uaclient.api.u.pro.services.dependencies.v1.ServiceWithDependencies`` .. list-table:: :header-rows: 1 @@ -1995,33 +2376,45 @@ by origin. * - 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 + * - ``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`` + + .. list-table:: + :header-rows: 1 + + * - 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`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``code`` + - ``str`` + - Short string that represents the reason. + * - ``title`` + - ``str`` + - Longer string describing the reason - possibly translated. - Raised exceptions: @@ -2034,36 +2427,62 @@ by origin. .. code-block:: bash - pro api u.pro.packages.summary.v1 + pro api u.pro.services.dependencies.v1 - Expected attributes in JSON structure: - .. code-block:: json + .. code-block:: 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, - }, - } + { + "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.packages.updates.v1 +u.pro.services.disable.v1 ========================= -This endpoint shows available updates for packages in a system, categorised by -where they can be obtained. +Disable a Pro service. This will automatically disable any services that +depend on the target service. -- Introduced in Ubuntu Pro Client Version: ``27.12~`` +- Introduced in Ubuntu Pro Client Version: ``32~`` - Args: - - This endpoint takes no arguments. + .. list-table:: + :header-rows: 1 + + * - 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) .. tab-set:: @@ -2074,81 +2493,30 @@ where they can be obtained. .. code-block:: python - from uaclient.api.u.pro.packages.updates.v1 import updates - - result = updates() + from uaclient.api.u.pro.services.disable.v1 import disable, DisableOptions + result = disable(DisableOptions(service="usg")) - Expected return object: - - ``uaclient.api.u.pro.packages.updates.v1.PackageUpdatesResult`` - - .. list-table:: - :header-rows: 1 - - * - 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`` - - .. list-table:: - :header-rows: 1 - - * - 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`` + - ``uaclient.api.u.pro.services.disable.v1.DisableResult`` .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - 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 + * - Field Name + - Type + - Description + * - ``disabled`` + - ``List[str]`` + - List of services disabled - Raised exceptions: - - No exceptions raised by this endpoint. + - ``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 .. tab-item:: CLI interaction :sync: CLI @@ -2157,41 +2525,42 @@ where they can be obtained. .. code-block:: bash - pro api u.pro.packages.updates.v1 + pro api u.pro.services.disable.v1 --args service=usg - Expected attributes in JSON structure: - .. code-block:: json + .. code-block:: 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": "", - }, - ] - } + { + "disabled": [ + "usg" + ] + } -u.pro.status.is_attached.v1 -=========================== +u.pro.services.enable.v1 +======================== -This endpoint shows if the machine is attached to a Pro subscription. +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: ``28~`` +- Introduced in Ubuntu Pro Client Version: ``32~`` - Args: - - This endpoint takes no arguments. + .. list-table:: + :header-rows: 1 + + * - 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) .. tab-set:: @@ -2202,23 +2571,40 @@ This endpoint shows if the machine is attached to a Pro subscription. .. code-block:: python - from uaclient.api.u.pro.status.is_attached.v1 import is_attached - - result = is_attached() + from uaclient.api.u.pro.services.enable.v1 import enable, EnableOptions + result = enable(EnableOptions(service="usg")) - Expected return object: - - ``uaclient.api.u.pro.status.is_attached.v1.IsAttachedResult`` + - ``uaclient.api.u.pro.services.enable.v1.EnableResult`` .. list-table:: - :header-rows: 1 + :header-rows: 1 + + * - 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. - * - Field Name - - Type - - Description - * - ``is_attached`` - - *bool* - - If the machine is attached to a Pro subscription + - Raised exceptions: + + - ``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 .. tab-item:: CLI interaction :sync: CLI @@ -2227,7 +2613,20 @@ This endpoint shows if the machine is attached to a Pro subscription. .. code-block:: bash - pro api u.pro.status.is_attached.v1 + pro api u.pro.services.enable.v1 --args service=usg + + - Expected attributes in JSON structure: + + .. code-block:: js + + { + "disabled": [], + "enabled": [ + "usg" + ], + "messages": [], + "reboot_required": false + } u.pro.status.enabled_services.v1 ================================ @@ -2263,7 +2662,7 @@ This endpoint shows the Pro services that are enabled on the machine. - Type - Description * - ``enabled_services`` - - *List[EnabledService]* + - ``List[EnabledService]`` - A list of ``EnabledService`` objects - ``uaclient.api.u.pro.status.enabled_services.v1.EnabledService`` @@ -2275,15 +2674,15 @@ This endpoint shows the Pro services that are enabled on the machine. - Type - Description * - ``name`` - - *str* + - ``str`` - | Name of the service. | Possible values are: ``cc-eal``, ``cis``, ``esm-apps``, ``esm-infra``, ``fips``, ``fips-updates``, ``livepatch``, ``realtime-kernel``, ``ros``, ``ros-updates``. | When ``usg`` is enabled, this value will be ``cis``. * - ``variant_enabled`` - - *bool* + - ``bool`` - If a variant of the service is enabled * - ``variant_name`` - - *Optional[str]* + - ``Optional[str]`` - Name of the variant, if a variant is enabled .. tab-item:: CLI interaction @@ -2295,6 +2694,73 @@ This endpoint shows the Pro services that are enabled on the machine. pro api u.pro.status.enabled_services.v1 +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~`` +- Args: + + - This endpoint takes no arguments. + +.. tab-set:: + + .. tab-item:: Python API interaction + :sync: python + + - Calling from Python code: + + .. code-block:: 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`` + + .. list-table:: + :header-rows: 1 + + * - Field Name + - Type + - Description + * - ``is_attached`` + - ``bool`` + - If the machine is attached to a Pro subscription + * - ``contract_status`` + - ``str`` + - The current contract status (active, grace-period, active-soon-to-expire, expired). + Please refer to the explanation tab for a description of each state. + * - ``contract_remaining_days`` + - ``int`` + - The number of days remaining for the contract to be valid + * - ``is_attached_and_contract_valid`` + - ``bool`` + - If the machine is attached and the contract is still valid + + .. tab-item:: CLI interaction + :sync: CLI + + - Calling from the CLI: + + .. code-block:: bash + + pro api u.pro.status.is_attached.v1 + + .. tab-item:: Explanation + :sync: 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 ============================== @@ -2329,7 +2795,7 @@ This endpoint returns the current APT News that gets displayed in `apt upgrade`. - Type - Description * - ``current_news`` - - *Optional[str]* + - ``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: @@ -2388,7 +2854,7 @@ formatted as a manifest file (i.e., ``package_name\tversion``). - Type - Description * - ``manifest_data`` - - *str* + - ``str`` - Manifest of ``apt`` and ``snap`` packages installed on the system - Raised exceptions: @@ -2455,25 +2921,25 @@ configured on the machine. - Type - Description * - ``systemd_apt_timer_enabled`` - - *bool* + - ``bool`` - Indicate if the ``apt-daily.timer`` jobs are enabled * - ``apt_periodic_job_enabled`` - - *bool* + - ``bool`` - Indicate if the ``APT::Periodic::Enabled`` configuration is turned off * - ``package_lists_refresh_frequency_days`` - - *int* + - ``int`` - The value of the ``APT::Periodic::Update-Package-Lists`` configuration * - ``unattended_upgrades_frequency_days`` - - *int* + - ``int`` - The value of the ``APT::Periodic::Unattended-Upgrade`` configuration * - ``unattended_upgrades_allowed_origins`` - - *List[str]* + - ``List[str]`` - The value of the ``Unattended-Upgrade::Allowed-Origins`` configuration * - ``unattended_upgrades_running`` - - *bool* + - ``bool`` - Indicate if the ``unattended-upgrade`` service is correctly configured and running * - ``unattended_upgrades_disabled_reason`` - - *object* + - ``object`` - Object that explains why ``unattended-upgrades`` is not running -- if the application is running, the object will be null * - ``unattended_upgrades_last_run`` - ``datetime.datetime`` @@ -2488,10 +2954,10 @@ configured on the machine. - Type - Description * - ``msg`` - - *str* + - ``str`` - The reason why ``unattended-upgrades`` is not running on the system * - ``code`` - - *str* + - ``str`` - The message code associated with the message - Raised exceptions: