1OPENSTACK(1)             OpenStack Command Line Client            OPENSTACK(1)
2
3
4

NAME

6       openstack - OpenStack Command Line Client
7
8       OpenStack Command Line
9

SYNOPSIS

11       openstack [<global-options>] <command> [<command-arguments>]
12
13       openstack help <command>
14
15       openstack --help
16

DESCRIPTION

18       openstack  provides  a common command-line interface to OpenStack APIs.
19       It is generally equivalent  to  the  CLIs  provided  by  the  OpenStack
20       project  client  libraries,  but with a distinct and consistent command
21       structure.
22

AUTHENTICATION METHODS

24       openstack uses a similar authentication scheme as the OpenStack project
25       CLIs,  with  the  credential information supplied either as environment
26       variables or as options on the command line.  The primary difference is
27       the    use    of    'project'    in    the    name   of   the   options
28       OS_PROJECT_NAME/OS_PROJECT_ID over the old tenant-based names.
29
30          export OS_AUTH_URL=<url-to-openstack-identity>
31          export OS_PROJECT_NAME=<project-name>
32          export OS_USERNAME=<user-name>
33          export OS_PASSWORD=<password>  # (optional)
34
35       openstack can use different types of authentication plugins provided by
36       the  keystoneclient  library.  The following default plugins are avail‐
37       able:
38
39token: Authentication with a token
40
41password: Authentication with a username and a password
42
43openid : Authentication using the protocol OpenID Connect
44
45       Refer to the keystoneclient  library  documentation  for  more  details
46       about  these  plugins  and  their  options,  and for a complete list of
47       available plugins.  Please bear in mind that  some  plugins  might  not
48       support  all of the functionalities of openstack; for example the v3un‐
49       scopedsaml plugin can deliver only unscoped tokens, some commands might
50       not be available through this authentication method.
51
52       Additionally, it is possible to use Keystone's service token to authen‐
53       ticate, by setting the options --os-token and --os-url (or the environ‐
54       ment  variables  OS_TOKEN  and  OS_URL respectively). This method takes
55       precedence over authentication plugins.
56
57       NOTE:
58          To use the v3unscopedsaml method, the lxml package will need  to  be
59          installed.
60
61   AUTHENTICATION USING FEDERATION
62       To use federated authentication, your configuration file needs the fol‐
63       lowing:
64
65          export OS_PROJECT_NAME=<project-name>
66          export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
67          export OS_AUTH_URL=<url-to-openstack-identity>
68          export OS_IDENTITY_API_VERSION=3
69          export OS_AUTH_PLUGIN=openid
70          export OS_AUTH_TYPE=v3oidcpassword
71          export OS_USERNAME=<username-in-idp>
72          export OS_PASSWORD=<password-in-idp>
73          export OS_IDENTITY_PROVIDER=<the-desired-idp>
74          export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>
75          export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>
76          export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>
77          export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>
78          export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
79          export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
80          export OS_ACCESS_TOKEN_ENDPOINT=<the-idp-access-token-url>
81

OPTIONS

