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 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 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 NOTE:
56 To use the v3unscopedsaml method, the lxml package will need to be
57 installed.
58
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 openstack recognizes the following global options:
69 --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 --os-auth-type <auth-type>
76 The authentication plugin type to use when connecting to the
77 Identity service.
78 If this option is not set, openstack will attempt to guess the
80 authentication method to use based on the other options.
81 If this option is set, its version must match
83 --os-identity-api-version
84 --os-auth-url <auth-url>
86 Authentication URL
87 --os-url <service-url>
89 Service URL, when using a service token for authentication
90 --os-domain-name <auth-domain-name>
92 Domain-level authorization scope (by name)
93 --os-domain-id <auth-domain-id>
95 Domain-level authorization scope (by ID)
96 --os-project-name <auth-project-name>
98 Project-level authentication scope (by name)
99 --os-project-id <auth-project-id>
101 Project-level authentication scope (by ID)
102 --os-project-domain-name <auth-project-domain-name>
104 Domain name containing project
105 --os-project-domain-id <auth-project-domain-id>
107 Domain ID containing project
108 --os-username <auth-username>
110 Authentication username
111 --os-password <auth-password>
113 Authentication password
114 --os-token <token>
116 Authenticated token or service token
117 --os-user-domain-name <auth-user-domain-name>
119 Domain name containing user
120 --os-user-domain-id <auth-user-domain-id>
122 Domain ID containing user
123 --os-trust-id <trust-id>
125 ID of the trust to use as a trustee user
126 --os-default-domain <auth-domain>
128 Default domain ID (Default: 'default')
129 --os-region-name <auth-region-name>
131 Authentication region name
132 --os-cacert <ca-bundle-file>
134 CA certificate bundle file
135 --verify` | :option:`--insecure
137 Verify or ignore server certificate (default: verify)
138 --os-cert <certificate-file>
140 Client certificate bundle file
141 --os-key <key-file>
143 Client certificate key file
144 --os-identity-api-version <identity-api-version>
146 Identity API version (Default: 2.0)
147 --os-XXXX-api-version <XXXX-api-version>
149 Additional API version options will be available depending on
150 the installed API libraries.
151 --os-interface <interface>
153 Interface type. Valid options are public, admin and internal.
154 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 --os-profile <hmac-key>
161 Performance profiling HMAC key for encrypting context data
162 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 --os-beta-command
167 Enable beta commands which are subject to change
168 --log-file <LOGFILE>
170 Specify a file to log output. Disabled by default.
171 -v, --verbose
173 Increase verbosity of output. Can be repeated.
174 -q, --quiet
176 Suppress output except warnings and errors
177 --debug
179 Show tracebacks on errors and set verbosity to debug
180 --help Show help message and exit
182 --timing
184 Print API call timing information
185
187 To get a list of the available commands:
188 openstack --help
190 To get a description of a specific command:
192 openstack help <command>
194 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 openstack --os-identity-api-version 3 --help
200 complete
202 Print the bash completion functions for the current command set.
203 help <command>
205 Print help for an individual command
206 Additional information on the OpenStackClient command structure and ar‐
208 guments is available in the OpenStackClient Commands wiki page.
209 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 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
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 Config Files
231 openstack will look for a file called clouds.yaml in the following lo‐
232 cations:
233 • Current Directory
235 • ~/.config/openstack
237 • /etc/openstack
239 The first file found wins.
241 The keys match the openstack global options but without the --os- pre‐
243 fix:
244 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 In the above example, the auth_url for the rackspace cloud is taken
269 from clouds-public.yaml:
270 public-clouds:
272 rackspace:
273 auth:
274 auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
275 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 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 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 See configuration about Logging Settings for more details.
296
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
303 Show the detailed information for server appweb01:
304 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 The same command if the auth environment variables (OS_AUTH_URL,
312 OS_PROJECT_NAME, OS_USERNAME, OS_PASSWORD) are set:
313 openstack server show appweb01
315 Create a new image:
317 openstack image create \
319 --disk-format=qcow2 \
320 --container-format=bare \
321 --public \
322 --copy-from http://somewhere.net/foo.img \
323 foo
324
326 ~/.config/openstack/clouds.yaml
327 Configuration file used by the --os-cloud global option.
328 ~/.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 ~/.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
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 OS_CLOUD
348 The name of a cloud configuration in clouds.yaml.
349 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 OS_AUTH_URL
355 Authentication URL
356 OS_URL Service URL (when using the service token)
358 OS_DOMAIN_NAME
360 Domain-level authorization scope (name or ID)
361 OS_PROJECT_NAME
363 Project-level authentication scope (name or ID)
364 OS_PROJECT_DOMAIN_NAME
366 Domain name or ID containing project
367 OS_USERNAME
369 Authentication username
370 OS_TOKEN
372 Authenticated or service token
373 OS_PASSWORD
375 Authentication password
376 OS_USER_DOMAIN_NAME
378 Domain name or ID containing user
379 OS_TRUST_ID
381 ID of the trust to use as a trustee user
382 OS_DEFAULT_DOMAIN
384 Default domain ID (Default: 'default')
385 OS_REGION_NAME
387 Authentication region name
388 OS_CACERT
390 CA certificate bundle file
391 OS_CERT
393 Client certificate bundle file
394 OS_KEY Client certificate key file
396 OS_IDENTITY_API_VERSION
398 Identity API version (Default: 2.0)
399 OS_XXXX_API_VERSION
401 Additional API version options will be available depending on
402 the installed API libraries.
403 OS_INTERFACE
405 Interface type. Valid options are public, admin and internal.
406 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
413 Bug reports are accepted at the python-openstackclient StoryBoard
414 project "https://storyboard.openstack.org/#!/project/975".
415
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
424 http://www.apache.org/licenses/LICENSE-2.0
425
427 The OpenStackClient page in the OpenStack Docs contains further docu‐
428 mentation.
429 The individual OpenStack project CLIs, the OpenStack API references.
431
433 OpenStack contributors
434
436 2012-2021 OpenStack Foundation
4375.4.0 Jan 27, 2021 OPENSTACK(1)