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:

[
    {
        "title": "Failed to connect to authentication server",
        "code": "connectivity-error",
        "meta": {}
    }
]

Warnings follow the exact same structure as errors. The only difference is that warnings means that the command was able to complete although unexpected scenarios happened when executing the command.

CLI arguments

There are two ways to provide data to APIs that require arguments.

• --args: Use this to individually provide arguments to the CLI endpoint.

  For example: pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN

• --data: Use this to provide a JSON object containing all the data:

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

Available endpoints

The currently available endpoints are:

• u.pro.version.v1

• u.pro.attach.auto.configure_retry_service.v1

• u.pro.attach.auto.full_auto_attach.v1

• u.pro.attach.auto.should_auto_attach.v1

• u.pro.attach.magic.initiate.v1

• u.pro.attach.magic.revoke.v1

• u.pro.attach.magic.wait.v1

• u.pro.attach.token.full_token_attach.v1

• u.pro.detach.v1

• u.pro.packages.summary.v1

• u.pro.packages.updates.v1

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

• u.pro.security.fix.cve.plan.v1

• u.pro.security.fix.usn.execute.v1

• u.pro.security.fix.usn.plan.v1

• u.pro.security.status.livepatch_cves.v1

• u.pro.security.status.reboot_required.v1

• u.pro.services.dependencies.v1

• u.pro.services.disable.v1

• u.pro.services.enable.v1

• u.pro.status.enabled_services.v1

• u.pro.status.is_attached.v1

• u.apt_news.current_news.v1

• u.security.package_manifest.v1

• u.unattended_upgrades.status.v1

u.pro.version.v1

This endpoint shows the installed Pro Client version.

• Introduced in Ubuntu Pro Client Version: 27.11~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.version.v1 import version

result = version()

Expected return object:

• uaclient.api.u.pro.version.v1.VersionResult

  Field Name	Type	Description
  installed_version	str	The current installed version

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

• VersionError: Raised if the Client cannot determine the version.

CLI interaction

Calling from the CLI:

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~

• Requires network access: No

Arguments:

Field Name	Type	Description
enable	Optional[List[str]]	Optional list of services to enable after auto-attaching.
enable_beta	Optional[List[str]]	Optional list of beta services to enable after auto-attaching.
cloud_override	Optional[str]	Ignore the result of cloud-id and act as if running on this cloud.

Note

If none of the lists are set, the services will be enabled based on the contract definitions.

Python API interaction

Calling from Python code:

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

CLI interaction

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
enable	Optional[List[str]]	Optional list of services to enable after auto-attaching.
enable_beta	Optional[List[str]]	Optional list of beta services to enable after auto-attaching.
cloud_override	Optional[str]	Ignore the result of cloud-id and act as if running on this cloud.

Note

If none of the lists are set, the services will be enabled based on the contract definitions.

Python API interaction

Calling from Python code:

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.

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: Yes

Arguments:

• This endpoint takes no arguments.

Python API interaction

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.

CLI interaction

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
magic_token	str	The Token provided by the initiate endpoint.

Python API interaction

Calling from Python code:

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.

CLI interaction

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
magic_token	str	The Token provided by the initiate endpoint.

Python API interaction

Calling from Python code:

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.

CLI interaction

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
token	str	The token associated with a Pro subscription
auto_enable_services	Optional[bool]	If false, the attach operation will not enable any service during the operation (default: true)

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.attach.token.full_token_attach.v1 import full_token_attach, FullTokenAttachOptions

options = FullTokenAttachOptions(token="TOKEN")
result = full_token_attach(options)

Expected return object:

• uaclient.api.u.pro.attach.token.full_token_attach.v1.FullTokenAttachResult

  Field Name	Type	Description
  enabled	List[str]	The services enabled during the attach operation
  reboot_required	bool	True if the system requires a reboot after the attach operation

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

• ConnectivityError: Raised if it is not possible to connect to the contracts service.

• ContractAPIError: Raised if there is an unexpected error in the contracts service interaction.

• LockHeldError: Raised if another Client process is holding the lock on the machine.

• NonRootUserError: Raised if a non-root user executes this endpoint.

CLI interaction

Calling from the CLI:

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~

