path: root/doc/rtd/topics/cli.rst

.. _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: 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
  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
    _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 <v#> 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_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``: 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]

.. _More details on machine-id: https://www.freedesktop.org/software/systemd/man/machine-id.html