From 48f5e9af9e3511e957a8862ce00c61d33a394636 Mon Sep 17 00:00:00 2001 From: Renan Rodrigo Date: Tue, 27 Aug 2024 01:32:19 -0300 Subject: [PATCH] docs: automatically generate the command entries for the manpage Add a template for the manpage with a placeholder for the commands, and make the clidocgen script fill it. Signed-off-by: Renan Rodrigo --- tools/clidocgen.py | 27 +++- ubuntu-advantage.1 | 179 +++++++++++-------------- ubuntu-advantage.1.template | 255 ++++++++++++++++++++++++++++++++++++ 3 files changed, 352 insertions(+), 109 deletions(-) mode change 100644 => 100755 tools/clidocgen.py create mode 100644 ubuntu-advantage.1.template diff --git a/tools/clidocgen.py b/tools/clidocgen.py old mode 100644 new mode 100755 index 948255c351..74697a6287 --- a/tools/clidocgen.py +++ b/tools/clidocgen.py @@ -1,5 +1,6 @@ +#!/usr/bin/python3 """ -Generate RST documentation for an ubuntu-pro-client cli commands. +Generate documentation for an ubuntu-pro-client cli commands. """ import sys @@ -9,6 +10,8 @@ from uaclient.cli import COMMANDS, get_parser from uaclient.cli.commands import ProCommand +VALID_TARGETS = ["manpage"] + MANPAGE_TEMPLATE = """\ .TP .BR "{name}" " {usage_options}" @@ -32,12 +35,24 @@ def _build_manpage_entry(command: ProCommand) -> str: ) -if __name__ == "__main__": - # get a parser so we register all the commands - _parser = get_parser() - +def _generate_manpage_section(): result = "" for command in COMMANDS: result += _build_manpage_entry(command) - print(result) + with open("./ubuntu-advantage.1.template", "r") as f: + template = f.read() + content = template.replace("<>", result) + with open("./ubuntu-advantage.1", "w") as f: + f.write(content) + + +if __name__ == "__main__": + # get a parser so we register all the commands + _parser = get_parser() + if len(sys.argv) > 1: + if sys.argv[1] == "manpage": + _generate_manpage_section() + sys.exit() + + raise ValueError("call the script with one of: " + " ".join(VALID_TARGETS)) diff --git a/ubuntu-advantage.1 b/ubuntu-advantage.1 index c5aa4fc733..0182eb1707 100644 --- a/ubuntu-advantage.1 +++ b/ubuntu-advantage.1 @@ -33,130 +33,108 @@ Show the Pro Client version and exit. .SH COMMANDS .TP -.BR "api" " " +.BR "api" " [-h] [--show-progress] [--args [OPTIONS ...]] [--data DATA] endpoint" 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: +please refer to the Pro Client API reference guide: https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/ .TP -.BR "attach" " [--no-auto-enable] [--attach-config=/path/to/file.yaml] " -Connect an Ubuntu Pro support contract to this machine. +.BR "attach" " [-h] [--no-auto-enable] [--attach-config ATTACH_CONFIG] [--format {cli,json}] [token]" +Attach this machine to an Ubuntu Pro subscription with a token obtained from: +https://ubuntu.com/pro/dashboard -The \fI--attach-config\fR option can be used to provide a file with the token -and optionally, a list of services to enable after attaching. The \fItoken\fR -parameter should not be used if this option is provided. An attach config file -looks like the following: - token: YOUR_TOKEN_HERE # required - enable_services: # optional list of service names to auto-enable - - esm-infra - - esm-apps - - cis +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. -The optional \fI--no-auto-enable\fR flag will disable the automatic -enablement of recommended entitlements which usually happens immediately -after a successful attach. +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 can be: +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 .TP -.B collect-logs [-o | --output ] -Create a tarball with all relevant logs and debug data. - -The \fI--output\fR parameter defines the path to the tarball. If not -provided, the file is saved as \fBpro_logs.tar.gz\fP in the current -directory. +.BR "auto-attach" " [-h]" +Automatically attach on an Ubuntu Pro cloud instance. .TP -.BR "config set/unset" " " - -Set/unset one of the available Pro configuration settings. +.BR "collect-logs" " [-h] [-o OUTPUT]" +Collect logs and relevant system information into a tarball. +This information can be later used for triaging/debugging issues. .TP -.BR "config show" " " -Show customizable configuration settings - -If no config is provided, this command will display all of the Pro configuration values +.BR "config" " [-h] {show,set,unset} ..." +Manage Ubuntu Pro Client configuration on this machine .TP -.B detach -Remove the Ubuntu Pro support contract from this machine. +.BR "detach" " [-h] [--assume-yes] [--format {cli,json}]" +Detach this machine from an Ubuntu Pro subscription. .TP -.BR "disable" " [anbox-cloud|cc-eal|cis|esm-apps|esm-infra|fips|fips-updates|" - landscape|livepatch|realtime-kernel|ros|ros-updates] - -Disable this machine's access to an Ubuntu Pro service. +.BR "disable" " [-h] [--assume-yes] [--format {cli,json}] [--purge] service [service ...]" +Disable an Ubuntu Pro service. .TP -.BR "enable" " [anbox-cloud|cc-eal|cis|esm-apps|esm-infra|fips|fips-updates|" -landscape|livepatch|realtime-kernel|ros|ros-updates] - -Activate and configure this machine's access to an Ubuntu Pro -service. +.BR "enable" " [-h] [--assume-yes] [--access-only] [--beta] [--format {cli,json}] [--variant VARIANT] service [service ...]" +Activate and configure this machine's access to an Ubuntu Pro service. .TP -.BR "fix" "[--dry-run] [--no-related] " -Fix a CVE or USN on the system by upgrading the appropriate package(s). - -The optional \fI--dry-run\fR flag will display everything that would be executed by the fix command -without actually making any changes. +.BR "fix" " [-h] [--dry-run] [--no-related] security_issue" +Inspect and resolve Common Vulnerabilities and Exposures (CVEs) and +Ubuntu Security Notices (USNs) on this machine. -The optional \fI--no-related\fR flag will modify how the fix command behaves when handling a USN. -With this flag, the command will not attempt to fix any USNs related to the target USN. - - can be any of the following formats: CVE-yyyy-nnnn, -CVE-yyyy-nnnnnnn, or USN-nnnn-dd. - -The exit code can be 0, 1, or 2. - 0: the fix was successfully applied or the security issue doesn't affect the system +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 .TP -.BR "refresh" " [contract|config|messages]" -Refresh three distinct Ubuntu Pro related artifacts in the system: +.BR "help" " [-h] [--format {tabular,json,yaml}] [--all] [service]" +Provide detailed information about Ubuntu Pro services. -.BR "contract" ":" -Update contract details from the server. - -.BR "config" ":" -Reload the config file. +.TP +.BR "refresh" " [-h] [{contract,config,messages}]" +Refresh three distinct Ubuntu Pro related artifacts in the system: -.BR "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` is specified, all targets are refreshed. +by passing the target name to the command. If no target +is specified, all targets are refreshed. -.TP -.B "security-status" " [--thirdparty | --unavailable | --esm-infra | --esm-apps]" +.TP +.BR "security-status" " [-h] [--format {json,yaml,text}] [--thirdparty | --unavailable | --esm-infra | --esm-apps]" Show security updates for packages in the system, including all available Expanded Security Maintenance (ESM) related content. Shows counts of how many packages are supported for security updates in the system. -The output contains basic information about Ubuntu Pro. For a -complete status on Ubuntu Pro services, run 'pro status'. - -The optional \fI--thirdparty\fR flag will only show information about third party packages +If called with --format json|yaml it shows a summary of the +installed packages based on the origin: -The optional \fI--unavailable\fR flag will only show information about unavailable packages + - 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 optional \fI--esm-infra\fR flag will only show information about esm-infra packages +The output contains basic information about Ubuntu Pro. For a +complete status on Ubuntu Pro services, run 'pro status'. -The optional \fI--esm-apps\fR flag will only show information about esm-apps packages .TP -.BR "status" " [--simulate-with-token TOKEN] [--all]" +.BR "status" " [-h] [--wait] [--format {tabular,json,yaml}] [--simulate-with-token TOKEN] [--all]" Report current status of Ubuntu Pro services on system. This shows whether this machine is attached to an Ubuntu Pro @@ -166,41 +144,36 @@ status of each service on this system. The attached status output has four columns: -.BR "SERVICE" ":" -name of the service - -.BR "ENTITLED" ":" -whether the contract to which this machine is attached entitles use of -this service. Possible values are: \fIyes\fR or \fIno\fR + * 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: -.BR "STATUS" ":" -whether the service is enabled on this machine. -Possible values are: \fIenabled\fR, \fIdisabled\fR, \fIn/a\fR (if your -contract entitles you to the service, but it isn't available for this -machine) or \fI—\fR (if you aren't entitled to this service) + * AVAILABLE: whether this service would be available if this machine + were attached. The possible values are yes or no. -.BR "DESCRIPTION" ":" -a brief description of the service +If --simulate-with-token is used, then the output has five +columns. SERVICE, AVAILABLE, ENTITLED and DESCRIPTION are the same +as mentioned above, and AUTO_ENABLED shows whether the service is set +to be enabled when that token is attached. -The unattached status output instead has three columns. \fBSERVICE\fR -and \fBDESCRIPTION\fR are the same as above, and there is the addition -of: +If the --all flag is set, beta and unavailable services are also +listed in the output. -.BR "AVAILABLE" ":" -whether this service would be available if this machine were attached. -The possible values are \fIyes\fR or \fIno\fR. -If --simulate-with-token is used, then the output has five columns. -\fBSERVICE\fR, \fBAVAILABLE\fR, \fBENTITLED\fR and \fBDESCRIPTION\fR are the -same as mentioned above, and \fBAUTO_ENABLED\fR shows whether the service is -set to be enabled when that token is attached. +.TP +.BR "system" " [-h] {reboot-required} ..." +Outputs system-related information about Pro services -If the \fI--all\fR flag is set, unavailable services are also listed in the -output. -.TP -.BR "system reboot-required" -Tells if the system needs to be rebooted .SH SERVICES diff --git a/ubuntu-advantage.1.template b/ubuntu-advantage.1.template new file mode 100644 index 0000000000..e08cf903ab --- /dev/null +++ b/ubuntu-advantage.1.template @@ -0,0 +1,255 @@ +.TH "UBUNTU-PRO" "1" "21 February 2020" "Canonical Ltd." "Ubuntu Pro" + + +.SH NAME +pro \- Manage Ubuntu Pro services from Canonical + + +.SH SYNOPSIS +.BR "pro" " [-h] [--debug] [--version] ..." + + +.SH DESCRIPTION +Ubuntu Pro is a collection of services offered by Canonical to +Ubuntu users. The Ubuntu Pro command line tool is used to attach +a system to an Ubuntu Pro contract to then enable and disable +services from Canonical. The available commands and services are +described in more detail below. + + +.SH OPTIONS +.TP +.BR "-h, --help" +Show help for pro or for the specified pro command. + +.TP +.BR "--debug" +Redirect all the debugging logs to the console. + +.TP +.BR "--version" +Show the Pro Client version and exit. + + +.SH COMMANDS +<> + + +.SH SERVICES +.TP +.B "Anbox Cloud (anbox-cloud)" +Anbox Cloud lets you stream mobile apps securely, at any scale, to any device, +letting you focus on your apps. Run Android in system containers on public or +private clouds with ultra low streaming latency. When the anbox-cloud service +is enabled, by default, the Appliance variant is enabled. Enabling this service +allows orchestration to provision a PPA with the Anbox Cloud resources. This +step also configures the Anbox Management Service (AMS) with the necessary +image server credentials. + +To learn more about Anbox Cloud, see https://anbox-cloud.io + +.TP +.B "Common Criteria EAL2 Provisioning (cc-eal)" +Common Criteria is an Information Technology Security Evaluation standard +(ISO/IEC IS 15408) for computer security certification. Ubuntu 16.04 has been +evaluated to assurance level EAL2 through CSEC. The evaluation was performed +on Intel x86_64, IBM Power8 and IBM Z hardware platforms. + +.TP +.B "CIS Audit (cis)/Ubuntu Security Guide (usg)" +Ubuntu Security Guide is a tool for hardening and auditing, allowing for +environment-specific customizations. It enables compliance with profiles such +as DISA-STIG and the CIS benchmarks. + +Find out more at https://ubuntu.com/security/certifications/docs/usg + +.TP +.B "Expanded Security Maintenance for Infrastructure (esm-infra)" +Expanded Security Maintenance for Infrastructure provides access to a private +PPA which includes available high and critical CVE fixes for Ubuntu LTS +packages in the Ubuntu Main repository between the end of the standard Ubuntu +LTS security maintenance and its end of life. It is enabled by default with +Ubuntu Pro. + +You can find out more about the service at https://ubuntu.com/security/esm + +.TP +.B "Expanded Security Maintenance for Applications (esm-apps)" +Expanded Security Maintenance for Applications is enabled by default on +entitled workloads. It provides access to a private PPA which includes +available high and critical CVE fixes for Ubuntu LTS packages in the Ubuntu +Main and Ubuntu Universe repositories from the Ubuntu LTS release date until +its end of life. + +You can find out more about the esm service at https://ubuntu.com/security/esm + +.TP +.B "FIPS 140-2 certified modules (fips)" +Installs FIPS 140 crypto packages for FedRAMP, FISMA and compliance use cases. +Note that "fips" does not provide security patching. For FIPS certified +modules with security patches please see "fips-updates". If you are unsure, +choose "fips-updates" for maximum security. + +Find out more at https://ubuntu.com/security/fips + + +.TP +.B "FIPS 140-2 certified modules with updates (fips-updates)" +fips-updates installs FIPS 140 crypto packages including all security patches +for those modules that have been provided since their certification date. + +You can find out more at https://ubuntu.com/security/fips + +.TP +.B "Landscape (landscape)" +Landscape Client can be installed on this machine and enrolled in Canonical's +Landscape SaaS: https://landscape.canonical.com or a self-hosted Landscape: +https://ubuntu.com/landscape/install + +Landscape allows you to manage many machines as easily as one, with an +intuitive dashboard and API interface for automation, hardening, auditing, and +more. + +Find out more about Landscape at https://ubuntu.com/landscape + +.TP +.B "Livepatch Service (livepatch)" +Livepatch provides selected high and critical kernel CVE fixes and other +non-security bug fixes as kernel livepatches. Livepatches are applied without +rebooting a machine which drastically limits the need for unscheduled system +reboots. Due to the nature of fips compliance, livepatches cannot be enabled +on fips-enabled systems. + +You can find out more about Ubuntu Kernel Livepatch service at https://ubuntu.com/security/livepatch + +.TP +.B "ROS ESM Security Updates (ros)" +ros provides access to a private PPA which includes security-related updates +for available high and critical CVE fixes for Robot Operating System (ROS) +packages. For access to ROS ESM and security updates, both esm-infra and +esm-apps services will also be enabled. To get additional non-security updates, +enable ros-updates. + +You can find out more about the ROS ESM service at https://ubuntu.com/robotics/ros-esm + + +.TP +.B "ROS ESM All Updates (ros-updates)" +ros-updates provides access to a private PPA that includes non-security-related +updates for Robot Operating System (ROS) packages. For full access to ROS ESM, +security and non-security updates, the esm-infra, esm-apps, and ros services +will also be enabled. + +You can find out more about the ROS ESM service at https://ubuntu.com/robotics/ros-esm + + +.SH CONFIGURATION SETTINGS +.TP +.BR "http_proxy" +If set, pro will use the specified http proxy when making any http requests + +.TP +.BR "https_proxy" +If set, pro will use the specified https proxy when making any https requests + +.TP +.BR "apt_http_proxy" " [DEPRECATED]" +If set, pro will configure apt to use the specified http proxy by writing a apt +config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. (Please use \fBglobal_apt_http_proxy\fP) + +.TP +.BR "apt_https_proxy" " [DEPRECATED]" +If set, pro will configure apt to use the specified https proxy by writing a apt +config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. (Please use \fBglobal_apt_https_proxy\fP) + +.TP +.BR "global_apt_http_proxy" +If set, pro will configure apt to use the specified http proxy by writing a apt +config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. Set this if you +prefer a global proxy for all resources, not just the ones from \fIesm.ubuntu.com\fB + +.TP +.BR "global_apt_https_proxy" +If set, pro will configure apt to use the specified https proxy by writing a apt +config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. Set this if you +prefer a global proxy for all resources, not just the ones from \fIesm.ubuntu.com\fB + +.TP +.BR "ua_apt_http_proxy" +If set, pro will configure apt to use the specified http proxy by writing a apt +config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. This proxy is limited +to accessing resources from \fIesm.ubuntu.com\fB + +.TP +.BR "ua_apt_https_proxy" +If set, pro will configure apt to use the specified https proxy by writing a apt +config file to /etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy. This proxy is limited +to accessing resources from \fIesm.ubuntu.com\fB + +.TP +.BR "_timer" +Sets the timer running interval for a specific job. Those intervals are checked +every time the systemd timer runs. + +.TP +.BR "apt_news" +If set to false, the Pro client will no longer display apt news messages on the output +of apt upgrade. + +.TP +.BR "apt_news_url" +Sets the url where the Pro client will consume apt news information from. + +.P +If needed, authentication to the proxy server can be performed by setting +username and password in the URL itself, as in: +.nf +.fam C + http_proxy: http://:@: +.fam T +.fi + + +.SH PRO UPGRADE DAEMON +Ubuntu Pro client sets up a daemon on supported platforms (currently on Azure and GCP) to +detect if an Ubuntu Pro license is purchased for the machine. If an Ubuntu Pro license +is detected, then the machine is automatically attached. +If you are uninterested in Ubuntu Pro services, you can safely stop and disable the +daemon using systemctl: + +sudo systemctl stop ubuntu-advantage.service +sudo systemctl disable ubuntu-advantage.service + +.SH TIMER JOBS +Ubuntu Pro client sets up a systemd timer to run jobs that need to be executed +recurrently. The timer itself ticks every 5 minutes on average, and decides +which jobs need to be executed based on their intervals. + +Jobs are executed by the timer script if the script has not yet run +successfully, or their interval since last successful run is already exceeded. +There is a random delay applied to the timer, to desynchronize job execution +time on machines spinned at the same time, avoiding multiple synchronized +calls to the same service. + +Current jobs being checked and executed are: +.TP +.B +\fBupdate_messaging\fP +Makes sure that the MOTD and APT messages match the available/enabled services +on the system, showing information about available packages or security +updates. + +.TP +.B +\fBmetering\fP +If attached, this job will ping the Canonical servers telling +which services are enabled on the machine. + + +.SH REPORTING BUGS +Please report bugs either by running `ubuntu-bug ubuntu-advantage-tools` or +login to Launchpad and navigate to +https://bugs.launchpad.net/ubuntu/+source/ubuntu-advantage-tools/+filebug + +.SH COPYRIGHT +Copyright (C) 2019-2020 Canonical Ltd.