83       openstack takes global options that control overall behaviour and  com‐
84       mand-specific  options that control the command operation.  Most global
85       options have a corresponding environment variable that may also be used
86       to  set  the  value. If both are present, the command-line option takes
87       priority. The environment variable names are derived  from  the  option
88       name  by  dropping  the leading dashes ('--'), converting each embedded
89       dash ('-') to an underscore ('_'), and converting to upper case.
90
91       openstack recognizes the following global options:
92
93       --os-cloud <cloud-name>
94              openstack will look for a clouds.yaml file that contains a cloud
95              configuration  to  use for authentication.  See CLOUD CONFIGURA‐
96              TION below for more information.
97
98       --os-auth-type <auth-type>
99              The authentication plugin type to use  when  connecting  to  the
100              Identity service.
101
102              If  this  option is not set, openstack will attempt to guess the
103              authentication method to use based on the other options.
104
105              If   this   option   is   set,   its    version    must    match
106              --os-identity-api-version
107
108       --os-auth-url <auth-url>
109              Authentication URL
110
111       --os-url <service-url>
112              Service URL, when using a service token for authentication
113
114       --os-domain-name <auth-domain-name>
115              Domain-level authorization scope (by name)
116
117       --os-domain-id <auth-domain-id>
118              Domain-level authorization scope (by ID)
119
120       --os-project-name <auth-project-name>
121              Project-level authentication scope (by name)
122
123       --os-project-id <auth-project-id>
124              Project-level authentication scope (by ID)
125
126       --os-project-domain-name <auth-project-domain-name>
127              Domain name containing project
128
129       --os-project-domain-id <auth-project-domain-id>
130              Domain ID containing project
131
132       --os-username <auth-username>
133              Authentication username
134
135       --os-password <auth-password>
136              Authentication password
137
138       --os-token <token>
139              Authenticated token or service token
140
141       --os-user-domain-name <auth-user-domain-name>
142              Domain name containing user
143
144       --os-user-domain-id <auth-user-domain-id>
145              Domain ID containing user
146
147       --os-trust-id <trust-id>
148              ID of the trust to use as a trustee user
149
150       --os-default-domain <auth-domain>
151              Default domain ID (Default: 'default')
152
153       --os-region-name <auth-region-name>
154              Authentication region name
155
156       --os-cacert <ca-bundle-file>
157              CA certificate bundle file
158
159       --verify` | :option:`--insecure
160              Verify or ignore server certificate (default: verify)
161
162       --os-cert <certificate-file>
163              Client certificate bundle file
164
165       --os-key <key-file>
166              Client certificate key file
167
168       --os-identity-api-version <identity-api-version>
169              Identity API version (Default: 2.0)
170
171       --os-XXXX-api-version <XXXX-api-version>
172              Additional  API  version  options will be available depending on
173              the installed API libraries.
174
175       --os-interface <interface>
176              Interface type. Valid options are public, admin and internal.
177
178       NOTE:
179          If you switch to openstackclient  from  project  specified  clients,
180          like: novaclient, neutronclient and so on, please use --os-interface
181          instead of --os-endpoint-type.
182
183       --os-profile <hmac-key>
184              Performance profiling HMAC key for encrypting context data
185
186              This key should be the value of one of the HMAC keys defined  in
187              the configuration files of OpenStack services to be traced.
188
189       --os-beta-command
190              Enable beta commands which are subject to change
191
192       --log-file <LOGFILE>
193              Specify a file to log output. Disabled by default.
194
195       -v, --verbose
196              Increase verbosity of output. Can be repeated.
197
198       -q, --quiet
199              Suppress output except warnings and errors
200
201       --debug
202              Show tracebacks on errors and set verbosity to debug
203
204       --help Show help message and exit
205
206       --timing
207              Print API call timing information
208

COMMANDS

210       To get a list of the available commands:
211
212          openstack --help
213
214       To get a description of a specific command:
215
216          openstack help <command>
217
218       Note that the set of commands shown will vary depending on the API ver‐
219       sions that are in effect at that time.  For example, to force the  dis‐
220       play of the Identity v3 commands:
221
222          openstack --os-identity-api-version 3 --help
223
224       complete
225              Print the bash completion functions for the current command set.
226
227       help <command>
228              Print help for an individual command
229
230       Additional information on the OpenStackClient command structure and ar‐
231       guments is available in the OpenStackClient Commands wiki page.
232
233   Command Objects
234       The list of command objects is growing  longer  with  the  addition  of
235       OpenStack  project  support.   The object names may consist of multiple
236       words to compose a unique name.  Occasionally when multiple APIs have a
237       common  name  with common overlapping purposes there will be options to
238       select which object to use, or the API resources will be merged, as  in
239       the  quota  object that has options referring to both Compute and Block
240       Storage quotas.
241
242   Command Actions
243       The actions used by OpenStackClient are defined with  specific  meaning
244       to  provide  a  consistent behavior for each object.  Some actions have
245       logical opposite actions, and those pairs will always match for any ob‐
246       ject that uses them.
247

CLOUD CONFIGURATION