• Requires network access: Yes

Arguments:

• This endpoint takes no arguments.

Python API interaction

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.

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
cves	List[str]	A list of CVE (i.e. CVE-2023-2650) titles

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.security.fix.cve.execute.v1 import execute, CVEFixExecuteOptions

options = CVEFixExecuteOptions(cves=["CVE-1234-1234", "CVE-1234-1235"])
result = execute(options)

Expected return object:

• uaclient.api.u.pro.security.fix.cve.execute.v1.CVESAPIFixExecuteResult

  Field Name	Type	Description
  cves_data	CVEAPIFixExecuteResult	A list of CVEAPIFixExecuteResult objects

• uaclient.api.u.pro.security.fix.cve.execute.v1.CVEAPIFixExecuteResult

  Field Name	Type	Description
  status	str	The status of fixing the CVEs
  cves	List[FixExecuteResult]	A list of FixExecuteResult objects

• uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteResult

  Field Name	Type	Description
  title	str	The title of the CVE
  description	Optional[str]	The description of the CVE
  status	str	The status of fixing the CVE
  upgraded_packages	Optional[List[UpgradedPackage]]	A list of UpgradedPackage objects
  errors	Optional[List[FixExecuteError]]	A list of FixExecuteError objects

• uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage

  Field Name	Type	Description
  name	str	The name of the package
  version	str	The version that the package was upgraded to
  pocket	str	The pocket which contained the package upgrade

• uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteError

  Field Name	Type	Description
  error_type	str	The type of the error
  reason	str	The reason why the error occurred
  failed_upgrades	Optional[List[FailedUpgrade]]	A list of FailedUpgrade objects

• uaclient.api.u.pro.security.fix._common.execute.v1.FailedUpgrade

  Field Name	Type	Description
  name	str	The name of the package
  pocket	Optional[str]	The pocket which contained the package upgrade

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

CLI interaction

Calling from the CLI:

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

Explanation

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
cves	List[str]	A list of CVE (i.e. CVE-2023-2650) titles

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.security.fix.cve.plan.v1 import plan, CVEFixPlanOptions

options = CVEFixPlanOptions(cves=["CVE-1234-1234", "CVE-1234-1235"])
result = plan(options)

Expected return object:

• uaclient.api.u.pro.security.fix.cve.plan.v1.CVESFixPlanResult

  Field Name	Type	Description
  cves_data	CVEFixPlanResult	A list of CVEFixPlanResult objects

• uaclient.api.u.pro.security.fix.cve.plan.v1.CVEFixPlanResult

  Field Name	Type	Description
  expected_status	str	The expected status of fixing the CVEs
  cves	List[FixPlanResult]	A list of FixPlanResult objects

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanResult

  Field Name	Type	Description
  title	str	The title of the issue
  description	Optional[str]	The description of the issue
  current_status	Optional[str]	The current status of the issue on the system
  expected_status	str	The expected status of fixing the issue
  affected_packages	Optional[List[str]]	A list of package names affected by the issue
  plan	List[FixPlanStep]	A list of FixPlanStep objects
  warnings	Optional[List[FixPlanWarning]]	A list of FixPlanWarning objects
  error	Optional[FixPlanError]	A FixPlanError object, if an error occurred.
  additional_data	Optional[AdditionalData]	Additional data for the issue

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanStep

  Field Name	Type	Description
  operation	str	The operation that would be performed to fix the issue. This can be either an attach, enable, apt-upgrade or a no-op type
  order	int	The execution order of the operation
  data	DataObject	A data object that can be either an AptUpgradeData, AttachData, EnableData, NoOpData

• uaclient.data_types.DataObject

  • This object has no fields.

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanWarning

  Field Name	Type	Description
  warning_type	str	The type of warning
  order	int	The execution order of the operation
  data	DataObject	A data object that represents either a PackageCannotBeInstalledData or a SecurityIssueNotFixedData

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanError

  Field Name	Type	Description
  msg	str	The error message
  code	Optional[str]	The message code

• uaclient.api.u.pro.security.fix._common.plan.v1.AdditionalData

  • This object has no fields.

