OPENSTACK(1)

📦
version 10.3.0 · 14 versions
, in ubuntu stonking

💖 openstack 💖

openstack — OpenStack Command Line Client

OpenStack Command Line

✨ NAME ✨

okay so bestie, this whole page is about openstack, the OpenStack Command Line Client — aka the OpenStack Command Line. that's it. that's the name. slay.

🎀 SYNOPSIS 🎀

here's how you actually call it, no cap:

openstack [<global-options>] <command> [<command-arguments>]
openstack help <command>
openstack --help

🦋 DESCRIPTION 🦋

so openstack gives you one common command-line interface to all the OpenStack APIs. it's generally equivalent to the CLIs that come out of the OpenStack project client libraries, BUT — and this is the glow-up — it's got a distinct and consistent command structure. literally the whole point. consistency. we love her for it.

🌈 AUTHENTICATION METHODS 🌈

openstack uses a scheme that's similar to the OpenStack project CLIs: you feed it your credential info either as environment variables or as options on the command line. the big primary difference? it uses project in the name of the options — OS_PROJECT_NAME/OS_PROJECT_ID — instead of the old tenant-based names. periodt, tenant is over.

export OS_AUTH_URL=<url-to-openstack-identity>
export OS_PROJECT_NAME=<project-name>
export OS_USERNAME=<user-name>
export OS_PASSWORD=<password>  # (optional)

openstack can use different types of authentication plugins provided by the keystoneclient library. these are the default plugins on the menu:

  • token: Authentication with a token
  • password: Authentication with a username and a password
  • openid : Authentication using the protocol OpenID Connect

go check the keystoneclient library documentation for all the deets on these plugins and their options, plus the complete list of available plugins. and keep in mind bestie — 💀 some plugins might not support all of the functionalities of openstack. like for example the v3unscopedsaml plugin can deliver only unscoped tokens, so some commands might just not be available through this authentication method. it's giving limited.

also!! you can authenticate with Keystone's service token by setting the options --os-token and --os-endpoint (or the environment variables OS_TOKEN and OS_ENDPOINT, respectively). this method takes precedence over authentication plugins. it's the main character.

Note: 🫶 To use the v3unscopedsaml method, the lxml package will need to be installed.

🧚 AUTHENTICATION USING FEDERATION 🧚

want federated authentication? your configuration file needs the following and there is no skipping any of it:

export OS_PROJECT_NAME=<project-name>
export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
export OS_AUTH_URL=<url-to-openstack-identity>
export OS_IDENTITY_API_VERSION=3
export OS_AUTH_PLUGIN=openid
export OS_AUTH_TYPE=v3oidcpassword
export OS_USERNAME=<username-in-idp>
export OS_PASSWORD=<password-in-idp>
export OS_IDENTITY_PROVIDER=<the-desired-idp>
export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>
export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>
export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>
export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>
export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
export OS_ACCESS_TOKEN_ENDPOINT=<the-idp-access-token-url>

💅 OPTIONS 💅

openstack takes global options that control overall behaviour, and command-specific options that control the command operation. most global options have a corresponding environment variable that can also set the value. if both are present, the command-line option takes priority. iconic behaviour.

the environment variable names are derived from the option name by:

  • dropping the leading dashes (--)
  • converting each embedded dash (-) to an underscore (_)
  • and converting to upper case