249       Working  with multiple clouds can be simplified by keeping the configu‐
250       ration information for those clouds in a local  file.   openstack  sup‐
251       ports using a clouds.yaml configuration file.
252
253   Config Files
254       openstack  will look for a file called clouds.yaml in the following lo‐
255       cations:
256
257       • Current Directory
258
259       • ~/.config/openstack
260
261       • /etc/openstack
262
263       The first file found wins.
264
265       The keys match the openstack global options but without the --os-  pre‐
266       fix:
267
268          clouds:
269            devstack:
270              auth:
271                auth_url: http://192.168.122.10:5000/
272                project_name: demo
273                username: demo
274                password: 0penstack
275              region_name: RegionOne
276            ds-admin:
277              auth:
278                auth_url: http://192.168.122.10:5000/
279                project_name: admin
280                username: admin
281                password: 0penstack
282              region_name: RegionOne
283            infra:
284              cloud: rackspace
285              auth:
286                project_id: 275610
287                username: openstack
288                password: xyzpdq!lazydog
289              region_name: DFW,ORD,IAD
290
291       In  the  above  example,  the auth_url for the rackspace cloud is taken
292       from clouds-public.yaml:
293
294          public-clouds:
295            rackspace:
296              auth:
297                auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
298
299   Authentication Settings
300       OpenStackClient uses the Keystone authentication  plugins  so  the  re‐
301       quired auth settings are not always known until the authentication type
302       is selected.  openstack will attempt to detect a couple of common  auth
303       types  based  on  the arguments passed in or found in the configuration
304       file, but if those are incomplete it may be impossible  to  know  which
305       auth type is intended.  The --os-auth-type option can always be used to
306       force a specific type.
307
308       When --os-token and --os-url are both present the  token_endpoint  auth
309       type is selected automatically.  If --os-auth-url and --os-username are
310       present password auth type is selected.
311
312   Logging Settings
313       openstack can record the operation history by logging settings in  con‐
314       figuration  file.  Recording  the  user  operation, it can identify the
315       change of the resource and it  becomes  useful  information  for  trou‐
316       bleshooting.
317
318       See Configuration about Logging Settings for more details.
319

NOTES

321       The command list displayed in help output reflects the API versions se‐
322       lected.  For example, to see Identity v3 commands  OS_IDENTITY_API_VER‐
323       SION must be set to 3.
324

EXAMPLES

326       Show the detailed information for server appweb01:
327
328          openstack \
329              --os-project-name ExampleCo \
330              --os-username demo --os-password secret \
331              --os-auth-url http://localhost:5000:/v2.0 \
332              server show appweb01
333
334       The same but using openid to authenticate in keystone:
335
336          openstack \
337              --os-project-name ExampleCo \
338              --os-auth-url http://localhost:5000:/v2.0 \
339              --os-auth-plugin openid \
340              --os-auth-type v3oidcpassword \
341              --os-username demo-idp \
342              --os-password secret-idp \
343              --os-identity-provider google \
344              --os-client-id the-id-assigned-to-keystone-in-google \
345              --os-client-secret 3315162f-2b28-4809-9369-cb54730ac837 \
346              --os-openid-scope 'openid email profile'\
347              --os-protocol openid \
348              --os-access-token-type access_token \
349              --os-discovery-endpoint https://accounts.google.com/.well-known/openid-configuration \
350              server show appweb01
351
352       The  same  command  if  the  auth  environment  variables (OS_AUTH_URL,
353       OS_PROJECT_NAME, OS_USERNAME, OS_PASSWORD) are set:
354
355          openstack server show appweb01
356
357       Create a new image:
358
359          openstack image create \
360              --disk-format=qcow2 \
361              --container-format=bare \
362              --public \
363              --copy-from http://somewhere.net/foo.img \
364              foo
365

FILES

367       ~/.config/openstack/clouds.yaml
368              Configuration file used by the --os-cloud global option.
369
370       ~/.config/openstack/clouds-public.yaml
371              Configuration file containing public cloud provider  information
372              such  as  authentication URLs and service definitions.  The con‐
373              tents of this file should be public and  sharable.   clouds.yaml
374              may contain references to clouds defined here as shortcuts.
375
376       ~/.openstack
377              Placeholder for future local state directory.  This directory is
378              intended to be shared among multiple OpenStack-related  applica‐
379              tions;  contents  are  namespaced with an identifier for the app
380              that owns it.  Shared contents (such as ~/.openstack/cache) have
381              no prefix and the contents must be portable.
382

ENVIRONMENT VARIABLES

