pax_global_header00006660000000000000000000000064130442004050014502gustar00rootroot0000000000000052 comment=fbcda721a944c3c3548ad1a260753e1d76fe9c71 python-openstackclient-2.3.1/000077500000000000000000000000001304420040500162125ustar00rootroot00000000000000python-openstackclient-2.3.1/.coveragerc000066400000000000000000000001571304420040500203360ustar00rootroot00000000000000[run] branch = True source = openstackclient omit = openstackclient/openstack/* [report] ignore_errors = True python-openstackclient-2.3.1/.gitignore000066400000000000000000000004221304420040500202000ustar00rootroot00000000000000*.DS_Store *.egg* *.log *.mo *.pyc *.swo *.swp *~ .coverage .idea .testrepository .tox AUTHORS build ChangeLog dist # Doc related doc/build doc/source/api/ # Development environment files .project .pydevproject cover # Files created by releasenotes build releasenotes/build python-openstackclient-2.3.1/.gitreview000066400000000000000000000001671304420040500202240ustar00rootroot00000000000000[gerrit] host=review.openstack.org port=29418 project=openstack/python-openstackclient.git defaultbranch=stable/mitaka python-openstackclient-2.3.1/.mailmap000066400000000000000000000001431304420040500176310ustar00rootroot00000000000000 python-openstackclient-2.3.1/.testr.conf000066400000000000000000000005771304420040500203110ustar00rootroot00000000000000[DEFAULT] test_command=OS_STDOUT_CAPTURE=${OS_STDOUT_CAPTURE:-1} \ OS_STDERR_CAPTURE=${OS_STDERR_CAPTURE:-1} \ OS_TEST_TIMEOUT=${OS_TEST_TIMEOUT:-60} \ ${PYTHON:-python} -m subunit.run discover -t ./ ${OS_TEST_PATH:-./openstackclient/tests} $LISTOPT $IDOPTION test_id_option=--load-list $IDFILE test_list_option=--list group_regex=([^\.]+\.)+ python-openstackclient-2.3.1/HACKING.rst000066400000000000000000000060101304420040500200050ustar00rootroot00000000000000OpenStack Style Commandments ============================ - Step 1: Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ - Step 2: Read on General ------- - thou shalt not violate causality in our time cone, or else Docstrings ---------- Docstrings should ONLY use triple-double-quotes (``"""``) Single-line docstrings should NEVER have extraneous whitespace between enclosing triple-double-quotes. Deviation! Sentence fragments do not have punctuation. Specifically in the command classes the one line docstring is also the help string for that command and those do not have periods. """A one line docstring looks like this""" Calling Methods --------------- Deviation! When breaking up method calls due to the 79 char line length limit, use the alternate 4 space indent. With the first argument on the succeeding line all arguments will then be vertically aligned. Use the same convention used with other data structure literals and terminate the method call with the last argument line ending with a comma and the closing paren on its own line indented to the starting line level. unnecessarily_long_function_name( 'string one', 'string two', kwarg1=constants.ACTIVE, kwarg2=['a', 'b', 'c'], ) Text encoding ------------- Note: this section clearly has not been implemented in this project yet, it is the intention to do so. All text within python code should be of type 'unicode'. WRONG: >>> s = 'foo' >>> s 'foo' >>> type(s) RIGHT: >>> u = u'foo' >>> u u'foo' >>> type(u) Transitions between internal unicode and external strings should always be immediately and explicitly encoded or decoded. All external text that is not explicitly encoded (database storage, commandline arguments, etc.) should be presumed to be encoded as utf-8. WRONG: infile = open('testfile', 'r') mystring = infile.readline() myreturnstring = do_some_magic_with(mystring) outfile.write(myreturnstring) RIGHT: infile = open('testfile', 'r') mystring = infile.readline() mytext = mystring.decode('utf-8') returntext = do_some_magic_with(mytext) returnstring = returntext.encode('utf-8') outfile.write(returnstring) Python 3.x Compatibility ------------------------ OpenStackClient strives to be Python 3.3 compatible. Common guidelines: * Convert print statements to functions: print statements should be converted to an appropriate log or other output mechanism. * Use six where applicable: x.iteritems is converted to six.iteritems(x) for example. Running Tests ------------- Note: Oh boy, are we behind on writing tests. But they are coming! The testing system is based on a combination of tox and testr. If you just want to run the whole suite, run `tox` and all will be fine. However, if you'd like to dig in a bit more, you might want to learn some things about testr itself. A basic walkthrough for OpenStack can be found at http://wiki.openstack.org/testr python-openstackclient-2.3.1/LICENSE000066400000000000000000000236371304420040500172320ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. python-openstackclient-2.3.1/README.rst000066400000000000000000000060711304420040500177050ustar00rootroot00000000000000=============== OpenStackClient =============== .. image:: https://img.shields.io/pypi/v/python-openstackclient.svg :target: https://pypi.python.org/pypi/python-openstackclient/ :alt: Latest Version .. image:: https://img.shields.io/pypi/dm/python-openstackclient.svg :target: https://pypi.python.org/pypi/python-openstackclient/ :alt: Downloads OpenStackClient (aka OSC) is a command-line client for OpenStack that brings the command set for Compute, Identity, Image, Object Store and Block Storage APIs together in a single shell with a uniform command structure. The primary goal is to provide a unified shell command structure and a common language to describe operations in OpenStack. * `PyPi`_ - package installation * `Online Documentation`_ * `Launchpad project`_ - release management * `Blueprints`_ - feature specifications * `Bugs`_ - issue tracking * `Source`_ * `Developer` - getting started as a developer * `Contributing` - contributing code * IRC: #openstack-sdks on Freenode (irc.freenode.net) * License: Apache 2.0 .. _PyPi: https://pypi.python.org/pypi/python-openstackclient .. _Online Documentation: http://docs.openstack.org/developer/python-openstackclient/ .. _Launchpad project: https://launchpad.net/python-openstackclient .. _Blueprints: https://blueprints.launchpad.net/python-openstackclient .. _Bugs: https://bugs.launchpad.net/python-openstackclient .. _Source: https://git.openstack.org/cgit/openstack/python-openstackclient .. _Developer: http://docs.openstack.org/infra/manual/python.html .. _Contributing: http://docs.openstack.org/infra/manual/developers.html Getting Started =============== OpenStack Client can be installed from PyPI using pip:: pip install python-openstackclient There are a few variants on getting help. A list of global options and supported commands is shown with ``--help``:: openstack --help There is also a ``help`` command that can be used to get help text for a specific command:: openstack help openstack help server create Configuration ============= The CLI is configured via environment variables and command-line options as listed in http://docs.openstack.org/developer/python-openstackclient/authentication.html. Authentication using username/password is most commonly used:: export OS_AUTH_URL= export OS_PROJECT_NAME= export OS_USERNAME= export OS_PASSWORD= # (optional) The corresponding command-line options look very similar:: --os-auth-url --os-project-name --os-username [--os-password ] If a password is not provided above (in plaintext), you will be interactively prompted to provide one securely. Authentication may also be performed using an already-acquired token and a URL pointing directly to the service API that presumably was acquired from the Service Catalog:: export OS_TOKEN= export OS_URL= The corresponding command-line options look very similar:: --os-token --os-url python-openstackclient-2.3.1/babel.cfg000066400000000000000000000000201304420040500177300ustar00rootroot00000000000000[python: **.py] python-openstackclient-2.3.1/doc/000077500000000000000000000000001304420040500167575ustar00rootroot00000000000000python-openstackclient-2.3.1/doc/Makefile000066400000000000000000000112641304420040500204230ustar00rootroot00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source .PHONY: help clean html pdf dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " pdf to make pdf with rst2pdf" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " text to make text files" @echo " man to make manual pages" @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: -rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." pdf: $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf @echo @echo "Build finished. The PDFs are in $(BUILDDIR)/pdf." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NebulaDocs.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NebulaDocs.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @echo "# mkdir -p $$HOME/.local/share/devhelp/NebulaDocs" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NebulaDocs" @echo "# devhelp" epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." make -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." python-openstackclient-2.3.1/doc/ext/000077500000000000000000000000001304420040500175575ustar00rootroot00000000000000python-openstackclient-2.3.1/doc/ext/__init__.py000066400000000000000000000000001304420040500216560ustar00rootroot00000000000000python-openstackclient-2.3.1/doc/ext/apidoc.py000066400000000000000000000026551304420040500214000ustar00rootroot00000000000000# Copyright 2014 OpenStack Foundation # # Licensed under the Apache License, Version 2.0 (the "License"); you may # not use this file except in compliance with the License. You may obtain # a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. import os.path as path from sphinx import apidoc # NOTE(blk-u): pbr will run Sphinx multiple times when it generates # documentation. Once for each builder. To run this extension we use the # 'builder-inited' hook that fires at the beginning of a Sphinx build. # We use ``run_already`` to make sure apidocs are only generated once # even if Sphinx is run multiple times. run_already = False def run_apidoc(app): global run_already if run_already: return run_already = True package_dir = path.abspath(path.join(app.srcdir, '..', '..', 'openstackclient')) source_dir = path.join(app.srcdir, 'api') apidoc.main(['apidoc', package_dir, '-f', '-H', 'openstackclient Modules', '-o', source_dir]) def setup(app): app.connect('builder-inited', run_apidoc) python-openstackclient-2.3.1/doc/source/000077500000000000000000000000001304420040500202575ustar00rootroot00000000000000python-openstackclient-2.3.1/doc/source/authentication.rst000066400000000000000000000136721304420040500240410ustar00rootroot00000000000000============== Authentication ============== OpenStackClient leverages `python-keystoneclient`_ authentication plugins to support a number of different authentication methods. .. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/authentication-plugins.html Authentication Process ---------------------- The user provides some number of authentication credential options. If an authentication type is not provided (``--os-auth-type``), the authentication options are examined to determine if one of the default types can be used. If no match is found an error is reported and OSC exits. Note that the authentication call to the Identity service has not yet occurred. It is deferred until the last possible moment in order to reduce the number of unnecessary queries to the server, such as when further processing detects an invalid command. Authentication Plugins ---------------------- The Keystone client library implements the base set of plugins. Additional plugins may be available from the Keystone project or other sources. There are at least three authentication types that are always available: * **Password**: A project, username and password are used to identify the user. An optional domain may also be included. This is the most common type and is the default any time a username is supplied. An authentication URL for the Identity service is also required. [Required: ``--os-auth-url``, ``--os-project-name``, ``--os-username``; Optional: ``--os-password``] * **Token**: This is slightly different from the usual token authentication (described below as token/endpoint) in that a token and an authentication URL are supplied and the plugin retrieves a new token. [Required: ``--os-auth-url``, ``--os-token``] * **Token/Endpoint**: This is the original token authentication (known as 'token flow' in the early CLI documentation in the OpenStack wiki). It requires a token and a direct endpoint that is used in the API call. The difference from the new Token type is this token is used as-is, no call is made to the Identity service from the client. This type is most often used to bootstrap a Keystone server where the token is the ``admin_token`` configured in ``keystone.conf``. It will also work with other services and a regular scoped token such as one obtained from a ``token issue`` command. [Required: ``--os-url``, ``--os-token``] * **Others**: Other authentication plugins such as SAML, Kerberos, and OAuth1.0 are under development and also supported. To use them, they must be selected by supplying the ``--os-auth-type`` option. Detailed Process ---------------- The authentication process in OpenStackClient is all contained in and handled by the ``ClientManager`` object. * On import ``api.auth``: * obtains the list of installed Keystone authentication plugins from the ``keystoneclient.auth.plugin`` entry point. * builds a list of authentication options from the plugins. * The command line arguments are processed and a configuration is loaded from :file:`clouds.yaml` if ``--os-cloud`` is provided. * A new ``ClientManager`` is created and supplied with the set of options from the command line, environment and/or :file:`clouds.yaml`: * If ``--os-auth-type`` is provided and is a valid and available plugin it is used. * If ``--os-auth-type`` is not provided an authentication plugin is selected based on the existing options. This is a short-circuit evaluation, the first match wins. * If ``--os-url`` and ``--os-token`` are both present ``token_endpoint`` is selected * If ``--os-username`` is supplied ``password`` is selected * If ``--os-token`` is supplied ``token`` is selected * If no selection has been made by now exit with error * Load the selected plugin class. * When an operation that requires authentication is attempted ``ClientManager`` makes the actual initial request to the Identity service. * if ``--os-auth-url`` is not supplied for any of the types except Token/Endpoint, exit with an error. Authenticating using Identity Server API v3 ------------------------------------------- To authenticate against an Identity Server API v3, the ``OS_IDENTITY_API_VERSION`` environment variable or ``--os-identity-api-version`` option must be changed to ``3``, instead of the default ``2.0``. Similarly ``OS_AUTH_URL`` or ``os-auth-url`` should also be updated. .. code-block:: bash $ export OS_IDENTITY_API_VERSION=3 (Defaults to 2.0) $ export OS_AUTH_URL=http://localhost:5000/v3 Since Identity API v3 authentication is a bit more complex, there are additional options that may be set, either as command line options or environment variables. The most common case will be a user supplying both user name and password, along with the project name; previously in v2.0 this would be sufficient, but since the Identity API v3 has a ``Domain`` component, we need to tell the client in which domain the user and project exists. If using a user name and password to authenticate, specify either it's owning domain name or ID. * ``--os-user-domain-name`` or ``OS_USER_DOMAIN_NAME`` * ``--os-user-domain-id`` or ``OS_USER_DOMAIN_ID`` If using a project name as authorization scope, specify either it's owning domain name or ID. * ``--os-project-domain-name`` or ``OS_PROJECT_DOMAIN_NAME`` * ``--os-project-domain-id`` or ``OS_PROJECT_DOMAIN_ID`` If using a domain as authorization scope, set either it's name or ID. * ``--os-domain-name`` or ``OS_DOMAIN_NAME`` * ``--os-domain-id`` or ``OS_DOMAIN_ID`` Note that if the user and project share the same domain, then simply setting ``os-default-domain`` or ``OS_DEFAULT_DOMAIN`` is sufficient. Thus, a minimal set of environment variables would be: .. code-block:: bash $ export OS_IDENTITY_API_VERSION=3 $ export OS_AUTH_URL=http://localhost:5000/v3 $ export OS_DEFAULT_DOMAIN=default $ export OS_USERNAME=admin $ export OS_PASSWORD=secret $ export OS_PROJECT_NAME=admin python-openstackclient-2.3.1/doc/source/backwards-incompatible.rst000066400000000000000000000153261304420040500254250ustar00rootroot00000000000000============================== Backwards Incompatible Changes ============================== Despite our best efforts, sometimes the OpenStackClient team may introduce a backwards incompatible change. For user convenience we are tracking any such changes here (as of the 1.0.0 release). Should positional arguments for a command need to change, the OpenStackClient team attempts to make the transition as painless as possible. Look for deprecation warnings that indicate the new commands (or options) to use. List of Backwards Incompatible Changes ====================================== 1. Rename command `openstack project usage list` The `project` part of the command was pointless. * In favor of: `openstack usage list` instead. * As of: 1.0.2 * Removed in: TBD * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1406654 * Commit: https://review.openstack.org/#/c/147379/ 2. should not be optional for command `openstack service create` Previously, the command was `openstack service create --type `, whereas now it is: `openstack service create --name ` This bug also affected python-keystoneclient, and keystone. * In favor of: making a positional argument. * As of: 1.0.2 * Removed in: TBD * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1404073 * Commit: https://review.openstack.org/#/c/143242/ 3. Command `openstack security group rule delete` now requires rule id Previously, the command was `openstack security group rule delete --proto [--src-ip --dst-port ] `, whereas now it is: `openstack security group rule delete `. * In favor of: Using `openstack security group rule delete `. * As of: 1.2.1 * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1450872 * Commit: https://review.openstack.org/#/c/179446/ 4. Command `openstack image create` does not update already existing image Previously, the image create command updated already existing image if it had same name. It disabled possibility to create multiple images with same name and lead to potentially unwanted update of existing images by image create command. Now, update code was moved from create action to set action. * In favor of: Create multiple images with same name (as glance does). * As of: 1.5.0 * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1461817 * Commit: https://review.openstack.org/#/c/194654/ 5. Command `openstack network list --dhcp` has been removed The --dhcp option to network list is not a logical use case of listing networks, it lists agents. Another command should be added in the future to provide this functionality. It is highly unlikely anyone uses this feature as we don't support any other agent commands. Use neutron dhcp-agent-list-hosting-net command instead. * In favor of: Create network agent list command in the future * As of: 1.6.0 * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/472613 * Commit: https://review.openstack.org/#/c/194654/ 6. Plugin interface change for default API versions Previously, the default version was set in the parsed arguments, but this makes it impossible to tell what has been passed in at the command line, set in an environment variable or is just the default. Now, the module should have a DEFAULT_API_VERSION that contains the value and it will be set after command line argument, environment and OCC file processing. * In favor of: DEFAULT_API_VERSION * As of: 1.2.1 * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1453229 * Commit: https://review.openstack.org/#/c/181514/ 7. `image set` commands will no longer return the modified resource Previously, modifying an image would result in the new image being displayed to the user. To keep things consistent with other `set` commands, we will no longer be showing the modified resource. * In favor of: Use `set` then `show` * As of: NA * Removed in: NA * Bug: NA * Commit: NA 8. `region` commands no longer support `url` The Keystone team removed support for thr `url` attribute from the client and server side. Changes to the `create`, `set` and `list` commands for regions have been affected. * In favor of: NA * As of 1.9.0 * Removed in: NA * Bug: https://launchpad.net/bugs/1506841 * Commit: https://review.openstack.org/#/c/236736/ 9. `flavor set/unset` commands will no longer return the modified resource Previously, modifying a flavor would result in the new flavor being displayed to the user. To keep things consistent with other `set/unset` commands, we will no longer be showing the modified resource. * In favor of: Use `set/unset` then `show` * As of: NA * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 * Commit: https://review.openstack.org/#/c/280663/ 10. `security group set` commands will no longer return the modified resource Previously, modifying a security group would result in the new security group being displayed to the user. To keep things consistent with other `set` commands, we will no longer be showing the modified resource. * In favor of: Use `set` then `show` * As of: NA * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 * Commit: https://review.openstack.org/#/c/281087/ 11. `compute agent set` commands will no longer return the modified resource Previously, modifying an agent would result in the new agent being displayed to the user. To keep things consistent with other `set` commands, we will no longer be showing the modified resource. * In favor of: Use `set` then `show` * As of: NA * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 * Commit: https://review.openstack.org/#/c/281088/ 13. `aggregate set` commands will no longer return the modified resource Previously, modifying an aggregate would result in the new aggregate being displayed to the user. To keep things consistent with other `set` commands, we will no longer be showing the modified resource. * In favor of: Use `set` then `show` * As of: NA * Removed in: NA * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 * Commit: https://review.openstack.org/#/c/281089/ For Developers ============== If introducing a backwards incompatible change, then add the tag: ``BackwardsIncompatibleImpact`` to your git commit message, and if possible, update this file. To review all changes that are affected, use the following query: https://review.openstack.org/#/q/project:openstack/python-openstackclient+AND+message:BackwardsIncompatibleImpact,n,z python-openstackclient-2.3.1/doc/source/command-list.rst000066400000000000000000000001451304420040500234000ustar00rootroot00000000000000============ Command List ============ .. toctree:: :glob: :maxdepth: 2 command-objects/* python-openstackclient-2.3.1/doc/source/command-objects/000077500000000000000000000000001304420040500233245ustar00rootroot00000000000000python-openstackclient-2.3.1/doc/source/command-objects/access-token.rst000066400000000000000000000015341304420040500264400ustar00rootroot00000000000000============ access token ============ Identity v3 `Requires: OS-OAUTH1 extension` access token create ------------------- Create an access token .. program:: access token create .. code:: bash os access token create --consumer-key --consumer-secret --request-key --request-secret --verifier .. option:: --consumer-key Consumer key (required) .. option:: --consumer-secret Consumer secret (required) .. option:: --request-key Request token to exchange for access token (required) .. option:: --request-secret Secret associated with (required) .. option:: --verifier Verifier associated with (required) python-openstackclient-2.3.1/doc/source/command-objects/aggregate.rst000066400000000000000000000047651304420040500260200ustar00rootroot00000000000000========= aggregate ========= Server aggregates provide a mechanism to group servers according to certain criteria. Compute v2 aggregate add host ------------------ Add host to aggregate .. program:: aggregate add host .. code:: bash os aggregate add host .. _aggregate_add_host-aggregate: .. describe:: Aggregate (name or ID) .. describe:: Host to add to :ref:`\ ` aggregate create ---------------- Create a new aggregate .. program:: aggregate create .. code:: bash os aggregate create [--zone ] [--property ] .. option:: --zone Availability zone name .. option:: --property Property to add to this aggregate (repeat option to set multiple properties) .. describe:: New aggregate name aggregate delete ---------------- Delete an existing aggregate .. program:: aggregate delete .. code:: bash os aggregate delete .. describe:: Aggregate to delete (name or ID) aggregate list -------------- List all aggregates .. program:: aggregate list .. code:: bash os aggregate list [--long] .. option:: --long List additional fields in output aggregate remove host --------------------- Remove host from aggregate .. program:: aggregate remove host .. code:: bash os aggregate remove host .. _aggregate_remove_host-aggregate: .. describe:: Aggregate (name or ID) .. describe:: Host to remove from :ref:`\ ` aggregate set ------------- Set aggregate properties .. program:: aggregate set .. code:: bash os aggregate set [--name ] [--zone ] [--property ] .. option:: --name Set aggregate name .. option:: --zone Set availability zone name .. option:: --property Property to set on :ref:`\ ` (repeat option to set multiple properties) .. _aggregate_set-aggregate: .. describe:: Aggregate to modify (name or ID) aggregate show -------------- Display aggregate details .. program:: aggregate show .. code:: bash os aggregate show .. describe:: Aggregate to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/availability-zone.rst000066400000000000000000000011021304420040500274730ustar00rootroot00000000000000================= availability zone ================= Block Storage v2, Compute v2, Network v2 availability zone list ---------------------- List availability zones and their status .. program availability zone list .. code:: bash os availability zone list [--compute] [--network] [--volume] [--long] .. option:: --compute List compute availability zones .. option:: --network List network availability zones .. option:: --volume List volume availability zones .. option:: --long List additional fields in output python-openstackclient-2.3.1/doc/source/command-objects/backup.rst000066400000000000000000000026641304420040500253330ustar00rootroot00000000000000====== backup ====== Block Storage v1 backup create ------------- Create new backup .. program:: backup create .. code:: bash os backup create [--container ] [--name ] [--description ] .. option:: --container Optional backup container name .. option:: --name Name of the backup .. option:: --description Description of the backup .. _backup_create-backup: .. describe:: Volume to backup (name or ID) backup delete ------------- Delete backup(s) .. program:: backup delete .. code:: bash os backup delete [ ...] .. _backup_delete-backup: .. describe:: Backup(s) to delete (ID only) backup list ----------- List backups .. program:: backup list .. code:: bash os backup list .. _backup_list-backup: .. option:: --long List additional fields in output backup restore -------------- Restore backup .. program:: backup restore .. code:: bash os backup restore .. _backup_restore-backup: .. describe:: Backup to restore (ID only) .. describe:: Volume to restore to (name or ID) backup show ----------- Display backup details .. program:: backup show .. code:: bash os backup show .. _backup_show-backup: .. describe:: Backup to display (ID only) python-openstackclient-2.3.1/doc/source/command-objects/catalog.rst000066400000000000000000000005661304420040500254770ustar00rootroot00000000000000======= catalog ======= Identity v2, v3 catalog list ------------ List services in the service catalog .. program:: catalog list .. code:: bash os catalog list catalog show ------------ Display service catalog details .. program:: catalog show .. code:: bash os catalog show .. describe:: Service to display (type or name) python-openstackclient-2.3.1/doc/source/command-objects/command.rst000066400000000000000000000003071304420040500254740ustar00rootroot00000000000000======= command ======= Internal Installed commands in the OSC process. command list ------------ List recognized commands by group .. program:: command list .. code:: bash os command list python-openstackclient-2.3.1/doc/source/command-objects/compute-agent.rst000066400000000000000000000025701304420040500266320ustar00rootroot00000000000000============= compute agent ============= Compute v2 compute agent create -------------------- Create compute agent .. program:: compute agent create .. code:: bash os compute agent create .. _compute_agent-create: .. describe:: Type of OS .. describe:: Type of architecture .. describe:: Version .. describe:: URL .. describe:: MD5 hash .. describe:: Type of hypervisor compute agent delete -------------------- Delete compute agent command .. program:: compute agent delete .. code:: bash os compute agent delete .. _compute_agent-delete: .. describe:: ID of agent to delete compute agent list ------------------ List compute agent command .. program:: compute agent list .. code:: bash os compute agent list [--hypervisor ] .. _compute_agent-list: .. describe:: --hypervisor Optional type of hypervisor compute agent set ----------------- Set compute agent command .. program:: agent set .. code:: bash os compute agent set .. _compute_agent-set: .. describe:: ID of the agent .. describe:: Version of the agent .. describe:: URL .. describe:: MD5 hash python-openstackclient-2.3.1/doc/source/command-objects/compute-service.rst000066400000000000000000000020461304420040500271720ustar00rootroot00000000000000=============== compute service =============== Compute v2 compute service delete ---------------------- Delete service command .. program:: compute service delete .. code:: bash os compute service delete .. _compute-service-delete: .. describe:: Compute service to delete (ID only) compute service list -------------------- List service command .. program:: compute service list .. code:: bash os compute service list [--host ] [--service ] .. _compute-service-list: .. describe:: --host Name of host .. describe:: --service Name of service compute service set ------------------- Set service command .. program:: compute service set .. code:: bash os compute service list [--enable | --disable] .. _compute-service-set: .. describe:: --enable Enable service (default) .. describe:: --disable Disable service .. describe:: Name of host .. describe:: Name of service python-openstackclient-2.3.1/doc/source/command-objects/configuration.rst000066400000000000000000000011141304420040500267220ustar00rootroot00000000000000============= configuration ============= Available for all services configuration show ------------------ Show the current openstack client configuration. This command is a little different from other show commands because it does not take a resource name or id to show. The command line options, such as --os-cloud, can be used to show different configurations. .. program:: configuration show .. code:: bash os configuration show [--mask | --unmask] .. option:: --mask Attempt to mask passwords (default) .. option:: --unmask Show password in clear text python-openstackclient-2.3.1/doc/source/command-objects/console-log.rst000066400000000000000000000006611304420040500263020ustar00rootroot00000000000000=========== console log =========== Server console text dump Compute v2 console log show ---------------- Show server's console output .. program:: console log show .. code:: bash os console log show [--lines ] .. option:: --lines Number of lines to display from the end of the log (default=all) .. describe:: Server to show log console log (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/console-url.rst000066400000000000000000000007521304420040500263240ustar00rootroot00000000000000=========== console url =========== Server remote console URL Compute v2 console url show ---------------- Show server's remote console URL .. program:: console url show .. code:: bash os console url show [--novnc | --xvpvnc | --spice] .. option:: --novnc Show noVNC console URL (default) .. option:: --xvpvnc Show xpvnc console URL .. option:: --spice Show SPICE console URL .. describe:: Server to show URL (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/consumer.rst000066400000000000000000000021321304420040500257070ustar00rootroot00000000000000======== consumer ======== Identity v3 `Requires: OS-OAUTH1 extension` consumer create --------------- Create new consumer .. program:: consumer create .. code:: bash os consumer create [--description ] .. option:: --description New consumer description consumer delete --------------- Delete consumer .. program:: consumer delete .. code:: bash os consumer delete .. describe:: Consumer to delete consumer list ------------- List consumers .. program:: consumer list .. code:: bash os consumer list consumer set ------------ Set consumer properties .. program:: consumer set .. code:: bash os consumer set [--description ] .. option:: --description New consumer description .. describe:: Consumer to modify consumer show ------------- Display consumer details .. program:: consumer show .. code:: bash os consumer show .. _consumer_show-consumer: .. describe:: Consumer to display python-openstackclient-2.3.1/doc/source/command-objects/container.rst000066400000000000000000000045021304420040500260410ustar00rootroot00000000000000========= container ========= Object Storage v1 container create ---------------- Create new container .. program:: container create .. code:: bash os container create [ ...] .. describe:: New container name(s) container delete ---------------- Delete container .. program:: container delete .. code:: bash os container delete [-r] | [--recursive] [ ...] .. option:: --recursive, -r Recursively delete objects in container before container delete .. describe:: Container(s) to delete container list -------------- List containers .. program:: container list .. code:: bash os container list [--prefix ] [--marker ] [--end-marker ] [--limit ] [--long] [--all] .. option:: --prefix Filter list using .. option:: --marker Anchor for paging .. option:: --end-marker End anchor for paging .. option:: --limit Limit the number of containers returned .. option:: --long List additional fields in output .. option:: --all List all containers (default is 10000) container save -------------- Save container contents locally .. program:: container save .. code:: bash os container save .. describe:: Container to save container set ------------- Set container properties .. program:: container set .. code:: bash os container set [--property [...] ] [] .. option:: --property Set a property on this container (repeat option to set multiple properties) .. describe:: Container to modify container show -------------- Display container details .. program:: container show .. code:: bash os container show [] .. describe:: Container to display container unset --------------- Unset container properties .. program:: container unset .. code:: bash os container unset [--property ] [] .. option:: --property Property to remove from container (repeat option to remove multiple properties) .. describe:: Container to modify python-openstackclient-2.3.1/doc/source/command-objects/credentials.rst000066400000000000000000000006141304420040500263540ustar00rootroot00000000000000=========== credentials =========== Identity v3 credentials create ------------------ .. ''[consider rolling the ec2 creds into this too]'' .. code:: bash os credentials create --x509 [] [] credentials show ---------------- .. code:: bash os credentials show [--token] [--user] [--x509 [--root]] python-openstackclient-2.3.1/doc/source/command-objects/domain.rst000066400000000000000000000030211304420040500253210ustar00rootroot00000000000000====== domain ====== Identity v3 domain create ------------- Create new domain .. program:: domain create .. code:: bash os domain create [--description ] [--enable | --disable] [--or-show] .. option:: --description New domain description .. option:: --enable Enable domain (default) .. option:: --disable Disable domain .. option:: --or-show Return existing domain If the domain already exists, return the existing domain data and do not fail. .. describe:: New domain name domain delete ------------- Delete domain .. program:: domain delete .. code:: bash os domain delete .. describe:: Domain to delete (name or ID) domain list ----------- List domains .. program:: domain list .. code:: bash os domain list domain set ---------- Set domain properties .. program:: domain set .. code:: bash os domain set [--name ] [--description ] [--enable | --disable] .. option:: --name New domain name .. option:: --description New domain description .. option:: --enable Enable domain .. option:: --disable Disable domain .. describe:: Domain to modify (name or ID) domain show ----------- Display domain details .. program:: domain show .. code:: bash os domain show .. describe:: Domain to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/ec2-credentials.rst000066400000000000000000000064151304420040500270300ustar00rootroot00000000000000=============== ec2 credentials =============== Identity v2 ec2 credentials create ---------------------- Create EC2 credentials .. program:: ec2 credentials create .. code-block:: bash os ec2 credentials create [--project ] [--user ] [--user-domain ] [--project-domain ] .. option:: --project Create credentials in project (name or ID; default: current authenticated project) .. option:: --user Create credentials for user (name or ID; default: current authenticated user) .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 The :option:`--project` and :option:`--user` options are typically only useful for admin users, but may be allowed for other users depending on the policy of the cloud and the roles granted to the user. ec2 credentials delete ---------------------- Delete EC2 credentials .. program:: ec2 credentials delete .. code-block:: bash os ec2 credentials delete [--user ] [--user-domain ] .. option:: --user Delete credentials for user (name or ID) .. option:: --user-domain Select user from a specific domain (name or ID) This can be used in case collisions between user names exist. .. versionadded:: 3 .. _ec2_credentials_delete-access-key: .. describe:: access-key Credentials access key The :option:`--user` option is typically only useful for admin users, but may be allowed for other users depending on the policy of the cloud and the roles granted to the user. ec2 credentials list -------------------- List EC2 credentials .. program:: ec2 credentials list .. code-block:: bash os ec2 credentials list [--user ] [--user-domain ] .. option:: --user Filter list by (name or ID) .. option:: --user-domain Select user from a specific domain (name or ID) This can be used in case collisions between user names exist. .. versionadded:: 3 The :option:`--user` option is typically only useful for admin users, but may be allowed for other users depending on the policy of the cloud and the roles granted to the user. ec2 credentials show -------------------- Display EC2 credentials details .. program:: ec2 credentials show .. code-block:: bash os ec2 credentials show [--user ] [--user-domain ] .. option:: --user Show credentials for user (name or ID) .. option:: --user-domain Select user from a specific domain (name or ID) This can be used in case collisions between user names exist. .. versionadded:: 3 .. _ec2_credentials_show-access-key: .. describe:: access-key Credentials access key The :option:`--user` option is typically only useful for admin users, but may be allowed for other users depending on the policy of the cloud and the roles granted to the user. python-openstackclient-2.3.1/doc/source/command-objects/endpoint.rst000066400000000000000000000057751304420040500257140ustar00rootroot00000000000000======== endpoint ======== Identity v2, v3 endpoint create --------------- Create new endpoint *Identity version 2 only* .. program:: endpoint create .. code:: bash os endpoint create --publicurl [--adminurl ] [--internalurl ] [--region ] .. option:: --publicurl New endpoint public URL (required) .. option:: --adminurl New endpoint admin URL .. option:: --internalurl New endpoint internal URL .. option:: --region New endpoint region ID .. _endpoint_create-endpoint: .. describe:: New endpoint service (name or ID) *Identity version 3 only* .. program:: endpoint create .. code:: bash os endpoint create [--region ] [--enable | --disable] .. option:: --region New endpoint region ID .. option:: --enable Enable endpoint (default) .. option:: --disable Disable endpoint .. describe:: New endpoint service (name or ID) .. describe:: New endpoint interface type (admin, public or internal) .. describe:: New endpoint URL endpoint delete --------------- Delete endpoint .. program:: endpoint delete .. code:: bash os endpoint delete .. _endpoint_delete-endpoint: .. describe:: Endpoint ID to delete endpoint list ------------- List endpoints .. program:: endpoint list .. code:: bash os endpoint list [--service ] [--region ] [--long] .. option:: --service Filter by service *Identity version 3 only* .. option:: --interface Filter by interface type (admin, public or internal) *Identity version 3 only* .. option:: --region Filter by region ID *Identity version 3 only* .. option:: --long List additional fields in output *Identity version 2 only* endpoint set ------------ Set endpoint properties *Identity version 3 only* .. program:: endpoint set .. code:: bash os endpoint set [--region ] [--interface ] [--url ] [--service ] [--enable | --disable] .. option:: --region New endpoint region ID .. option:: --interface New endpoint interface type (admin, public or internal) .. option:: --url New endpoint URL .. option:: --service New endpoint service (name or ID) .. option:: --enable Enable endpoint .. option:: --disable Disable endpoint .. _endpoint_set-endpoint: .. describe:: Endpoint ID to modify endpoint show ------------- Display endpoint details .. program:: endpoint show .. code:: bash os endpoint show .. _endpoint_show-endpoint: .. describe:: Endpoint ID to display python-openstackclient-2.3.1/doc/source/command-objects/extension.rst000066400000000000000000000012201304420040500260650ustar00rootroot00000000000000========= extension ========= Many OpenStack server APIs include API extensions that enable additional functionality. extension list -------------- List API extensions .. program:: extension list .. code:: bash os extension list [--compute] [--identity] [--network] [--volume] [--long] .. option:: --compute List extensions for the Compute API .. option:: --identity List extensions for the Identity API .. option:: --network List extensions for the Network API .. option:: --volume List extensions for the Block Storage API .. option:: --long List additional fields in output python-openstackclient-2.3.1/doc/source/command-objects/federation-protocol.rst000066400000000000000000000047731304420040500300500ustar00rootroot00000000000000=================== federation protocol =================== Identity v3 `Requires: OS-FEDERATION extension` federation protocol create -------------------------- Create new federation protocol .. program:: federation protocol create .. code:: bash os federation protocol create --identity-provider --mapping .. option:: --identity-provider Identity provider that will support the new federation protocol (name or ID) (required) .. option:: --mapping Mapping that is to be used (name or ID) (required) .. describe:: New federation protocol name (must be unique per identity provider) federation protocol delete -------------------------- Delete federation protocol .. program:: federation protocol delete .. code:: bash os federation protocol delete --identity-provider .. option:: --identity-provider Identity provider that supports (name or ID) (required) .. describe:: Federation protocol to delete (name or ID) federation protocol list ------------------------ List federation protocols .. program:: federation protocol list .. code:: bash os federation protocol list --identity-provider .. option:: --identity-provider Identity provider to list (name or ID) (required) federation protocol set ----------------------- Set federation protocol properties .. program:: federation protocol set .. code:: bash os federation protocol set --identity-provider [--mapping ] .. option:: --identity-provider Identity provider that supports (name or ID) (required) .. option:: --mapping Mapping that is to be used (name or ID) .. describe:: Federation protocol to modify (name or ID) federation protocol show ------------------------ Display federation protocol details .. program:: federation protocol show .. code:: bash os federation protocol show --identity-provider .. option:: --identity-provider Identity provider that supports (name or ID) (required) .. describe:: Federation protocol to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/flavor.rst000066400000000000000000000054131304420040500253520ustar00rootroot00000000000000====== flavor ====== Compute v2 flavor create ------------- Create new flavor .. program:: flavor create .. code:: bash os flavor create [--id ] [--ram ] [--disk ] [--ephemeral-disk ] [--swap ] [--vcpus ] [--rxtx-factor ] [--public | --private] .. option:: --id Unique flavor ID; 'auto' creates a UUID (default: auto) .. option:: --ram Memory size in MB (default 256M) .. option:: --disk Disk size in GB (default 0G) .. option:: --ephemeral-disk Ephemeral disk size in GB (default 0G) .. option:: --swap Swap space size in GB (default 0G) .. option:: --vcpus Number of vcpus (default 1) .. option:: --rxtx-factor RX/TX factor (default 1) .. option:: --public Flavor is available to other projects (default) .. option:: --private Flavor is not available to other projects .. _flavor_create-flavor-name: .. describe:: New flavor name flavor delete ------------- Delete flavor .. program:: flavor delete .. code:: bash os flavor delete .. _flavor_delete-flavor: .. describe:: Flavor to delete (name or ID) flavor list ----------- List flavors .. program:: flavor list .. code:: bash os flavor list [--public | --private | --all] [--long] [--marker ] [--limit ] .. option:: --public List only public flavors (default) .. option:: --private List only private flavors .. option:: --all List all flavors, whether public or private .. option:: --long List additional fields in output .. option:: --marker The last flavor ID of the previous page .. option:: --limit Maximum number of flavors to display flavor show ----------- Display flavor details .. program:: flavor show .. code:: bash os flavor show .. _flavor_show-flavor: .. describe:: Flavor to display (name or ID) flavor set ---------- Set flavor properties .. program:: flavor set .. code:: bash os flavor set [--property [...] ] .. option:: --property Property to add or modify for this flavor (repeat option to set multiple properties) .. describe:: Flavor to modify (name or ID) flavor unset ------------ Unset flavor properties .. program:: flavor unset .. code:: bash os flavor unset [--property [...] ] .. option:: --property Property to remove from flavor (repeat option to remove multiple properties) .. describe:: Flavor to modify (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/group.rst000066400000000000000000000104141304420040500252120ustar00rootroot00000000000000===== group ===== Identity v3 group add user -------------- Add user to group .. program:: group add user .. code:: bash os group add user [--group-domain ] [--user-domain ] .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. versionadded:: 3 .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. describe:: Group to contain (name or ID) .. describe:: User to add to (name or ID) group contains user ------------------- Check user membership in group .. program:: group contains user .. code:: bash os group contains user [--group-domain ] [--user-domain ] .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. versionadded:: 3 .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. describe:: Group to check (name or ID) .. describe:: User to check (name or ID) group create ------------ Create new group .. program:: group create .. code:: bash os group create [--domain ] [--description ] [--or-show] .. option:: --domain Domain to contain new group (name or ID) .. option:: --description New group description .. option:: --or-show Return existing group If the group already exists, return the existing group data and do not fail. .. describe:: New group name group delete ------------ Delete group .. program:: group delete .. code:: bash os group delete [--domain ] [ ...] .. option:: --domain Domain containing group(s) (name or ID) .. describe:: Group(s) to delete (name or ID) group list ---------- List groups .. program:: group list .. code:: bash os group list [--domain ] [--user [--user-domain ]] [--long] .. option:: --domain Filter group list by (name or ID) .. option:: --user Filter group list by (name or ID) .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. option:: --long List additional fields in output group remove user ----------------- Remove user from group .. program:: group remove user .. code:: bash os group remove user [--group-domain ] [--user-domain ] .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. versionadded:: 3 .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. describe:: Group containing (name or ID) .. describe:: User to remove from (name or ID) group set --------- Set group properties .. program:: group set .. code:: bash os group set [--domain ] [--name ] [--description ] .. option:: --domain Domain containing (name or ID) .. option:: --name New group name .. option:: --description New group description .. describe:: Group to modify (name or ID) group show ---------- Display group details .. program:: group show .. code:: bash os group show [--domain ] .. option:: --domain Domain containing (name or ID) .. describe:: Group to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/host.rst000066400000000000000000000006761304420040500250440ustar00rootroot00000000000000==== host ==== Compute v2 The physical computer running a hypervisor. host list --------- List all hosts .. program:: host list .. code:: bash os host list [--zone ] .. option:: --zone Only return hosts in the availability zone host show --------- Display host details .. program:: host show .. code:: bash os host show .. describe:: Name of host python-openstackclient-2.3.1/doc/source/command-objects/hypervisor-stats.rst000066400000000000000000000003401304420040500274210ustar00rootroot00000000000000================ hypervisor stats ================ Compute v2 hypervisor stats show --------------------- Display hypervisor stats details .. program:: hypervisor stats show .. code:: bash os hypervisor stats show python-openstackclient-2.3.1/doc/source/command-objects/hypervisor.rst000066400000000000000000000010221304420040500262630ustar00rootroot00000000000000========== hypervisor ========== Compute v2 hypervisor list --------------- List hypervisors .. program:: hypervisor list .. code:: bash os hypervisor list [--matching ] .. option:: --matching Filter hypervisors using substring hypervisor show --------------- Display hypervisor details .. program:: hypervisor show .. code:: bash os hypervisor show .. _hypervisor_show-flavor: .. describe:: Hypervisor to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/identity-provider.rst000066400000000000000000000047131304420040500275440ustar00rootroot00000000000000================= identity provider ================= Identity v3 `Requires: OS-FEDERATION extension` identity provider create ------------------------ Create new identity provider .. program:: identity provider create .. code:: bash os identity provider create [--remote-id [...] | --remote-id-file ] [--description ] [--enable | --disable] .. option:: --remote-id Remote IDs to associate with the Identity Provider (repeat to provide multiple values) .. option:: --remote-id-file Name of a file that contains many remote IDs to associate with the identity provider, one per line .. option:: --description New identity provider description .. option:: --enable Enable the identity provider (default) .. option:: --disable Disable the identity provider .. describe:: New identity provider name (must be unique) identity provider delete ------------------------ Delete identity provider .. program:: identity provider delete .. code:: bash os identity provider delete .. describe:: Identity provider to delete identity provider list ---------------------- List identity providers .. program:: identity provider list .. code:: bash os identity provider list identity provider set --------------------- Set identity provider properties .. program:: identity provider set .. code:: bash os identity provider set [--remote-id [...] | --remote-id-file ] [--description ] [--enable | --disable] .. option:: --remote-id Remote IDs to associate with the Identity Provider (repeat to provide multiple values) .. option:: --remote-id-file Name of a file that contains many remote IDs to associate with the identity provider, one per line .. option:: --description Set identity provider description .. option:: --enable Enable the identity provider .. option:: --disable Disable the identity provider .. describe:: Identity provider to modify identity provider show ---------------------- Display identity provider details .. program:: identity provider show .. code:: bash os identity provider show .. describe:: Identity provider to display python-openstackclient-2.3.1/doc/source/command-objects/image.rst000066400000000000000000000225571304420040500251530ustar00rootroot00000000000000====== image ====== Image v1, v2 image create ------------ *Image v1, v2* Create/upload an image .. program:: image create .. code:: bash os image create [--id ] [--store ] [--container-format ] [--disk-format ] [--size ] [--min-disk ] [--min-ram ] [--location ] [--copy-from ] [--file ] [--volume ] [--force] [--checksum ] [--protected | --unprotected] [--public | --private] [--property [...] ] [--tag [...] ] [--project [--project-domain ]] .. option:: --id Image ID to reserve .. option:: --store Upload image to this store *Image version 1 only.* .. option:: --container-format Image container format (default: bare) .. option:: --disk-format Image disk format (default: raw) .. option:: --size Image size, in bytes (only used with --location and --copy-from) *Image version 1 only.* .. option:: --min-disk Minimum disk size needed to boot image, in gigabytes .. option:: --min-ram Minimum RAM size needed to boot image, in megabytes .. option:: --location Download image from an existing URL *Image version 1 only.* .. option:: --copy-from Copy image from the data store (similar to --location) *Image version 1 only.* .. option:: --file Upload image from local file .. option:: --volume Create image from a volume .. option:: --force Force image creation if volume is in use (only meaningful with --volume) .. option:: --checksum Image hash used for verification *Image version 1 only.* .. option:: --protected Prevent image from being deleted .. option:: --unprotected Allow image to be deleted (default) .. option:: --public Image is accessible to the public .. option:: --private Image is inaccessible to the public (default) .. option:: --property Set a property on this image (repeat for multiple values) .. option:: --tag Set a tag on this image (repeat for multiple values) .. versionadded:: 2 .. option:: --project Set an alternate project on this image (name or ID). Previously known as `--owner`. .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. versionadded:: 2 .. describe:: New image name image delete ------------ Delete image(s) .. program:: image delete .. code:: bash os image delete .. describe:: Image(s) to delete (name or ID) image list ---------- List available images .. program:: image list .. code:: bash os image list [--public | --private | --shared] [--property ] [--long] [--sort [:]] [--limit ] [--marker ] .. option:: --public List only public images .. option:: --private List only private images .. option:: --shared List only shared images *Image version 2 only.* .. option:: --property Filter output based on property .. option:: --long List additional fields in output .. option:: --sort [:] Sort output by selected keys and directions(asc or desc) (default: asc), multiple keys and directions can be specified separated by comma .. option:: --limit Maximum number of images to display. .. option:: --marker The last image (name or ID) of the previous page. Display list of images after marker. Display all images if not specified. image save ---------- Save an image locally .. program:: image save .. code:: bash os image save --file .. option:: --file Downloaded image save filename (default: stdout) .. describe:: Image to save (name or ID) image set --------- *Image v1, v2* Set image properties .. program:: image set .. code:: bash os image set [--name ] [--min-disk ] [--min-ram ] [--container-format ] [--disk-format ] [--size ] [--protected | --unprotected] [--public | --private] [--store ] [--location ] [--copy-from ] [--file ] [--volume ] [--force] [--checksum ] [--stdin] [--property [...] ] [--tag [...] ] [--architecture ] [--instance-id ] [--kernel-id ] [--os-distro ] [--os-version ] [--ramdisk-id ] [--activate|--deactivate] [--project [--project-domain ]] .. option:: --name New image name .. option:: --min-disk Minimum disk size needed to boot image, in gigabytes .. option:: --min-ram Minimum RAM size needed to boot image, in megabytes .. option:: --container-format Image container format (default: bare) .. option:: --disk-format Image disk format (default: raw) .. option:: --size Size of image data (in bytes) *Image version 1 only.* .. option:: --protected Prevent image from being deleted .. option:: --unprotected Allow image to be deleted (default) .. option:: --public Image is accessible to the public .. option:: --private Image is inaccessible to the public (default) .. option:: --store Upload image to this store *Image version 1 only.* .. option:: --location Download image from an existing URL *Image version 1 only.* .. option:: --copy-from Copy image from the data store (similar to --location) *Image version 1 only.* .. option:: --file Upload image from local file *Image version 1 only.* .. option:: --volume Update image with a volume *Image version 1 only.* .. option:: --force Force image update if volume is in use (only meaningful with --volume) *Image version 1 only.* .. option:: --checksum Image hash used for verification *Image version 1 only.* .. option:: --stdin Allow to read image data from standard input *Image version 1 only.* .. option:: --property Set a property on this image (repeat option to set multiple properties) .. versionadded:: 2 .. option:: --tag Set a tag on this image (repeat for multiple values) .. versionadded:: 2 .. option:: --architecture Operating system architecture .. versionadded:: 2 .. option:: --instance-id ID of server instance used to create this image .. versionadded:: 2 .. option:: --kernel-id ID of kernel image used to boot this disk image .. versionadded:: 2 .. option:: --os-distro Operating system distribution name .. versionadded:: 2 .. option:: --os-version Operating system distribution version .. versionadded:: 2 .. option:: --ramdisk-id ID of ramdisk image used to boot this disk image .. versionadded:: 2 .. option:: --activate Activate the image. .. versionadded:: 2 .. option:: --deactivate Deactivate the image. .. versionadded:: 2 .. option:: --project Set an alternate project on this image (name or ID). Previously known as `--owner`. .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. versionadded:: 2 .. describe:: Image to modify (name or ID) image show ---------- Display image details .. program:: image show .. code:: bash os image show .. describe:: Image to display (name or ID) image add project ----------------- *Only supported for Image v2* Associate project with image .. program:: image add project .. code:: bash os image add project [--project-domain ] .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. describe:: Image to share (name or ID). .. describe:: Project to associate with image (name or ID) image remove project -------------------- *Only supported for Image v2* Disassociate project with image .. program:: image remove project .. code:: bash os image remove remove [--project-domain ] .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. describe:: Image to unshare (name or ID). .. describe:: Project to disassociate with image (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/ip-fixed.rst000066400000000000000000000012541304420040500255650ustar00rootroot00000000000000======== ip fixed ======== Compute v2 ip fixed add ------------ Add fixed IP address to server .. program:: ip fixed add .. code:: bash os ip fixed add .. describe:: Network to fetch an IP address from (name or ID) .. describe:: Server to receive the IP address (name or ID) ip fixed remove --------------- Remove fixed IP address from server .. program:: ip fixed remove .. code:: bash os ip fixed remove .. describe:: IP address to remove from server (name only) .. describe:: Server to remove the IP address from (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/ip-floating-pool.rst000066400000000000000000000003421304420040500272350ustar00rootroot00000000000000================ ip floating pool ================ Compute v2 ip floating pool list --------------------- List pools of floating IP addresses .. program:: ip floating pool list .. code:: bash os ip floating pool list python-openstackclient-2.3.1/doc/source/command-objects/ip-floating.rst000066400000000000000000000030171304420040500262700ustar00rootroot00000000000000=========== ip floating =========== Compute v2, Network v2 ip floating add --------------- Add floating IP address to server .. program:: ip floating add .. code:: bash os ip floating add .. describe:: IP address to add to server (name only) .. describe:: Server to receive the IP address (name or ID) ip floating create ------------------ Create new floating IP address .. program:: ip floating create .. code:: bash os ip floating create .. describe:: Pool to fetch IP address from (name or ID) ip floating delete ------------------ Delete floating IP .. program:: ip floating delete .. code:: bash os ip floating delete .. describe:: Floating IP to delete (IP address or ID) ip floating list ---------------- List floating IP addresses .. program:: ip floating list .. code:: bash os ip floating list ip floating remove ------------------ Remove floating IP address from server .. program:: ip floating remove .. code:: bash os ip floating remove .. describe:: IP address to remove from server (name only) .. describe:: Server to remove the IP address from (name or ID) ip floating show ---------------- Display floating IP details .. program:: ip floating show .. code:: bash os ip floating show .. describe:: Floating IP to display (IP address or ID) python-openstackclient-2.3.1/doc/source/command-objects/keypair.rst000066400000000000000000000017371304420040500255320ustar00rootroot00000000000000======= keypair ======= The badly named keypair is really the public key of an OpenSSH key pair to be used for access to created servers. Compute v2 keypair create -------------- Create new public key .. program:: keypair create .. code:: bash os keypair create [--public-key ] .. option:: --public-key Filename for public key to add .. describe:: New public key name keypair delete -------------- Delete public key .. program:: keypair delete .. code:: bash os keypair delete .. describe:: Public key to delete keypair list ------------ List public key fingerprints .. program:: keypair list .. code:: bash os keypair list keypair show ------------ Display public key details .. program:: keypair show .. code:: bash os keypair show [--public-key] .. option:: --public-key Show only bare public key .. describe:: Public key to display python-openstackclient-2.3.1/doc/source/command-objects/limits.rst000066400000000000000000000013521304420040500253600ustar00rootroot00000000000000====== limits ====== The Compute and Block Storage APIs have resource usage limits. Compute v2, Block Storage v1 limits show ----------- Show compute and block storage limits .. program:: limits show .. code:: bash os limits show --absolute [--reserved] | --rate [--project ] [--domain ] .. option:: --absolute Show absolute limits .. option:: --rate Show rate limits .. option:: --reserved Include reservations count [only valid with :option:`--absolute`] .. option:: --project Show limits for a specific project (name or ID) [only valid with --absolute] .. option:: --domain Domain that owns --project (name or ID) [only valid with --absolute] python-openstackclient-2.3.1/doc/source/command-objects/mapping.rst000066400000000000000000000023471304420040500255170ustar00rootroot00000000000000======= mapping ======= Identity v3 `Requires: OS-FEDERATION extension` mapping create -------------- Create new mapping .. program:: mapping create .. code:: bash os mapping create --rules .. option:: --rules Filename that contains a set of mapping rules (required) .. _mapping_create-mapping: .. describe:: New mapping name (must be unique) mapping delete -------------- Delete mapping .. program:: mapping delete .. code:: bash os mapping delete .. _mapping_delete-mapping: .. describe:: Mapping to delete mapping list ------------ List mappings .. program:: mapping list .. code:: bash os mapping list mapping set ----------- Set mapping properties .. program:: mapping set .. code:: bash os mapping set [--rules ] .. option:: --rules Filename that contains a new set of mapping rules .. _mapping_set-mapping: .. describe:: Mapping to modify mapping show ------------ Display mapping details .. program:: mapping show .. code:: bash os mapping show .. _mapping_show-mapping: .. describe:: Mapping to display python-openstackclient-2.3.1/doc/source/command-objects/module.rst000066400000000000000000000004201304420040500253370ustar00rootroot00000000000000====== module ====== Internal Installed Python modules in the OSC process. module list ----------- List module versions .. program:: module list .. code:: bash os module list [--all] .. option:: --all Show all modules that have version information python-openstackclient-2.3.1/doc/source/command-objects/network.rst000066400000000000000000000050441304420040500255520ustar00rootroot00000000000000======= network ======= Compute v2, Network v2 network create -------------- Create new network .. program:: network create .. code:: bash os network create [--project [--project-domain ]] [--enable | --disable] [--share | --no-share] [--availability-zone-hint ] .. option:: --project Owner's project (name or ID) (Network v2 only) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. (Network v2 only) .. option:: --enable Enable network (default) (Network v2 only) .. option:: --disable Disable network (Network v2 only) .. option:: --share Share the network between projects .. option:: --no-share Do not share the network between projects .. option:: --availability-zone-hint Availability Zone in which to create this network (requires the Network Availability Zone extension, this option can be repeated). (Network v2 only) .. option:: --subnet IPv4 subnet for fixed IPs (in CIDR notation) (Compute v2 network only) .. _network_create-name: .. describe:: New network name network delete -------------- Delete network(s) .. program:: network delete .. code:: bash os network delete [ ...] .. _network_delete-network: .. describe:: Network(s) to delete (name or ID) network list ------------ List networks .. program:: network list .. code:: bash os network list [--external] [--long] .. option:: --external List external networks .. option:: --long List additional fields in output network set ----------- Set network properties .. program:: network set .. code:: bash os network set [--name ] [--enable | --disable] [--share | --no-share] .. option:: --name Set network name .. option:: --enable Enable network .. option:: --disable Disable network .. option:: --share Share the network between projects .. option:: --no-share Do not share the network between projects .. _network_set-network: .. describe:: Network to modify (name or ID) network show ------------ Display network details .. program:: network show .. code:: bash os network show .. _network_show-network: .. describe:: Network to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/object-store-account.rst000066400000000000000000000015561304420040500301170ustar00rootroot00000000000000==================== object store account ==================== Object Storage v1 object store account set ------------------------ Set account properties .. program:: object store account set .. code:: bash os object store account set [--property [...] ] .. option:: --property Set a property on this account (repeat option to set multiple properties) object store account show ------------------------- Display account details .. program:: object store account show .. code:: bash os object store account show object store account unset -------------------------- Unset account properties .. program:: object store account unset .. code:: bash os object store account unset [--property ] .. option:: --property Property to remove from account (repeat option to remove multiple properties) python-openstackclient-2.3.1/doc/source/command-objects/object.rst000066400000000000000000000054761304420040500253400ustar00rootroot00000000000000====== object ====== Object Storage v1 object create ------------- Upload object to container .. program:: object create .. code:: bash os object create [ ...] .. describe:: Container for new object .. describe:: Local filename(s) to upload object delete ------------- Delete object from container .. program:: object delete .. code:: bash os object delete [ ...] .. describe:: Delete object(s) from .. describe:: Object(s) to delete object list ----------- List objects .. program object list .. code:: bash os object list [--prefix ] [--delimiter ] [--marker ] [--end-marker ] [--limit ] [--long] [--all] ] .. option:: --prefix Filter list using .. option:: --delimiter Roll up items with .. option:: --marker Anchor for paging .. option:: --end-marker End anchor for paging .. option:: --limit Limit number of objects returned .. option:: --long List additional fields in output .. option:: --all List all objects in (default is 10000) .. describe:: Container to list object save ----------- Save object locally .. program:: object save .. code:: bash os object save [--file ] [] [] .. option:: --file Destination filename (defaults to object name) .. describe:: Download from .. describe:: Object to save object set ---------- Set object properties .. program:: object set .. code:: bash os object set [--property [...] ] [] .. option:: --property Set a property on this object (repeat option to set multiple properties) .. describe:: Modify from .. describe:: Object to modify object show ----------- Display object details .. program:: object show .. code:: bash os object show .. describe:: Display from .. describe:: Object to display object unset ------------ Unset object properties .. program:: object unset .. code:: bash os object unset [--property ] [] .. option:: --property Property to remove from object (repeat option to remove multiple properties) .. describe:: Modify from .. describe:: Object to modify python-openstackclient-2.3.1/doc/source/command-objects/policy.rst000066400000000000000000000023321304420040500253550ustar00rootroot00000000000000====== policy ====== Identity v3 policy create ------------- Create new policy .. program:: policy create .. code:: bash os policy create [--type ] .. option:: --type New MIME type of the policy rules file (defaults to application/json) .. describe:: New serialized policy rules file policy delete ------------- Delete policy .. program:: policy delete .. code:: bash os policy delete .. describe:: Policy to delete policy list ----------- List policies .. program:: policy list .. code:: bash os policy list [--long] .. option:: --long List additional fields in output policy set ---------- Set policy properties .. program:: policy set .. code:: bash os policy set [--type ] [--rules ] .. option:: --type New MIME type of the policy rules file .. describe:: --rules New serialized policy rules file .. describe:: Policy to modify policy show ----------- Display policy details .. program:: policy show .. code:: bash os policy show .. describe:: Policy to display python-openstackclient-2.3.1/doc/source/command-objects/port.rst000066400000000000000000000006541304420040500250470ustar00rootroot00000000000000==== port ==== Network v2 port delete ----------- Delete port(s) .. program:: port delete .. code:: bash os port delete [ ...] .. _port_delete-port: .. describe:: Port(s) to delete (name or ID) port show --------- Display port details .. program:: port show .. code:: bash os port show .. _port_show-port: .. describe:: Port to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/project.rst000066400000000000000000000073121304420040500255270ustar00rootroot00000000000000======= project ======= Identity v2, v3 project create -------------- Create new project .. program:: project create .. code:: bash os project create [--domain ] [--parent ] [--description ] [--enable | --disable] [--property ] [--or-show] .. option:: --domain Domain owning the project (name or ID) .. versionadded:: 3 .. option:: --parent Parent of the project (name or ID) .. versionadded:: 3 .. option:: --description Project description .. option:: --enable Enable project (default) .. option:: --disable Disable project .. option:: --property Add a property to :ref:`\ ` (repeat option to set multiple properties) .. option:: --or-show Return existing project If the project already exists return the existing project data and do not fail. .. _project_create-name: .. describe:: New project name project delete -------------- Delete project(s) .. program:: project delete .. code:: bash os project delete [--domain ] [ ...] .. option:: --domain Domain owning :ref:`\ ` (name or ID) .. versionadded:: 3 .. _project_delete-project: .. describe:: Project to delete (name or ID) project list ------------ List projects .. program:: project list .. code:: bash os project list [--domain ] [--user ] [--long] .. option:: --domain Filter projects by :option:`\ <--domain>` (name or ID) .. versionadded:: 3 .. option:: --user Filter projects by :option:`\ <--user>` (name or ID) .. versionadded:: 3 .. option:: --long List additional fields in output project set ----------- Set project properties .. program:: project set .. code:: bash os project set [--name ] [--domain ] [--description ] [--enable | --disable] [--property ] .. option:: --name Set project name .. option:: --domain Domain owning :ref:`\ ` (name or ID) .. versionadded:: 3 .. option:: --description Set project description .. option:: --enable Enable project (default) .. option:: --disable Disable project .. option:: --property Set a property on :ref:`\ ` (repeat option to set multiple properties) *Identity version 2 only* .. _project_set-project: .. describe:: Project to modify (name or ID) project show ------------ Display project details .. program:: project show .. code:: bash os project show [--domain ] .. option:: --domain Domain owning :ref:`\ ` (name or ID) .. versionadded:: 3 .. option:: --parents Show the project\'s parents as a list .. versionadded:: 3 .. option:: --children Show project\'s subtree (children) as a list .. versionadded:: 3 .. _project_show-project: .. describe:: Project to display (name or ID) project unset ------------- Unset project properties *Identity version 2 only* .. program:: project unset .. code:: bash os project unset --property [--property ...] .. option:: --property Property key to remove from project (repeat option to remove multiple properties) .. describe:: Project to modify (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/quota.rst000066400000000000000000000064711304420040500252170ustar00rootroot00000000000000===== quota ===== Resource quotas appear in multiple APIs, OpenStackClient presents them as a single object with multiple properties. Compute v2, Block Storage v1 quota set --------- Set quotas for project .. program:: quota set .. code:: bash os quota set # Compute settings [--cores ] [--fixed-ips ] [--floating-ips ] [--injected-file-size ] [--injected-files ] [--instances ] [--key-pairs ] [--properties ] [--ram ] # Block Storage settings [--gigabytes ] [--snapshots ] [--volumes ] [--volume-type ] Set quotas for class .. code:: bash os quota set --class # Compute settings [--cores ] [--fixed-ips ] [--floating-ips ] [--injected-file-size ] [--injected-files ] [--instances ] [--key-pairs ] [--properties ] [--ram ] # Block Storage settings [--gigabytes ] [--snapshots ] [--volumes ] .. option:: --class Set quotas for ```` .. option:: --properties New value for the properties quota .. option:: --ram New value for the ram quota .. option:: --secgroup-rules New value for the secgroup-rules quota .. option:: --instances New value for the instances quota .. option:: --key-pairs New value for the key-pairs quota .. option:: --fixed-ips New value for the fixed-ips quota .. option:: --secgroups New value for the secgroups quota .. option:: --injected-file-size New value for the injected-file-size quota .. option:: --floating-ips New value for the floating-ips quota .. option:: --injected-files New value for the injected-files quota .. option:: --cores New value for the cores quota .. option:: --injected-path-size New value for the injected-path-size quota .. option:: --gigabytes New value for the gigabytes quota .. option:: --volumes New value for the volumes quota .. option:: --snapshots New value for the snapshots quota .. option:: --volume-type Set quotas for a specific quota show ---------- Show quotas for project .. program:: quota show .. code:: bash os quota show [--default] .. option:: --default Show default quotas for :ref:`\ ` .. _quota_show-project: .. describe:: Show quotas for class .. code:: bash os quota show --class .. option:: --class Show quotas for :ref:`\ ` .. _quota_show-class: .. describe:: Class to show python-openstackclient-2.3.1/doc/source/command-objects/region.rst000066400000000000000000000027221304420040500253440ustar00rootroot00000000000000====== region ====== Identity v3 region create ------------- Create new region .. program:: region create .. code:: bash os region create [--parent-region ] [--description ] .. option:: --parent-region Parent region ID .. option:: --description New region description .. _region_create-region-id: .. describe:: New region ID region delete ------------- Delete region .. program:: region delete .. code:: bash os region delete .. _region_delete-region-id: .. describe:: Region ID to delete region list ----------- List regions .. program:: region list .. code:: bash os region list [--parent-region ] .. option:: --parent-region Filter by parent region ID region set ---------- Set region properties .. program:: region set .. code:: bash os region set [--parent-region ] [--description ] .. option:: --parent-region New parent region ID .. option:: --description New region description .. _region_set-region-id: .. describe:: Region to modify region show ----------- Display region details .. program:: region show .. code:: bash os region show .. _region_show-region-id: .. describe:: Region to display python-openstackclient-2.3.1/doc/source/command-objects/request-token.rst000066400000000000000000000021271304420040500266660ustar00rootroot00000000000000============= request token ============= Identity v3 `Requires: OS-OAUTH1 extension` request token authorize ----------------------- Authorize a request token .. program:: request token authorize .. code:: bash os request token authorize --request-key --role .. option:: --request-key Request token to authorize (ID only) (required) .. option:: --role Roles to authorize (name or ID) (repeat to set multiple values) (required) request token create -------------------- Create a request token .. program:: request token create .. code:: bash os request token create --consumer-key --consumer-secret --project [--domain ] .. option:: --consumer-key Consumer key (required) .. option:: --description Consumer secret (required) .. option:: --project Project that consumer wants to access (name or ID) (required) .. option:: --domain Domain owning (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/role-assignment.rst000066400000000000000000000030251304420040500271650ustar00rootroot00000000000000=============== role assignment =============== Identity v3 role assignment list -------------------- List role assignments .. program:: role assignment list .. code:: bash os role assignment list [--role ] [--user ] [--user-domain ] [--group ] [--group-domain ] [--domain ] [--project ] [--project-domain ] [--effective] [--inherited] .. option:: --role Role to filter (name or ID) .. option:: --user User to filter (name or ID) .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. option:: --group Group to filter (name or ID) .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. option:: --domain Domain to filter (name or ID) .. option:: --project Project to filter (name or ID) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. option:: --effective Returns only effective role assignments (defaults to False) .. option:: --inherited Specifies if the role grant is inheritable to the sub projects .. option:: --names Returns role assignments with names instead of IDs python-openstackclient-2.3.1/doc/source/command-objects/role.rst000066400000000000000000000117371304420040500250300ustar00rootroot00000000000000==== role ==== Identity v2, v3 role add -------- Add role to a user or group in a project or domain .. program:: role add .. code:: bash os role add --domain | --project [--project-domain ] --user [--user-domain ] | --group [--group-domain ] --inherited .. option:: --domain Include (name or ID) .. versionadded:: 3 .. option:: --project Include (name or ID) .. option:: --user Include (name or ID) .. option:: --group Include (name or ID) .. versionadded:: 3 .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. versionadded:: 3 .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. versionadded:: 3 .. option:: --inherited Specifies if the role grant is inheritable to the sub projects. .. versionadded:: 3 .. describe:: Role to add to : (name or ID) role create ----------- Create new role .. program:: role create .. code:: bash os role create [--or-show] .. option:: --or-show Return existing role If the role already exists return the existing role data and do not fail. .. describe:: New role name role delete ----------- Delete role(s) .. program:: role delete .. code:: bash os role delete [ ...] .. describe:: Role to delete (name or ID) role list --------- List roles .. program:: role list .. code:: bash os role list --domain | --project [--project-domain ] --user [--user-domain ] | --group [--group-domain ] --inherited .. option:: --domain Filter roles by (name or ID) .. versionadded:: 3 .. option:: --project Filter roles by (name or ID) .. versionadded:: 3 .. option:: --user Filter roles by (name or ID) .. versionadded:: 3 .. option:: --group Filter roles by (name or ID) .. versionadded:: 3 .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. versionadded:: 3 .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. versionadded:: 3 .. option:: --inherited Specifies if the role grant is inheritable to the sub projects. .. versionadded:: 3 role remove ----------- Remove role from domain/project : user/group .. program:: role remove .. code:: bash os role remove --domain | --project [--project-domain ] --user [--user-domain ] | --group [--group-domain ] --inherited .. option:: --domain Include (name or ID) .. versionadded:: 3 .. option:: --project Include (name or ID) .. option:: --user Include (name or ID) .. option:: --group Include (name or ID) .. versionadded:: 3 .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. versionadded:: 3 .. option:: --group-domain Domain the group belongs to (name or ID). This can be used in case collisions between group names exist. .. versionadded:: 3 .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. versionadded:: 3 .. option:: --inherited Specifies if the role grant is inheritable to the sub projects. .. versionadded:: 3 .. describe:: Role to remove (name or ID) role set -------- Set role properties .. versionadded:: 3 .. program:: role set .. code:: bash os role set [--name ] .. option:: --name Set role name .. describe:: Role to modify (name or ID) role show --------- Display role details .. program:: role show .. code:: bash os role show .. describe:: Role to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/router.rst000066400000000000000000000050351304420040500254010ustar00rootroot00000000000000====== router ====== Network v2 router create ------------- Create new router .. program:: router create .. code:: bash os router create [--project [--project-domain ]] [--enable | --disable] [--distributed] [--availability-zone-hint ] .. option:: --project Owner's project (name or ID) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. option:: --enable Enable router (default) .. option:: --disable Disable router .. option:: --distributed Create a distributed router .. option:: --availability-zone-hint Availability Zone in which to create this router (requires the Router Availability Zone extension, this option can be repeated). .. _router_create-name: .. describe:: New router name router delete ------------- Delete router(s) .. program:: router delete .. code:: bash os router delete [ ...] .. _router_delete-router: .. describe:: Router(s) to delete (name or ID) router list ----------- List routers .. program:: router list .. code:: bash os router list [--long] .. option:: --long List additional fields in output router set ---------- Set router properties .. program:: router set .. code:: bash os router set [--name ] [--enable | --disable] [--distributed | --centralized] [--route destination=,gateway= | --clear-routes] .. option:: --name Set router name .. option:: --enable Enable router .. option:: --disable Disable router .. option:: --distributed Set router to distributed mode (disabled router only) .. option:: --centralized Set router to centralized mode (disabled router only) .. option:: --route destination=,gateway= Routes associated with the router. Repeat this option to set multiple routes. destination: destination subnet (in CIDR notation). gateway: nexthop IP address. .. option:: --clear-routes Clear routes associated with the router .. _router_set-router: .. describe:: Router to modify (name or ID) router show ----------- Display router details .. program:: router show .. code:: bash os router show .. _router_show-router: .. describe:: Router to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/security-group-rule.rst000066400000000000000000000031451304420040500300270ustar00rootroot00000000000000=================== security group rule =================== Compute v2, Network v2 security group rule create -------------------------- Create a new security group rule .. program:: security group rule create .. code:: bash os security group rule create [--proto ] [--src-ip | --src-group ] [--dst-port ] .. option:: --proto IP protocol (icmp, tcp, udp; default: tcp) .. option:: --src-ip Source IP address block (may use CIDR notation; default: 0.0.0.0/0) .. option:: --src-group Source security group (ID only) .. option:: --dst-port Destination port, may be a range: 137:139 (default: 0; only required for proto tcp and udp) .. describe:: Create rule in this security group (name or ID) security group rule delete -------------------------- Delete a security group rule .. program:: security group rule delete .. code:: bash os security group rule delete .. describe:: Security group rule to delete (ID only) security group rule list ------------------------ List security group rules .. program:: security group rule list .. code:: bash os security group rule list [] .. describe:: List all rules in this security group (name or ID) security group rule show ------------------------ Display security group rule details .. program:: security group rule show .. code:: bash os security group rule show .. describe:: Security group rule to display (ID only) python-openstackclient-2.3.1/doc/source/command-objects/security-group.rst000066400000000000000000000031631304420040500270620ustar00rootroot00000000000000============== security group ============== Compute v2, Network v2 security group create --------------------- Create a new security group .. program:: security group create .. code:: bash os security group create [--description ] .. option:: --description Security group description .. describe:: New security group name security group delete --------------------- Delete a security group .. program:: security group delete .. code:: bash os security group delete .. describe:: Security group to delete (name or ID) security group list ------------------- List security groups .. program:: security group list .. code:: bash os security group list [--all-projects] .. option:: --all-projects Display information from all projects (admin only) *Network version 2 ignores this option and will always display information* *for all projects.* security group set ------------------ Set security group properties .. program:: security group set .. code:: bash os security group set [--name ] [--description ] .. option:: --name New security group name .. option:: --description New security group description .. describe:: Security group to modify (name or ID) security group show ------------------- Display security group details .. program:: security group show .. code:: bash os security group show .. describe:: Security group to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/server-image.rst000066400000000000000000000011071304420040500264430ustar00rootroot00000000000000============ server image ============ A server image is a disk image created from a running server instance. The image is created in the Image store. Compute v2 server image create ------------------- Create a new disk image from a running server .. program:: server image create .. code:: bash os server image create [--name ] [--wait] .. option:: --name Name of new image (default is server name) .. option:: --wait Wait for image create to complete .. describe:: Server (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/server.rst000066400000000000000000000335151304420040500253730ustar00rootroot00000000000000====== server ====== Compute v2 server add security group ------------------------- Add security group to server .. program:: server add security group .. code:: bash os server add security group .. describe:: Server (name or ID) .. describe:: Security group to add (name or ID) server add volume ----------------- Add volume to server .. program:: server add volume .. code:: bash os server add volume [--device ] .. option:: --device Server internal device name for volume .. describe:: Server (name or ID) .. describe:: Volume to add (name or ID) server create ------------- Create a new server .. program:: server create .. code:: bash os server create --image | --volume --flavor [--security-group [...] ] [--key-name ] [--property [...] ] [--file ] [...] ] [--user-data ] [--availability-zone ] [--block-device-mapping [...] ] [--nic [...] ] [--hint [...] ] [--config-drive |True ] [--min ] [--max ] [--wait] .. option:: --image Create server from this image (name or ID) .. option:: --volume Create server from this volume (name or ID) .. option:: --flavor Create server with this flavor (name or ID) .. option:: --security-group Security group to assign to this server (name or ID) (repeat for multiple groups) .. option:: --key-name Keypair to inject into this server (optional extension) .. option:: --property Set a property on this server (repeat for multiple values) .. option:: --file File to inject into image before boot (repeat for multiple files) .. option:: --user-data User data file to serve from the metadata server .. option:: --availability-zone Select an availability zone for the server .. option:: --block-device-mapping Map block devices; map is ::: (optional extension) .. option:: --nic Create a NIC on the server. Specify option multiple times to create multiple NICs. Either net-id or port-id must be provided, but not both. net-id: attach NIC to network with this UUID, port-id: attach NIC to port with this UUID, v4-fixed-ip: IPv4 fixed address for NIC (optional), v6-fixed-ip: IPv6 fixed address for NIC (optional). .. option:: --hint Hints for the scheduler (optional extension) .. option:: --config-drive |True Use specified volume as the config drive, or 'True' to use an ephemeral drive .. option:: --min Minimum number of servers to launch (default=1) .. option:: --max Maximum number of servers to launch (default=1) .. option:: --wait Wait for build to complete .. describe:: New server name server delete ------------- Delete server(s) .. program:: server delete .. code:: bash os server delete [ ...] [--wait] .. option:: --wait Wait for delete to complete .. describe:: Server(s) to delete (name or ID) server dump create ------------------ Create a dump file in server(s) Trigger crash dump in server(s) with features like kdump in Linux. It will create a dump file in the server(s) dumping the server(s)' memory, and also crash the server(s). OSC sees the dump file (server dump) as a kind of resource. .. program:: server dump create .. code:: bash os server dump create [ ...] .. describe:: Server(s) to create dump file (name or ID) server list ----------- List servers .. code:: bash os server list [--reservation-id ] [--ip ] [--ip6 ] [--name ] [--instance-name ] [--status ] [--flavor ] [--image ] [--host ] [--all-projects] [--project [--project-domain ]] [--long] [--marker ] [--limit ] .. option:: --reservation-id Only return instances that match the reservation .. option:: --ip Regular expression to match IP addresses .. option:: --ip6 Regular expression to match IPv6 addresses .. option:: --name Regular expression to match names .. option:: --instance-name Regular expression to match instance name (admin only) .. option:: --status Search by server status .. option:: --flavor Search by flavor (name or ID) .. option:: --image Search by image (name or ID) .. option:: --host Search by hostname .. option:: --all-projects Include all projects (admin only) .. option:: --project Search by project (admin only) (name or ID) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. option:: --user Search by user (admin only) (name or ID) .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. .. option:: --long List additional fields in output .. option:: --marker The last server (name or ID) of the previous page. Display list of servers after marker. Display all servers if not specified. .. option:: --limit Maximum number of servers to display. If limit equals -1, all servers will be displayed. If limit is greater than 'osapi_max_limit' option of Nova API, 'osapi_max_limit' will be used instead. server lock ----------- Lock server(s). A non-admin user will not be able to execute actions .. program:: server lock .. code:: bash os server lock [ ...] .. describe:: Server(s) to lock (name or ID) server migrate -------------- Migrate server to different host .. program:: server migrate .. code:: bash os server migrate --live [--shared-migration | --block-migration] [--disk-overcommit | --no-disk-overcommit] [--wait] .. option:: --live Target hostname .. option:: --shared-migration Perform a shared live migration (default) .. option:: --block-migration Perform a block live migration .. option:: --disk-overcommit Allow disk over-commit on the destination host .. option:: --no-disk-overcommit Do not over-commit disk on the destination host (default) .. option:: --wait Wait for resize to complete .. describe:: Server to migrate (name or ID) server pause ------------ Pause server(s) .. program:: server pause .. code:: bash os server pause [ ...] .. describe:: Server(s) to pause (name or ID) server reboot ------------- Perform a hard or soft server reboot .. program:: server reboot .. code:: bash os server reboot [--hard | --soft] [--wait] .. option:: --hard Perform a hard reboot .. option:: --soft Perform a soft reboot .. option:: --wait Wait for reboot to complete .. describe:: Server (name or ID) server rebuild -------------- Rebuild server .. program:: server rebuild .. code:: bash os server rebuild [--image ] [--password ] [--wait] .. option:: --image Recreate server from the specified image (name or ID). Defaults to the currently used one. .. option:: --password Set the password on the rebuilt instance .. option:: --wait Wait for rebuild to complete .. describe:: Server (name or ID) server remove security group ---------------------------- Remove security group from server .. program:: server remove security group .. code:: bash os server remove security group .. describe:: Name or ID of server to use .. describe:: Name or ID of security group to remove from server server remove volume -------------------- Remove volume from server .. program:: server remove volume .. code:: bash os server remove volume .. describe:: Server (name or ID) .. describe:: Volume to remove (name or ID) server rescue ------------- Put server in rescue mode .. program:: server rescure .. code:: bash os server rescue .. describe:: Server (name or ID) server resize ------------- Scale server to a new flavor .. program:: server resize .. code:: bash os server resize --flavor [--wait] os server resize --confirm | --revert .. option:: --flavor Resize server to specified flavor .. option:: --confirm Confirm server resize is complete .. option:: --revert Restore server state before resize .. option:: --wait Wait for resize to complete .. describe:: Server (name or ID) A resize operation is implemented by creating a new server and copying the contents of the original disk into a new one. It is also a two-step process for the user: the first is to perform the resize, the second is to either confirm (verify) success and release the old server, or to declare a revert to release the new server and restart the old one. server resume ------------- Resume server(s) .. program:: server resume .. code:: bash os server resume [ ...] .. describe:: Server(s) to resume (name or ID) server set ---------- Set server properties .. program:: server set .. code:: bash os server set --name --property [--property ] ... --root-password .. option:: --name New server name .. option:: --root-password Set new root password (interactive only) .. option:: --property Property to add/change for this server (repeat option to set multiple properties) .. describe:: Server (name or ID) server shelve ------------- Shelve server(s) .. program:: server shelve .. code:: bash os server shelve [ ...] .. describe:: Server(s) to shelve (name or ID) server show ----------- Show server details .. program:: server show .. code:: bash os server show [--diagnostics] .. option:: --diagnostics Display server diagnostics information .. describe:: Server (name or ID) server ssh ---------- Ssh to server .. program:: server ssh .. code:: bash os server ssh [--login ] [--port ] [--identity ] [--option ] [--public | --private | --address-type ] .. option:: --login Login name (ssh -l option) .. option:: --port Destination port (ssh -p option) .. option:: --identity Private key file (ssh -i option) .. option:: --option Options in ssh_config(5) format (ssh -o option) .. option:: --public Use public IP address .. option:: --private Use private IP address .. option:: --address-type Use other IP address (public, private, etc) .. describe:: Server (name or ID) server start ------------ Start server(s) .. program:: server start .. code:: bash os server start [ ...] .. describe:: Server(s) to start (name or ID) server stop ----------- Stop server(s) .. program:: server stop .. code:: bash os server stop [ ...] .. describe:: Server(s) to stop (name or ID) server suspend -------------- Suspend server(s) .. program:: server suspend .. code:: bash os server suspend [ ...] .. describe:: Server(s) to suspend (name or ID) server unlock ------------- Unlock server(s) .. program:: server unlock .. code:: bash os server unlock [ ...] .. describe:: Server(s) to unlock (name or ID) server unpause -------------- Unpause server(s) .. program:: server unpause .. code:: bash os server unpause [ ...] .. describe:: Server(s) to unpause (name or ID) server unrescue --------------- Restore server from rescue mode .. program:: server unrescue .. code:: bash os server unrescue .. describe:: Server (name or ID) server unset ------------ Unset server properties .. program:: server unset .. code:: bash os server unset --property [--property ] ... .. option:: --property Property key to remove from server (repeat to set multiple values) .. describe:: Server (name or ID) server unshelve --------------- Unshelve server(s) .. program:: server unshelve .. code:: bash os server unshelve [ ...] .. describe:: Server(s) to unshelve (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/service-provider.rst000066400000000000000000000043551304420040500273550ustar00rootroot00000000000000================ service provider ================ Identity v3 `Requires: OS-FEDERATION extension` service provider create ----------------------- Create new service provider .. program:: service provider create .. code:: bash os service provider create [--description ] [--enable | --disable] --auth-url --service-provider-url .. option:: --auth-url Authentication URL of remote federated service provider (required) .. option:: --service-provider-url A service URL where SAML assertions are being sent (required) .. option:: --description New service provider description .. option:: --enable Enable the service provider (default) .. option:: --disable Disable the service provider .. describe:: New service provider name (must be unique) service provider delete ----------------------- Delete service provider .. program:: service provider delete .. code:: bash os service provider delete .. describe:: Service provider to delete service provider list --------------------- List service providers .. program:: service provider list .. code:: bash os service provider list service provider set -------------------- Set service provider properties .. program:: service provider set .. code:: bash os service provider set [--enable | --disable] [--description ] [--auth-url ] [--service-provider-url ] .. option:: --service-provider-url New service provider URL, where SAML assertions are sent .. option:: --auth-url New Authentication URL of remote federated service provider .. option:: --description New service provider description .. option:: --enable Enable the service provider .. option:: --disable Disable the service provider .. describe:: Service provider to modify service provider show --------------------- Display service provider details .. program:: service provider show .. code:: bash os service provider show .. describe:: Service provider to display python-openstackclient-2.3.1/doc/source/command-objects/service.rst000066400000000000000000000042511304420040500255200ustar00rootroot00000000000000======= service ======= Identity v2, v3 service create -------------- Create new service .. program:: service create .. code-block:: bash os service create [--name ] [--description ] [--enable | --disable] .. option:: --name New service name .. option:: --description New service description .. option:: --enable Enable service (default) *Identity version 3 only* .. option:: --disable Disable service *Identity version 3 only* .. _service_create-type: .. describe:: New service type (compute, image, identity, volume, etc) service delete -------------- Delete service .. program:: service delete .. code-block:: bash os service delete .. _service_delete-type: .. describe:: Service to delete (type, name or ID) service list ------------ List services .. program:: service list .. code-block:: bash os service list [--long] .. option:: --long List additional fields in output Returns service fields ID, Name and Type. :option:`--long` adds Description and Enabled (*Identity version 3 only*) to the output. service set ----------- Set service properties * Identity version 3 only* .. program:: service set .. code-block:: bash os service set [--type ] [--name ] [--description ] [--enable | --disable] .. option:: --type New service type (compute, image, identity, volume, etc) .. option:: --name New service name .. option:: --description New service description .. option:: --enable Enable service .. option:: --disable Disable service .. _service_set-service: .. describe:: Service to update (type, name or ID) service show ------------ Display service details .. program:: service show .. code-block:: bash os service show [--catalog] .. option:: --catalog Show service catalog information *Identity version 2 only* .. _service_show-service: .. describe:: Service to display (type, name or ID) python-openstackclient-2.3.1/doc/source/command-objects/snapshot.rst000066400000000000000000000043011304420040500257130ustar00rootroot00000000000000======== snapshot ======== Block Storage v1 snapshot create --------------- Create new snapshot .. program:: snapshot create .. code:: bash os snapshot create [--name ] [--description ] [--force] .. option:: --name Name of the snapshot .. option:: --description Description of the snapshot .. option:: --force Create a snapshot attached to an instance. Default is False .. _snapshot_create-snapshot: .. describe:: Volume to snapshot (name or ID) snapshot delete --------------- Delete snapshot(s) .. program:: snapshot delete .. code:: bash os snapshot delete [ ...] .. _snapshot_delete-snapshot: .. describe:: Snapshot(s) to delete (name or ID) snapshot list ------------- List snapshots .. program:: snapshot list .. code:: bash os snapshot list [--all-projects] .. option:: --all-projects Include all projects (admin only) .. option:: --long List additional fields in output snapshot set ------------ Set snapshot properties .. program:: snapshot set .. code:: bash os snapshot set [--name ] [--description ] [--property [...] ] .. _snapshot_restore-snapshot: .. option:: --name New snapshot name .. option:: --description New snapshot description .. option:: --property Property to add or modify for this snapshot (repeat option to set multiple properties) .. describe:: Snapshot to modify (name or ID) snapshot show ------------- Display snapshot details .. program:: snapshot show .. code:: bash os snapshot show .. _snapshot_show-snapshot: .. describe:: Snapshot to display (name or ID) snapshot unset -------------- Unset snapshot properties .. program:: snapshot unset .. code:: bash os snapshot unset [--property ] .. option:: --property Property to remove from snapshot (repeat option to remove multiple properties) .. describe:: Snapshot to modify (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/subnet-pool.rst000066400000000000000000000014021304420040500263220ustar00rootroot00000000000000=========== subnet pool =========== Network v2 subnet pool delete ------------------ Delete subnet pool .. program:: subnet pool delete .. code:: bash os subnet pool delete .. _subnet_pool_delete-subnet-pool: .. describe:: Subnet pool to delete (name or ID) subnet pool list ---------------- List subnet pools .. program:: subnet pool list .. code:: bash os subnet pool list [--long] .. option:: --long List additional fields in output subnet pool show ---------------- Display subnet pool details .. program:: subnet pool show .. code:: bash os subnet pool show .. _subnet_pool_show-subnet-pool: .. describe:: Subnet pool to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/subnet.rst000066400000000000000000000011621304420040500253560ustar00rootroot00000000000000====== subnet ====== Network v2 subnet delete ------------- Delete a subnet .. program:: subnet delete .. code:: bash os subnet delete .. _subnet_delete-subnet: .. describe:: Subnet to delete (name or ID) subnet list ----------- List subnets .. program:: subnet list .. code:: bash os subnet list [--long] .. option:: --long List additional fields in output subnet show ----------- Show subnet details .. program:: subnet show .. code:: bash os subnet show .. _subnet_show-subnet: .. describe:: Subnet to show (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/token.rst000066400000000000000000000004731304420040500252020ustar00rootroot00000000000000===== token ===== Identity v2, v3 token issue ----------- Issue new token .. program:: token issue .. code:: bash os token issue token revoke ------------ Revoke existing token .. program:: token revoke .. code:: bash os token revoke .. describe:: Token to be deleted python-openstackclient-2.3.1/doc/source/command-objects/trust.rst000066400000000000000000000033631304420040500252440ustar00rootroot00000000000000===== trust ===== Identity v3 trust create ------------ Create new trust .. program:: trust create .. code:: bash os trust create --project --role [--impersonate] [--expiration ] [--project-domain ] [--trustor-domain ] [--trustee-domain ] .. option:: --project Project being delegated (name or ID) (required) .. option:: --role Roles to authorize (name or ID) (repeat to set multiple values) (required) .. option:: --impersonate Tokens generated from the trust will represent (defaults to False) .. option:: --expiration Sets an expiration date for the trust (format of YYYY-mm-ddTHH:MM:SS) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between user names exist. .. option:: --trustor-domain Domain that contains (name or ID) .. option:: --trustee-domain Domain that contains (name or ID) .. describe:: User that is delegating authorization (name or ID) .. describe:: User that is assuming authorization (name or ID) trust delete ------------ Delete trust(s) .. program:: trust delete .. code:: bash os trust delete [ ...] .. describe:: Trust(s) to delete trust list ---------- List trusts .. program:: trust list .. code:: bash os trust list trust show ---------- Display trust details .. program:: trust show .. code:: bash os trust show .. describe:: Trust to display python-openstackclient-2.3.1/doc/source/command-objects/usage.rst000066400000000000000000000014711304420040500251650ustar00rootroot00000000000000===== usage ===== Compute v2 usage list ---------- List resource usage per project .. program:: usage list .. code:: bash os usage list --start --end .. option:: --start Usage range start date, ex 2012-01-20 (default: 4 weeks ago) .. option:: --end Usage range end date, ex 2012-01-20 (default: tomorrow) usage show ---------- Show resource usage for a single project .. program:: usage show .. code:: bash os usage show --project --start --end .. option:: --project Name or ID of project to show usage for .. option:: --start Usage range start date, ex 2012-01-20 (default: 4 weeks ago) .. option:: --end Usage range end date, ex 2012-01-20 (default: tomorrow) python-openstackclient-2.3.1/doc/source/command-objects/user-role.rst000066400000000000000000000005651304420040500260010ustar00rootroot00000000000000========= user role ========= Identity v2 user role list -------------- List user-role assignments *Removed in version 3.* .. program:: user role list .. code:: bash os user role list [--project ] [] .. option:: --project Filter users by `` (name or ID) .. describe:: User to list (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/user.rst000066400000000000000000000070401304420040500250350ustar00rootroot00000000000000==== user ==== Identity v2, v3 user create ----------- Create new user .. program:: user create .. code:: bash os user create [--domain ] [--project [--project-domain ]] [--password ] [--password-prompt] [--email ] [--description ] [--enable | --disable] [--or-show] .. option:: --domain Default domain (name or ID) .. versionadded:: 3 .. option:: --project Default project (name or ID) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. option:: --password Set user password .. option:: --password-prompt Prompt interactively for password .. option:: --email Set user email address .. option:: --description User description .. versionadded:: 3 .. option:: --enable Enable user (default) .. option:: --disable Disable user .. option:: --or-show Return existing user If the username already exist return the existing user data and do not fail. .. describe:: New user name user delete ----------- Delete user(s) .. program:: user delete .. code:: bash os user delete [--domain ] [ ...] .. option:: --domain Domain owning :ref:`\ ` (name or ID) .. versionadded:: 3 .. _user_delete-user: .. describe:: User to delete (name or ID) user list --------- List users .. program:: user list .. code:: bash os user list [--project ] [--domain ] [--group | --project ] [--long] .. option:: --project Filter users by `` (name or ID) .. option:: --domain Filter users by `` (name or ID) *Identity version 3 only* .. option:: --group Filter users by `` membership (name or ID) *Identity version 3 only* .. option:: --long List additional fields in output user set -------- Set user properties .. program:: user set .. code:: bash os user set [--name ] [--project [--project-domain ]] [--password ] [--email ] [--description ] [--enable|--disable] .. option:: --name Set user name .. option:: --project Set default project (name or ID) .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. .. option:: --password Set user password .. option:: --password-prompt Prompt interactively for password .. option:: --email Set user email address .. option:: --description Set user description .. versionadded:: 3 .. option:: --enable Enable user (default) .. option:: --disable Disable user .. describe:: User to modify (name or ID) user show --------- Display user details .. program:: user show .. code:: bash os user show [--domain ] .. option:: --domain Domain owning :ref:`\ ` (name or ID) .. versionadded:: 3 .. _user_show-user: .. describe:: User to display (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/volume-qos.rst000066400000000000000000000054161304420040500261730ustar00rootroot00000000000000========== volume qos ========== Block Storage v1, v2 volume qos associate -------------------- Associate a QoS specification to a volume type .. program:: volume qos associate .. code:: bash os volume qos associate .. describe:: QoS specification to modify (name or ID) .. describe:: Volume type to associate the QoS (name or ID) volume qos create ----------------- Create new QoS Specification .. program:: volume qos create .. code:: bash os volume qos create [--consumer ] [--property [...] ] .. option:: --consumer Consumer of the QoS. Valid consumers: 'front-end', 'back-end', 'both' (defaults to 'both') .. option:: --property Set a property on this QoS specification (repeat option to set multiple properties) .. describe:: New QoS specification name volume qos delete ----------------- Delete QoS specification .. program:: volume qos delete .. code:: bash os volume qos delete [ ...] .. describe:: QoS specification(s) to delete (name or ID) volume qos disassociate ----------------------- Disassociate a QoS specification from a volume type .. program:: volume qos disassoiate .. code:: bash os volume qos disassociate --volume-type | --all .. option:: --volume-type Volume type to disassociate the QoS from (name or ID) .. option:: --all Disassociate the QoS from every volume type .. describe:: QoS specification to modify (name or ID) volume qos list --------------- List QoS specifications .. program:: volume qos list .. code:: bash os volume qos list volume qos set -------------- Set QoS specification properties .. program:: volume qos set .. code:: bash os volume qos set [--property [...] ] .. option:: --property Property to add or modify for this QoS specification (repeat option to set multiple properties) .. describe:: QoS specification to modify (name or ID) volume qos show --------------- Display QoS specification details .. program:: volume qos show .. code:: bash os volume qos show .. describe:: QoS specification to display (name or ID) volume qos unset ---------------- Unset QoS specification properties .. program:: volume qos unset .. code:: bash os volume qos unset [--property ] .. option:: --property Property to remove from QoS specification (repeat option to remove multiple properties) .. describe:: QoS specification to modify (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/volume-type.rst000066400000000000000000000042361304420040500263510ustar00rootroot00000000000000=========== volume type =========== Block Storage v1, v2 volume type create ------------------ Create new volume type .. program:: volume type create .. code:: bash os volume type create [--description ] [--public | --private] [--property [...] ] .. option:: --description New volume type description .. versionadded:: 2 .. option:: --public Volume type is accessible to the public .. versionadded:: 2 .. option:: --private Volume type is not accessible to the public .. versionadded:: 2 .. option:: --property Set a property on this volume type (repeat option to set multiple properties) .. describe:: New volume type name volume type delete ------------------ Delete volume type .. program:: volume type delete .. code:: bash os volume type delete .. describe:: Volume type to delete (name or ID) volume type list ---------------- List volume types .. program:: volume type list .. code:: bash os volume type list [--long] .. option:: --long List additional fields in output volume type set --------------- Set volume type properties .. program:: volume type set .. code:: bash os volume type set [--name ] [--description ] [--property [...] ] .. option:: --name Set volume type name .. versionadded:: 2 .. option:: --description Set volume type description .. versionadded:: 2 .. option:: --property Property to add or modify for this volume type (repeat option to set multiple properties) .. describe:: Volume type to modify (name or ID) volume type unset ----------------- Unset volume type properties .. program:: volume type unset .. code:: bash os volume type unset [--property ] .. option:: --property Property to remove from volume type (repeat option to remove multiple properties) .. describe:: Volume type to modify (name or ID) python-openstackclient-2.3.1/doc/source/command-objects/volume.rst000066400000000000000000000101011304420040500253560ustar00rootroot00000000000000====== volume ====== Block Storage v1, v2 volume create ------------- Create new volume .. program:: volume create .. code:: bash os volume create --size [--snapshot ] [--description ] [--type ] [--user ] [--project ] [--availability-zone ] [--image ] [--source ] [--property [...] ] .. option:: --size (required) New volume size in GB .. option:: --snapshot Use as source of new volume .. option:: --description New volume description .. option:: --type Use as the new volume type .. option:: --user Specify an alternate user (name or ID) .. option:: --project Specify an alternate project (name or ID) .. option:: --availability-zone Create new volume in .. option:: --image Use as source of new volume (name or ID) .. option:: --source Volume to clone (name or ID) .. option:: --property Set a property on this volume (repeat option to set multiple properties) .. describe:: New volume name The :option:`--project` and :option:`--user` options are typically only useful for admin users, but may be allowed for other users depending on the policy of the cloud and the roles granted to the user. volume delete ------------- Delete volume(s) .. program:: volume delete .. code:: bash os volume delete [--force] [ ...] .. option:: --force Attempt forced removal of volume(s), regardless of state (defaults to False) .. describe:: Volume(s) to delete (name or ID) volume list ----------- List volumes .. program:: volume list .. code:: bash os volume list [--all-projects] [--project [--project-domain ]] [--user [--user-domain ]] [--name ] [--status ] [--long] .. option:: --project Filter results by project (name or ID) (admin only) *Volume version 2 only* .. option:: --project-domain Domain the project belongs to (name or ID). This can be used in case collisions between project names exist. *Volume version 2 only* .. option:: --user Filter results by user (name or ID) (admin only) *Volume version 2 only* .. option:: --user-domain Domain the user belongs to (name or ID). This can be used in case collisions between user names exist. *Volume version 2 only* .. option:: --name Filter results by volume name .. option:: --status Filter results by status .. option:: --all-projects Include all projects (admin only) .. option:: --long List additional fields in output volume set ---------- Set volume properties .. program:: volume set .. code:: bash os volume set [--name ] [--description ] [--size ] [--property [...] ] .. option:: --name New volume name .. option:: --description New volume description .. option:: --size Extend volume size in GB .. option:: --property Property to add or modify for this volume (repeat option to set multiple properties) .. describe:: Volume to modify (name or ID) volume show ----------- Show volume details .. program:: volume show .. code:: bash os volume show .. describe:: Volume to display (name or ID) volume unset ------------ Unset volume properties .. program:: volume unset .. code:: bash os volume unset [--property ] .. option:: --property Property to remove from volume (repeat option to remove multiple properties) .. describe:: Volume to modify (name or ID) python-openstackclient-2.3.1/doc/source/command-options.rst000066400000000000000000000117351304420040500241270ustar00rootroot00000000000000=============== Command Options =============== OpenStackClient commands all have a set of zero or more options unique to the command, however there are of course ways in which these options are common and consistent across all of the commands that include them. These are the set of guidelines for OSC developers that help keep the interface and commands consistent. In some cases (like the boolean variables below) we use the same pattern for defining and using options in all situations. The alternative of only using it when necessary leads to errors when copy-n-paste is used for a new command without understanding why or why not that instance is correct. General Command Options ======================= Boolean Options --------------- Boolean options for any command that sets a resource state, such as 'enabled' or 'public', shall always have both positive and negative options defined. The names of those options shall either be a naturally occurring pair of words (in English) or a positive option and a negative option with `no-` prepended (such as in the traditional GNU option usage) like `--share` and `--no-share`. In order to handle those APIs that behave differently when a field is set to `None` and when the field is not present in a passed argument list or dict, each of the boolean options shall set its own variable to `True` as part of a mutiually exclusive group, rather than the more common configuration of setting a single destination variable `True` or `False` directly. This allows us to detect the situation when neither option is present (both variables will be `False`) and act accordingly for those APIs where this matters. This also requires that each of the boolean values be tested in the `take_action()` method to correctly set (or not) the underlying API field values. .. option:: --enable Enable (default) .. option:: --disable Disable Implementation ~~~~~~~~~~~~~~ The parser declaration should look like this: .. code-block:: python enable_group = parser.add_mutually_exclusive_group() enable_group.add_argument( '--enable', action='store_true', help=_('Enable (default)'), ) enable_group.add_argument( '--disable', action='store_true', help=_('Disable '), ) An example handler in `take_action()`: .. code-block:: python # This leaves 'enabled' undefined if neither option is present if parsed_args.enable: kwargs['enabled'] = True if parsed_args.disable: kwargs['enabled'] = False Options with Choices -------------------- Some options have a specific set of values (or choices) that are valid. These choices may be validated by the CLI. If the underlying API is stable and the list of choices are unlikely to change then the CLI may validate the choices. Otherwise, the CLI must defer validation of the choices to the API. If the option has a default choice then it must be documented. Having the CLI validate choices will be faster and may provide a better error message for the user if an invalid choice is specified (for example: ``argument --test: invalid choice: 'choice4' (choose from 'choice1', 'choice2', 'choice3')``). The trade-off is that CLI changes are required in order to take advantage of new choices. Implementation ~~~~~~~~~~~~~~ An example parser declaration: .. code-block:: python choice_option.add_argument( '--test', metavar=', choices=['choice1', 'choice2', 'choice3'], help=_('Test type (choice1, choice2 or choice3)'), ) List Command Options ==================== Additional Fields ----------------- Most list commands only return a subset of the available fields by default. Additional fields are available with the `--long` option. All list commands should allow `--long` even if they return all fields by default. .. option:: --long List additional fields in output Implementation ~~~~~~~~~~~~~~ The parser declaration should look like this: .. code-block:: python parser.add_argument( '--long', action='store_true', default=False, help='List additional fields in output', ) Pagination ---------- There are many ways to do pagination, some OpenStack APIs support it, some don't. OpenStackClient attempts to define a single common way to specify pagination on the command line. .. option:: --marker Anchor for paging .. option:: --limit Limit number of returned (*integer*) Implementation ~~~~~~~~~~~~~~ The parser declaration should look like this: .. code-block:: python parser.add_argument( "--marker", metavar="", help="Anchor for paging", ) parser.add_argument( "--limit", metavar="", type=int, help="Limit the number of returned", ) python-openstackclient-2.3.1/doc/source/command-wrappers.rst000066400000000000000000000037211304420040500242730ustar00rootroot00000000000000====================== Command Class Wrappers ====================== When we want to deprecate a command, policy says we need to alert the user. We do this with a message logged at WARNING level before any command output is emitted. OpenStackClient command classes are derived from the ``cliff`` classes. Cliff uses ``setuptools`` entry points for dispatching the parsed command to the respective handler classes. This lends itself to modifying the command execution at run-time. The obvious approach to adding the deprecation message would be to just add the message to the command class ``take_action()`` method directly. But then the various deprecations are scattered throughout the code base. If we instead wrap the deprecated command class with a new class we can put all of the wrappers into a separate, dedicated module. This also lets us leave the original class unmodified and puts all of the deprecation bits in one place. This is an example of a minimal wrapper around a command class that logs a deprecation message as a warning to the user then calls the original class. * Subclass the deprecated command. * Set class attribute ``deprecated`` to ``True`` to signal cliff to not emit help text for this command. * Log the deprecation message at WARNING level and refer to the replacement for the deprecated command in the log warning message. * Change the entry point class in ``setup.cfg`` to point to the new class. Example Deprecation Class ------------------------- .. code-block:: python class ListFooOld(ListFoo): """List resources""" # This notifies cliff to not display the help for this command deprecated = True log = logging.getLogger('deprecated') def take_action(self, parsed_args): self.log.warning( "%s is deprecated, use 'foobar list'", getattr(self, 'cmd_name', 'this command'), ) return super(ListFooOld, self).take_action(parsed_args) python-openstackclient-2.3.1/doc/source/commands.rst000066400000000000000000000273641304420040500226260ustar00rootroot00000000000000================= Command Structure ================= OpenStackClient has a consistent and predictable format for all of its commands. Commands take the form:: openstack [] [] [] * 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 -------------- Global options are global in the sense that they apply to every command 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 to upper case. For example, the default value of ``--os-username`` can be set by defining the environment variable ``OS_USERNAME``. Command Object(s) and Action ---------------------------- Commands consist of an object described by one or more words followed by an action. Commands that require two objects have the primary object ahead of the action and the secondary object after the action. Any positional arguments identifying the objects shall appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)." :: Examples: .. code-block:: bash $ group add user $ volume type list # 'volume type' is a two-word single object Command Arguments and Options ----------------------------- Each command may have its own set of options distinct from the global options. They follow the same style as the global options and always appear between the command and any positional arguments the command requires. Objects ------- The objects consist of one or more 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 Volume quotas. * ``access token``: (**Identity**) long-lived OAuth-based token * ``availability zone``: (**Compute**, **Network**, **Volume**) a logical partition of hosts or block storage or network services * ``aggregate``: (**Compute**) a grouping of servers * ``backup``: (**Volume**) a volume copy * ``catalog``: (**Identity**) service catalog * ``command``: (**Internal**) installed commands in the OSC process * ``configuration``: (**Internal**) openstack client configuration * ``console log``: (**Compute**) server console text dump * ``console url``: (**Compute**) server remote console URL * ``consumer``: (**Identity**) OAuth-based delegatee * ``container``: (**Object Storage**) a grouping of objects * ``credentials``: (**Identity**) specific to identity providers * ``domain``: (**Identity**) a grouping of projects * ``ec2 credentials``: (**Identity**) AWS EC2-compatible credentials * ``endpoint``: (**Identity**) the base URL used to contact a specific service * ``extension``: (**Compute**, **Identity**, **Network**, **Volume**) OpenStack server API extensions * ``federation protocol``: (**Identity**) the underlying protocol used while federating identities * ``flavor``: (**Compute**) predefined server configurations: ram, root disk, etc * ``group``: (**Identity**) a grouping of users * ``host``: (**Compute**) - the physical computer running a hypervisor * ``hypervisor``: (**Compute**) the virtual machine manager * ``hypervisor stats``: (**Compute**) hypervisor statistics over all compute nodes * ``identity provider``: (**Identity**) a source of users and authentication * ``image``: (**Image**) a disk image * ``ip fixed``: (**Compute**, **Network**) - an internal IP address assigned to a server * ``ip floating``: (**Compute**, **Network**) - a public IP address that can be mapped to a server * ``ip floating pool``: (**Compute**, **Network**) - a pool of public IP addresses * ``keypair``: (**Compute**) an SSH public key * ``limits``: (**Compute**, **Volume**) resource usage limits * ``mapping``: (**Identity**) a definition to translate identity provider attributes to Identity concepts * ``module``: (**Internal**) - installed Python modules in the OSC process * ``network``: (**Compute**, **Network**) - a virtual network for connecting servers and other resources * ``object``: (**Object Storage**) a single file in the Object Storage * ``policy``: (**Identity**) determines authorization * ``port``: (**Network**) - a virtual port for connecting servers and other resources to a network * ``project``: (**Identity**) owns a group of resources * ``quota``: (**Compute**, **Volume**) resource usage restrictions * ``region``: (**Identity**) a subset of an OpenStack deployment * ``request token``: (**Identity**) temporary OAuth-based token * ``role``: (**Identity**) a policy object used to determine authorization * ``role assignment``: (**Identity**) a relationship between roles, users or groups, and domains or projects * ``router``: (**Network**) - a virtual router * ``security group``: (**Compute**, **Network**) - groups of network access rules * ``security group rule``: (**Compute**, **Network**) - the individual rules that define protocol/IP/port access * ``server``: (**Compute**) virtual machine instance * ``server dump``: (**Compute**) a dump file of a server created by features like kdump * ``server image``: (**Compute**) saved server disk image * ``service``: (**Identity**) a cloud service * ``service provider``: (**Identity**) a resource that consumes assertions from an ``identity provider`` * ``snapshot``: (**Volume**) a point-in-time copy of a volume * ``subnet``: (**Network**) - a contiguous range of IP addresses assigned to a network * ``subnet pool``: (**Network**) - a pool of subnets * ``token``: (**Identity**) a bearer token managed by Identity service * ``usage``: (**Compute**) display host resources being consumed * ``user``: (**Identity**) individual cloud resources users * ``user role``: (**Identity**) roles assigned to a user * ``volume``: (**Volume**) block volumes * ``volume type``: (**Volume**) deployment-specific types of volumes available Plugin Objects -------------- The following are known `Objects` used by OpenStack :doc:`plugins`. These are listed here to avoid name conflicts when creating new plugins. For a complete list check out :doc:`plugin-commands`. * ``action definition``: (**Workflow Engine (Mistral)**) * ``action execution``: (**Workflow Engine (Mistral)**) * ``baremetal``: (**Baremetal (Ironic)**) * ``congress datasource``: (**Policy (Congress)**) * ``congress driver``: (**Policy (Congress)**) * ``congress policy``: (**Policy (Congress)**) * ``congress policy rule``: (**Policy (Congress)**) * ``cron trigger``: (**Workflow Engine (Mistral)**) * ``dataprocessing data source``: (**Data Processing (Sahara)**) * ``dataprocessing image``: (**Data Processing (Sahara)**) * ``dataprocessing image tags``: (**Data Processing (Sahara)**) * ``dataprocessing plugin``: (**Data Processing (Sahara)**) * ``message-broker cluster``: (**Message Broker (Cue)**) * ``message flavor``: (**Messaging (Zaqar)**) * ``orchestration resource``: (**Orchestration (Heat)**) * ``orchestration template``: (**Orchestration (Heat)**) * ``pool``: (**Messaging (Zaqar)**) * ``ptr record``: (**DNS (Designate)**) * ``queue``: (**Messaging (Zaqar)**) * ``recordset``: (**DNS (Designate)**) * ``secret``: (**Key Manager (Barbican)**) * ``secret container``: (**Key Manager (Barbican)**) * ``secret order``: (**Key Manager (Barbican)**) * ``software config``: (**Orchestration (Heat)**) * ``software deployment``: (**Orchestration (Heat)**) * ``stack event``: (**Orchestration (Heat)**) * ``stack hook``: (**Orchestration (Heat)**) * ``stack output``: (**Orchestration (Heat)**) * ``stack resource``: (**Orchestration (Heat)**) * ``stack snapshot``: (**Orchestration (Heat)**) * ``stack template``: (**Orchestration (Heat)**) * ``task exeuction``: (**Workflow Engine (Mistral)**) * ``tld``: (**DNS (Designate)**) * ``workbook``: (**Workflow Engine (Mistral)**) * ``workflow``: (**Workflow Engine (Mistral)**) * ``workflow execution``: (**Workflow Engine (Mistral)**) * ``zone``: (**DNS (Designate)**) * ``zone blacklist``: (**DNS (Designate)**) * ``zone transfer``: (**DNS (Designate)**) 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 * ``create`` (``delete``) - create a new occurrence of the specified object * ``delete`` (``create``) - delete specific occurrences of the specified objects * ``issue`` (``revoke``) - issue a token * ``list`` - display summary information about multiple objects * ``lock`` (``unlock``) - lock one or more servers so that non-admin user won't be able to execute actions * ``migrate`` - move a server to a different host; ``--live`` performs a live migration if possible * ``pause`` (``unpause``) - stop one or more servers and leave them 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 * ``restore`` - restore a heat stack snapshot * ``resume`` (``suspend``) - return one or more suspended servers to running state * ``revoke`` (``issue``) - revoke a token * ``save`` - download an object locally * ``set`` (``unset``) - set a property on the object, formerly called metadata * ``shelve`` (``unshelve``) - shelve one or more servers * ``show`` - display detailed information about the specific object * ``start`` (``stop``) - start one or more servers * ``stop`` (``start``) - stop one or more servers * ``suspend`` (``resume``) - stop one or more servers and save to disk freeing memory * ``unlock`` (``lock``) - unlock one or more servers * ``unpause`` (``pause``) - return one or more paused servers to running state * ``unrescue`` (``rescue``) - return a server to normal boot mode * ``unset`` (``set``) - remove an attribute of the object * ``unshelve`` (``shelve``) - unshelve one or more servers 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. See :doc:`plugins` for more information. Command Entry Points -------------------- Commands are added to the client using ``setuptools`` entry points in ``setup.cfg``. There is a single common group ``openstack.cli`` for commands that are not versioned, and a group for each combination of OpenStack API and version that is supported. For example, to support Identity API v3 there is a group called ``openstack.identity.v3`` that contains the individual commands. The command entry points have the form:: action_object = fully.qualified.module.vXX.object:ActionObject For example, the ``list user`` command for the Identity API is identified in ``setup.cfg`` with:: openstack.identity.v3 = # ... list_user = openstackclient.identity.v3.user:ListUser # ... python-openstackclient-2.3.1/doc/source/conf.py000066400000000000000000000206251304420040500215630ustar00rootroot00000000000000# -*- coding: utf-8 -*- # # OpenStack Command Line Client documentation build configuration file, created # by sphinx-quickstart on Wed May 16 12:05:58 2012. # # This file is execfile()d with the current directory set to its containing # dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import os import sys import pbr.version # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))) # NOTE(blk-u): Path for our Sphinx extension, remove when # https://launchpad.net/bugs/1260495 is fixed. sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) # -- General configuration ---------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'oslosphinx', 'ext.apidoc', 'stevedore.sphinxext', ] # Add any paths that contain templates here, relative to this directory. #templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'OpenStack Command Line Client' copyright = u'2012-2013 OpenStack Foundation' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # version_info = pbr.version.VersionInfo('python-openstackclient') # # The short X.Y version. version = version_info.version_string() # The full version, including alpha/beta/rc tags. release = version_info.release_string() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = [] # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. modindex_common_prefix = ['openstackclient.'] # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. #html_theme_path = ["."] #html_theme = '_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". #html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'OpenStackCommandLineClientdoc' # -- Options for LaTeX output ------------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]) # . latex_documents = [ ('index', 'OpenStackCommandLineClient.tex', u'OpenStack Command Line Client Documentation', u'OpenStack', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output ------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ( 'man/openstack', 'openstack', u'OpenStack Command Line Client', [u'OpenStack contributors'], 1, ), ] # If true, show URL addresses after external links. #man_show_urls = False # -- Options for Texinfo output ----------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ('index', 'OpenStackCommandLineClient', u'OpenStack Command Line Client Documentation', u'OpenStack', 'OpenStackCommandLineClient', 'One line description of project.', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] # If false, no module index is generated. #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' python-openstackclient-2.3.1/doc/source/configuration.rst000066400000000000000000000143701304420040500236650ustar00rootroot00000000000000============= Configuration ============= OpenStackClient is primarily configured using command line options and environment variables. Most of those settings can also be placed into a configuration file to simplify managing multiple cloud configurations. There is a relationship between the global options, environment variables and keywords used in the configuration files that should make translation between these three areas simple. 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. The keyword names in the configurations files are derived from the global option names by dropping the ``--os-`` prefix if present. Global Options -------------- The :doc:`openstack manpage ` lists all of the global options recognized by OpenStackClient and the default authentication plugins. Environment Variables --------------------- The :doc:`openstack manpage ` also lists all of the environment variables recognized by OpenStackClient and the default authentication plugins. Configuration Files ------------------- clouds.yaml ~~~~~~~~~~~ :file:`clouds.yaml` is a configuration file that contains everything needed to connect to one or more clouds. It may contain private information and is generally considered private to a user. OpenStackClient looks for a file called :file:`clouds.yaml` in the following locations: * current directory * :file:`~/.config/openstack` * :file:`/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 interface: internal In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken from :file:`clouds-public.yaml` (see below). The first two entries are for two of the default users of the same DevStack cloud. The third entry is for a Rackspace Cloud Servers account. It is equivalent to the following options if the ``rackspace`` entry in :file:`clouds-public.yaml` (below) is present: :: --os-auth-url https://identity.api.rackspacecloud.com/v2.0/ --os-project-id 275610 --os-username openstack --os-password xyzpdq!lazydog --os-region-name DFW --os-interface internal and can be selected on the command line:: openstack --os-cloud infra server list Note that multiple regions are listed in the ``rackspace`` entry. An otherwise identical configuration is created for each region. If ``-os-region-name`` is not specified on the command line, the first region in the list is used by default. The selection of ``interface`` (as seen above in the ``rackspace`` entry) is optional. For this configuration to work, every service for this cloud instance must already be configured to support this type of interface. clouds-public.yaml ~~~~~~~~~~~~~~~~~~ :file:`clouds-public.yaml` is a configuration file that is intended to contain public information about clouds that are common across a large number of users. The idea is that :file:`clouds-public.yaml` could easily be shared among users to simplify public cloud configuration. Similar to :file:`clouds.yaml`, OpenStackClient looks for :file:`clouds-public.yaml` in the following locations: * current directory * :file:`~/.config/openstack` * :file:`/etc/openstack` The first file found wins. The keys here are referenced in :file:`clouds.yaml` ``cloud`` keys. Anything that appears in :file:`clouds.yaml` :: public-clouds: rackspace: auth: auth_url: 'https://identity.api.rackspacecloud.com/v2.0/' Debugging ~~~~~~~~~ You may find the :doc:`config show ` helpful to debug configuration issues. It will display your current configuration. Logging Settings ---------------- By setting `log_level` or `log_file` in the configuration :file:`clouds.yaml`, a user may enable additional logging:: clouds: devstack: auth: auth_url: http://192.168.122.10:35357/ project_name: demo username: demo password: 0penstack region_name: RegionOne operation_log: logging: TRUE file: /tmp/openstackclient_demo.log level: info ds-admin: auth: auth_url: http://192.168.122.10:35357/ project_name: admin username: admin password: 0penstack region_name: RegionOne log_file: /tmp/openstackclient_admin.log log_level: debug :dfn:`log_file`: ```` Full path to logging file. :dfn:`log_level`: ``error`` | ``info`` | ``debug`` If log level is not set, ``warning`` will be used. If log level is ``info``, the following information is recorded: * cloud name * user name * project name * CLI start time (logging start time) * CLI end time * CLI arguments * CLI return value * and any ``info`` messages. If log level is ``debug``, the following information is recorded: * cloud name * user name * project name * CLI start time (logging start time) * CLI end time * CLI arguments * CLI return value * API request header/body * API response header/body * and any ``debug`` messages. When a command is executed, these logs are saved every time. Recording the user operations can help to identify resource changes and provide useful information for troubleshooting. If saving the output of a single command use the `--log-file` option instead. * `--log-file ` The logging level for `--log-file` can be set by using following options. * `-v, --verbose` * `-q, --quiet` * `--debug` python-openstackclient-2.3.1/doc/source/developing.rst000066400000000000000000000076231304420040500231550ustar00rootroot00000000000000=============================== Developing with OpenStackClient =============================== Communication ------------- Meetings ========= The OpenStackClient team meets regularly on every Thursday. For details please refer to the `wiki`_. .. _`wiki`: https://wiki.openstack.org/wiki/Meetings/OpenStackClient Testing ------- Using ``tox`` ============= Before running tests, you should have ``tox`` installed and available in your environment: .. code-block:: bash $ pip install tox To execute the full suite of tests maintained within OpenStackClient, run: .. code-block:: bash $ tox .. NOTE:: The first time you run ``tox``, it will take additional time to build virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild your virtualenv in a similar manner. To run tests for one or more specific test environments (for example, the most common configuration of Python 2.7 and PEP-8), list the environments with the ``-e`` option, separated by spaces: .. code-block:: bash $ tox -e py27,pep8 See ``tox.ini`` for the full list of available test environments. Running functional tests ======================== OpenStackClient also maintains a set of functional tests that are optimally designed to be run against OpenStack's gate. Optionally, a developer may choose to run these tests against any OpenStack deployment, however depending on the services available, results will vary. To run the entire suite of functional tests: .. code-block:: bash $ tox -e functional To run a specific functional test: .. code-block:: bash $ tox -e functional -- --regex functional.tests.compute.v2.test_server Running with PDB ================ Using PDB breakpoints with ``tox`` and ``testr`` normally doesn't work since the tests fail with a `BdbQuit` exception rather than stopping at the breakpoint. To run with PDB breakpoints during testing, use the `debug` ``tox`` environment rather than ``py27``. Here's an example, passing the name of a test since you'll normally only want to run the test that hits your breakpoint: .. code-block:: bash $ tox -e debug opentackclient.tests.identity.v3.test_group For reference, the `debug` ``tox`` environment implements the instructions here: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests Building the Documentation -------------------------- The documentation is generated with Sphinx using the ``tox`` command. To create HTML docs, run the following: .. code-block:: bash $ tox -e docs The resultant HTML will be the ``doc/build/html`` directory. Release Notes ------------- The release notes for a patch should be included in the patch. See the `Project Team Guide`_ for more information on using reno in OpenStack. .. _`Project Team Guide`: http://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes If any of the following applies to the patch, a release note is required: * The deployer needs to take an action when upgrading * The plugin interface changes * A new feature is implemented * A command or option is removed * Current behavior is changed * A security bug is fixed Reno is used to generate release notes. Please read the docs for details. In summary, use .. code-block:: bash $ tox -e venv -- reno new Then edit the sample file that was created and push it with your change. To see the results: .. code-block:: bash $ git commit # Commit the change because reno scans git log. $ tox -e releasenotes Then look at the generated release notes files in releasenotes/build/html in your favorite browser. Testing new code ---------------- If a developer wants to test new code (feature, command or option) that they have written, OpenStackClient may be installed from source by running the following commands in the base directory of the project: .. code-block:: bash $ python setup.py develop or .. code-block:: bash $ pip install -e . python-openstackclient-2.3.1/doc/source/history.rst000066400000000000000000000000351304420040500225100ustar00rootroot00000000000000.. include:: ../../ChangeLog python-openstackclient-2.3.1/doc/source/humaninterfaceguide.rst000066400000000000000000000340701304420040500250240ustar00rootroot00000000000000===================== Human Interface Guide ===================== *Note: This page covers the OpenStackClient CLI only but looks familiar because it was derived from the Horizon HIG.* Overview ======== What is a HIG? The Human Interface Guidelines document was created for OpenStack developers in order to direct the creation of new OpenStackClient command interfaces. Personas ======== Personas are archetypal users of the system. Keep these types of users in mind when designing the interface. Alice the admin --------------- Alice is an administrator who is responsible for maintaining the OpenStack cloud installation. She has many years of experience with Linux systems administration. Darren the deployer ------------------- Darren is responsible for doing the initial OpenStack deployment on the host machines. Emile the end-user ------------------ Emile uses the cloud to do software development inside of the virtual machines. She uses the command-line tools because she finds it quicker than using the dashboard. Principles ========== The principles established in this section define the high-level priorities to be used when designing and evaluating interactions for the OpenStack command line interface. Principles are broad in scope and can be considered the philosophical foundation for the OpenStack experience; while they may not describe the tactical implementation of design, they should be used when deciding between multiple courses of design. A significant theme for designing for the OpenStack experience concerns focusing on common uses of the system rather than adding complexity to support functionality that is rarely used. Consistency ----------- Consistency between OpenStack experiences will ensure that the command line interface feels like a single experience instead of a jumble of disparate products. Fractured experiences only serve to undermine user expectations about how they should interact with the system, creating an unreliable user experience. To avoid this, each interaction and visual representation within the system must be used uniformly and predictably. The architecture and elements detailed in this document will provide a strong foundation for establishing a consistent experience. Example Review Criteria ~~~~~~~~~~~~~~~~~~~~~~~ * Do the command actions adhere to a consistent application of actions? * Has a new type of command subject or output been introduced? * Does the design use command elements (options and arguments) as defined? (See Core Elements.) * Can any newly proposed command elements (actions or subjects) be accomplished with existing elements? * Does the design adhere to the structural model of the core experience? (See Core Architecture.) * Are any data objects displayed or manipulated in a way contradictory to how they are handled elsewhere in the core experience? Simplicity ---------- To best support new users and create straight forward interactions, designs should be as simple as possible. When crafting new commands, designs should minimize the amount of noise present in output: large amounts of nonessential data, overabundance of possible actions, etc. Designs should focus on the intent of the command, requiring only the necessary components and either removing superfluous elements or making them accessible through optional arguments. An example of this principle occurs in OpenStack's use of tables: only the most often used columns are shown by default. Further data may be accessed through the output control options, allowing users to specify the types of data that they find useful in their day-to-day work. Example Review Criteria ~~~~~~~~~~~~~~~~~~~~~~~ * Can options be used to combine otherwise similar commands? * How many of the displayed elements are relevant to the majority of users? * If multiple actions are required for the user to complete a task, is each step required or can the process be more efficient? User-Centered Design -------------------- Commands should be design based on how a user will interact with the system and not how the system's backend is organized. While database structures and APIs may define what is possible, they often do not define good user experience; consider user goals and the way in which users will want to interact with their data, then design for these work flows and mold the interface to the user, not the user to the interface. Commands should be discoverable via the interface itself. To determine a list of available commands, use the :code:`-h` or :code:`--help` options: .. code-block:: bash $ openstack --help For help with an individual command, use the :code:`help` command: .. code-block:: bash $ openstack help server create Example Review Criteria ~~~~~~~~~~~~~~~~~~~~~~~ * How quickly can a user figure out how to accomplish a given task? * Has content been grouped and ordered according to usage relationships? * Do work flows support user goals or add complexity? Transparency ------------ Make sure users understand the current state of their infrastructure and interactions. For example, users should be able to access information about the state of each machine/virtual machine easily, without having to actively seek out this information. Whenever the user initiates an action, make sure a confirmation is displayed[1] to show that an input has been received. Upon completion of a process, make sure the user is informed. Ensure that the user never questions the state of their environment. [1] This goes against the common UNIX philosophy of only reporting error conditions and output that is specifically requested. Example Review Criteria ~~~~~~~~~~~~~~~~~~~~~~~ * Does the user receive feedback when initiating a process? * When a process is completed? * Does the user have quick access to the state of their infrastructure? Architecture ============ Command Structure ----------------- OpenStackClient has a consistent and predictable format for all of its commands. * The top level command name is :code:`openstack` * Sub-commands take the form: .. code-block:: bash openstack [] [] [] Subcommands shall have three distinct parts to its commands (in order that they appear): * global options * command object(s) and action * command options and arguments Output formats: * user-friendly tables with headers, etc * machine-parsable delimited Notes: * All long options names shall begin with two dashes ('--') and use a single dash ('-') internally between words (:code:`--like-this`). Underscores ('_') shall not be used in option names. * Authentication options conform to the common CLI authentication guidelines in :doc:`authentication`. Global Options ~~~~~~~~~~~~~~ Global options are global in the sense that they apply to every command 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 to upper case. For example, :code:`--os-username` can be set from the environment via :code:`OS_USERNAME`. --help ++++++ The standard :code:`--help` global option displays the documentation for invoking the program and a list of the available commands on standard output. All other options and commands are ignored when this is present. The traditional short form help option (:code:`-h`) is also available. --version +++++++++ The standard :code:`--version` option displays the name and version on standard output. All other options and commands are ignored when this is present. Command Object(s) and Action ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Commands consist of an object described by one or more words followed by an action. Commands that require two objects have the primary object ahead of the action and the secondary object after the action. Any positional arguments identifying the objects shall appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)." [] Examples: * :code:`group add user ` * :code:`volume type list` # Note that :code:`volume type` is a two-word single object The :code:`help` command is unique as it appears in front of a normal command and displays the help text for that command rather than execute it. Object names are always specified in command in their singular form. This is contrary to natural language use. Command Arguments and Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each command may have its own set of options distinct from the global options. They follow the same style as the global options and always appear between the command and any positional arguments the command requires. Option Forms ++++++++++++ * **boolean**: boolean options shall use a form of :code:`--|--` (preferred) or :code:`--