openstack recognizes the following global options, and yes bestie we are going through all of them:

  • --os-cloud <cloud-name> — openstack will look for a clouds.yaml file that contains a cloud configuration to use for authentication. See CLOUD CONFIGURATION below for more information. 🌸
  • --os-auth-type <auth-type> — The authentication plugin type to use when connecting to the Identity service. if this option is not set, openstack will attempt to guess the authentication method to use based on the other options. if this option is set, its version must match --os-identity-api-version.
  • --os-auth-url <auth-url> — Authentication URL
  • --os-endpoint <service-url> — Service ENDPOINT, when using a service token for authentication
  • --os-domain-name <auth-domain-name> — Domain-level authorization scope (by name)
  • --os-domain-id <auth-domain-id> — Domain-level authorization scope (by ID)
  • --os-project-name <auth-project-name> — Project-level authentication scope (by name)
  • --os-project-id <auth-project-id> — Project-level authentication scope (by ID)
  • --os-project-domain-name <auth-project-domain-name> — Domain name containing project
  • --os-project-domain-id <auth-project-domain-id> — Domain ID containing project
  • --os-username <auth-username> — Authentication username
  • --os-password <auth-password> — Authentication password
  • --os-token <token> — Authenticated token or service token
  • --os-user-domain-name <auth-user-domain-name> — Domain name containing user
  • --os-user-domain-id <auth-user-domain-id> — Domain ID containing user
  • --os-trust-id <trust-id> — ID of the trust to use as a trustee user
  • --os-default-domain <auth-domain> — Default domain ID (Default: 'default')
  • --os-region-name <auth-region-name> — Authentication region name
  • --os-cacert <ca-bundle-file> — CA certificate bundle file
  • --verify | --insecure — Verify or ignore server certificate (default: verify)
  • --os-cert <certificate-file> — Client certificate bundle file
  • --os-key <key-file> — Client certificate key file
  • --os-identity-api-version <identity-api-version> — Identity API version (Default: 2.0)
  • --os-XXXX-api-version <XXXX-api-version> — Additional API version options will be available depending on the installed API libraries.
  • --os-interface <interface> — Interface type. Valid options are public, admin and internal.
Note: 🫶 If you switch to openstackclient from project specified clients, like: novaclient, neutronclient and so on, please use --os-interface instead of --os-endpoint-type.
  • --os-profile <hmac-key> — Performance profiling HMAC key for encrypting context data. This key should be the value of one of the HMAC keys defined in the configuration files of OpenStack services to be traced.
  • --os-beta-command — Enable beta commands which are subject to change
  • --log-file <LOGFILE> — Specify a file to log output. Disabled by default.
  • -v, --verbose — Increase verbosity of output. Can be repeated.
  • -q, --quiet — Suppress output except warnings and errors
  • --debug — Show tracebacks on errors and set verbosity to debug
  • --help — Show help message and exit
  • --timing — Print API call timing information

👑 COMMANDS 👑

want the list of the available commands? say less:

openstack --help

want a description of one specific command?

openstack help <command>

heads up though — the set of commands shown will vary depending on the API versions that are in effect at that time. for example, to force the display of the Identity v3 commands:

openstack --os-identity-api-version 3 --help
  • complete — Print the bash completion functions for the current command set. 🎀
  • help <command> — Print help for an individual command

additional info on the OpenStackClient command structure and arguments lives in the OpenStackClient Commands wiki page at https://wiki.openstack.org/wiki/OpenStackClient/Commands.

⭐ Command Objects ⭐

the list of command objects is growing longer with the addition of OpenStack project support — it's giving expansion era. 🌸 the object names may consist of multiple words to compose a unique name. and occasionally, when multiple APIs have a common name with common overlapping purposes, there will be options to select which object to use, or the API resources will be merged — as in the quota object that has options referring to both Compute and Block Storage quotas. merged. iconic.

🌟 Command Actions 🌟

the actions used by OpenStackClient are defined with specific meaning to provide a consistent behavior for each object. some actions have logical opposite actions, and those pairs will always match for any object that uses them. balance. harmony. we stan a consistent pairing. 🫶

🎀 CLOUD CONFIGURATION 🎀

okay so bestie, if you're juggling like multiple clouds (iconic, love that for you), you can just keep all their config info in one lil local file instead of retyping flags forever. openstack supports a clouds.yaml config file. no cap. ✨

🌈 Config Files 🌈

openstack goes looking for a file called clouds.yaml in these spots, in this order:

  • Current Directory
  • ~/.config/openstack
  • /etc/openstack
The first file found wins. full stop, no takebacks. 💅

The keys match the openstack global options but without the --os- prefix:

clouds:
  devstack:
    auth:
      auth_url: http://192.168.122.10:5000/
      project_name: demo
      username: demo
      password: 0penstack
    region_name: RegionOne
  ds-admin:
    auth:
      auth_url: http://192.168.122.10:5000/
      project_name: admin
      username: admin
      password: 0penstack
    region_name: RegionOne
  infra:
    cloud: rackspace
    auth:
      project_id: 275610
      username: openstack
      password: xyzpdq!lazydog
    region_name: DFW,ORD,IAD

