1OPENSTACK(1) OpenStack Command Line Client OPENSTACK(1)
2
6 openstack - OpenStack Command Line Client
7 OpenStack Command Line
9
11 openstack [<global-options>] <command> [<command-arguments>]
12 openstack help <command>
14 openstack --help
16
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
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 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 openstack can use different types of authentication plugins provided by
36 the keystoneclient library. The following default plugins are avail‐
37 able:
38 • token: Authentication with a token
40 • password: Authentication with a username and a password
42 • openid : Authentication using the protocol OpenID Connect
44 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 Additionally, it is possible to use Keystone's service token to authen‐
53 ticate, by setting the options --os-token and --os-endpoint (or the en‐
54 vironment variables OS_TOKEN and OS_ENDPOINT respectively). This method
55 takes precedence over authentication plugins.
56 NOTE:
58 To use the v3unscopedsaml method, the lxml package will need to be
59 installed.
60 AUTHENTICATION USING FEDERATION
62 To use federated authentication, your configuration file needs the fol‐
63 lowing:
64 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
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 openstack recognizes the following global options:
92 --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 --os-auth-type <auth-type>
99 The authentication plugin type to use when connecting to the
100 Identity service.
101 If this option is not set, openstack will attempt to guess the
103 authentication method to use based on the other options.
104 If this option is set, its version must match
106 --os-identity-api-version
107 --os-auth-url <auth-url>
109 Authentication URL
110 --os-endpoint <service-url>
112 Service ENDPOINT, when using a service token for authentication
113 --os-domain-name <auth-domain-name>
115 Domain-level authorization scope (by name)
116 --os-domain-id <auth-domain-id>
118 Domain-level authorization scope (by ID)
119 --os-project-name <auth-project-name>
121 Project-level authentication scope (by name)
122 --os-project-id <auth-project-id>
124 Project-level authentication scope (by ID)
125 --os-project-domain-name <auth-project-domain-name>
127 Domain name containing project
128 --os-project-domain-id <auth-project-domain-id>
130 Domain ID containing project
131 --os-username <auth-username>
133 Authentication username
134 --os-password <auth-password>
136 Authentication password
137 --os-token <token>
139 Authenticated token or service token
140 --os-user-domain-name <auth-user-domain-name>
142 Domain name containing user
143 --os-user-domain-id <auth-user-domain-id>
145 Domain ID containing user
146 --os-trust-id <trust-id>
148 ID of the trust to use as a trustee user
149 --os-default-domain <auth-domain>
151 Default domain ID (Default: 'default')
152 --os-region-name <auth-region-name>
154 Authentication region name
155 --os-cacert <ca-bundle-file>
157 CA certificate bundle file
158 --verify` | :option:`--insecure
160 Verify or ignore server certificate (default: verify)
161 --os-cert <certificate-file>
163 Client certificate bundle file
164 --os-key <key-file>
166 Client certificate key file
167 --os-identity-api-version <identity-api-version>
169 Identity API version (Default: 2.0)
170 --os-XXXX-api-version <XXXX-api-version>
172 Additional API version options will be available depending on
173 the installed API libraries.
174 --os-interface <interface>
176 Interface type. Valid options are public, admin and internal.
177 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 --os-profile <hmac-key>
184 Performance profiling HMAC key for encrypting context data
185 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 --os-beta-command
190 Enable beta commands which are subject to change
191 --log-file <LOGFILE>
193 Specify a file to log output. Disabled by default.
194 -v, --verbose
196 Increase verbosity of output. Can be repeated.
197 -q, --quiet
199 Suppress output except warnings and errors
200 --debug
202 Show tracebacks on errors and set verbosity to debug
203 --help Show help message and exit
205 --timing
207 Print API call timing information
208
210 To get a list of the available commands:
211 openstack --help
213 To get a description of a specific command:
215 openstack help <command>
217 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 openstack --os-identity-api-version 3 --help
223 complete
225 Print the bash completion functions for the current command set.
226 help <command>
228 Print help for an individual command
229 Additional information on the OpenStackClient command structure and ar‐
231 guments is available in the OpenStackClient Commands wiki page.
232 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 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
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 Config Files
254 openstack will look for a file called clouds.yaml in the following lo‐
255 cations:
256 • Current Directory
258 • ~/.config/openstack
260 • /etc/openstack
262 The first file found wins.
264 The keys match the openstack global options but without the --os- pre‐
266 fix:
267 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 In the above example, the auth_url for the rackspace cloud is taken
292 from clouds-public.yaml:
293 public-clouds:
295 rackspace:
296 auth:
297 auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
298 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 When --os-token and --os-endpoint are both present the token_endpoint
309 auth type is selected automatically. If --os-auth-url and
310 --os-username are present password auth type is selected.
311 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 See Configuration about Logging Settings for more details.
319
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
326 Show the detailed information for server appweb01:
327 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 The same but using openid to authenticate in keystone:
335 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 The same command if the auth environment variables (OS_AUTH_URL,
353 OS_PROJECT_NAME, OS_USERNAME, OS_PASSWORD) are set:
354 openstack server show appweb01
356 Create a new image:
358 openstack image create \
360 --disk-format=qcow2 \
361 --container-format=bare \
362 --public \
363 --copy-from http://somewhere.net/foo.img \
364 foo
365
367 ~/.config/openstack/clouds.yaml
368 Configuration file used by the --os-cloud global option.
369 ~/.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 ~/.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
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 OS_CLOUD
389 The name of a cloud configuration in clouds.yaml.
390 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 OS_AUTH_URL
396 Authentication URL
397 OS_AUTH_TYPE
399 Define the authentication plugin that will be used to handle the
400 authentication process. One of the following:
401 • v2password
403 • v2token
405 • v3password
407 • v3token
409 • v3oidcclientcredentials
411 • v3oidcpassword
413 • v3oidcauthorizationcode
415 • v3oidcaccesstoken
417 • v3totp
419 • v3tokenlessauth
421 • v3applicationcredential
423 • v3multifactor
425 OS_ENDPOINT
427 Service ENDPOINT (when using the service token)
428 OS_DOMAIN_NAME
430 Domain-level authorization scope (name or ID)
431 OS_PROJECT_NAME
433 Project-level authentication scope (name or ID)
434 OS_PROJECT_DOMAIN_NAME
436 Domain name or ID containing project
437 OS_USERNAME
439 Authentication username
440 OS_TOKEN
442 Authenticated or service token
443 OS_PASSWORD
445 Authentication password
446 OS_USER_DOMAIN_NAME
448 Domain name or ID containing user
449 OS_TRUST_ID
451 ID of the trust to use as a trustee user
452 OS_DEFAULT_DOMAIN
454 Default domain ID (Default: 'default')
455 OS_REGION_NAME
457 Authentication region name
458 OS_CACERT
460 CA certificate bundle file
461 OS_CERT
463 Client certificate bundle file
464 OS_KEY Client certificate key file
466 OS_IDENTITY_API_VERSION
468 Identity API version (Default: 2.0)
469 OS_XXXX_API_VERSION
471 Additional API version options will be available depending on
472 the installed API libraries.
473 OS_INTERFACE
475 Interface type. Valid options are public, admin and internal.
476 OS_PROTOCOL
478 Define the protocol that is used to execute the federated au‐
479 thentication process. It is used in the Keystone authentication
480 URL generation process.
481 OS_IDENTITY_PROVIDER
483 Define the identity provider of your federation that will be
484 used. It is used by the Keystone authentication URL generation
485 process. The available Identity Providers can be listed using
486 the openstack identity provider list command
487 OS_CLIENT_ID
489 Configure the CLIENT_ID that the CLI will use to authenticate
490 the application (OpenStack) in the Identity Provider. This value
491 is defined on the identity provider side. Do not confuse with
492 the user ID.
493 OS_CLIENT_SECRET
495 Configure the OS_CLIENT_SECRET that the CLI will use to authen‐
496 ticate the CLI (OpenStack secret in the identity provider).
497 OS_OPENID_SCOPE
499 Configure the attribute scopes that will be claimed by the Ser‐
500 vice Provider (SP), in this case OpenStack, from the identity
501 provider. These scopes and which attributes each scope contains
502 are defined in the identity provider side. This parameter can
503 receive multiple values separated by space.
504 OS_ACCESS_TOKEN_TYPE
506 Define the type of access token that is used in the token intro‐
507 spection process. This variable can assume only one of the
508 states ("access_token" or "id_token").
509 OS_DISCOVERY_ENDPOINT
511 Configure the identity provider's discovery URL. This URL will
512 provide a discover document that contains metadata describing
513 the identity provider endpoints. This variable is optional if
514 the variable OS_ACCESS_TOKEN_ENDPOINT is defined.
515 OS_ACCESS_TOKEN_ENDPOINT
517 Overrides the value presented in the discovery document re‐
518 trieved from OS_DISCOVERY_ENDPOINT URL request. This variable is
519 optional if the OS_DISCOVERY_ENDPOINT is configured.
520 NOTE:
522 If you switch to openstackclient from project specified clients,
523 like: novaclient, neutronclient and so on, please use OS_INTERFACE
524 instead of OS_ENDPOINT_TYPE.
525
527 Bug reports are accepted at the python-openstackclient StoryBoard
528 project "https://storyboard.openstack.org/#!/project/975".
529
531 Please refer to the AUTHORS file distributed with OpenStackClient.
532
534 Copyright 2011-2014 OpenStack Foundation and the authors listed in the
535 AUTHORS file.
536
538 http://www.apache.org/licenses/LICENSE-2.0
539
541 The OpenStackClient page in the OpenStack Docs contains further docu‐
542 mentation.
543 The individual OpenStack project CLIs, the OpenStack API references.
545
547 OpenStack contributors
548
550 2012-2023 OpenStack Foundation
5516.2.0 Jul 21, 2023 OPENSTACK(1)