• uaclient.api.u.pro.security.fix._common.plan.v1.AptUpgradeData

  Field Name	Type	Description
  binary_packages	List[str]	A list of binary packages that need to be upgraded
  source_packages	List[str]	A list of source packages that need to be upgraded
  pocket	str	The pocket where the packages will be installed from

• uaclient.api.u.pro.security.fix._common.plan.v1.AttachData

  Field Name	Type	Description
  reason	str	The reason why an attach operation is needed
  required_service	str	The required service that requires the attach operation
  source_packages	List[str]	The source packages that require the attach operation

• uaclient.api.u.pro.security.fix._common.plan.v1.EnableData

  Field Name	Type	Description
  service	str	The service that needs to be enabled
  source_packages	List[str]	The source packages that require the service to be enabled

• uaclient.api.u.pro.security.fix._common.plan.v1.NoOpData

  Field Name	Type	Description
  status	str	The status of the issue when no operation can be performed

• uaclient.api.u.pro.security.fix._common.plan.v1.NoOpAlreadyFixedData

  Field Name	Type	Description
  status	str	The status of the issue when no operation can be performed
  source_packages	List[str]	The source packages that are already fixed
  pocket	str	The pocket where the packages would have been installed from

• uaclient.api.u.pro.security.fix._common.plan.v1.NoOpLivepatchFixData

  Field Name	Type	Description
  status	str	The status of the CVE when no operation can be performed
  patch_version	str	Version of the patch from Livepatch that fixed the CVE

• uaclient.api.u.pro.security.fix._common.plan.v1.PackageCannotBeInstalledData

  Field Name	Type	Description
  binary_package	str	The binary package that cannot be installed
  binary_package_version	str	The version of the binary package that cannot be installed
  source_package	str	The source package associated with the binary package
  related_source_packages	List[str]	A list of source packages that come from the same pocket as the affected package
  pocket	str	The pocket where the affected package should be installed from

• uaclient.api.u.pro.security.fix._common.plan.v1.SecurityIssueNotFixedData

  Field Name	Type	Description
  source_packages	List[str]	A list of source packages that cannot be fixed at the moment
  status	str	The status of the CVE regarding those packages

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

CLI interaction

Calling from the CLI:

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
usns	List[str]	A list of USNs (i.e. USN-6188-1) titles

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.security.fix.usn.execute.v1 import execute, USNFixExecuteOptions

options = USNFixExecuteOptions(usns=["USN-1234-1", "USN-1235-1"])
result = execute(options)

Expected return object:

• uaclient.api.u.pro.security.fix.usn.execute.v1.USNSAPIFixExecuteResult

  Field Name	Type	Description
  usns_data	USNAPIFixExecuteResult	A list of USNAPIFixExecuteResult objects

• uaclient.api.u.pro.security.fix.usn.execute.v1.USNAPIFixExecuteResult

  Field Name	Type	Description
  status	str	The status of fixing the USNs
  usns	List[FixExecuteUSNResult]	A list of FixExecuteUSNResult objects

• uaclient.api.u.pro.security.fix.usn.execute.v1.FixExecuteUSNResult

  Field Name	Type	Description
  target_usn	FixExecuteResult	The FixExecuteResult for the target USN
  related_usns	Optional[List[FixExecuteResult]]	A list of FixExecuteResult objects for the related USNs

• uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteResult

  Field Name	Type	Description
  title	str	The title of the CVE
  description	Optional[str]	The description of the CVE
  status	str	The status of fixing the CVE
  upgraded_packages	Optional[List[UpgradedPackage]]	A list of UpgradedPackage objects
  errors	Optional[List[FixExecuteError]]	A list of FixExecuteError objects

• uaclient.api.u.pro.security.fix._common.execute.v1.UpgradedPackage

  Field Name	Type	Description
  name	str	The name of the package
  version	str	The version that the package was upgraded to
  pocket	str	The pocket which contained the package upgrade

• uaclient.api.u.pro.security.fix._common.execute.v1.FixExecuteError

  Field Name	Type	Description
  error_type	str	The type of the error
  reason	str	The reason why the error occurred
  failed_upgrades	Optional[List[FailedUpgrade]]	A list of FailedUpgrade objects

