diff options
Diffstat (limited to 'doc/source/cli/man')
| -rw-r--r-- | doc/source/cli/man/openstack.rst | 509 |
1 files changed, 509 insertions, 0 deletions
diff --git a/doc/source/cli/man/openstack.rst b/doc/source/cli/man/openstack.rst new file mode 100644 index 00000000..ab990979 --- /dev/null +++ b/doc/source/cli/man/openstack.rst @@ -0,0 +1,509 @@ +.. _manpage: + +==================== +:program:`openstack` +==================== + +OpenStack Command Line + + +SYNOPSIS +======== + +:program:`openstack` [<global-options>] <command> [<command-arguments>] + +:program:`openstack help` <command> + +:program:`openstack` :option:`--help` + + +DESCRIPTION +=========== + +:program:`openstack` provides a common command-line interface to OpenStack APIs. It is generally +equivalent to the CLIs provided by the OpenStack project client libraries, but with +a distinct and consistent command structure. + + +AUTHENTICATION METHODS +====================== + +:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with +the credential information supplied either as environment variables or as options on the +command line. The primary difference is the use of 'project' in the name of the options +``OS_PROJECT_NAME``/``OS_PROJECT_ID`` over the old tenant-based names. + +:: + + export OS_AUTH_URL=<url-to-openstack-identity> + export OS_PROJECT_NAME=<project-name> + export OS_USERNAME=<user-name> + export OS_PASSWORD=<password> # (optional) + +:program:`openstack` can use different types of authentication plugins provided by the keystoneclient library. The following default plugins are available: + +* ``token``: Authentication with a token +* ``password``: Authentication with a username and a password + +Refer to the keystoneclient library documentation for more details about these plugins and their options, and for a complete list of available plugins. +Please bear in mind that some plugins might not support all of the functionalities of :program:`openstack`; for example the v3unscopedsaml plugin can deliver only unscoped tokens, some commands might not be available through this authentication method. + +Additionally, it is possible to use Keystone's service token to authenticate, by setting the options :option:`--os-token` and :option:`--os-url` (or the environment variables :envvar:`OS_TOKEN` and :envvar:`OS_URL` respectively). This method takes precedence over authentication plugins. + +.. NOTE:: + To use the ``v3unscopedsaml`` method, the lxml package will need to be installed. + +OPTIONS +======= + +:program:`openstack` takes global options that control overall behaviour and command-specific options that control the command operation. Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived from the option name by dropping the leading dashes ('--'), converting each embedded dash ('-') to an underscore ('_'), and converting to upper case. + +:program:`openstack` recognizes the following global options: + +.. option:: --os-cloud <cloud-name> + + :program:`openstack` will look for a ``clouds.yaml`` file that contains + a cloud configuration to use for authentication. See CLOUD CONFIGURATION + below for more information. + +.. option:: --os-auth-type <auth-type> + + The authentication plugin type to use when connecting to the Identity service. + + If this option is not set, :program:`openstack` will attempt to guess the + authentication method to use based on the other options. + + If this option is set, its version must match + :option:`--os-identity-api-version` + +.. option:: --os-auth-url <auth-url> + + Authentication URL + +.. option:: --os-url <service-url> + + Service URL, when using a service token for authentication + +.. option:: --os-domain-name <auth-domain-name> + + Domain-level authorization scope (by name) + +.. option:: --os-domain-id <auth-domain-id> + + Domain-level authorization scope (by ID) + +.. option:: --os-project-name <auth-project-name> + + Project-level authentication scope (by name) + +.. option:: --os-project-id <auth-project-id> + + Project-level authentication scope (by ID) + +.. option:: --os-project-domain-name <auth-project-domain-name> + + Domain name containing project + +.. option:: --os-project-domain-id <auth-project-domain-id> + + Domain ID containing project + +.. option:: --os-username <auth-username> + + Authentication username + +.. option:: --os-password <auth-password> + + Authentication password + +.. option:: --os-token <token> + + Authenticated token or service token + +.. option:: --os-user-domain-name <auth-user-domain-name> + + Domain name containing user + +.. option:: --os-user-domain-id <auth-user-domain-id> + + Domain ID containing user + +.. option:: --os-trust-id <trust-id> + + ID of the trust to use as a trustee user + +.. option:: --os-default-domain <auth-domain> + + Default domain ID (Default: 'default') + +.. option:: --os-region-name <auth-region-name> + + Authentication region name + +.. option:: --os-cacert <ca-bundle-file> + + CA certificate bundle file + +.. option:: --verify` | :option:`--insecure + + Verify or ignore server certificate (default: verify) + +.. option:: --os-cert <certificate-file> + + Client certificate bundle file + +.. option:: --os-key <key-file> + + Client certificate key file + +.. option:: --os-identity-api-version <identity-api-version> + + Identity API version (Default: 2.0) + +.. option:: --os-XXXX-api-version <XXXX-api-version> + + Additional API version options will be available depending on the installed + API libraries. + +.. option:: --os-interface <interface> + + Interface type. Valid options are `public`, `admin` and `internal`. + +.. NOTE:: + If you switch to openstackclient from project specified clients, like: + novaclient, neutronclient and so on, please use `--os-interface` instead of + `--os-endpoint-type`. + +.. option:: --os-profile <hmac-key> + + Performance profiling HMAC key for encrypting context data + + This key should be the value of one of the HMAC keys defined in the + configuration files of OpenStack services to be traced. + +.. option:: --os-beta-command + + Enable beta commands which are subject to change + +.. option:: --log-file <LOGFILE> + + Specify a file to log output. Disabled by default. + +.. option:: -v, --verbose + + Increase verbosity of output. Can be repeated. + +.. option:: -q, --quiet + + Suppress output except warnings and errors + +.. option:: --debug + + Show tracebacks on errors and set verbosity to debug + +.. option:: --help + + Show help message and exit + +COMMANDS +======== + +To get a list of the available commands:: + + openstack --help + +To get a description of a specific command:: + + openstack help <command> + +Note that the set of commands shown will vary depending on the API versions +that are in effect at that time. For example, to force the display of the +Identity v3 commands:: + + openstack --os-identity-api-version 3 --help + +.. option:: complete + + Print the bash completion functions for the current command set. + +.. option:: help <command> + + Print help for an individual command + +Additional information on the OpenStackClient command structure and arguments +is available in the `OpenStackClient Commands`_ wiki page. + +.. _`OpenStackClient Commands`: https://wiki.openstack.org/wiki/OpenStackClient/Commands + +Command Objects +--------------- + +The list of command objects is growing longer with the addition of OpenStack +project support. The object names may consist of multiple words to compose a +unique name. Occasionally when multiple APIs have a common name with common +overlapping purposes there will be options to select which object to use, or +the API resources will be merged, as in the ``quota`` object that has options +referring to both Compute and Block Storage quotas. + +Command Actions +--------------- + +The actions used by OpenStackClient are defined with specific meaning to provide a consistent behavior for each object. Some actions have logical opposite actions, and those pairs will always match for any object that uses them. + + +CLOUD CONFIGURATION +=================== + +Working with multiple clouds can be simplified by keeping the configuration +information for those clouds in a local file. :program:`openstack` supports +using a ``clouds.yaml`` configuration file. + +Config Files +------------ + +:program:`openstack` will look for a file called clouds.yaml in the following +locations: + +* Current Directory +* ~/.config/openstack +* /etc/openstack + +The first file found wins. + +The keys match the :program:`openstack` global options but without the +``--os-`` prefix: + +:: + + clouds: + devstack: + auth: + auth_url: http://192.168.122.10:35357/ + project_name: demo + username: demo + password: 0penstack + region_name: RegionOne + ds-admin: + auth: + auth_url: http://192.168.122.10:35357/ + project_name: admin + username: admin + password: 0penstack + region_name: RegionOne + infra: + cloud: rackspace + auth: + project_id: 275610 + username: openstack + password: xyzpdq!lazydog + region_name: DFW,ORD,IAD + +In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken +from :file:`clouds-public.yaml`: + +:: + + public-clouds: + rackspace: + auth: + auth_url: 'https://identity.api.rackspacecloud.com/v2.0/' + +Authentication Settings +----------------------- + +OpenStackClient uses the Keystone authentication plugins so the required +auth settings are not always known until the authentication type is +selected. :program:`openstack` will attempt to detect a couple of common +auth types based on the arguments passed in or found in the configuration +file, but if those are incomplete it may be impossible to know which +auth type is intended. The :option:`--os-auth-type` option can always be +used to force a specific type. + +When :option:`--os-token` and :option:`--os-url` are both present the +``token_endpoint`` auth type is selected automatically. If +:option:`--os-auth-url` and :option:`--os-username` are present ``password`` +auth type is selected. + +Logging Settings +---------------- + +:program:`openstack` can record the operation history by logging settings +in configuration file. Recording the user operation, it can identify the +change of the resource and it becomes useful information for troubleshooting. + +See :ref:`configuration` about Logging Settings for more details. + + +NOTES +===== + +The command list displayed in help output reflects the API versions selected. For +example, to see Identity v3 commands ``OS_IDENTITY_API_VERSION`` must be set to ``3``. + + +EXAMPLES +======== + +Show the detailed information for server ``appweb01``:: + + openstack \ + --os-project-name ExampleCo \ + --os-username demo --os-password secret \ + --os-auth-url http://localhost:5000:/v2.0 \ + server show appweb01 + +The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`, +:envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set:: + + openstack server show appweb01 + +Create a new image:: + + openstack image create \ + --disk-format=qcow2 \ + --container-format=bare \ + --public \ + --copy-from http://somewhere.net/foo.img \ + foo + + +FILES +===== + +:file:`~/.config/openstack/clouds.yaml` + Configuration file used by the :option:`--os-cloud` global option. + +:file:`~/.config/openstack/clouds-public.yaml` + Configuration file containing public cloud provider information such as + authentication URLs and service definitions. The contents of this file + should be public and sharable. ``clouds.yaml`` may contain references + to clouds defined here as shortcuts. + +:file:`~/.openstack` + Placeholder for future local state directory. This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it. Shared contents (such as :file:`~/.openstack/cache`) have no prefix and the contents must be portable. + + +ENVIRONMENT VARIABLES +===================== + +The following environment variables can be set to alter the behaviour of :program:`openstack`. Most of them have corresponding command-line options that take precedence if set. + +.. envvar:: OS_CLOUD + + The name of a cloud configuration in ``clouds.yaml``. + +.. envvar:: OS_AUTH_PLUGIN + + The authentication plugin to use when connecting to the Identity service, its version must match the Identity API version + +.. envvar:: OS_AUTH_URL + + Authentication URL + +.. envvar:: OS_URL + + Service URL (when using the service token) + +.. envvar:: OS_DOMAIN_NAME + + Domain-level authorization scope (name or ID) + +.. envvar:: OS_PROJECT_NAME + + Project-level authentication scope (name or ID) + +.. envvar:: OS_PROJECT_DOMAIN_NAME + + Domain name or ID containing project + +.. envvar:: OS_USERNAME + + Authentication username + +.. envvar:: OS_TOKEN + + Authenticated or service token + +.. envvar:: OS_PASSWORD + + Authentication password + +.. envvar:: OS_USER_DOMAIN_NAME + + Domain name or ID containing user + +.. envvar:: OS_TRUST_ID + + ID of the trust to use as a trustee user + +.. envvar:: OS_DEFAULT_DOMAIN + + Default domain ID (Default: 'default') + +.. envvar:: OS_REGION_NAME + + Authentication region name + +.. envvar:: OS_CACERT + + CA certificate bundle file + +.. envvar:: OS_CERT + + Client certificate bundle file + +.. envvar:: OS_KEY + + Client certificate key file + +.. envvar:: OS_IDENTITY_API_VERSION + + Identity API version (Default: 2.0) + +.. envvar:: OS_XXXX_API_VERSION + + Additional API version options will be available depending on the installed + API libraries. + +.. envvar:: OS_INTERFACE + + Interface type. Valid options are `public`, `admin` and `internal`. + +.. NOTE:: + If you switch to openstackclient from project specified clients, like: + novaclient, neutronclient and so on, please use `OS_INTERFACE` instead of + `OS_ENDPOINT_TYPE`. + +BUGS +==== + +Bug reports are accepted at the python-openstackclient LaunchPad project +"https://bugs.launchpad.net/python-openstackclient/+bugs". + + +AUTHORS +======= + +Please refer to the AUTHORS file distributed with OpenStackClient. + + +COPYRIGHT +========= + +Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file. + + +LICENSE +======= + +http://www.apache.org/licenses/LICENSE-2.0 + + +SEE ALSO +======== + +The `OpenStackClient page <http://docs.openstack.org/developer/python-openstackclient/>`_ +in the `OpenStack Docs <https://docs.openstack.org/>`_ contains further +documentation. + +The individual OpenStack project CLIs, the OpenStack API references. |