diff --git a/docs/explanations/how_to_interpret_the_security_status_command.rst b/docs/explanations/how_to_interpret_the_security_status_command.rst index 978fa23aee..565998b64c 100644 --- a/docs/explanations/how_to_interpret_the_security_status_command.rst +++ b/docs/explanations/how_to_interpret_the_security_status_command.rst @@ -208,63 +208,48 @@ source): Machine-readable output ======================= -If you run the ``pro security-status --format yaml`` command on your machine, -you should expect to see an output that follows this structure: - -.. code-block:: text - - _schema_version: '0.1' - summary: - num_esm_apps_packages: 0 - num_esm_apps_updates: 0 - num_esm_infra_packages: 1 - num_esm_infra_updates: 1 - num_main_packages: 70 - num_multiverse_packages: 10 - num_restricted_packages: 10 - num_third_party_packages: 0 - num_universe_packages: 9 - num_installed_packages: 100 - num_standard_security_updates: 0 - ua: - attached: true - enabled_services: - - esm-apps - - esm-infra - entitled_services: - - esm-apps - - esm-infra - packages: - - origin: esm.ubuntu.com - package: zlib1g - service_name: esm-infra - status: upgrade_available - version: 1:1.2.8.dfsg-2ubuntu4.3+esm1 - download_size: 123456 - livepatch: - fixed_cves: - - Name: cve-2013-1798 - Patched: true - -Let's understand what each key means in the output of the -``pro security-status --format yaml`` command: - -``summary`` ------------ - -This provides a summary of the system related to Ubuntu Pro and the different -package sources in the system: +If you need a machine readable version of ``pro security-status``, you can use +these API endpoint to achieve that: + +* :ref:`u.pro.packages.summary.v1 ` +* :ref:`u.pro.packages.updates.v1 ` +* :ref:`u.pro.status.is_attached.v1 ` +* :ref:`u.pro.status.enabled_services.v1 ` +* :ref:`u.pro.security.status.livepatch_cves.v1 ` + +``u.pro.packages.summary.v1`` +------------------------------ + +This API is responsible for providing a summary of where all the installed packages +in the machine comes from. + +When called through ``pro api u.pro.packages.summary.v1``, it will produce a data output +with the following structure: + +.. code-block:: js + + { + "summary":{ + "num_installed_packages": 1, + "num_esm_apps_packages": 2, + "num_esm_infra_packages": 3, + "num_main_packages": 4, + "num_multiverse_packages": 5, + "num_restricted_packages": 6, + "num_third_party_packages": 7, + "num_universe_packages": 8, + "num_unknown_packages": 9, + }, + } + +The summary object contains the following fields: * **num_installed_packages**: The total number of installed packages on the system. * **num_esm_apps_packages**: The number of packages installed from ``esm-apps``. -* **num_esm_apps_updates**: The number of ``esm-apps`` package updates - available to the system. * **num_esm_infra_packages**: The number of packages installed from ``esm-infra``. -* **num_esm_infra_updates**: The number of ``esm-infra`` package updates - available to the system. * **num_main_packages**: The number of packages installed from the ``main`` archive component. * **num_multiverse_packages**: The number of packages installed from the @@ -278,47 +263,59 @@ package sources in the system: * **num_unknown_packages**: The number of packages installed from sources not known to ``apt`` (e.g., those installed locally through ``dpkg`` or packages without a remote reference). -* **num_standard_security_updates**: The number of standard security updates - available to the system. -.. note:: - It is worth mentioning here that the ``_updates`` fields are presenting the - number of **security** updates for **installed** packages. For example, - let's assume your machine has a universe package that has a security update - from ``esm-infra``. The count will be displayed as: +``u.pro.packages.updates.v1`` +------------------------------ - .. code-block:: text +This API is responsible for listing the available package updates in the system. - num_esm_infra_packages: 0 - num_esm_infra_updates: 1 - num_universe_packages: 1 - - After upgrading the system, the count will turn to: +When called through ``pro api u.pro.packages.updates.v1``, it will produce a data output +with the following structure: - .. code-block:: text +.. code-block:: js - num_esm_infra_packages: 1 - num_esm_infra_updates: 0 - num_universe_packages: 0 - -* **ua**: An object representing the state of Ubuntu Pro on the system: + { + "summary": { + "num_updates": 15, + "num_esm_apps_updates": 2, + "num_esm_infra_updates": 3, + "num_standard_security_updates": 5, + "num_standard_updates": 5, + }, + "updates": [ + { + "download_size": 6, + "origin": "", + "package": "", + "provided_by": "", + "status": "", + "version": "", + }, + ] + } - * **attached**: If the system is attached to an Ubuntu Pro subscription. - * **enabled_services**: A list of services that are enabled on the system. - If unattached, this will always be an empty list. - * **entitled_services**: A list of services that are entitled on your - Ubuntu Pro subscription. If unattached, this will always be an empty list. -``packages`` ------------- +Note that there are two distinct object in the JSON response, **summary** and **updates**. +The summary object will contain the following attributes: -This provides a list of security updates for packages installed on the system. -Every entry on the list will follow this structure: +* **num_updates**: The total number of available updates to the system. +* **num_esm_apps_updates**: The number of ``esm-apps`` package updates + available to the system. +* **num_esm_infra_updates**: The number of ``esm-infra`` package updates + available to the system. +* **num_standard_security_updates**: The number of standard security updates + available to the system. +* **num_standard_updates**: The number of standard updates available to the system. + +While the updates object will be a list of package updates, where each update object +will contain the following attributes: +* **download_size**: The number of bytes that would be downloaded in order to + install the update. * **origin**: The host where the update comes from. * **package**: The name of the package. -* **service_name**: The service that provides the package update. It can be +* **provided_by**: The service that provides the package update. It can be one of: ``esm-infra``, ``esm-apps`` or ``standard-security``. * **status**: The status for this update. It will be one of: @@ -329,14 +326,106 @@ Every entry on the list will follow this structure: but the service required to provide the upgrade is not enabled. * **"upgrade_unavailable"**: The machine is attached, but the contract is not entitled to the service which provides the upgrade. - * **version**: The update version. -* **download_size**: The number of bytes that would be downloaded in order to - install the update. - -``livepatch`` -------------- -This displays Livepatch-related information. Currently, the only information -presented is **`fixed_cves`**. This represents a list of CVEs that were fixed -by Livepatches applied to the kernel. +``u.pro.status.is_attached.v1`` +-------------------------------- + +This API is responsible for telling if the system is attached to a Pro subscription + +When called through ``pro api u.pro.status.is_attached.v1``, it will produce a data output +with the following structure: + +.. code-block:: js + + { + "contract_remaining_days": 360, + "contract_status": "active", + "is_attached": true, + "is_attached_and_contract_valid": true + } + +The JSON response object will contain the following fields: + +* **contract_remaining_days**: The number of days left in the Ubuntu Pro subscription +* **contract_status**: The status of the Ubuntu Pro subscription: + + * **active**: The contract is currently valid. + * **grace-period**: The contract is in the grace period. This means that + it is expired, but there are still some days where the contract will be + valid. + * **active-soon-to-expire**: The contract is almost expired, but still + valid. + * **expired**: The contract is expired and no longer valid. + +* **is_attached**: true if the machine is attached to an Ubuntu Pro subscription +* **is_attached_and_contract_valid**: true if the machine is attached to an Ubuntu + Pro subscription and that subscription is not expired + +``u.pro.status.enabled_services.v1`` +------------------------------------- + +This API is responsible for telling which services are enabled in the machine. + +When called through ``pro api u.pro.status.enabled_services.v1``, it will produce a data output +with the following structure: + +.. code-block:: js + + { + "enabled_services": [ + { + "name": "esm-apps", + "variant_enabled": false, + "variant_name": null + }, + { + "name": "esm-infra", + "variant_enabled": false, + "variant_name": null + }, + { + "name": "realtime-kernel", + "variant_enabled": true, + "variant_name": "raspi" + } + ] + } + +You can see that the JSON response has an object named **enabled_services** that is a list +of services that are enabled in the machine. Each enabled service has these attributes: + +* **name**: The name of the service. +* **variant_enabled**: true if a variant of the service was enable. +* **variant_name**: The variant name if **variant_enabled** is true, **null** otherwise. + + +``u.pro.security.status.livepatch_cves.v1`` +-------------------------------------------- + +This endpoint lists Livepatch patches for the currently-running kernel. + +When called through ``pro api u.pro.security.status.livepatch_cves.v1``, it will +produce a data output with the following structure: + +.. code-block:: js + + { + "fixed_cves":[ + { + "name": "", + "patched": true + }, + { + "name": "", + "patched": false + }, + ] + } + +You can see that the JSON response has an object named **fixed_cves** that is a list +of CVEs that are addressed by the current Livepatch patch. Each CVE object will have the +following attributes: + +* **name**: The name of the CVE. +* **patched**: true if a CVE was patched by Livepatch patch, false otherwise. diff --git a/docs/explanations/status_columns.rst b/docs/explanations/status_columns.rst index 6c370d09e0..765d7d7e14 100644 --- a/docs/explanations/status_columns.rst +++ b/docs/explanations/status_columns.rst @@ -129,143 +129,7 @@ Some status information can be obtained from API functions. These include: * Which Ubuntu Pro services are currently enabled on the machine? See :ref:`u.pro.status.enabled_services.v1` -If you need status-related information for which there is no API function, then -``pro status --format=json`` (described below) is the recommended -machine-readable interface. - .. attention:: Let us know what status information you need that is missing from the API by clicking "Give feedback" at the top of this page. - -``pro status --format=json`` ----------------------------- - -The ``pro status`` command supports a ``--format`` flag with options including -``json`` and ``yaml``. These result in a machine-readable form of the -information presented by the ``pro status`` command. - -.. note:: - - ``pro status`` should return the same results whether using ``sudo`` or - not, but earlier versions did not always do this. We recommend using - ``sudo`` whenever possible. - -For example, running ``sudo pro status --format=json`` on an attached machine -may give you something like this: - -.. code-block:: javascript - - { - "_doc": "Content provided in json response is currently considered Experimental and may change", - "_schema_version": "0.1", - "account": { - "created_at": "2000-01-02T03:04:05+06:00", - "id": "account_id", - "name": "Test" - }, - "attached": true, - "config": { ...effectiveConfiguration }, - "config_path": "/etc/ubuntu-advantage/uaclient.conf", - "contract": { - "created_at": "2000-01-02T03:04:05+06:00", - "id": "contract_id", - "name": "contract_name", - "products": [ "uaa-essential" ], - "tech_support_level": "essential" - }, - "effective": null, - "environment_vars": [...proClientEnvironmentVariables], - "errors": [], - "execution_details": "No Ubuntu Pro operations are running", - "execution_status": "inactive", - "expires": "9999-12-31T00:00:00+00:00", - "features": {}, - "machine_id": "machine_id", - "notices": [], - "result": "success", - "services": [ - { - "available": "yes", - "blocked_by": [], - "description": "Expanded Security Maintenance for Applications", - "description_override": null, - "entitled": "yes", - "name": "esm-apps", - "status": "enabled", - "status_details": "Ubuntu Pro: ESM Apps is active", - "warning": null - }, - { - "available": "yes", - "blocked_by": [], - "description": "Expanded Security Maintenance for Infrastructure", - "description_override": null, - "entitled": "yes", - "name": "esm-infra", - "status": "enabled", - "status_details": "Ubuntu Pro: ESM Infra is active", - "warning": null - }, - { - "available": "yes", - "blocked_by": [], - "description": "Canonical Livepatch service", - "description_override": null, - "entitled": "yes", - "name": "livepatch", - "status": "enabled", - "status_details": "", - "warning": null - }, - ...otherServiceStatusObjects - ], - "simulated": false, - "version": "27.13.6~18.04.1", - "warnings": [] - } - -Some particularly important attributes in the output include: - -* ``attached``: This boolean value indicates whether this machine is attached - to an Ubuntu Pro account. Starting with version 28.1, we recommend using the - :ref:`u.pro.status.is_attached.v1` - API instead. This does not tell you if any particular service (e.g. - ``esm-infra``) is enabled. You must check the individual service item in the - ``services`` list for that status (described below). -* ``expires``: This is the date that the Ubuntu Pro subscription is valid until - (in RFC3339 format). After this date has passed the machine should be treated - as if unattached and with no services enabled. ``attached`` may still say - ``true`` and services may still say they are ``entitled`` and ``enabled``, - but if the ``expires`` date has passed, you should assume the services are - not functioning. -* ``services``: This is a list of Ubuntu Pro services. Starting with version - 28.1, if you are looking for enabled services, we recommend using the - :ref:`u.pro.status.enabled_services.v1` - API instead. Each item has its own attributes. Widely applicable services - include those with ``name`` equal to ``esm-infra``, ``esm-apps``, and - ``livepatch``. Some important fields in each service object are: - - * ``name``: The name of the service. - * ``entitled``: A boolean indicating whether the attached Ubuntu Pro account - is allowed to enable this service. - * ``status``: A string indicating the service's current status on the machine. - Any value other than ``enabled`` should be treated as if the service is not - enabled and not working properly on the machine. Possible values are: - - * ``enabled``: The service is enabled and working. - * ``disabled``: The service can be enabled but is not currently. - * ``n/a``: The service cannot be enabled on this machine. - * ``warning``: The service is supposed to be enabled but something is - wrong. Check the ``warning`` field in the service item for additional - information. - -For example, if you want to programmatically find the status of ``esm-infra`` -on a particular machine, you can use the following command: - -.. code-block:: bash - - sudo pro status --format=json | jq '.services[] | select(.name == "esm-infra").status' - -This command will print one of the ``status`` values defined above. -