• uaclient.api.u.pro.security.fix._common.execute.v1.FailedUpgrade

  Field Name	Type	Description
  name	str	The name of the package
  pocket	Optional[str]	The pocket which contained the package upgrade

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

CLI interaction

Calling from the CLI:

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

Explanation

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
usns	List[str]	A list of USNs (i.e. USN-6119-1) titles

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.security.fix.usn.plan.v1 import plan, USNFixPlanOptions

options = USNFixPlanOptions(cves=["USN-1234-1", "USN-1235-1"])
result = plan(options)

Expected return object:

• uaclient.api.u.pro.security.fix.usn.plan.v1.USNSFixPlanResult

  Field Name	Type	Description
  usns_data	USNFixPlanResult	A list of USNFixPlanResult objects

• uaclient.api.u.pro.security.fix.usn.plan.v1.USNFixPlanResult

  Field Name	Type	Description
  expected_status	str	The expected status of fixing the USNs
  usns	List[FixPlanUSNResult]	A list of FixPlanUSNResult objects

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanUSNResult

  Field Name	Type	Description
  target_usn_plan	FixPlanResult	A FixPlanResult object for the target USN
  related_usns_plan	Optional[List[FixPlanResult]]	A list of FixPlanResult objects for the related USNs

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanResult

  Field Name	Type	Description
  title	str	The title of the issue
  description	Optional[str]	The description of the issue
  current_status	Optional[str]	The current status of the issue on the system
  expected_status	str	The expected status of fixing the issue
  affected_packages	Optional[List[str]]	A list of package names affected by the issue
  plan	List[FixPlanStep]	A list of FixPlanStep objects
  warnings	Optional[List[FixPlanWarning]]	A list of FixPlanWarning objects
  error	Optional[FixPlanError]	A FixPlanError object, if an error occurred.
  additional_data	Optional[AdditionalData]	Additional data for the issue

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanStep

  Field Name	Type	Description
  operation	str	The operation that would be performed to fix the issue. This can be either an attach, enable, apt-upgrade or a no-op type
  order	int	The execution order of the operation
  data	DataObject	A data object that can be either an AptUpgradeData, AttachData, EnableData, NoOpData

• uaclient.data_types.DataObject

  • This object has no fields.

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanWarning

  Field Name	Type	Description
  warning_type	str	The type of warning
  order	int	The execution order of the operation
  data	DataObject	A data object that represents either a PackageCannotBeInstalledData or a SecurityIssueNotFixedData

• uaclient.api.u.pro.security.fix._common.plan.v1.FixPlanError

  Field Name	Type	Description
  msg	str	The error message
  code	Optional[str]	The message code

• uaclient.api.u.pro.security.fix._common.plan.v1.AdditionalData

  • This object has no fields.

• uaclient.api.u.pro.security.fix._common.plan.v1.USNAdditionalData

  Field Name	Type	Description
  associated_cves	List[str]	The associated CVEs for the USN
  associated_launchpad_bugs	List[str]	The associated Launchpad bugs for the USN

• uaclient.api.u.pro.security.fix._common.plan.v1.AptUpgradeData

  Field Name	Type	Description
  binary_packages	List[str]	A list of binary packages that need to be upgraded
  source_packages	List[str]	A list of source packages that need to be upgraded
  pocket	str	The pocket where the packages will be installed from

• uaclient.api.u.pro.security.fix._common.plan.v1.AttachData

  Field Name	Type	Description
  reason	str	The reason why an attach operation is needed
  required_service	str	The required service that requires the attach operation
  source_packages	List[str]	The source packages that require the attach operation

• uaclient.api.u.pro.security.fix._common.plan.v1.EnableData

  Field Name	Type	Description
  service	str	The service that needs to be enabled
  source_packages	List[str]	The source packages that require the service to be enabled

• uaclient.api.u.pro.security.fix._common.plan.v1.NoOpData

  Field Name	Type	Description
  status	str	The status of the issue when no operation can be performed

• uaclient.api.u.pro.security.fix._common.plan.v1.NoOpAlreadyFixedData

  Field Name	Type	Description
  status	str	The status of the issue when no operation can be performed
  source_packages	List[str]	The source packages that are already fixed
  pocket	str	The pocket where the packages would have been installed from