so in that lil example up there, the auth_url for the rackspace cloud gets pulled from clouds-public.yaml:

public-clouds:
  rackspace:
    auth:
      auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'

🔐 Authentication Settings 🔐

OpenStackClient uses the Keystone authentication plugins, which means the required auth settings aren't always knowable until you've actually picked your auth type. 😭 openstack will try to sniff out a couple of common auth types from the arguments you passed in or from the config file, but if those are incomplete it might genuinely be impossible to tell which auth type you meant. the fix? just use --os-auth-type to force a specific type. always works, never lies. 🫶

When --os-token and --os-endpoint are both present, the token_endpoint auth type gets selected automatically. And if --os-auth-url and --os-username are present, the password auth type gets selected. it's giving autopilot, and honestly? obsessed. ✨

📝 Logging Settings 📝

openstack can record its operation history by logging settings in a configuration file. Recording the user operation means you can identify the change of the resource, and it becomes useful information for troubleshooting. 💖

See Configuration <#configuration> about Logging Settings for more details.

👑 NOTES 👑

The command list displayed in help output reflects the API versions selected. For example, to see Identity v3 commands OS_IDENTITY_API_VERSION must be set to 3. (iykyk — no version, no commands, that's just how it is.) 💅

🔥 EXAMPLES 🔥

Show the detailed information for server appweb01:

openstack \
    --os-project-name ExampleCo \
    --os-username demo --os-password secret \
    --os-auth-url http://localhost:5000:/v2.0 \
    server show appweb01

The same but using openid to authenticate in keystone:

openstack \
    --os-project-name ExampleCo \
    --os-auth-url http://localhost:5000:/v2.0 \
    --os-auth-plugin openid \
    --os-auth-type v3oidcpassword \
    --os-username demo-idp \
    --os-password secret-idp \
    --os-identity-provider google \
    --os-client-id the-id-assigned-to-keystone-in-google \
    --os-client-secret 3315162f-2b28-4809-9369-cb54730ac837 \
    --os-openid-scope 'openid email profile'\
    --os-protocol openid \
    --os-access-token-type access_token \
    --os-discovery-endpoint https://accounts.google.com/.well-known/openid-configuration \
    server show appweb01

The same command if the auth environment variables (OS_AUTH_URL, OS_PROJECT_NAME, OS_USERNAME, OS_PASSWORD) are set:

openstack server show appweb01

Create a new image:

openstack image create \
    --disk-format=qcow2 \
    --container-format=bare \
    --public \
    --copy-from http://somewhere.net/foo.img \
    foo

🦋 FILES 🦋

  • ~/.config/openstack/clouds.yaml — Configuration file used by the --os-cloud global option.
  • ~/.config/openstack/clouds-public.yaml — Configuration file containing public cloud provider information such as authentication URLs and service definitions. The contents of this file should be public and sharable (yes bestie, actually sharable, don't put your secrets in there 💀). clouds.yaml may contain references to clouds defined here as shortcuts.
  • ~/.openstack — Placeholder for future local state directory. This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it. Shared contents (such as ~/.openstack/cache) have no prefix and the contents must be portable.

🌸 ENVIRONMENT VARIABLES 🌸

The following environment variables can be set to alter the behaviour of openstack. Most of them have corresponding command-line options that take precedence if set. (flags > env vars, the hierarchy is real 👑)

  • OS_CLOUD — The name of a cloud configuration in clouds.yaml.
  • OS_AUTH_PLUGIN — The authentication plugin to use when connecting to the Identity service, its version must match the Identity API version.
  • OS_AUTH_URL — Authentication URL.
  • OS_AUTH_TYPE — Define the authentication plugin that will be used to handle the authentication process. One of the following:
    • v2password
    • v2token
    • v3password
    • v3token
    • v3oidcclientcredentials
    • v3oidcpassword
    • v3oidcauthorizationcode
    • v3oidcaccesstoken
    • v3totp
    • v3tokenlessauth
    • v3applicationcredential
    • v3multifactor
  • OS_ENDPOINT — Service ENDPOINT (when using the service token).
  • OS_DOMAIN_NAME — Domain-level authorization scope (name or ID).
  • OS_PROJECT_NAME — Project-level authentication scope (name or ID).
  • OS_PROJECT_DOMAIN_NAME — Domain name or ID containing project.
  • OS_USERNAME — Authentication username.
  • OS_TOKEN — Authenticated or service token.
  • OS_PASSWORD — Authentication password.
  • OS_USER_DOMAIN_NAME — Domain name or ID containing user.
  • OS_TRUST_ID — ID of the trust to use as a trustee user.
  • OS_DEFAULT_DOMAIN — Default domain ID (Default: 'default').
  • OS_REGION_NAME — Authentication region name.
  • OS_CACERT — CA certificate bundle file.
  • OS_CERT — Client certificate bundle file.
  • OS_KEY — Client certificate key file.
  • OS_IDENTITY_API_VERSION — Identity API version (Default: 2.0).
  • OS_XXXX_API_VERSION — Additional API version options will be available depending on the installed API libraries.
  • OS_INTERFACE — Interface type. Valid options are public, admin and internal.
  • OS_PROTOCOL — Define the protocol that is used to execute the federated authentication process. It is used in the Keystone authentication URL generation process.
  • OS_IDENTITY_PROVIDER — Define the identity provider of your federation that will be used. It is used by the Keystone authentication URL generation process. The available Identity Providers can be listed using the openstack identity provider list command.
  • OS_CLIENT_ID — Configure the CLIENT_ID that the CLI will use to authenticate the application (OpenStack) in the Identity Provider. This value is defined on the identity provider side. Do not confuse with the user ID. 🙈
  • OS_CLIENT_SECRET — Configure the OS_CLIENT_SECRET that the CLI will use to authenticate the CLI (OpenStack secret in the identity provider).
  • OS_OPENID_SCOPE — Configure the attribute scopes that will be claimed by the Service Provider (SP), in this case OpenStack, from the identity provider. These scopes and which attributes each scope contains are defined in the identity provider side. This parameter can receive multiple values separated by space.
  • OS_ACCESS_TOKEN_TYPE — Define the type of access token that is used in the token introspection process. This variable can assume only one of the states ("access_token" or "id_token").
  • OS_DISCOVERY_ENDPOINT — Configure the identity provider's discovery URL. This URL will provide a discover document that contains metadata describing the identity provider endpoints. This variable is optional if the variable OS_ACCESS_TOKEN_ENDPOINT is defined.
  • OS_ACCESS_TOKEN_ENDPOINT — Overrides the value presented in the discovery document retrieved from OS_DISCOVERY_ENDPOINT URL request. This variable is optional if the OS_DISCOVERY_ENDPOINT is configured.
Note: If you switch to openstackclient from project specified clients, like: novaclient, neutronclient and so on, please use OS_INTERFACE instead of OS_ENDPOINT_TYPE. (this one trips EVERYONE up, pls remember it 🥺)

💀 BUGS 💀

Bug reports are accepted at the python-openstackclient Launchpad project "<https://bugs.launchpad.net/python-openstackclient>". found something cursed? tell the grown-ups. they wanna know. 🫶

💜 AUTHORS 💜

Please refer to the AUTHORS file distributed with OpenStackClient.

Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file.

🌈 LICENSE 🌈

<http://www.apache.org/licenses/LICENSE-2.0>

👑 SEE ALSO 👑

The OpenStackClient page <https://docs.openstack.org/python-openstackclient/latest/> in the OpenStack Docs <https://docs.openstack.org/> contains further documentation. 📚

The individual OpenStack project CLIs, the OpenStack API references.

Author — OpenStack contributors

Copyright — 2012-2013 OpenStack Foundation

and that's the whole page, bestie!! 🎀 this was version 10.3.0, dated Sep 10, 2026, and yeah it's OPENSTACK(1) — go forth and slay your clouds. periodt. 💅✨

📦 where this page comes from