384       The  following  environment variables can be set to alter the behaviour
385       of openstack.  Most of them  have  corresponding  command-line  options
386       that take precedence if set.
387
388       OS_CLOUD
389              The name of a cloud configuration in clouds.yaml.
390
391       OS_AUTH_PLUGIN
392              The authentication plugin to use when connecting to the Identity
393              service, its version must match the Identity API version
394
395       OS_AUTH_URL
396              Authentication URL
397
398       OS_AUTH_TYPE
399              Define the authentication plugin that will be used to handle the
400              authentication process. One of the following:
401
402v2password
403
404v2token
405
406v3password
407
408v3token
409
410v3oidcclientcredentials
411
412v3oidcpassword
413
414v3oidcauthorizationcode
415
416v3oidcaccesstoken
417
418v3totp
419
420v3tokenlessauth
421
422v3applicationcredential
423
424v3multifactor
425
426       OS_URL Service URL (when using the service token)
427
428       OS_DOMAIN_NAME
429              Domain-level authorization scope (name or ID)
430
431       OS_PROJECT_NAME
432              Project-level authentication scope (name or ID)
433
434       OS_PROJECT_DOMAIN_NAME
435              Domain name or ID containing project
436
437       OS_USERNAME
438              Authentication username
439
440       OS_TOKEN
441              Authenticated or service token
442
443       OS_PASSWORD
444              Authentication password
445
446       OS_USER_DOMAIN_NAME
447              Domain name or ID containing user
448
449       OS_TRUST_ID
450              ID of the trust to use as a trustee user
451
452       OS_DEFAULT_DOMAIN
453              Default domain ID (Default: 'default')
454
455       OS_REGION_NAME
456              Authentication region name
457
458       OS_CACERT
459              CA certificate bundle file
460
461       OS_CERT
462              Client certificate bundle file
463
464       OS_KEY Client certificate key file
465
466       OS_IDENTITY_API_VERSION
467              Identity API version (Default: 2.0)
468
469       OS_XXXX_API_VERSION
470              Additional  API  version  options will be available depending on
471              the installed API libraries.
472
473       OS_INTERFACE
474              Interface type. Valid options are public, admin and internal.
475
476       OS_PROTOCOL
477              Define the protocol that is used to execute  the  federated  au‐
478              thentication  process. It is used in the Keystone authentication
479              URL generation process.
480
481       OS_IDENTITY_PROVIDER
482              Define the identity provider of your  federation  that  will  be
483              used.  It  is used by the Keystone authentication URL generation
484              process. The available Identity Providers can  be  listed  using
485              the openstack identity provider list command
486
487       OS_CLIENT_ID
488              Configure  the  CLIENT_ID  that the CLI will use to authenticate
489              the application (OpenStack) in the Identity Provider. This value
490              is  defined  on  the identity provider side. Do not confuse with
491              the user ID.
492
493       OS_CLIENT_SECRET
494              Configure the OS_CLIENT_SECRET that the CLI will use to  authen‐
495              ticate the CLI (OpenStack secret in the identity provider).
496
497       OS_OPENID_SCOPE
498              Configure  the attribute scopes that will be claimed by the Ser‐
499              vice Provider (SP), in this case OpenStack,  from  the  identity
500              provider.  These scopes and which attributes each scope contains
501              are defined in the identity provider side.  This  parameter  can
502              receive multiple values separated by space.
503
504       OS_ACCESS_TOKEN_TYPE
505              Define the type of access token that is used in the token intro‐
506              spection process.  This variable can  assume  only  one  of  the
507              states ("access_token" or "id_token").
508
509       OS_DISCOVERY_ENDPOINT
510              Configure  the  identity provider's discovery URL. This URL will
511              provide a discover document that  contains  metadata  describing
512              the  identity  provider  endpoints. This variable is optional if
513              the variable OS_ACCESS_TOKEN_ENDPOINT is defined.
514
515       OS_ACCESS_TOKEN_ENDPOINT
516              Overrides the value presented  in  the  discovery  document  re‐
517              trieved from OS_DISCOVERY_ENDPOINT URL request. This variable is
518              optional if the OS_DISCOVERY_ENDPOINT is configured.
519
520       NOTE:
521          If you switch to openstackclient  from  project  specified  clients,
522          like:  novaclient,  neutronclient and so on, please use OS_INTERFACE
523          instead of OS_ENDPOINT_TYPE.
524

BUGS

526       Bug reports  are  accepted  at  the  python-openstackclient  StoryBoard
527       project "https://storyboard.openstack.org/#!/project/975".
528

AUTHORS

530       Please refer to the AUTHORS file distributed with OpenStackClient.
531
533       Copyright  2011-2014 OpenStack Foundation and the authors listed in the
534       AUTHORS file.
535

LICENSE

537       http://www.apache.org/licenses/LICENSE-2.0
538

SEE ALSO

540       The OpenStackClient page in the OpenStack Docs contains  further  docu‐
541       mentation.
542
543       The individual OpenStack project CLIs, the OpenStack API references.
544

AUTHOR

546       OpenStack contributors
547
549       2012-2023 OpenStack Foundation
550
551
552
553
5546.0.0                            Jan 20, 2023                     OPENSTACK(1)
Impressum