• uaclient.api.u.pro.security.fix._common.plan.v1.PackageCannotBeInstalledData

  Field Name	Type	Description
  binary_package	str	The binary package that cannot be installed
  binary_package_version	str	The version of the binary package that cannot be installed
  source_package	str	The source package associated with the binary package
  related_source_packages	List[str]	A list of source packages that come from the same pocket as the affected package
  pocket	str	The pocket where the affected package should be installed from

• uaclient.api.u.pro.security.fix._common.plan.v1.SecurityIssueNotFixedData

  Field Name	Type	Description
  source_packages	List[str]	A list of source packages that cannot be fixed at the moment
  status	str	The status of the CVE regarding those packages

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

CLI interaction

Calling from the CLI:

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
service	str	Pro service to disable
purge	Optional[bool]	Also remove all packages that were installed from this service. Only supported by some services. (default: false)

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.services.disable.v1 import disable, DisableOptions
result = disable(DisableOptions(service="usg"))

Expected return object:

• uaclient.api.u.pro.services.disable.v1.DisableResult

  Field Name	Type	Description
  disabled	List[str]	List of services disabled

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

• NonRootUserError: When called as non-root user

• UnattachedError: When called on a machine that is not attached to a Pro subscription

• EntitlementNotFoundError: When the service argument is not a valid Pro service name

• LockHeldError: When another Ubuntu Pro related operation is in progress

• EntitlementNotDisabledError: When the service fails to disable

CLI interaction

Calling from the CLI:

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~

• Requires network access: Yes

Arguments:

Field Name	Type	Description
service	str	Pro service to be enabled
variant	Optional[str]	Optional variant of the Pro service to be enabled.
access_only	Optional[bool]	If true and the target service supports it, only enable access to the service (default: false)

Python API interaction

Calling from Python code:

from uaclient.api.u.pro.services.enable.v1 import enable, EnableOptions
result = enable(EnableOptions(service="usg"))

Expected return object:

• uaclient.api.u.pro.services.enable.v1.EnableResult

  Field Name	Type	Description
  enabled	List[str]	List of services that were enabled.
  disabled	List[str]	List of services that were disabled.
  reboot_required	bool	True if one of the services that was enabled requires a reboot.
  messages	List[str]	List of information message strings about the service that was just enabled. Possibly translated.

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

• NonRootUserError: When called as non-root user

• UnattachedError: When called on a machine that is not attached to a Pro subscription

• NotSupported: When called for a service that doesn’t support being enabled via API (currently only Landscape)

• EntitlementNotFoundError: When the service argument is not a valid Pro service name or if the variant is not a valid variant of the target service

• LockHeldError: When another Ubuntu Pro related operation is in progress

• EntitlementNotEnabledError: When the service fails to enable

CLI interaction

Calling from the CLI:

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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
}

Explanation

The contract_status field can return 4 different states, they are:

• active: The contract is currently valid.

• grace-period: The contract is in the grace period. This means that it is expired, but there are still some days where the contract will be valid.

• active-soon-to-expire: The contract is almost expired, but still valid.

• expired: The contract is expired and no longer valid.

u.apt_news.current_news.v1

This endpoint returns the current APT News that gets displayed in apt upgrade.

• Introduced in Ubuntu Pro Client Version: 29~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

Calling from Python code:

from uaclient.api.u.apt_news.current_news.v1 import current_news

result = current_news().current_news

Expected return object:

• uaclient.api.u.apt_news.current_news.v1.CurrentNewsResult

  Field Name	Type	Description
  current_news	Optional[str]	The current APT News to be displayed for the system. This could be a str with up to three lines (i.e. up to two \n characters). If there is no APT News to be displayed, this will be None.

Raised exceptions:

• UbuntuProError: UbuntuProError is the base class of all exceptions raised by Ubuntu Pro Client and it is best practice to handle this error on any API call. (Note: if any API call raises an exception that does not inherit from UbuntuProError, please report a bug).

CLI interaction

Calling from the CLI:

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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~

• Requires network access: No

Arguments:

• This endpoint takes no arguments.

Python API interaction

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

CLI interaction

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