Merge "Update README and CLI help"
This commit is contained in:
Jenkins
83
README.rst
83
README.rst
@@ -5,15 +5,15 @@ This is a client for the OpenStack Identity API, implemented by Keystone.
|
|||||||
There's a Python API (the ``keystoneclient`` module), and a command-line script
|
There's a Python API (the ``keystoneclient`` module), and a command-line script
|
||||||
(``keystone``).
|
(``keystone``).
|
||||||
|
|
||||||
Development takes place via the usual OpenStack processes as outlined in
|
Development takes place via the usual OpenStack processes as outlined in the
|
||||||
the `OpenStack wiki`_. The master repository is on GitHub__.
|
`OpenStack wiki`_. The master repository is on GitHub__.
|
||||||
|
|
||||||
__ http://wiki.openstack.org/HowToContribute
|
__ http://wiki.openstack.org/HowToContribute
|
||||||
__ http://github.com/openstack/python-keystoneclient
|
__ http://github.com/openstack/python-keystoneclient
|
||||||
|
|
||||||
This code a fork of `Rackspace's python-novaclient`__ which is in turn a fork of
|
This code a fork of `Rackspace's python-novaclient`__ which is in turn a fork
|
||||||
`Jacobian's python-cloudservers`__. The python-keystoneclient is licensed under
|
of `Jacobian's python-cloudservers`__. The python-keystoneclient is licensed
|
||||||
the Apache License like the rest of OpenStack.
|
under the Apache License like the rest of OpenStack.
|
||||||
|
|
||||||
__ http://github.com/rackspace/python-novaclient
|
__ http://github.com/rackspace/python-novaclient
|
||||||
__ http://github.com/jacobian/python-cloudservers
|
__ http://github.com/jacobian/python-cloudservers
|
||||||
@@ -37,40 +37,45 @@ By way of a quick-start::
|
|||||||
Command-line API
|
Command-line API
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
Installing this package gets you a shell command, ``keystone``, that you
|
Installing this package gets you a shell command, ``keystone``, that you can
|
||||||
can use to interact with OpenStack's Identity API.
|
use to interact with OpenStack's Identity API.
|
||||||
|
|
||||||
You'll need to provide your OpenStack tenant, username and password. You can
|
You'll need to provide your OpenStack tenant, username and password. You can do
|
||||||
do this with the ``--os-tenant-name``, ``--os-username`` and ``--os-password``
|
this with the ``--os-tenant-name``, ``--os-username`` and ``--os-password``
|
||||||
params, but it's easier to just set them as environment variables::
|
params, but it's easier to just set them as environment variables::
|
||||||
|
|
||||||
export OS_TENANT_NAME=project
|
export OS_TENANT_NAME=project
|
||||||
export OS_USERNAME=user
|
export OS_USERNAME=user
|
||||||
export OS_PASSWORD=pass
|
export OS_PASSWORD=pass
|
||||||
|
|
||||||
You will also need to define the authentication url with ``--os-auth-url`` and the
|
You will also need to define the authentication url with ``--os-auth-url`` and
|
||||||
version of the API with ``--os-identity-api-version``. Or set them as an environment
|
the version of the API with ``--os-identity-api-version``. Or set them as an
|
||||||
variables as well::
|
environment variables as well::
|
||||||
|
|
||||||
export OS_AUTH_URL=http://example.com:5000/v2.0
|
export OS_AUTH_URL=http://example.com:5000/v2.0
|
||||||
export OS_IDENTITY_API_VERSION=2.0
|
export OS_IDENTITY_API_VERSION=2.0
|
||||||
|
|
||||||
Alternatively, to authenticate to Keystone without a username/password,
|
Alternatively, to bypass username/password authentication, you can provide a
|
||||||
such as when there are no users in the database yet, use the service
|
pre-established token. In Keystone, this approach is necessary to bootstrap the
|
||||||
token and endpoint arguemnts. The service token is set in keystone.conf as
|
service with an administrative user, tenant & role (to do so, provide the
|
||||||
``admin_token``; set it with ``service_token``. Note: keep the service token
|
client with the value of your ``admin_token`` defined in ``keystone.conf`` in
|
||||||
secret as it allows total access to Keystone's database. The admin endpoint is set
|
addition to the URL of your admin API deployment, typically on port 35357)::
|
||||||
with ``--endpoint`` or ``SERVICE_ENDPOINT``::
|
|
||||||
|
|
||||||
export SERVICE_TOKEN=thequickbrownfox-jumpsover-thelazydog
|
export OS_SERVICE_TOKEN=thequickbrownfox-jumpsover-thelazydog
|
||||||
export SERVICE_ENDPOINT=http://example.com:35357/v2.0
|
export OS_SERVICE_ENDPOINT=http://example.com:35357/v2.0
|
||||||
|
|
||||||
Since Keystone can return multiple regions in the Service Catalog, you
|
Since the Identity service can return multiple regions in the service catalog,
|
||||||
can specify the one you want with ``--region_name`` (or
|
you can specify the one you want with ``--os-region-name`` (or ``export
|
||||||
``export OS_REGION_NAME``). It defaults to the first in the list returned.
|
OS_REGION_NAME``)::
|
||||||
|
|
||||||
You'll find complete documentation on the shell by running
|
export OS_REGION_NAME=north
|
||||||
``keystone help``::
|
|
||||||
|
.. WARNING::
|
||||||
|
|
||||||
|
If a region is not specified and multiple regions are returned by the
|
||||||
|
Identity service, the client may not access the same region consistently.
|
||||||
|
|
||||||
|
You'll find complete documentation on the shell by running ``keystone help``::
|
||||||
|
|
||||||
usage: keystone [--os-username <auth-user-name>]
|
usage: keystone [--os-username <auth-user-name>]
|
||||||
[--os-password <auth-password>]
|
[--os-password <auth-password>]
|
||||||
@@ -81,8 +86,7 @@ You'll find complete documentation on the shell by running
|
|||||||
[--os-token <service-token>]
|
[--os-token <service-token>]
|
||||||
[--os-endpoint <service-endpoint>]
|
[--os-endpoint <service-endpoint>]
|
||||||
[--os-cacert <ca-certificate>] [--os-cert <certificate>]
|
[--os-cacert <ca-certificate>] [--os-cert <certificate>]
|
||||||
[--os-key <key>] [--insecure] [--token <service-token>]
|
[--os-key <key>] [--insecure]
|
||||||
[--endpoint <service-endpoint>]
|
|
||||||
<subcommand> ...
|
<subcommand> ...
|
||||||
|
|
||||||
Command-line interface to the OpenStack Identity API.
|
Command-line interface to the OpenStack Identity API.
|
||||||
@@ -136,22 +140,31 @@ You'll find complete documentation on the shell by running
|
|||||||
|
|
||||||
Optional arguments:
|
Optional arguments:
|
||||||
--os-username <auth-user-name>
|
--os-username <auth-user-name>
|
||||||
Defaults to env[OS_USERNAME]
|
Name used for authentication with the OpenStack
|
||||||
|
Identity service. Defaults to env[OS_USERNAME]
|
||||||
--os-password <auth-password>
|
--os-password <auth-password>
|
||||||
Defaults to env[OS_PASSWORD]
|
Password used for authentication with the OpenStack
|
||||||
|
Identity service. Defaults to env[OS_PASSWORD]
|
||||||
--os-tenant-name <auth-tenant-name>
|
--os-tenant-name <auth-tenant-name>
|
||||||
Defaults to env[OS_TENANT_NAME]
|
Tenant to request authorization on. Defaults to
|
||||||
|
env[OS_TENANT_NAME]
|
||||||
--os-tenant-id <tenant-id>
|
--os-tenant-id <tenant-id>
|
||||||
Defaults to env[OS_TENANT_ID]
|
Tenant to request authorization on. Defaults to
|
||||||
|
env[OS_TENANT_ID]
|
||||||
--os-auth-url <auth-url>
|
--os-auth-url <auth-url>
|
||||||
Defaults to env[OS_AUTH_URL]
|
Specify the Identity endpoint to use for
|
||||||
|
authentication. Defaults to env[OS_AUTH_URL]
|
||||||
--os-region-name <region-name>
|
--os-region-name <region-name>
|
||||||
Defaults to env[OS_REGION_NAME]
|
Defaults to env[OS_REGION_NAME]
|
||||||
--os-identity-api-version <identity-api-version>
|
--os-identity-api-version <identity-api-version>
|
||||||
Defaults to env[OS_IDENTITY_API_VERSION] or 2.0
|
Defaults to env[OS_IDENTITY_API_VERSION] or 2.0
|
||||||
--os-token <service-token>
|
--os-token <service-token>
|
||||||
Defaults to env[OS_SERVICE_TOKEN]
|
Specify an existing token to use instead of retrieving
|
||||||
|
one via authentication (e.g. with username &
|
||||||
|
password). Defaults to env[OS_SERVICE_TOKEN]
|
||||||
--os-endpoint <service-endpoint>
|
--os-endpoint <service-endpoint>
|
||||||
|
Specify an endpoint to use instead of retrieving one
|
||||||
|
from the service catalog (via authentication).
|
||||||
Defaults to env[OS_SERVICE_ENDPOINT]
|
Defaults to env[OS_SERVICE_ENDPOINT]
|
||||||
--os-cacert <ca-certificate>
|
--os-cacert <ca-certificate>
|
||||||
Defaults to env[OS_CACERT]
|
Defaults to env[OS_CACERT]
|
||||||
@@ -162,9 +175,5 @@ You'll find complete documentation on the shell by running
|
|||||||
SSL (https) requests. The server's certificate will
|
SSL (https) requests. The server's certificate will
|
||||||
not be verified against any certificate authorities.
|
not be verified against any certificate authorities.
|
||||||
This option should be used with caution.
|
This option should be used with caution.
|
||||||
--token <service-token>
|
|
||||||
Deprecated. use --os-token
|
|
||||||
--endpoint <service-endpoint>
|
|
||||||
Deprecated. use --os-endpoint
|
|
||||||
|
|
||||||
See "keystone help COMMAND" for help on a specific command.
|
See "keystone help COMMAND" for help on a specific command.
|
||||||
|
|||||||
@@ -71,35 +71,43 @@ class OpenStackIdentityShell(object):
|
|||||||
parser.add_argument('--os-username',
|
parser.add_argument('--os-username',
|
||||||
metavar='<auth-user-name>',
|
metavar='<auth-user-name>',
|
||||||
default=env('OS_USERNAME'),
|
default=env('OS_USERNAME'),
|
||||||
help='Defaults to env[OS_USERNAME]')
|
help='Name used for authentication with the '
|
||||||
|
'OpenStack Identity service. '
|
||||||
|
'Defaults to env[OS_USERNAME]')
|
||||||
parser.add_argument('--os_username',
|
parser.add_argument('--os_username',
|
||||||
help=argparse.SUPPRESS)
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
parser.add_argument('--os-password',
|
parser.add_argument('--os-password',
|
||||||
metavar='<auth-password>',
|
metavar='<auth-password>',
|
||||||
default=env('OS_PASSWORD'),
|
default=env('OS_PASSWORD'),
|
||||||
help='Defaults to env[OS_PASSWORD]')
|
help='Password used for authentication with the '
|
||||||
|
'OpenStack Identity service. '
|
||||||
|
'Defaults to env[OS_PASSWORD]')
|
||||||
parser.add_argument('--os_password',
|
parser.add_argument('--os_password',
|
||||||
help=argparse.SUPPRESS)
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
parser.add_argument('--os-tenant-name',
|
parser.add_argument('--os-tenant-name',
|
||||||
metavar='<auth-tenant-name>',
|
metavar='<auth-tenant-name>',
|
||||||
default=env('OS_TENANT_NAME'),
|
default=env('OS_TENANT_NAME'),
|
||||||
help='Defaults to env[OS_TENANT_NAME]')
|
help='Tenant to request authorization on. '
|
||||||
|
'Defaults to env[OS_TENANT_NAME]')
|
||||||
parser.add_argument('--os_tenant_name',
|
parser.add_argument('--os_tenant_name',
|
||||||
help=argparse.SUPPRESS)
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
parser.add_argument('--os-tenant-id',
|
parser.add_argument('--os-tenant-id',
|
||||||
metavar='<tenant-id>',
|
metavar='<tenant-id>',
|
||||||
default=env('OS_TENANT_ID'),
|
default=env('OS_TENANT_ID'),
|
||||||
help='Defaults to env[OS_TENANT_ID]')
|
help='Tenant to request authorization on. '
|
||||||
|
'Defaults to env[OS_TENANT_ID]')
|
||||||
parser.add_argument('--os_tenant_id',
|
parser.add_argument('--os_tenant_id',
|
||||||
help=argparse.SUPPRESS)
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
parser.add_argument('--os-auth-url',
|
parser.add_argument('--os-auth-url',
|
||||||
metavar='<auth-url>',
|
metavar='<auth-url>',
|
||||||
default=env('OS_AUTH_URL'),
|
default=env('OS_AUTH_URL'),
|
||||||
help='Defaults to env[OS_AUTH_URL]')
|
help='Specify the Identity endpoint to use for '
|
||||||
|
'authentication. '
|
||||||
|
'Defaults to env[OS_AUTH_URL]')
|
||||||
parser.add_argument('--os_auth_url',
|
parser.add_argument('--os_auth_url',
|
||||||
help=argparse.SUPPRESS)
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
@@ -122,12 +130,18 @@ class OpenStackIdentityShell(object):
|
|||||||
parser.add_argument('--os-token',
|
parser.add_argument('--os-token',
|
||||||
metavar='<service-token>',
|
metavar='<service-token>',
|
||||||
default=env('OS_SERVICE_TOKEN'),
|
default=env('OS_SERVICE_TOKEN'),
|
||||||
help='Defaults to env[OS_SERVICE_TOKEN]')
|
help='Specify an existing token to use instead of '
|
||||||
|
'retrieving one via authentication (e.g. '
|
||||||
|
'with username & password). '
|
||||||
|
'Defaults to env[OS_SERVICE_TOKEN]')
|
||||||
|
|
||||||
parser.add_argument('--os-endpoint',
|
parser.add_argument('--os-endpoint',
|
||||||
metavar='<service-endpoint>',
|
metavar='<service-endpoint>',
|
||||||
default=env('OS_SERVICE_ENDPOINT'),
|
default=env('OS_SERVICE_ENDPOINT'),
|
||||||
help='Defaults to env[OS_SERVICE_ENDPOINT]')
|
help='Specify an endpoint to use instead of '
|
||||||
|
'retrieving one from the service catalog '
|
||||||
|
'(via authentication). '
|
||||||
|
'Defaults to env[OS_SERVICE_ENDPOINT]')
|
||||||
|
|
||||||
parser.add_argument('--os-cacert',
|
parser.add_argument('--os-cacert',
|
||||||
metavar='<ca-certificate>',
|
metavar='<ca-certificate>',
|
||||||
@@ -153,26 +167,25 @@ class OpenStackIdentityShell(object):
|
|||||||
parser.add_argument('--insecure',
|
parser.add_argument('--insecure',
|
||||||
default=False,
|
default=False,
|
||||||
action="store_true",
|
action="store_true",
|
||||||
help="Explicitly allow keystoneclient to perform "
|
help='Explicitly allow keystoneclient to perform '
|
||||||
"\"insecure\" SSL (https) requests. The "
|
'"insecure" SSL (https) requests. The '
|
||||||
"server's certificate will not be verified "
|
'server\'s certificate will not be verified '
|
||||||
"against any certificate authorities. This "
|
'against any certificate authorities. This '
|
||||||
"option should be used with caution.")
|
'option should be used with caution.')
|
||||||
|
|
||||||
#FIXME(heckj):
|
#FIXME(heckj):
|
||||||
# deprecated command line options for essex compatibility. To be
|
# deprecated command line options for essex compatibility. To be
|
||||||
# removed in Grizzly release cycle.
|
# removed in Grizzly release cycle.
|
||||||
|
|
||||||
parser.add_argument('--token',
|
parser.add_argument('--token',
|
||||||
metavar='<service-token>',
|
metavar='<service-token>',
|
||||||
dest='os_token',
|
dest='os_token',
|
||||||
default=env('SERVICE_TOKEN'),
|
default=env('SERVICE_TOKEN'),
|
||||||
help='Deprecated. use --os-token')
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
parser.add_argument('--endpoint',
|
parser.add_argument('--endpoint',
|
||||||
dest='os_endpoint',
|
dest='os_endpoint',
|
||||||
metavar='<service-endpoint>',
|
metavar='<service-endpoint>',
|
||||||
default=env('SERVICE_ENDPOINT'),
|
default=env('SERVICE_ENDPOINT'),
|
||||||
help='Deprecated. use --os-endpoint')
|
help=argparse.SUPPRESS)
|
||||||
|
|
||||||
return parser
|
return parser
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user