diff --git a/features/cli/help.feature b/features/cli/help.feature index b9db99bf30..9e11772b1f 100644 --- a/features/cli/help.feature +++ b/features/cli/help.feature @@ -39,6 +39,7 @@ Feature: Pro Client help text usage: pro collect-logs [-h] [-o OUTPUT] Collect logs and relevant system information into a tarball. + This information can be later used for triaging/debugging issues. : -h, --help show this help message and exit @@ -54,6 +55,11 @@ Feature: Pro Client help text Calls the Client API endpoints. + For a list of all of the supported endpoints and their structure, + please refer to the Pro Client API reference guide: + + https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/ + positional arguments: endpoint API endpoint to call @@ -94,7 +100,7 @@ Feature: Pro Client help text [--format {cli,json}] [--variant VARIANT] service [service ...] - Enable an Ubuntu Pro service. + Activate and configure this machine's access to an Ubuntu Pro service. positional arguments: service the name(s) of the Ubuntu Pro services to enable. One @@ -127,6 +133,16 @@ Feature: Pro Client help text and prompt you to attach the machine to your Ubuntu Pro account using a web browser. + The --attach-config option can be used to provide a file with the token + and optionally, a list of services to enable after attaching. To know more, + visit: + https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/how_to_attach_with_config_file/ + + The exit code will be: + 0: on successful attach + 1: in case of any error while trying to attach + 2: if the machine is already attached + positional arguments: token token obtained for Ubuntu Pro authentication @@ -175,11 +191,12 @@ Feature: Pro Client help text If called with --format json|yaml it shows a summary of the installed packages based on the origin: - - main/restricted/universe/multiverse: packages from the Ubuntu archive - - esm-infra/esm-apps: packages from the ESM archive - - third-party: packages installed from non-Ubuntu sources - - unknown: packages which don't have an installation source (like local - deb packages or packages for which the source was removed) + + - main/restricted/universe/multiverse: packages from the Ubuntu archive + - esm-infra/esm-apps: packages from the ESM archive + - third-party: packages installed from non-Ubuntu sources + - unknown: packages which don't have an installation source (like local + deb packages or packages for which the source was removed) The output contains basic information about Ubuntu Pro. For a complete status on Ubuntu Pro services, run 'pro status'. @@ -200,7 +217,13 @@ Feature: Pro Client help text """ usage: pro fix [-h] [--dry-run] [--no-related] security_issue - Inspect and resolve CVEs and USNs (Ubuntu Security Notices) on this machine. + Inspect and resolve Common Vulnerabilities and Exposures (CVEs) and + Ubuntu Security Notices (USNs) on this machine. + + The exit code will be: + 0: the fix was successfully applied or the system is not affected + 1: the fix cannot be applied + 2: the fix was applied but requires a reboot before it takes effect positional arguments: security_issue Security vulnerability ID to inspect and resolve on this @@ -223,28 +246,28 @@ Feature: Pro Client help text Report current status of Ubuntu Pro services on system. - This shows whether this machine is attached to an Ubuntu Advantage + This shows whether this machine is attached to an Ubuntu Pro support contract. When attached, the report includes the specific support contract details including contract name, expiry dates, and the status of each service on this system. The attached status output has four columns: - * SERVICE: name of the service - * ENTITLED: whether the contract to which this machine is attached - entitles use of this service. Possible values are: yes or no - * STATUS: whether the service is enabled on this machine. Possible - values are: enabled, disabled, n/a (if your contract entitles - you to the service, but it isn't available for this machine) or — (if - you aren't entitled to this service) - * DESCRIPTION: a brief description of the service + * SERVICE: name of the service + * ENTITLED: whether the contract to which this machine is attached + entitles use of this service. Possible values are: yes or no + * STATUS: whether the service is enabled on this machine. Possible + values are: enabled, disabled, n/a (if your contract entitles + you to the service, but it isn't available for this machine) or — (if + you aren't entitled to this service) + * DESCRIPTION: a brief description of the service The unattached status output instead has three columns. SERVICE and DESCRIPTION are the same as above, and there is the addition of: - * AVAILABLE: whether this service would be available if this machine - were attached. The possible values are yes or no. + * AVAILABLE: whether this service would be available if this machine + were attached. The possible values are yes or no. If --simulate-with-token is used, then the output has five columns. SERVICE, AVAILABLE, ENTITLED and DESCRIPTION are the same @@ -270,12 +293,12 @@ Feature: Pro Client help text Refresh three distinct Ubuntu Pro related artifacts in the system: - * contract: Update contract details from the server. - * config: Reload the config file. - * messages: Update APT and MOTD messages related to UA. + * contract: Update contract details from the server. + * config: Reload the config file. + * messages: Update APT and MOTD messages related to Pro. You can individually target any of the three specific actions, - by passing the target name to the command. If no `target` + by passing the target name to the command. If no target is specified, all targets are refreshed. positional arguments: @@ -290,7 +313,7 @@ Feature: Pro Client help text """ usage: pro system [-h] {reboot-required} ... - Output system related information related to Pro services + Outputs system-related information about Pro services : -h, --help show this help message and exit @@ -309,13 +332,13 @@ Feature: Pro Client help text This command will output one of the three following states for the machine regarding reboot: - * no: The machine doesn't require a reboot - * yes: The machine requires a reboot - * yes-kernel-livepatches-applied: There are only kernel related - packages that require a reboot, but Livepatch has already provided - patches for the current running kernel. The machine still needs a - reboot, but you can assess if the reboot can be performed in the - nearest maintenance window. + * no: The machine doesn't require a reboot + * yes: The machine requires a reboot + * yes-kernel-livepatches-applied: There are only kernel-related + packages that require a reboot, but Livepatch has already provided + patches for the current running kernel. The machine still needs a + reboot, but you can assess if the reboot can be performed in the + nearest maintenance window. : -h, --help show this help message and exit @@ -325,7 +348,7 @@ Feature: Pro Client help text """ usage: pro config [-h] {show,set,unset} ... - Manage Ubuntu Pro configuration + Manage Ubuntu Pro Client configuration on this machine : -h, --help show this help message and exit @@ -334,7 +357,8 @@ Feature: Pro Client help text {show,set,unset} show Show customizable configuration settings set Set and apply Ubuntu Pro configuration settings - unset Unset Ubuntu Pro configuration setting + unset Unset an Ubuntu Pro configuration setting, restoring the + default value. """ When I run `pro config show --help` as non-root Then I will see the following on stdout @@ -372,7 +396,7 @@ Feature: Pro Client help text """ usage: pro config unset [-h] key - Unset Ubuntu Pro configuration setting + Unset an Ubuntu Pro configuration setting, restoring the default value. positional arguments: key configuration key to unset from Ubuntu Pro services. One of: diff --git a/uaclient/cli/api.py b/uaclient/cli/api.py index 54a0f21b16..ee1b8a42af 100644 --- a/uaclient/cli/api.py +++ b/uaclient/cli/api.py @@ -51,6 +51,7 @@ def action_api(args, *, cfg, **kwargs): help=messages.CLI_ROOT_API, description=messages.CLI_API_DESC, action=action_api, + preserve_description=True, argument_groups=[ ProArgumentGroup( arguments=[ diff --git a/uaclient/cli/collect_logs.py b/uaclient/cli/collect_logs.py index dcbc5c077e..dbe4eaa49c 100644 --- a/uaclient/cli/collect_logs.py +++ b/uaclient/cli/collect_logs.py @@ -28,6 +28,7 @@ def action_collect_logs(args, *, cfg, **kwargs): "collect-logs", help=messages.CLI_ROOT_COLLECT_LOGS, description=messages.CLI_COLLECT_LOGS_DESC, + preserve_description=True, action=action_collect_logs, argument_groups=[ ProArgumentGroup( diff --git a/uaclient/cli/fix.py b/uaclient/cli/fix.py index 3b2773a029..472ecc1011 100644 --- a/uaclient/cli/fix.py +++ b/uaclient/cli/fix.py @@ -915,6 +915,7 @@ def action_fix(args, *, cfg, **kwargs): help=messages.CLI_ROOT_FIX, description=messages.CLI_FIX_DESC, action=action_fix, + preserve_description=True, argument_groups=[ ProArgumentGroup( arguments=[ diff --git a/uaclient/messages/__init__.py b/uaclient/messages/__init__.py index 043def88f3..2ec766046f 100644 --- a/uaclient/messages/__init__.py +++ b/uaclient/messages/__init__.py @@ -896,7 +896,15 @@ class TxtColor: "do not prompt for confirmation before performing the {command}" ) -CLI_API_DESC = t.gettext("Calls the Client API endpoints.") +CLI_API_DESC = t.gettext( + """\ +Calls the Client API endpoints. + +For a list of all of the supported endpoints and their structure, +please refer to the Pro Client API reference guide: + +{url}""" +).format(url=urls.PRO_CLIENT_DOCS_API_REFERENCE) CLI_API_ENDPOINT = t.gettext("API endpoint to call") CLI_API_SHOW_PROGRESS = t.gettext( "For endpoints that support progress updates, show each progress update " @@ -912,7 +920,9 @@ class TxtColor: ) CLI_COLLECT_LOGS_DESC = t.gettext( - "Collect logs and relevant system information into a tarball." + """\ +Collect logs and relevant system information into a tarball. +This information can be later used for triaging/debugging issues.""" ) CLI_COLLECT_LOGS_OUTPUT = t.gettext( "tarball where the logs will be stored. (Defaults to " "./pro_logs.tar.gz)" @@ -929,11 +939,15 @@ class TxtColor: "key=value pair to configure for Ubuntu Pro services." " Key must be one of: {options}" ) -CLI_CONFIG_UNSET_DESC = t.gettext("Unset Ubuntu Pro configuration setting") +CLI_CONFIG_UNSET_DESC = t.gettext( + "Unset an Ubuntu Pro configuration setting, restoring the default value." +) CLI_CONFIG_UNSET_KEY = t.gettext( "configuration key to unset from Ubuntu Pro services. One of: {options}" ) -CLI_CONFIG_DESC = t.gettext("Manage Ubuntu Pro configuration") +CLI_CONFIG_DESC = t.gettext( + "Manage Ubuntu Pro Client configuration on this machine" +) CLI_ATTACH_DESC = t.gettext( """\ @@ -942,8 +956,19 @@ class TxtColor: When running this command without a token, it will generate a short code and prompt you to attach the machine to your Ubuntu Pro account using -a web browser.""" +a web browser. + +The --attach-config option can be used to provide a file with the token +and optionally, a list of services to enable after attaching. To know more, +visit: +https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/how_to_attach_with_config_file/ + +The exit code will be: + 0: on successful attach + 1: in case of any error while trying to attach + 2: if the machine is already attached""" ).format(url=urls.PRO_DASHBOARD) + CLI_ATTACH_TOKEN = t.gettext("token obtained for Ubuntu Pro authentication") CLI_ATTACH_NO_AUTO_ENABLE = t.gettext( "do not enable any recommended services automatically" @@ -954,8 +979,14 @@ class TxtColor: ) CLI_FIX_DESC = t.gettext( - "Inspect and resolve CVEs and USNs (Ubuntu Security Notices) on this" - " machine." + """\ +Inspect and resolve Common Vulnerabilities and Exposures (CVEs) and +Ubuntu Security Notices (USNs) on this machine. + +The exit code will be: + 0: the fix was successfully applied or the system is not affected + 1: the fix cannot be applied + 2: the fix was applied but requires a reboot before it takes effect""" ) CLI_FIX_ISSUE = t.gettext( "Security vulnerability ID to inspect and resolve on this system." @@ -991,11 +1022,12 @@ class TxtColor: If called with --format json|yaml it shows a summary of the installed packages based on the origin: -- main/restricted/universe/multiverse: packages from the Ubuntu archive -- esm-infra/esm-apps: packages from the ESM archive -- third-party: packages installed from non-Ubuntu sources -- unknown: packages which don't have an installation source (like local - deb packages or packages for which the source was removed) + + - main/restricted/universe/multiverse: packages from the Ubuntu archive + - esm-infra/esm-apps: packages from the ESM archive + - third-party: packages installed from non-Ubuntu sources + - unknown: packages which don't have an installation source (like local + deb packages or packages for which the source was removed) The output contains basic information about Ubuntu Pro. For a complete status on Ubuntu Pro services, run 'pro status'. @@ -1018,12 +1050,12 @@ class TxtColor: """\ Refresh three distinct Ubuntu Pro related artifacts in the system: -* contract: Update contract details from the server. -* config: Reload the config file. -* messages: Update APT and MOTD messages related to UA. + * contract: Update contract details from the server. + * config: Reload the config file. + * messages: Update APT and MOTD messages related to Pro. You can individually target any of the three specific actions, -by passing the target name to the command. If no `target` +by passing the target name to the command. If no target is specified, all targets are refreshed. """ ) @@ -1041,7 +1073,9 @@ class TxtColor: ) CLI_HELP_ALL = t.gettext("Include beta services") -CLI_ENABLE_DESC = t.gettext("Enable an Ubuntu Pro service.") +CLI_ENABLE_DESC = t.gettext( + "Activate and configure this machine's access to an Ubuntu Pro service." +) CLI_ENABLE_SERVICE = t.gettext( "the name(s) of the Ubuntu Pro services to enable." " One of: {options}" ) @@ -1063,7 +1097,7 @@ class TxtColor: ) CLI_SYSTEM_DESC = t.gettext( - "Output system related information related to Pro services" + "Outputs system-related information about Pro services" ) CLI_SYSTEM_REBOOT_REQUIRED = t.gettext("does the system need to be rebooted") CLI_SYSTEM_REBOOT_REQUIRED_DESC = t.gettext( @@ -1073,13 +1107,13 @@ class TxtColor: This command will output one of the three following states for the machine regarding reboot: -* no: The machine doesn't require a reboot -* yes: The machine requires a reboot -* yes-kernel-livepatches-applied: There are only kernel related - packages that require a reboot, but Livepatch has already provided - patches for the current running kernel. The machine still needs a - reboot, but you can assess if the reboot can be performed in the - nearest maintenance window. + * no: The machine doesn't require a reboot + * yes: The machine requires a reboot + * yes-kernel-livepatches-applied: There are only kernel-related + packages that require a reboot, but Livepatch has already provided + patches for the current running kernel. The machine still needs a + reboot, but you can assess if the reboot can be performed in the + nearest maintenance window. """ ) @@ -1087,28 +1121,28 @@ class TxtColor: """\ Report current status of Ubuntu Pro services on system. -This shows whether this machine is attached to an Ubuntu Advantage +This shows whether this machine is attached to an Ubuntu Pro support contract. When attached, the report includes the specific support contract details including contract name, expiry dates, and the status of each service on this system. The attached status output has four columns: -* SERVICE: name of the service -* ENTITLED: whether the contract to which this machine is attached - entitles use of this service. Possible values are: yes or no -* STATUS: whether the service is enabled on this machine. Possible - values are: enabled, disabled, n/a (if your contract entitles - you to the service, but it isn't available for this machine) or — (if - you aren't entitled to this service) -* DESCRIPTION: a brief description of the service + * SERVICE: name of the service + * ENTITLED: whether the contract to which this machine is attached + entitles use of this service. Possible values are: yes or no + * STATUS: whether the service is enabled on this machine. Possible + values are: enabled, disabled, n/a (if your contract entitles + you to the service, but it isn't available for this machine) or — (if + you aren't entitled to this service) + * DESCRIPTION: a brief description of the service The unattached status output instead has three columns. SERVICE and DESCRIPTION are the same as above, and there is the addition of: -* AVAILABLE: whether this service would be available if this machine - were attached. The possible values are yes or no. + * AVAILABLE: whether this service would be available if this machine + were attached. The possible values are yes or no. If --simulate-with-token is used, then the output has five columns. SERVICE, AVAILABLE, ENTITLED and DESCRIPTION are the same diff --git a/uaclient/messages/urls.py b/uaclient/messages/urls.py index 245beb7cad..d712711291 100644 --- a/uaclient/messages/urls.py +++ b/uaclient/messages/urls.py @@ -11,6 +11,7 @@ PRO_CLIENT_DOCS_RELATED_USNS = "https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/cves_and_usns_explained.html#what-are-related-usns" # noqa: E501 PRO_CLIENT_DOCS_CLOUD_PRO_IMAGES = "https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/what_are_ubuntu_pro_cloud_instances.html" # noqa: E501 PRO_CLIENT_DOCS_PROXY_CONFIG = "https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/configure_proxies.html" # noqa: E501 +PRO_CLIENT_DOCS_API_REFERENCE = "https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/" # noqa: E501 # TODO: If/when `pro disable fips --purge` exists, reference that where # this URL is used