.. _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 usage: /usr/bin/cloud-init [-h] [--version] [--file FILES] [--debug] [--force] {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} ... optional arguments: -h, --help show this help message and exit --version, -v show program's version number and exit --file FILES, -f FILES additional yaml configuration files to use --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} init initializes cloud-init and performs initial modules modules activates 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. 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 .. _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: * ``schema``: a **#cloud-config** format and schema validator. It accepts a cloud-config yaml file and annotates potential schema errors locally without the need for deployment. Schema validation is work in progress and supports a subset of cloud-config modules. * ``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. .. _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 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_init_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 * **: 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 _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 Below demonstrates how to query standardized metadata from clouds: .. code-block:: shell-session % cloud-init query v1.cloud_name aws # or openstack, azure, gce etc. # Any standardized instance-data under a key is aliased as a top-level key for convenience. % cloud-init query cloud_name aws # or openstack, azure, gce etc. # Query datasource-specific metadata on EC2 % 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: .. code-block:: shell-session # Generate a custom hostname fqdn based on instance-id, cloud and region % cloud-init query --format 'custom-{{instance_id}}.{{region}}.{{v1.cloud_name}}.com' custom-i-0e91f69987f37ec74.us-east-2.aws.com .. _cli_single: single ====== Attempt to run a single named cloud config module. * *\\-\\-name*: the cloud-config module name to run * *\\-\\-frequency*: optionally override the declared module frequency with one of (always|once-per-instance|once) 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 Below are examples of output when cloud-init is running, showing status and the currently running modules, as well as when it is done. .. code-block:: shell-session $ cloud-init status status: running $ cloud-init status --long status: running time: Fri, 26 Jan 2018 21:39:43 +0000 detail: Running in stage: init-local $ cloud-init status status: done $ cloud-init status --long status: done time: Wed, 17 Jan 2018 20:41:59 +0000 detail: DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net] .. vi: textwidth=79