diff options
Diffstat (limited to 'doc/source/commands.rst')
| -rw-r--r-- | doc/source/commands.rst | 76 |
1 files changed, 42 insertions, 34 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst index e0cfee7a..a9d10c96 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -12,9 +12,9 @@ Commands take the form:: openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>] -* All long options names begin with two dashes ('--') and use a single dash - ('-') internally between words (--like-this). Underscores ('_') are not used - in option names. +* All long options names begin with two dashes (``--``) and use a single dash + (``-``) internally between words (``--like-this``). Underscores (``_``) are + not used in option names. Global Options @@ -25,11 +25,12 @@ invocation regardless of action to be performed. They include authentication credentials and API version selection. 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 +names are derived from the option name by dropping the leading dashes (``--``), +converting each embedded dash (``-``) to an underscore (``_``), and converting to upper case. -For example, ``--os-username`` can be set from the environment via ``OS_USERNAME``. +For example, the default value of ``--os-username`` can be set by defining +the environment variable ``OS_USERNAME``. Command Object(s) and Action @@ -64,39 +65,46 @@ 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" (<container> <object>), the positional arguments appear in the same order -* attach (detach) - deprecated; use add/remove -* create (delete) - create a new occurrence of the specified object -* delete (create) - delete a specific occurrence 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 +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 <container> <object>``, + the positional arguments appear in the same order +* ``create`` (``delete``) - create a new occurrence of the specified object +* ``delete`` (``create``) - delete a specific occurrence of the specified object +* ``issue`` (``revoke``) - issue a token +* ``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 +* ``revoke`` (``issue``) - revoke a token +* ``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 ============== The command structure is designed to support seamless addition of plugin command modules via ``setuptools`` entry points. The plugin commands must -be subclasses of Cliff's command.Command object. +be subclasses of Cliff's command.Command object. See :doc:`plugins` for +more information. Command Entry Points @@ -111,7 +119,7 @@ entry points have the form:: verb_object = fully.qualified.module.vXX.object:VerbObject -For example, the 'list user' command fir the Identity API is identified in +For example, the ``list user`` command for the Identity API is identified in ``setup.cfg`` with:: openstack.identity.v3 = |