diff options
Diffstat (limited to 'doc/source/man/openstack.rst')
| -rw-r--r-- | doc/source/man/openstack.rst | 507 |
1 files changed, 0 insertions, 507 deletions
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst deleted file mode 100644 index 66a99f32..00000000 --- a/doc/source/man/openstack.rst +++ /dev/null @@ -1,507 +0,0 @@ -==================== -: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 :doc:`../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. |