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
43       Refer to the keystoneclient  library  documentation  for  more  details
44       about  these  plugins  and  their  options,  and for a complete list of
45       available plugins.  Please bear in mind that  some  plugins  might  not
46       support  all of the functionalities of openstack; for example the v3un‐
47       scopedsaml plugin can deliver only unscoped tokens, some commands might
48       not be available through this authentication method.
49
50       Additionally, it is possible to use Keystone's service token to authen‐
51       ticate, by setting the options --os-token and --os-url (or the environ‐
52       ment  variables  OS_TOKEN  and  OS_URL respectively). This method takes
53       precedence over authentication plugins.
54
55       NOTE:
56          To use the v3unscopedsaml method, the lxml package will need  to  be
57          installed.
58

OPTIONS

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

COMMANDS

187       To get a list of the available commands:
188
189          openstack --help
190
191       To get a description of a specific command:
192
193          openstack help <command>
194
195       Note that the set of commands shown will vary depending on the API ver‐
196       sions  that are in effect at that time.  For example, to force the dis‐
197       play of the Identity v3 commands:
198
199          openstack --os-identity-api-version 3 --help
200
201       complete
202              Print the bash completion functions for the current command set.
203
204       help <command>
205              Print help for an individual command
206
207       Additional information on the OpenStackClient command structure and ar‐
208       guments is available in the OpenStackClient Commands wiki page.
209
210   Command Objects
211       The  list  of  command  objects  is growing longer with the addition of
212       OpenStack project support.  The object names may  consist  of  multiple
213       words to compose a unique name.  Occasionally when multiple APIs have a
214       common name with common overlapping purposes there will be  options  to
215       select  which object to use, or the API resources will be merged, as in
216       the quota object that has options referring to both Compute  and  Block
217       Storage quotas.
218
219   Command Actions
220       The  actions  used by OpenStackClient are defined with specific meaning
221       to provide a consistent behavior for each object.   Some  actions  have
222       logical opposite actions, and those pairs will always match for any ob‐
223       ject that uses them.
224

CLOUD CONFIGURATION

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

NOTES

298       The command list displayed in help output reflects the API versions se‐
299       lected.   For example, to see Identity v3 commands OS_IDENTITY_API_VER‐
300       SION must be set to 3.
301

EXAMPLES

303       Show the detailed information for server appweb01:
304
305          openstack \
306              --os-project-name ExampleCo \
307              --os-username demo --os-password secret \
308              --os-auth-url http://localhost:5000:/v2.0 \
309              server show appweb01
310
311       The same  command  if  the  auth  environment  variables  (OS_AUTH_URL,
312       OS_PROJECT_NAME, OS_USERNAME, OS_PASSWORD) are set:
313
314          openstack server show appweb01
315
316       Create a new image:
317
318          openstack image create \
319              --disk-format=qcow2 \
320              --container-format=bare \
321              --public \
322              --copy-from http://somewhere.net/foo.img \
323              foo
324

FILES

326       ~/.config/openstack/clouds.yaml
327              Configuration file used by the --os-cloud global option.
328
329       ~/.config/openstack/clouds-public.yaml
330              Configuration  file containing public cloud provider information
331              such as authentication URLs and service definitions.   The  con‐
332              tents  of  this file should be public and sharable.  clouds.yaml
333              may contain references to clouds defined here as shortcuts.
334
335       ~/.openstack
336              Placeholder for future local state directory.  This directory is
337              intended  to be shared among multiple OpenStack-related applica‐
338              tions; contents are namespaced with an identifier  for  the  app
339              that owns it.  Shared contents (such as ~/.openstack/cache) have
340              no prefix and the contents must be portable.
341

ENVIRONMENT VARIABLES

343       The following environment variables can be set to alter  the  behaviour
344       of  openstack.   Most  of  them have corresponding command-line options
345       that take precedence if set.
346
347       OS_CLOUD
348              The name of a cloud configuration in clouds.yaml.
349
350       OS_AUTH_PLUGIN
351              The authentication plugin to use when connecting to the Identity
352              service, its version must match the Identity API version
353
354       OS_AUTH_URL
355              Authentication URL
356
357       OS_URL Service URL (when using the service token)
358
359       OS_DOMAIN_NAME
360              Domain-level authorization scope (name or ID)
361
362       OS_PROJECT_NAME
363              Project-level authentication scope (name or ID)
364
365       OS_PROJECT_DOMAIN_NAME
366              Domain name or ID containing project
367
368       OS_USERNAME
369              Authentication username
370
371       OS_TOKEN
372              Authenticated or service token
373
374       OS_PASSWORD
375              Authentication password
376
377       OS_USER_DOMAIN_NAME
378              Domain name or ID containing user
379
380       OS_TRUST_ID
381              ID of the trust to use as a trustee user
382
383       OS_DEFAULT_DOMAIN
384              Default domain ID (Default: 'default')
385
386       OS_REGION_NAME
387              Authentication region name
388
389       OS_CACERT
390              CA certificate bundle file
391
392       OS_CERT
393              Client certificate bundle file
394
395       OS_KEY Client certificate key file
396
397       OS_IDENTITY_API_VERSION
398              Identity API version (Default: 2.0)
399
400       OS_XXXX_API_VERSION
401              Additional  API  version  options will be available depending on
402              the installed API libraries.
403
404       OS_INTERFACE
405              Interface type. Valid options are public, admin and internal.
406
407       NOTE:
408          If you switch to openstackclient  from  project  specified  clients,
409          like:  novaclient,  neutronclient and so on, please use OS_INTERFACE
410          instead of OS_ENDPOINT_TYPE.
411

BUGS

413       Bug reports  are  accepted  at  the  python-openstackclient  StoryBoard
414       project "https://storyboard.openstack.org/#!/project/975".
415

AUTHORS

417       Please refer to the AUTHORS file distributed with OpenStackClient.
418
420       Copyright  2011-2014 OpenStack Foundation and the authors listed in the
421       AUTHORS file.
422

LICENSE

424       http://www.apache.org/licenses/LICENSE-2.0
425

SEE ALSO

427       The OpenStackClient page in the OpenStack Docs contains  further  docu‐
428       mentation.
429
430       The individual OpenStack project CLIs, the OpenStack API references.
431

AUTHOR

433       OpenStack contributors
434
436       2012-2021 OpenStack Foundation
437
438
439
440
4415.4.0                            Jan 27, 2021                     OPENSTACK(1)
Impressum