1OPENSTACK(1) python-openstackclient 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
47 v3unscopedsaml plugin can deliver only unscoped tokens, some commands
48 might 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
184 To get a list of the available commands:
185 openstack --help
187 To get a description of a specific command:
189 openstack help <command>
191 Note that the set of commands shown will vary depending on the API ver‐
193 sions that are in effect at that time. For example, to force the dis‐
194 play of the Identity v3 commands:
195 openstack --os-identity-api-version 3 --help
197 complete
199 Print the bash completion functions for the current command set.
200 help <command>
202 Print help for an individual command
203 Additional information on the OpenStackClient command structure and
205 arguments is available in the OpenStackClient Commands wiki page.
206 Command Objects
208 The list of command objects is growing longer with the addition of
209 OpenStack project support. The object names may consist of multiple
210 words to compose a unique name. Occasionally when multiple APIs have a
211 common name with common overlapping purposes there will be options to
212 select which object to use, or the API resources will be merged, as in
213 the quota object that has options referring to both Compute and Block
214 Storage quotas.
215 Command Actions
217 The actions used by OpenStackClient are defined with specific meaning
218 to provide a consistent behavior for each object. Some actions have
219 logical opposite actions, and those pairs will always match for any
220 object that uses them.
221
223 Working with multiple clouds can be simplified by keeping the configu‐
224 ration information for those clouds in a local file. openstack sup‐
225 ports using a clouds.yaml configuration file.
226 Config Files
228 openstack will look for a file called clouds.yaml in the following
229 locations:
230 · Current Directory
232 · ~/.config/openstack
234 · /etc/openstack
236 The first file found wins.
238 The keys match the openstack global options but without the --os- pre‐
240 fix:
241 clouds:
243 devstack:
244 auth:
245 auth_url: http://192.168.122.10:35357/
246 project_name: demo
247 username: demo
248 password: 0penstack
249 region_name: RegionOne
250 ds-admin:
251 auth:
252 auth_url: http://192.168.122.10:35357/
253 project_name: admin
254 username: admin
255 password: 0penstack
256 region_name: RegionOne
257 infra:
258 cloud: rackspace
259 auth:
260 project_id: 275610
261 username: openstack
262 password: xyzpdq!lazydog
263 region_name: DFW,ORD,IAD
264 In the above example, the auth_url for the rackspace cloud is taken
266 from clouds-public.yaml:
267 public-clouds:
269 rackspace:
270 auth:
271 auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
272 Authentication Settings
274 OpenStackClient uses the Keystone authentication plugins so the
275 required auth settings are not always known until the authentication
276 type is selected. openstack will attempt to detect a couple of common
277 auth types based on the arguments passed in or found in the configura‐
278 tion file, but if those are incomplete it may be impossible to know
279 which auth type is intended. The --os-auth-type option can always be
280 used to force a specific type.
281 When --os-token and --os-url are both present the token_endpoint auth
283 type is selected automatically. If --os-auth-url and --os-username are
284 present password auth type is selected.
285 Logging Settings
287 openstack can record the operation history by logging settings in con‐
288 figuration file. Recording the user operation, it can identify the
289 change of the resource and it becomes useful information for trou‐
290 bleshooting.
291 See configuration about Logging Settings for more details.
293
295 The command list displayed in help output reflects the API versions
296 selected. For example, to see Identity v3 commands OS_IDEN‐
297 TITY_API_VERSION must be set to 3.
298
300 Show the detailed information for server appweb01:
301 openstack \
303 --os-project-name ExampleCo \
304 --os-username demo --os-password secret \
305 --os-auth-url http://localhost:5000:/v2.0 \
306 server show appweb01
307 The same command if the auth environment variables (OS_AUTH_URL,
309 OS_PROJECT_NAME, OS_USERNAME, OS_PASSWORD) are set:
310 openstack server show appweb01
312 Create a new image:
314 openstack image create \
316 --disk-format=qcow2 \
317 --container-format=bare \
318 --public \
319 --copy-from http://somewhere.net/foo.img \
320 foo
321
323 ~/.config/openstack/clouds.yaml
324 Configuration file used by the --os-cloud global option.
325 ~/.config/openstack/clouds-public.yaml
327 Configuration file containing public cloud provider information
328 such as authentication URLs and service definitions. The con‐
329 tents of this file should be public and sharable. clouds.yaml
330 may contain references to clouds defined here as shortcuts.
331 ~/.openstack
333 Placeholder for future local state directory. This directory is
334 intended to be shared among multiple OpenStack-related applica‐
335 tions; contents are namespaced with an identifier for the app
336 that owns it. Shared contents (such as ~/.openstack/cache) have
337 no prefix and the contents must be portable.
338
340 The following environment variables can be set to alter the behaviour
341 of openstack. Most of them have corresponding command-line options
342 that take precedence if set.
343 OS_CLOUD
345 The name of a cloud configuration in clouds.yaml.
346 OS_AUTH_PLUGIN
348 The authentication plugin to use when connecting to the Identity
349 service, its version must match the Identity API version
350 OS_AUTH_URL
352 Authentication URL
353 OS_URL Service URL (when using the service token)
355 OS_DOMAIN_NAME
357 Domain-level authorization scope (name or ID)
358 OS_PROJECT_NAME
360 Project-level authentication scope (name or ID)
361 OS_PROJECT_DOMAIN_NAME
363 Domain name or ID containing project
364 OS_USERNAME
366 Authentication username
367 OS_TOKEN
369 Authenticated or service token
370 OS_PASSWORD
372 Authentication password
373 OS_USER_DOMAIN_NAME
375 Domain name or ID containing user
376 OS_TRUST_ID
378 ID of the trust to use as a trustee user
379 OS_DEFAULT_DOMAIN
381 Default domain ID (Default: 'default')
382 OS_REGION_NAME
384 Authentication region name
385 OS_CACERT
387 CA certificate bundle file
388 OS_CERT
390 Client certificate bundle file
391 OS_KEY Client certificate key file
393 OS_IDENTITY_API_VERSION
395 Identity API version (Default: 2.0)
396 OS_XXXX_API_VERSION
398 Additional API version options will be available depending on
399 the installed API libraries.
400 OS_INTERFACE
402 Interface type. Valid options are public, admin and internal.
403 NOTE:
405 If you switch to openstackclient from project specified clients,
406 like: novaclient, neutronclient and so on, please use OS_INTERFACE
407 instead of OS_ENDPOINT_TYPE.
408
410 Bug reports are accepted at the python-openstackclient LaunchPad
411 project "https://bugs.launchpad.net/python-openstackclient/+bugs".
412
414 Please refer to the AUTHORS file distributed with OpenStackClient.
415
417 Copyright 2011-2014 OpenStack Foundation and the authors listed in the
418 AUTHORS file.
419
421 http://www.apache.org/licenses/LICENSE-2.0
422
424 The OpenStackClient page in the OpenStack Docs contains further docu‐
425 mentation.
426 The individual OpenStack project CLIs, the OpenStack API references.
428
430 OpenStack contributors
431
433 2012-2013 OpenStack Foundation
4343.14.1 Aug 13, 2018 OPENSTACK(1)