From 038269cf7fbbfad9ccc9d85a762e2ff4f7d97d11 Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Fri, 21 Feb 2014 12:46:07 -0600 Subject: Update release notes for 0.3.1 * update README * update man page * fix doc errors Change-Id: I5682654bf482289879c8ba9016e348f2b2782971 --- doc/source/commands.rst | 30 ++++++++++++ doc/source/man/openstack.rst | 107 ++++++++++++++++++++++++++++++------------- doc/source/releases.rst | 23 ++++++++-- 3 files changed, 123 insertions(+), 37 deletions(-) (limited to 'doc/source') diff --git a/doc/source/commands.rst b/doc/source/commands.rst index 0b93c64d..31e7c148 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -61,6 +61,36 @@ They follow the same style as the global options and always appear between the command and any positional arguments the command requires. +Actions +------- + +The actions used by OpenStackClient are defined below to provide a consistent meaning to each action. Many of them have logical opposite actions. Those actions with an opposite action are noted in parens if applicable. + +* authorize - authorize a token (used in OAuth) +* add (remove) - add some object to a container object; the command is built in the order of "container add object" ( ), the positional arguments appear in the same order +* attach (detach) - deprecated; use add/remove +* create (delete) - create a new occurrance of the specified object +* delete (create) - delete a specific occurrance of the specified object +* detach (attach) - deprecated; use add/remove +* list - display summary information about multiple objects +* lock (unlock) +* migrate - move a server to a different host; --live performs a live migration if possible +* pause (unpause) - stop a server and leave it in memory +* reboot - forcibly reboot a server +* rebuild - rebuild a server using (most of) the same arguments as in the original create +* remove (add) - remove an object from a group of objects +* rescue (unrescue) - reboot a server in a special rescue mode allowing access to the original disks +* resize - change a server's flavor +* resume (suspend) - return a suspended server to running state +* save - download an object locally +* set (unset) - set a property on the object, formerly called metadata +* show - display detailed information about the specific object +* suspend (resume) - stop a server and save to disk freeing memory +* unlock (lock) +* unpause (pause) - return a paused server to running state +* unrescue (rescue) - return a server to normal boot mode +* unset (set) - remove an attribute of the object + Implementation ============== diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst index 3a780e24..74db6815 100644 --- a/doc/source/man/openstack.rst +++ b/doc/source/man/openstack.rst @@ -18,7 +18,7 @@ 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 librariess, but with +equivalent to the CLIs provided by the OpenStack project client libraries, but with a distinct and consistent command structure. :program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with @@ -37,49 +37,51 @@ command line. The primary difference is the use of 'project' in the name of the 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 topions: -:option:`--os-auth-url ` +:option:`--os-auth-url` Authentication URL -:option:`--os-project-name ` - Authentication project name (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied) +:option:`--os-domain-name` | :option:`--os-domain-id` + Domain-level authorization scope (name or ID) + +:option:`--os-project-name` | :option:`--os-project-id` + Project-level authentication scope (name or ID) -:option:`--os-project-id ` - Authentication tenant ID (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied) +:option:`--os-project-domain-name` | :option:`--os-project-domain-id` + Domain name or id containing project -:option:`--os-username ` +:option:`--os-username` Authentication username -:option:`--os-password ` +:option:`--os-user-domain-name` | :option:`--os-user-domain-id` + Domain name or id containing user + +:option:`--os-password` Authentication password -:option:`--os-region-name ` +:option:`--os-region-name` Authentication region name -:option:`--os-default-domain ` +:option:`--os-default-domain` Default domain ID (Default: 'default') -:options:`--os-use-keyring` +:option:`--os-use-keyring` Use keyring to store password (default: False) -:option:`--os-cacert ` +:option:`--os-cacert` CA certificate bundle file -:option:`--verify|--insecure` +:option:`--verify` | :option:`--insecure` Verify or ignore server certificate (default: verify) -:option:`--os-identity-api-version ` +:option:`--os-identity-api-version` Identity API version (Default: 2.0) -:option:`--os-XXXX-api-version ` - Additional API version options will be presend depending on the installed API libraries. - - -NOTES -===== - -[This section intentionally left blank. So there.] +:option:`--os-XXXX-api-version` + Additional API version options will be available depending on the installed API libraries. COMMANDS @@ -87,7 +89,7 @@ COMMANDS To get a list of the available commands:: - openstack -h + openstack --help To get a description of a specific command:: @@ -101,12 +103,23 @@ To get a description of a specific command:: Print help for an individual command +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-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 server show appweb01 + openstack \ + --os-project-name ExampleCo \ + --os-username demo --os-password secrete \ + --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:: @@ -126,25 +139,53 @@ Create a new image:: FILES ===== - :file:`~/.openstack` +: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` +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_AUTH_URL` + Authentication URL + +: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` - Set the username + Authentication username + +:envvar:`OS_USER_DOMAIN_NAME` + Domain name or id containing user :envvar:`OS_PASSWORD` - Set the password + Authentication password -:envvar:`OS_PROJECT_NAME` - Set the project name +:envvar:`OS_REGION_NAME` + Authentication region name -:envvar:`OS_AUTH_URL` - Set the authentication URL +:envvar:`OS_DEFAULT_DOMAIN` + Default domain ID (Default: ‘default’) + +:envvar:`OS_USE_KEYRING` + Use keyring to store password (default: False) + +:envvar:`OS_CACERT` + CA certificate bundle file + +:envvar:`OS_IDENTITY_API_VERISON` + Identity API version (Default: 2.0) + +:envvar:`OS_XXXX_API_VERISON` + Additional API version options will be available depending on the installed API libraries. BUGS @@ -163,7 +204,7 @@ Please refer to the AUTHORS file distributed with OpenStackClient. COPYRIGHT ========= -Copyright 2011-2013 OpenStack Foundation and the authors listed in the AUTHORS file. +Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file. LICENSE diff --git a/doc/source/releases.rst b/doc/source/releases.rst index 7d74318e..34bdce62 100644 --- a/doc/source/releases.rst +++ b/doc/source/releases.rst @@ -2,6 +2,25 @@ Release Notes ============= +0.3.1 (28 Feb 2014) +=================== + +* add ``token create`` command +* internal changes for Python 3.3 compatability +* Bug 1100116_: Prompt interactive user for passwords in ``user create`` and ``user set`` +* Bug 1198171_: add domain support options for Identity v3 +* Bug 1241177_: Fix region handling in volume commands +* Bug 1256935_: Clean up ``security group rule list`` output format +* Bug 1269821_: Fix for unreleased Glance client change in internal class structure +* Bug 1284957_: Correctly pass ``--cacert`` and ``--insecure`` to Identity client in token flow auth + +.. _1100116: https://bugs.launchpad.net/ubuntu/+source/python-keystoneclient/+bug/1100116 +.. _1198171: https://bugs.launchpad.net/keystone/+bug/1198171 +.. _1241177: https://bugs.launchpad.net/python-openstackclient/+bug/1241177 +.. _1256935: https://bugs.launchpad.net/python-openstackclient/+bug/1256935 +.. _1269821: https://bugs.launchpad.net/python-openstackclient/+bug/1269821 +.. _1284957: https://bugs.launchpad.net/python-openstackclient/+bug/1284957 + 0.3.0 (17 Dec 2013) =================== @@ -10,10 +29,6 @@ Release Notes * add options to support TLS cetificate verification * add object-store show commands for container and object -.. commented to save format of bug fix -.. * 1254168_: OS_REGION_NAME is not used -.. _1254168: https://bugs.launchpad.net/python-openstackclient/+bug/1254168 - 0.2.2 (20 Sep 2013) =================== -- cgit v1.2.1