summaryrefslogtreecommitdiff
path: root/README.rst
blob: 153b500cd5946ba4c828ffa4fe14328c87060e83 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
Python bindings to the OpenStack Identity API (Keystone)
========================================================

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
(``keystone``).

Development takes place via the usual OpenStack processes as outlined in the
`OpenStack wiki <http://wiki.openstack.org/HowToContribute>`_.  The master
repository is on `GitHub <http://github.com/openstack/python-keystoneclient>`_.

This code is a fork of `Rackspace's python-novaclient
<http://github.com/rackspace/python-novaclient>`_ which is in turn a fork of
`Jacobian's python-cloudservers
<http://github.com/jacobian/python-cloudservers>`_. ``python-keystoneclient``
is licensed under the Apache License like the rest of OpenStack.

.. contents:: Contents:
   :local:

Python API
----------

By way of a quick-start::

    # use v2.0 auth with http://example.com:5000/v2.0
    >>> from keystoneclient.v2_0 import client
    >>> keystone = client.Client(username=USERNAME, password=PASSWORD, tenant_name=TENANT, auth_url=AUTH_URL)
    >>> keystone.tenants.list()
    >>> tenant = keystone.tenants.create(tenant_name="test", description="My new tenant!", enabled=True)
    >>> tenant.delete()


Command-line API
----------------

Installing this package gets you a shell command, ``keystone``, that you can
use to interact with OpenStack's Identity API.

You'll need to provide your OpenStack tenant, username and password. You can do
this with the ``--os-tenant-name``, ``--os-username`` and ``--os-password``
params, but it's easier to just set them as environment variables::

    export OS_TENANT_NAME=project
    export OS_USERNAME=user
    export OS_PASSWORD=pass

You will also need to define the authentication url with ``--os-auth-url`` and
the version of the API with ``--os-identity-api-version``.  Or set them as an
environment variables as well::

    export OS_AUTH_URL=http://example.com:5000/v2.0
    export OS_IDENTITY_API_VERSION=2.0

Alternatively, to bypass username/password authentication, you can provide a
pre-established token. In Keystone, this approach is necessary to bootstrap the
service with an administrative user, tenant & role (to do so, provide the
client with the value of your ``admin_token`` defined in ``keystone.conf`` in
addition to the URL of your admin API deployment, typically on port 35357)::

    export OS_SERVICE_TOKEN=thequickbrownfox-jumpsover-thelazydog
    export OS_SERVICE_ENDPOINT=http://example.com:35357/v2.0

Since the Identity service can return multiple regions in the service catalog,
you can specify the one you want with ``--os-region-name`` (or ``export
OS_REGION_NAME``)::

    export OS_REGION_NAME=north

.. 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.

If you need to connect to a server that is TLS-enabled (the auth URL begins
with 'https') and it uses a certificate from a private CA or a self-signed
certificate you will need to specify the path to an appropriate CA certificate
to use to validate the server certificate with ``--os-cacert`` or an
environment variable::

    export OS_CACERT=/etc/ssl/my-root-cert.pem

Certificate verification can be turned off using ``--insecure``. This should
be used with caution.

You'll find complete documentation on the shell by running ``keystone help``::

    usage: keystone [--version] [--timeout <seconds>]
                    [--os-username <auth-user-name>]
                    [--os-password <auth-password>]
                    [--os-tenant-name <auth-tenant-name>]
                    [--os-tenant-id <tenant-id>] [--os-auth-url <auth-url>]
                    [--os-region-name <region-name>]
                    [--os-identity-api-version <identity-api-version>]
                    [--os-token <service-token>]
                    [--os-endpoint <service-endpoint>]
                    [--os-cacert <ca-certificate>] [--insecure]
                    [--os-cert <certificate>] [--os-key <key>] [--os-cache]
                    [--force-new-token] [--stale-duration <seconds>]
                    <subcommand> ...

    Command-line interface to the OpenStack Identity API.

    Positional arguments:
    <subcommand>
        catalog
        ec2-credentials-create
                            Create EC2-compatible credentials for user per tenant
        ec2-credentials-delete
                            Delete EC2-compatible credentials
        ec2-credentials-get
                            Display EC2-compatible credentials
        ec2-credentials-list
                            List EC2-compatible credentials for a user
        endpoint-create     Create a new endpoint associated with a service
        endpoint-delete     Delete a service endpoint
        endpoint-get
        endpoint-list       List configured service endpoints
        password-update     Update own password
        role-create         Create new role
        role-delete         Delete role
        role-get            Display role details
        role-list           List all roles
        service-create      Add service to Service Catalog
        service-delete      Delete service from Service Catalog
        service-get         Display service from Service Catalog
        service-list        List all services in Service Catalog
        tenant-create       Create new tenant
        tenant-delete       Delete tenant
        tenant-get          Display tenant details
        tenant-list         List all tenants
        tenant-update       Update tenant name, description, enabled status
        token-get
        user-create         Create new user
        user-delete         Delete user
        user-get            Display user details.
        user-list           List users
        user-password-update
                            Update user password
        user-role-add       Add role to user
        user-role-list      List roles granted to a user
        user-role-remove    Remove role from user
        user-update         Update user's name, email, and enabled status
        discover            Discover Keystone servers, supported API versions and
                            extensions.
        bootstrap           Grants a new role to a new user on a new tenant, after
                            creating each.
        bash-completion     Prints all of the commands and options to stdout.
        help                Display help about this program or one of its
                            subcommands.

    Optional arguments:
    --version               Shows the client version and exits
    --timeout <seconds>     Set request timeout (in seconds)
    --os-username <auth-user-name>
                            Name used for authentication with the OpenStack
                            Identity service. Defaults to env[OS_USERNAME]
    --os-password <auth-password>
                            Password used for authentication with the OpenStack
                            Identity service. Defaults to env[OS_PASSWORD]
    --os-tenant-name <auth-tenant-name>
                            Tenant to request authorization on. Defaults to
                            env[OS_TENANT_NAME]
    --os-tenant-id <tenant-id>
                            Tenant to request authorization on. Defaults to
                            env[OS_TENANT_ID]
    --os-auth-url <auth-url>
                            Specify the Identity endpoint to use for
                            authentication. Defaults to env[OS_AUTH_URL]
    --os-region-name <region-name>
                            Defaults to env[OS_REGION_NAME]
    --os-identity-api-version <identity-api-version>
                            Defaults to env[OS_IDENTITY_API_VERSION] or 2.0
    --os-token <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>
                            Specify an endpoint to use instead of retrieving one
                            from the service catalog (via authentication).
                            Defaults to env[OS_SERVICE_ENDPOINT]
    --os-cacert <ca-certificate>
                            Specify a CA bundle file to use in verifying a TLS
                            (https) server certificate. Defaults to env[OS_CACERT]
    --insecure              Explicitly allow keystoneclient to perform "insecure"
                            TLS (https) requests. The server's certificate will
                            not be verified against any certificate authorities.
                            This option should be used with caution.
    --os-cert <certificate>
                            Defaults to env[OS_CERT]
    --os-key <key>          Defaults to env[OS_KEY]
    --os-cache              Use the auth token cache. Defaults to env[OS_CACHE]
    --force-new-token       If the keyring is available and in use, token will
                            always be stored and fetched from the keyring until
                            the token has expired. Use this option to request a
                            new token and replace the existing one in the keyring.
    --stale-duration <seconds>
                            Stale duration (in seconds) used to determine whether
                            a token has expired when retrieving it from keyring.
                            This is useful in mitigating process or network
                            delays. Default is 30 seconds.

    See "keystone help COMMAND" for help on a specific command.