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:

{
    "_schema_version": "v1",
    "data": {
        "attributes": {
            // <endpoint specific attributes>
        },
        "meta": {
            "environment_vars": []
        },
        "type": "<response_type>"
    },
    "errors": [],
    "result": "<success|failure>",
    "version": "<client version>",
    "warnings": []
}

Version dependencies#

The package name of Ubuntu Pro Client is ubuntu-advantage-tools.

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~:

ubuntu-advantage-tools (>= 27.11~)

Runtime version detection#

If you need to detect the current version at runtime, the most reliable way is to query dpkg.

dpkg-query --showformat='${Version}' --show ubuntu-advantage-tools

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~:

dpkg --compare-versions "$(dpkg-query --showformat='${Version}' --show ubuntu-advantage-tools)" 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:

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 behaviour 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:

[
    {
        "msg": "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#

This endpoint shows the installed Pro Client version.

  • Introduced in Ubuntu Pro Client Version: 27.11~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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.

Calling from the CLI:

pro api u.pro.version.v1

Expected attributes in JSON structure:

{
    "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~

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.

Calling from Python code:

from uaclient.api.u.pro.attach.auto.configure_retry_service.v1 import configure_retry_service, ConfigureRetryServiceOptions

options = ConfigureRetryServiceOptions(enable=["<service1>", "<service2>"], enable_beta=["<beta_service3>"])
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).

Calling from the CLI:

pro api u.pro.attach.auto.configure_retry_service.v1 --data {"enable": ["esm-infra", "esm-apps"]}

Expected attributes in JSON structure:

{}

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~

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.

Calling from Python code:

from uaclient.api.u.pro.attach.auto.full_auto_attach.v1 import full_auto_attach, FullAutoAttachOptions

options = FullAutoAttachOptions(enable=["<service1>", "<service2>"], enable_beta=["<beta_service3>"])
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.

Calling from the CLI:

pro api u.pro.attach.auto.full_auto_attach.v1 --data {"enable": ["esm-infra", "esm-apps"]}

Expected attributes in JSON structure:

{}

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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.attach.auto.should_auto_attach.v1

Expected attributes in JSON structure:

{
    "should_auto_attach": false
}

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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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.

Calling from the CLI:

pro api u.pro.attach.magic.initiate.v1

Expected attributes in JSON structure:

{
    "user_code":"<UI_code>",
    "token":"<magic_token>",
    "expires": "<yyyy-MM-dd>T<HH:mm:ss>.<TZ>",
    "expires_in": 600
}

u.pro.attach.magic.revoke.v1#

This endpoint revokes a Magic Attach Token.

  • Introduced in Ubuntu Pro Client Version: 27.11~

Arguments:

Field Name

Type

Description

magic_token

str

The Token provided by the initiate endpoint.

Calling from Python code:

from uaclient.api.u.pro.attach.magic.revoke.v1 import MagicAttachRevokeOptions, revoke

options = MagicAttachWaitOptions(magic_token="<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.

Calling from the CLI:

pro api u.pro.attach.magic.revoke.v1 --args magic_token=<token>

Expected attributes in JSON structure:

{}

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~

Arguments:

Field Name

Type

Description

magic_token

str

The Token provided by the initiate endpoint.

Calling from Python code:

from uaclient.api.u.pro.attach.magic.wait.v1 import MagicAttachWaitOptions, wait

options = MagicAttachWaitOptions(magic_token="<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.

Calling from the CLI:

pro api u.pro.attach.magic.wait.v1 --args magic_token=<magic_token>

Expected attributes in JSON structure:

{
    "user_code":"<UI_code>",
    "token":"<magic_token>",
    "expires": "<yyyy-MM-dd>T<HH:mm:ss>.<TZ>",
    "expires_in": 500,
    "contract_id": "<Contract-ID>",
    "contract_token": "<attach_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~

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)

Calling from Python code:

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.

Calling from the CLI:

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:

{
    "token": "TOKEN",
    "auto_enable_services": false
}

Then we can call the API like this:

cat file.json | pro api u.pro.attach.token.full_token_attach.v1 --data -

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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.

Calling from the CLI:

pro api u.pro.detach.v1

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.packages.summary.v1

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.packages.updates.v1

Expected attributes in JSON structure:

{
    "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": "<some site>",
            "package": "<package name>",
            "provided_by": "<service name>",
            "status": "<update status>",
            "version": "<updated version>",
        },
    ]
}

u.pro.security.fix.cve.execute.v1#

This endpoint fixes the specified CVEs on the machine.

  • Introduced in Ubuntu Pro Client Version: 30~

Arguments:

Field Name

Type

Description

cves

List[str]

A list of CVE (i.e. CVE-2023-2650) titles

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.security.fix.cve.execute.v1 --data '{"cves": ["CVE-1234-1234", "CVE-1234-1235"]}'

Expected attributes in JSON structure:

{
    "cves_data": {
        "status": "fixed",
        "cves": [
            {
                "title": "CVE-1234-56789",
                "description": "..."
                "status": "fixed",
                "upgraded_packages": {
                    "name": "pkg1",
                    "version": "1.1",
                    "pocket": "standard-updates"
                },
                "errors": []
            }
        ]
    }
}

When using the CVE endpoint, the expected output is as follows:

{
    "_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:

{
    "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~

Arguments:

Field Name

Type

Description

cves

List[str]

A list of CVE (i.e. CVE-2023-2650) titles

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-56789", "CVE-1234-1235"]}'

Expected attributes in JSON structure:

{
    "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~

Arguments:

Field Name

Type

Description

usns

List[str]

A list of USNs (i.e. USN-6188-1) titles

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.security.fix.usn.execute.v1 --data '{"usns": ["USN-1234-1", "USN-1235-1"]}'

Expected attributes in JSON structure:

{
    "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": []
            }
        ]
    }
}

When using the USN endpoint, the expected output is as follows:

{
    "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.

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:

{
    "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~

Arguments:

Field Name

Type

Description

usns

List[str]

A list of USNs (i.e. USN-6119-1) titles

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.security.fix.usn.plan.v1 --data '{"usns": ["USN-1234-1", "USN-1235-1"]}'

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.security.status.livepatch_cves.v1

Expected attributes in JSON structure:

{
    "fixed_cves":[
        {
            "name": "<CVE Name>",
            "patched": true
        },
        {
            "name": "<Other CVE 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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.security.status.reboot_required.v1

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.services.dependencies.v1

Expected attributes in JSON structure:

{
    "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~

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)

Calling from Python code:

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

Calling from the CLI:

pro api u.pro.services.disable.v1 --args service=usg

Expected attributes in JSON structure:

{
    "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~

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)

Calling from Python code:

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

Calling from the CLI:

pro api u.pro.services.enable.v1 --args service=usg

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.status.enabled_services.v1

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.pro.status.is_attached.v1

Expected attributes in JSON structure:

{
    "contract_remaining_days": 360,
    "contract_status": "active",
    "is_attached": true,
    "is_attached_and_contract_valid": true
}

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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.apt_news.current_news.v1

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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).

Calling from the CLI:

pro api u.security.package_manifest.v1

Expected attributes in JSON structure:

{
    "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~

Arguments:

  • This endpoint takes no arguments.

Calling from Python code:

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

Calling from the CLI:

pro api u.unattended_upgrades.status.v1

Expected attributes in JSON structure:

{
    "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:

    {
        "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"
                ]
            }
        }
    }