diff options
Diffstat (limited to 'doc/rtd/topics/cli.rst')
| -rw-r--r-- | doc/rtd/topics/cli.rst | 405 |
1 files changed, 0 insertions, 405 deletions
diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst deleted file mode 100644 index 463ac38c..00000000 --- a/doc/rtd/topics/cli.rst +++ /dev/null @@ -1,405 +0,0 @@ -.. _cli: - -CLI Interface -************* - -For the latest list of subcommands and arguments use cloud-init's ``--help`` -option. This can be used against cloud-init itself or any of its subcommands. - -.. code-block:: shell-session - - $ cloud-init --help - -Example output: - -.. code-block:: - - usage: cloud-init [-h] [--version] [--file FILES] [--debug] [--force] - {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status,schema} ... - - options: - -h, --help show this help message and exit - --version, -v Show program's version number and exit. - --file FILES, -f FILES - Use additional yaml configuration files. - --debug, -d Show additional pre-action logging (default: False). - --force Force running even if no datasource is found (use at your own risk). - - Subcommands: - {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status,schema} - init Initialize cloud-init and perform initial modules. - modules Activate modules using a given configuration key. - single Run a single module. - query Query standardized instance metadata from the command line. - dhclient-hook Run the dhclient hook to record network info. - features List defined features. - analyze Devel tool: Analyze cloud-init logs and data. - devel Run development tools. - collect-logs Collect and tar all cloud-init debug info. - clean Remove logs and artifacts so cloud-init can re-run. - status Report cloud-init status or wait on completion. - schema Validate cloud-config files using jsonschema. - - -The rest of this document will give an overview of each of the subcommands. - - -.. _cli_analyze: - -analyze -======= - -Get detailed reports of where cloud-init spends its time during the boot -process. For more complete reference see :ref:`analyze`. - -Possible subcommands include: - -* *blame*: report ordered by most costly operations -* *dump*: machine-readable JSON dump of all cloud-init tracked events -* *show*: show time-ordered report of the cost of operations during each - boot stage -* *boot*: show timestamps from kernel initialization, kernel finish - initialization, and cloud-init start - - -.. _cli_clean: - -clean -===== - -Remove cloud-init artifacts from ``/var/lib/cloud`` to simulate a clean -instance. On reboot, cloud-init will re-run all stages as it did on first boot. - -* ``--logs``: optionally remove all cloud-init log files in ``/var/log/`` -* ``--reboot``: reboot the system after removing artifacts -* ``--machine-id``: Remove ``/etc/machine-id`` on this image. Best practice - when cloning a golden image to ensure that the next boot of that image - auto-generates an unique machine ID. `More details on machine-id`_. - - -.. _cli_collect_logs: - -collect-logs -============ - -Collect and tar cloud-init generated logs, data files, and system -information for triage. This subcommand is integrated with apport. - -Logs collected include: - - * ``/var/log/cloud-init.log`` - * ``/var/log/cloud-init-output.log`` - * ``/run/cloud-init`` - * ``/var/lib/cloud/instance/user-data.txt`` - * cloud-init package version - * ``dmesg`` output - * journalctl output - -.. note:: - - Ubuntu users can file bugs with ``ubuntu-bug cloud-init`` to - automatically attach these logs to a bug report - - -.. _cli_devel: - -devel -===== - -Collection of development tools under active development. These tools will -likely be promoted to top-level subcommands when stable. - -Do **NOT** rely on the output of these commands as they can and will change. - -Current subcommands: - - * ``net-convert``: manually use cloud-init's network format conversion, useful - for testing configuration or testing changes to the network conversion logic - itself. - * ``render``: use cloud-init's jinja template render to - process **#cloud-config** or **custom-scripts**, injecting any variables - from ``/run/cloud-init/instance-data.json``. It accepts a user-data file - containing the jinja template header ``## template: jinja`` and renders - that content with any instance-data.json variables present. - * ``hotplug-hook``: respond to newly added system devices by retrieving - updated system metadata and bringing up/down the corresponding device. - This command is intended to be called via a systemd service and is - not considered user-accessible except for debugging purposes. - - -.. _cli_features: - -features -======== - -Print out each feature supported. If cloud-init does not have the -features subcommand, it also does not support any features described in -this document. - -.. code-block:: shell-session - - $ cloud-init features - -Example output: - -.. code-block:: - - NETWORK_CONFIG_V1 - NETWORK_CONFIG_V2 - - -.. _cli_init: - -init -==== - -Generally run by OS init systems to execute cloud-init's stages -*init* and *init-local*. See :ref:`boot_stages` for more info. -Can be run on the commandline, but is generally gated to run only once -due to semaphores in ``/var/lib/cloud/instance/sem/`` and -``/var/lib/cloud/sem``. - -* ``--local``: run *init-local* stage instead of *init* - - -.. _cli_modules: - -modules -======= - -Generally run by OS init systems to execute *modules:config* and -*modules:final* boot stages. This executes cloud config :ref:`modules` -configured to run in the init, config and final stages. The modules are -declared to run in various boot stages in the file -``/etc/cloud/cloud.cfg`` under keys: - -* *cloud_init_modules* -* *cloud_config_modules* -* *cloud_final_modules* - -Can be run on the command line, but each module is gated to run only once due -to semaphores in ``/var/lib/cloud/``. - -* ``--mode [init|config|final]``: run ``modules:init``, ``modules:config`` or - `modules:final` cloud-init stages. See :ref:`boot_stages` for more info. - - -.. _cli_query: - -query -===== - -Query standardized cloud instance metadata crawled by cloud-init and stored -in ``/run/cloud-init/instance-data.json``. This is a convenience command-line -interface to reference any cached configuration metadata that cloud-init -crawls when booting the instance. See :ref:`instance_metadata` for more info. - -* ``--all``: dump all available instance data as json which can be queried -* ``--instance-data``: optional path to a different instance-data.json file - to source for queries -* ``--list-keys``: list available query keys from cached instance data -* ``--format``: a string that will use jinja-template syntax to render a - string replacing -* ``<varname>``: a dot-delimited variable path into the instance-data.json - object - -Below demonstrates how to list all top-level query keys that are standardized -aliases: - -.. code-block:: shell-session - - $ cloud-init query --list-keys - -Example output: - -.. code-block:: - - _beta_keys - availability_zone - base64_encoded_keys - cloud_name - ds - instance_id - local_hostname - platform - public_ssh_keys - region - sensitive_keys - subplatform - userdata - v1 - vendordata - -Here are a few examples of how to query standardized metadata from clouds: - -.. code-block:: shell-session - - $ cloud-init query v1.cloud_name - -Example output: - -.. code-block:: - - aws # or openstack, azure, gce etc. - -Any standardized instance-data under a <v#> key is aliased as a top-level key -for convenience: - -.. code-block:: shell-session - - $ cloud-init query cloud_name - -Example output: - -.. code-block:: - - aws # or openstack, azure, gce etc. - -One can also query datasource-specific metadata on EC2, e.g.: - -.. code-block:: shell-session - - $ cloud-init query ds.meta_data.public_ipv4 - - -.. note:: - - The standardized instance data keys under **v#** are guaranteed not to change - behavior or format. If using top-level convenience aliases for any - standardized instance data keys, the most value (highest **v#**) of that key - name is what is reported as the top-level value. So these aliases act as a - 'latest'. - -This data can then be formatted to generate custom strings or data. For -example, we can generate a custom hostname fqdn based on instance-id, cloud and -region: - -.. code-block:: shell-session - - $ cloud-init query --format 'custom-{{instance_id}}.{{region}}.{{v1.cloud_name}}.com' - -.. code-block:: - - custom-i-0e91f69987f37ec74.us-east-2.aws.com - - -.. _cli_schema: - -schema -====== - -Validate cloud-config files using jsonschema. - -* ``-h, --help``: show this help message and exit -* ``-c CONFIG_FILE, --config-file CONFIG_FILE``: Path of the cloud-config yaml - file to validate -* ``--system``: Validate the system cloud-config userdata -* ``-d DOCS [DOCS ...], --docs DOCS [DOCS ...]``: Print schema module docs. - Choices: all or space-delimited cc_names. -* ``--annotate``: Annotate existing cloud-config file with errors - -The following example checks a config file and annotates the config file with -errors on stdout. - -.. code-block:: shell-session - - $ cloud-init schema -c ./config.yml --annotate - - -.. _cli_single: - -single -====== - -Attempt to run a single named cloud config module. - -* ``--name``: the cloud-config module name to run -* ``--frequency``: module frequency for this run. - One of (always|once-per-instance|once) -* ``--report``: enable reporting - -The following example re-runs the cc_set_hostname module ignoring the module -default frequency of once-per-instance: - -.. code-block:: shell-session - - $ cloud-init single --name set_hostname --frequency always - -.. note:: - - Mileage may vary trying to re-run each cloud-config module, as - some are not idempotent. - - -.. _cli_status: - -status -====== - -Report whether cloud-init is running, done, disabled or errored. Exits -non-zero if an error is detected in cloud-init. - -* ``--long``: detailed status information -* ``--wait``: block until cloud-init completes -* ``--format [yaml|json|tabular]``: machine-readable JSON or YAML detailed - output - -The ``status`` command can be used simply as follows: - -.. code-block:: shell-session - - $ cloud-init status - -Which shows whether cloud-init is currently running, done, disabled, or in -error, as in this example output: - -.. code-block:: - - status: running - -The ``--long`` option, shown below, provides a more verbose output. - -.. code-block:: shell-session - - $ cloud-init status --long - -Example output when cloud-init is running: - -.. code-block:: - - status: running - time: Fri, 26 Jan 2018 21:39:43 +0000 - detail: - Running in stage: init-local - -Example output when cloud-init is done: - -.. code-block:: - - status: done - boot_status_code: enabled-by-generator - last_update: Tue, 16 Aug 2022 19:12:58 +0000 - detail: - DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net] - -The detailed output can be shown in machine-readable JSON or YAML with the -``format`` option, for example: - -.. code-block:: shell-session - - $ cloud-init status --format=json - -Which would produce the following example output: - -.. code-block:: - - { - "boot_status_code": "enabled-by-generator", - "datasource": "nocloud", - "detail": "DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net]", - "errors": [], - "last_update": "Tue, 16 Aug 2022 19:12:58 +0000", - "status": "done" - } - -.. _More details on machine-id: https://www.freedesktop.org/software/systemd/man/machine-id.html |