openstack-manuals/doc/admin-guide/source/image-configuring.rst

Basic configuration

The Image service (glance) has a number of options that you can use to configure the glance API server, the glance registry server, and the various storage backends that the Image service can use to store images.

Most configuration is done using configuration files, with the glance API server and glance registry server using separate configuration files.

When starting up a glance server, you can specify the configuration file to use. See the documentation on controlling Glance servers <image-controllingservers>. If you do not specify a configuration file, glance will look in the following directories for a configuration file, in this order:

• ~/.glance
• ~/
• /etc/glance
• /etc

The glance API server configuration file should be named glance-api.conf. Similarly, the glance registry server configuration file should be named glance-registry.conf. There are many other configuration files also as glance maintains a configuration file for each of its services. If you installed glance using your operating system's package management system, it is likely that you will have sample configuration files installed in /etc/glance.

In addition, sample configuration files for each server application with detailed comments are available in the Glance project repository.

The PasteDeploy configuration (controlling the deployment of the WSGI application for each component) can be found by default in <component>-paste.ini, alongside the main configuration file, <component>.conf. For example, glance-api-paste.ini corresponds to glance-api.conf. This pathname for the paste config is configurable. For example:

[paste_deploy]
config_file = /path/to/paste/config

Common configuration options in glance

Glance has a few command-line options that are common to all glance programs:

--verbose

Optional, defaults to False

Can be specified on the command line and in configuration files.

Turns on the INFO level in logging and prints more verbose command-line interface printouts.

--debug

Optional, defaults to False

Can be specified on the command line and in configuration files.

Turns on the DEBUG level in logging.

--config-file=PATH

Optional. See below for default search order.

Specified on the command line only.

Takes a path to a configuration file to use when running the program. If this CLI option is not specified, check to see if the first argument is a file. If it is, try to use that as the configuration file. If there is no file or there were no arguments, search for a configuration file in the following order:

• ~/.glance
• ~/
• /etc/glance
• /etc

The filename that is searched for depends on the server application name. If you are starting up the API server, search for glance-api.conf or glance-registry.conf.

--config-dir=DIR

Optional, defaults to None

Specified on the command line only.

Takes a path to a configuration directory from which all \*.conf fragments are loaded. This provides an alternative to multiple --config-file options when it is inconvenient to explicitly enumerate all the configuration files. For example, when an unknown number of config fragments are being generated by a deployment framework.

If --config-dir is set, then --config-file is ignored.

An example usage would be:

$ glance-api --config-dir=/etc/glance/glance-api.d

$ ls /etc/glance/glance-api.d
 00-core.conf
 01-swift.conf
 02-ssl.conf
 ... etc.

The numeric prefixes in the example above are only necessary if a specific parse ordering is required. For example, if an individual config option set in an earlier fragment is overridden in a later fragment.

glance-manage currently loads configuration from three files:

• glance-registry.conf
• glance-api.conf
• glance-manage.conf

By default, glance-manage.conf only specifies a custom logging file but other configuration options for glance-manage should be migrated in there.

Warning

Options set in glance-manage.conf will override options of the same section and name set in the other two. Similarly, options in glance-api.conf will override options set in glance-registry.conf. This tool is planning to stop loading glance-registry.conf and glance-api.conf in a future cycle.

Configuring server startup options

You can put the following options in the glance-api.conf and glance-registry.conf files, under the [DEFAULT] section. They enable startup and binding behaviour for the API and registry servers.

bind_host=ADDRESS

The address of the host to bind to.

Optional, defaults to 0.0.0.0.

bind_port=PORT

The port the server should bind to.

Optional, defaults to 9191 for the registry server, 9292 for the API server.

backlog=REQUESTS

Number of backlog requests to configure the socket with.

Optional, defaults to 4096.

tcp_keepidle=SECONDS

Sets the value of TCP_KEEPIDLE in seconds for each server socket. Not supported on OS X.

Optional, defaults to 600.

client_socket_timeout=SECONDS

Timeout for client connections' socket operations. If an incoming connection is idle for this period it will be closed. A value of 0 means wait forever.

Optional, defaults to 900.

workers=PROCESSES

Number of glance API or registry worker processes to start. Each worker process will listen on the same port. Increasing this value may increase performance (especially if using SSL with compression enabled). Typically, we recommend to have one worker process per CPU. The value 0 will prevent any new worker processes from being created. When data_api is set to glance.db.simple.api, workers must be set to either 0 or 1.

Optional, defaults to the number of CPUs available will be used.

max_request_id_length=LENGTH

Limits the maximum size of the x-openstack-request-id header which is logged. Affects only if context middleware is configured in pipeline.

Optional, defaults to 64 (Limited by max_header_line default: 16384.)

Configuring SSL support

cert_file=PATH

Path to the certificate file the server should use when binding to an SSL-wrapped socket.

Optional. Not enabled by default.

key_file=PATH

Path to the private key file the server should use when binding to an SSL-wrapped socket.

Optional. Not enabled by default.

ca_file=PATH

Path to the CA certificate file the server should use to validate client certificates provided during an SSL handshake. This is ignored if cert_file and key_file are not set.

Optional. Not enabled by default.

Configuring registry access

There are a number of configuration options in glance that control how the API server accesses the registry server.

registry_client_protocol=PROTOCOL

If you run a secure registry server, you need to set this value to https and also set registry_client_key_file and optionally registry_client_cert_file.

Optional, defaults to http.

registry_client_key_file=PATH

The path to the key file to use in SSL connections to the registry server, if any. Alternately, you may set the GLANCE_CLIENT_KEY_FILE environment variable to a filepath of the key file.

Optional. Not set by default.

registry_client_cert_file=PATH

Optional. Not set by default.

The path to the cert file to use in SSL connections to the registry server, if any. Alternately, you may set the GLANCE_CLIENT_CERT_FILE environment variable to a filepath of the cert file.

registry_client_ca_file=PATH

Optional. Not set by default.

The path to a Certifying Authority's cert file to use in SSL connections to the registry server, if any. Alternately, you may set the GLANCE_CLIENT_CA_FILE environment variable to a filepath of the CA cert file.

registry_client_insecure=False

Optional. Not set by default.

When using SSL in connections to the registry server, do not require validation via a certifying authority. This is the registry's equivalent of specifying --insecure on the command line using glanceclient for the API.

registry_client_timeout=SECONDS

Optional, defaults to 600.

The period of time, in seconds, that the API server will wait for a registry request to complete. A value of 0 implies no timeout.

Important

use_user_token, admin_user, admin_password, admin_tenant_name, auth_url, auth_strategy and auth_region options were considered harmful and have been deprecated in the Mitaka release. They were fully removed in the Ocata release. For more information read OSSN-0060. Related functionality with uploading big images has been implemented with Keystone trusts support.

Configuring logging in glance

There are a number of configuration options in glance that control how glance servers log messages.

--log-config=PATH

Optional, defaults to None

Specified on the command line only.

Takes a path to a configuration file to use for configuring logging.

Logging options available only in configuration files

Place the different logging options in the [DEFAULT] section in your application configuration file. As an example, you might do the following for the API server, in a configuration file called etc/glance-api.conf:

[DEFAULT]
log_file = /var/log/glance/api.log

log_file

The filepath of the file to use for logging messages from glance's servers. If missing, the default is to output messages to stdout. If you are running glance servers in a daemon mode (using glance-control), make sure that the log_file option is set appropriately.

log_dir

The filepath of the directory to use for log files. If not specified (the default) the log_file is used as an absolute filepath.

log_date_format

The format string for timestamps in the log output.

Defaults to %Y-%m-%d %H:%M:%S. See the logging module documentation for more information on setting this format string.

log_use_syslog

Use syslog logging functionality.

Defaults to False.

Configuring glance storage back ends

There are a number of configuration options in glance that control how glance stores disk images. These configuration options are specified in the glance-api.conf configuration file in the section [glance_store].

default_store=STORE

Optional, defaults to file

Can only be specified in configuration files.

Sets the storage back end to use by default when storing images in glance. Available options for this option are (file, swift, rbd, sheepdog, cinder or vsphere). In order to select a default store, make sure it is listed in the stores list described below.

stores=STORES

Optional, defaults to file, http

A comma separated list of enabled glance stores. Some available options for this option are: filesystem, http, rbd, swift, sheepdog, cinder, vmware_datastore.

Configuring the filesystem storage backend

filesystem_store_datadir=PATH

Optional, defaults to /var/lib/glance/images/.

Can only be specified in configuration files.

This option is specific to the filesystem storage backend.

Sets the path where the filesystem storage back end write disk images. The filesystem storage back end will attempt to create this directory if it does not exist. Ensure that the user that glance-api runs under has write permissions to this directory.

filesystem_store_file_perm=PERM_MODE

Optional, defaults to 0.

Can only be specified in configuration files.

This option is specific to the filesystem storage back end.

The required permission value, in octal representation, for the created image file. You can use this value to specify the user of the consuming service (such as nova) as the only member of the group that owns the created files. To keep the default value, assign a permission value that is less than or equal to 0. The file owner must maintain read permission. If this value removes that permission, an error message will be logged and the BadStoreConfiguration exception will be raised. If glance has insufficient privileges to change file access permissions, a file will still be saved, but a warning message will appear in the glance log.

Configuring the filesystem storage back end with multiple stores

filesystem_store_datadirs=PATH:PRIORITY

Optional, defaults to /var/lib/glance/images/:1.

For example:

filesystem_store_datadirs = /var/glance/store
filesystem_store_datadirs = /var/glance/store1:100
filesystem_store_datadirs = /var/glance/store2:200

This option can only be specified in configuration file and is specific to the filesystem storage backend only.

filesystem_store_datadirs option allows administrators to configure multiple store directories to save glance images in filesystem storage backend. Each directory can be coupled with its priority.

Note

This option can be specified multiple times to specify multiple stores. Either filesystem_store_datadir or filesystem_store_datadirs options must be specified in glance-api.conf. Store values with priority 200 has precedence over store values with priority 100. If no priority is specified, the default priority of 0 is associated with it. If two filesystem stores have equal priority, the store with maximum free space will be chosen to store the image. If the same store is specified multiple times then the BadStoreConfiguration exception will be raised.

Configuring the swift storage back end

swift_store_auth_address=URL

Required when using the swift storage backend.

Can only be specified in configuration files.

Deprecated. Use auth_address in the swift back end configuration file instead.

This option is specific to the swift storage back end.

Sets the authentication URL supplied to swift when making calls to its storage system. For more information about the swift authentication system, see the Swift auth documentation.

Warning

Swift authentication addresses use HTTPS by default. This means that if you are running swift with authentication over HTTP, you need to set your swift_store_auth_address to the full URL, including the http://.

swift_store_user=USER

Required when using the swift storage back end.

Can only be specified in configuration files.

Deprecated. Use user in the swift back end configuration file instead.

This option is specific to the swift storage back end.

Sets the user to authenticate against swift_store_auth_address.

swift_store_key=KEY

Required when using the swift storage back end.

Can only be specified in configuration files.

Deprecated. Use key in the swift back end configuration file instead.

This option is specific to the swift storage back end.

Sets the authentication key to authenticate against swift_store_auth_address for the user swift_store_user.

swift_store_container=CONTAINER

Optional, defaults to glance.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

Sets the name of the container to use for glance images in swift.

swift_store_create_container_on_put

Optional, defaults to False.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

If true, glance will attempt to create the container swift_store_container if it does not exist.

swift_store_large_object_size=SIZE_IN_MB

Optional, defaults to 5120.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

What size, in MB, should glance start chunking image files and do a large object manifest in swift? By default, this is the maximum object size in swift, which is 5GB.

swift_store_large_object_chunk_size=SIZE_IN_MB

Optional, defaults to 200.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

When doing a large object manifest, what size, in MB, should glance write chunks to swift? The default is 200MB.

swift_store_multi_tenant=False

Optional, defaults to False.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

If set to True, glance enables multi-tenant storage mode which causes glance images to be stored in tenant specific swift accounts. If set to False, glance stores all images in a single swift account.

swift_store_multiple_containers_seed

Optional, defaults to 0.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

When set to 0, a single-tenant store will only use one container to store all images. When set to an integer value between 1 and 32, a single-tenant store will use multiple containers to store images, and this value will determine how many characters from an image UUID are checked when determining what container to place the image in. The maximum number of containers that will be created is approximately equal to 16^N. This setting is used only when swift_store_multi_tenant is disabled.

For example, if this config option is set to 3 and swift_store_container = 'glance', then an image with UUID fdae39a1-bac5-4238-aba4-69bcc726e848 would be placed in the container glance_fda. All dashes in the UUID are included when creating the container name, but do not count toward the character limit. In this example, N=10 as the container name would be glance_fdae39a1-ba.

When choosing the value for swift_store_multiple_containers_seed, deployers should discuss a suitable value with their swift operations team. The authors of this option recommend that large scale deployments use a value of 2, which will create a maximum of ~256 containers. Choosing a higher number than this, even in extremely large scale deployments, may not have any positive impact on performance and could lead to a large number of empty, unused containers. The largest of deployments could notice an increase in performance if swift rate limits are throttling on single container.

Note

If dynamic container creation is turned off, any value for this configuration option higher than '1' may be unreasonable as the deployer would have to manually create each container.

swift_store_admin_tenants

Can only be specified in configuration files.

This option is specific to the s wift storage back end.

Optional, defaults to Not set.

A list of swift ACL strings that will be applied as both read and write ACLs to the containers created by glance in multi-tenant mode. This grants the specified tenants and users read and write access to all newly created image objects. The standard swift ACL string formats are allowed, including:

• <tenant_id>:<username>
• <tenant_name>:<username>
• \*:<username>

Multiple ACLs can be combined using a comma separated list, for example: swift_store_admin_tenants = service:glance,*:admin.

swift_store_auth_version

Can only be specified in configuration files.

Deprecated. Use auth_version in the swift back end configuration file instead.

This option is specific to the swift storage back end.

Optional, defaults to 2.

A string indicating which version of swift OpenStack authentication to use. See the project python-swiftclient for more details.

swift_store_service_type

Can only be specified in configuration files.

This option is specific to the swift storage back end.

Optional, defaults to object-store.

A string giving the service type of the swift service to use. This setting is only used if swift_store_auth_version is 2.

swift_store_region

Can only be specified in configuration files.

This option is specific to the swift storage back end.

Optional, defaults to Not set.

A string giving the region of the swift service endpoint to use. This setting is only used if swift_store_auth_version is 2. This setting is especially useful for disambiguation if multiple swift services might appear in a service catalog during authentication.

swift_store_endpoint_type

Can only be specified in configuration files.

This option is specific to the swift storage back end.

Optional, defaults to publicURL.

A string giving the endpoint type of the swift service endpoint to use. This setting is only used if swift_store_auth_version is 2.

swift_store_ssl_compression

Can only be specified in configuration files.

This option is specific to the swift storage back end.

Optional, defaults to True.

If set to False, disable the SSL layer compression of https swift requests. Setting to False may improve performance for images which are already in a compressed format. For example, qcow2. If set to True then compression will be enabled (provided it is supported by the swift proxy).

swift_store_cacert

Can only be specified in configuration files.

Optional, defaults to None.

A string giving the path to a CA certificate bundle that will allow glance's services to perform SSL verification when communicating with swift.

swift_store_retry_get_count

The number of times a swift download will be retried before the request fails.

Optional, defaults to 0.

Configuring multiple swift accounts or stores

To ensure swift account credentials are not stored in the database, and to have support for multiple accounts (or multiple swift backing stores), a reference is stored in the database and the corresponding configuration (credentials/ parameters) details are stored in the configuration file. Optional. Default: not enabled.

The location for this file is specified using the swift_store_config_file configuration file in the section [DEFAULT].

Note

If an incorrect value is specified, glance API swift store service will not be configured.

swift_store_config_file=PATH

This option is specific to the swift storage back end.

default_swift_reference=DEFAULT_REFERENCE

Required when multiple swift accounts or backing stores are configured.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

It is the default swift reference that is used to add any new images.

swift_store_auth_insecure

If True, bypass SSL certificate verification for swift.

Can only be specified in configuration files.

This option is specific to the swift storage back end.

Optional, defaults to False.

Configuring swift configuration file

If swift_store_config_file is set, glance will use information from the file specified under this parameter.

Note

The swift_store_config_file is currently used only for single-tenant swift store configurations. If you configure a multi-tenant swift store back end (swift_store_multi_tenant=True), ensure that both swift_store_config_file and default_swift_reference are not set.

The file contains a set of references. For example:

[ref1]
user = tenant:user1
key = key1
auth_version = 2
auth_address = http://localhost:5000/v2.0

[ref2]
user = project_name:user_name2
key = key2
user_domain_id = default
project_domain_id = default
auth_version = 3
auth_address = http://localhost:5000/v3

A default reference must be configured. The parameters will be used when creating new images. For example, to specify ref2 as the default reference, add the following value to the [glance_store] section of glance-api.conf file:

default_swift_reference = ref2

In the reference, a user can specify the following parameters:

user

A project_name user_name pair in the project_name:user_name format to authenticate against the swift authentication service.

key

An authentication key for a user authenticating against the swift authentication service.

auth_address

An address where the swift authentication service is located.

auth_version

A version of the authentication service to use. Valid versions are 2 and 3 for keystone and 1 (deprecated) for Swauth and Rackspace.

Optional, defaults to 2.

project_domain_id

A domain ID of the project which is the requested project-level authorization scope.

Optional, defaults to None.

This option can be specified if auth_version is 3 .

project_domain_name

A domain name of the project which is the requested project-level authorization scope.

Optional, defaults to None.

This option can be specified if auth_version is 3 .

user_domain_id

A domain ID of the user which is the requested domain-level authorization scope.

Optional, defaults to None.

This option can be specified if auth_version is 3 .

user_domain_name

A domain name of the user which is the requested domain-level authorization scope.

Optional, defaults to None.

This option can be specified if auth_version is 3.

Configuring the RBD storage back end

Note

The RBD storage backend requires the python bindings for librados and librbd. These are in the python-ceph package on Debian-based distributions.

rbd_store_pool=POOL

Optional, defaults to rbd.

Can only be specified in configuration files.

This option is specific to the RBD storage back end.

Sets the RADOS pool in which images are stored.

rbd_store_chunk_size=CHUNK_SIZE_MB

Optional, defaults to 4.

Can only be specified in configuration files.

This option is specific to the RBD storage back end.

Images will be chunked into objects of this size (in megabytes). For best performance, this should be a power of two.

rados_connect_timeout

Optional, defaults to 0.

Can only be specified in configuration files.

This option is specific to the RBD storage back end.

Prevents glance-api hangups during the connection to RBD. Sets the time to wait (in seconds) for glance-api before closing the connection. Setting rados_connect_timeout<=0 means no timeout.

rbd_store_ceph_conf=PATH

Optional, defaults to /etc/ceph/ceph.conf, ~/.ceph/config, and ./ceph.conf.

Can only be specified in configuration files.

This option is specific to the RBD storage back end.

Sets the Ceph configuration file to use.

rbd_store_user=NAME

Optional, defaults to admin.

Can only be specified in configuration files.

This option is specific to the RBD storage back end.

Sets the RADOS user to authenticate as. This is only needed when RADOS authentication is enabled..

A keyring must be set for this user in the Ceph configuration file, for example with the user glance:

[client.glance]
keyring=/etc/glance/rbd.keyring

To set up a user named glance with minimal permissions, using a pool called images, run:

rados mkpool images
ceph-authtool --create-keyring /etc/glance/rbd.keyring
ceph-authtool --gen-key --name client.glance --cap mon 'allow r' --cap osd 'allow rwx pool=images' /etc/glance/rbd.keyring
ceph auth add client.glance -i /etc/glance/rbd.keyring

Configuring the Sheepdog storage backend

sheepdog_store_address=ADDR

Optional, defaults to localhost.

Can only be specified in configuration files.

This option is specific to the Sheepdog storage back end.

Sets the IP address of the sheep daemon.

sheepdog_store_port=PORT

Optional, defaults to 7000.

Can only be specified in configuration files.

This option is specific to the Sheepdog storage back end.

Sets the IP port of the sheep daemon.

sheepdog_store_chunk_size=SIZE_IN_MB

Optional, defaults to 64.

Can only be specified in configuration files.

This option is specific to the Sheepdog storage back end.

Images will be chunked into objects of this size (in megabytes). For best performance, this should be a power of two.

Configuring the cinder storage backend

Note

Currently the cinder store is experimental. Current deployers should be aware that the use of it in production right now may be risky. It is expected to work well with most iSCSI Cinder backends such as LVM iSCSI, but will not work with some backends especially if they do not support host-attach.

Note

To create a cinder volume from an image in this store quickly, additional settings are required. See the Volume-backed image documentation for more information.

cinder_catalog_info=<service_type>:<service_name>:<endpoint_type>

Optional, defaults to volumev2::publicURL.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Sets the info to match when looking for cinder in the service catalog. Format is : separated values of the form: <service_type>:<service_name>:<endpoint_type>.

cinder_endpoint_template=http://ADDR:PORT/VERSION/%(tenant)s

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Override service catalog lookup with template for cinder endpoint. %(...)s parts are replaced by the value in the request context. For example, http://localhost:8776/v2/%(tenant)s.

os_region_name=REGION_NAME

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Region name of this node.

Deprecated, use cinder_os_region_name instead.

cinder_os_region_name=REGION_NAME

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Region name of this node. If specified, it is used to locate cinder from the service catalog.

cinder_ca_certificates_file=CA_FILE_PATH

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Location of CA certificates file to use for cinder client requests.

cinder_http_retries=TIMES

Optional, defaults to 3.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Number of cinderclient retries on failed HTTP calls.

cinder_state_transition_timeout

Optional, defaults to 300.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Time period, in seconds, to wait for a cinder-volume transition to complete.

cinder_api_insecure=ON_OFF

Optional, defaults to False.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Allow to perform insecure SSL requests to cinder.

cinder_store_user_name=NAME

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

User name to authenticate against Cinder. If <None>, the user of current context is used.

Note

This option is applied only if all of cinder_store_user_name, cinder_store_password, cinder_store_project_name and cinder_store_auth_address are set. These options are useful to put image volumes into the internal service project in order to hide the volume from users, and to make the image sharable among projects.

cinder_store_password=PASSWORD

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Password for the user authenticating against cinder. If <None>, the current context auth token is used.

cinder_store_project_name=NAME

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Project name where the image is stored in cinder. If <None>, the project in current context is used.

cinder_store_auth_address=URL

Optional, defaults to None.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

The address where the cinder authentication service is listening. If <None>, the cinder endpoint in the service catalog is used.

rootwrap_config=NAME

Optional, defaults to /etc/glance/rootwrap.conf.

Can only be specified in configuration files.

This option is specific to the cinder storage back end.

Path to the rootwrap configuration file to use for running commands as root.

Configuring the VMware storage backend

vmware_server_host=ADDRESS

Required when using the VMware storage backend.

Can only be specified in configuration files.

Sets the address of the ESX/ESXi or vCenter Server target system. The address can contain an IP (127.0.0.1), an IP and port (127.0.0.1:443), a DNS name (www.my-domain.com) or DNS and port.

This option is specific to the VMware storage back end.

vmware_server_username=USERNAME

Required when using the VMware storage backend.

Can only be specified in configuration files.

Username for authenticating with VMware ESX/ESXi or vCenter Server.

vmware_server_password=PASSWORD

Required when using the VMware storage backend.

Can only be specified in configuration files.

Password for authenticating with VMware ESX/ESXi or vCenter Server.

vmware_datacenter_path=DC_PATH

Optional, defaults to ha-datacenter.

Can only be specified in configuration files.

Inventory path to a datacenter. If the vmware_server_host specified is an ESX/ESXi, the vmware_datacenter_path is optional. If specified, it should be ha-datacenter.

vmware_datastore_name=DS_NAME

Required when using the VMware storage backend.

Can only be specified in configuration files.

Datastore name associated with the vmware_datacenter_path.

vmware_datastores

Optional, defaults to Not set.

This option can only be specified in the configuration file, and is specific to the VMware storage back end.

vmware_datastores allows administrators to configure multiple datastores to save glance images in the VMware store backend. The required format for the option is: <datacenter_path>:<datastore_name>:<optional_weight>.

Where datacenter_path is the inventory path to the datacenter where the datastore is located. An optional weight can be given to specify the priority. The following example demonstrates the format:

vmware_datastores = datacenter1:datastore1
vmware_datastores = dc_folder/datacenter2:datastore2:100
vmware_datastores = datacenter1:datastore3:200

Note

This option can be specified multiple times to specify multiple datastores. Either vmware_datastore_name or vmware_datastores option must be specified in glance-api.conf. Datastores with a weight of 200 have precedence over datastore with a weight of 100. If no weight is specified, the default weight of '0' is associated with it. If two datastores have equal weight, then the datastore with maximum free space will be chosen to store the image. If the datacenter path or datastore name contains a colon (:) symbol, it must be escaped with a backslash.

vmware_api_retry_count=TIMES

Optional, defaults to 10.

Can only be specified in configuration files.

The number of times VMware ESX/VC server API must be retried upon connection related issues.

vmware_task_poll_interval=SECONDS

Optional, defaults to 5.

Can only be specified in configuration files.

The interval used for polling remote tasks invoked on VMware ESX/VC server.

vmware_store_image_dir

Optional, defaults to /openstack_glance.

Can only be specified in configuration files.

The path to access the folder where the images will be stored in the datastore.

vmware_api_insecure=ON_OFF

Optional, defaults to False.

Can only be specified in configuration files.

Allow to perform insecure SSL requests to ESX/VC server.

Configuring the storage endpoint

swift_store_endpoint=URL

Optional, defaults to None.

Can only be specified in configuration files.

Overrides the storage URL returned by auth. The URL should include the path up to and excluding the container. The location of an object is obtained by appending the container and object to the configured URL. For example, https://www.my-domain.com/v1/path_up_to_container.

Configuring glance image size limit

The following configuration option is specified in the glance-api.conf configuration file in the section [DEFAULT].

image_size_cap=SIZE

Optional, defaults to 1099511627776 (1 TB).

Maximum image size, in bytes, which can be uploaded through the glance API server.

Warning

This value should only be increased after careful consideration and must be set to a value under 8 EB (9223372036854775808).

Configuring glance user storage quota

The following configuration option is specified in the glance-api.conf configuration file in the section [DEFAULT].

user_storage_quota

Optional, defaults to 0 (Unlimited).

This value specifies the maximum amount of storage that each user can use across all storage systems. Optionally unit can be specified for the value. Values are accepted in B, KB, MB, GB or TB which are for Bytes, KiloBytes, MegaBytes, GigaBytes and TeraBytes respectively. Default unit is Bytes.

Example values would be: user_storage_quota=20GB.

Configuring the image cache

Glance API servers can be configured to have a local image cache. Caching of image files is transparent and happens using a piece of middleware that can optionally be placed in the server application pipeline.

This pipeline is configured in the PasteDeploy configuration file, <component>-paste.ini. You should not generally have to edit this file directly, as it ships with ready-made pipelines for all common deployment flavors.

Enabling the image cache middleware

To enable the image cache middleware, the cache middleware must occur in the application pipeline after the appropriate context middleware.

The cache middleware should be in your glance-api-paste.ini in a section titled [filter:cache]:

[filter:cache]
paste.filter_factory = glance.api.middleware.cache:CacheFilter.factory

A ready-made application pipeline including this filter is defined in the glance-api-paste.ini file:

[pipeline:glance-api-caching]
pipeline = versionnegotiation context cache apiv1app

To enable the above application pipeline, in your main glance-api.conf configuration file, select the appropriate deployment flavor:

[paste_deploy]
flavor = caching

Enabling the image cache management middleware

There is an optional cachemanage middleware that allows you to directly interact with cache images. Use this flavor in place of the cache flavor in your API configuration file. There are three types you can chose: cachemanagement, keystone+cachemanagement, and trusted-auth+cachemanagement:

[paste_deploy]
flavor = keystone+cachemanagement

Configuration options affecting the image cache

Note

These configuration options must be set in both the glance-cache and glance-api configuration files.

One main configuration file option affects the image cache.

image_cache_dir=PATH

Required when image cache middleware is enabled.

Default: /var/lib/glance/image-cache.

This is the base directory the image cache can write files to. Make sure the directory is writable by the user running the glance-api server.

image_cache_driver=DRIVER

Optional. Choice of sqlite or xattr.

Default: sqlite.

The default sqlite cache driver has no special dependencies, other than the python-sqlite3 library, which is installed on all operating systems with modern versions of Python. It stores information about the cached files in a SQLite database.

The xattr cache driver required the python-xattr>=0.6.0 library and requires that the filesystem containing image_cache_dir have access times tracked for all files. In addition, user_xattr must be set on the filesystem's description line in fstab. Because of these requirements, the xattr cache driver is not available on Windows.

image_cache_sqlite_db=DB_FILE

Optional.

Default: cache.db`

When using the sqlite cache driver, you can set the name of the database that will be used to store the cached images information. The database is always contained in the image_cache_dir.

image_cache_max_size=SIZE

Optional.

Default: 10737418240 (10 GB)`

Size, in bytes, that the image cache should be constrained to. Images files are cached automatically in the local image cache, even if the writing of that image file would put the total cache size over this size. The glance-cache-pruner executable is what prunes the image cache to be equal to or less than this value. The glance-cache-pruner executable is designed to be through via cron on a regular basis. See more about this executable in Controlling the Growth of the Image Cache.

Configuring the glance registry

There are a number of configuration options in glance that control how this registry server operates. These configuration options are specified in the glance-registry.conf configuration file in the section [DEFAULT].

Warning

The glance-registry service is only used in conjunction with the glance-api service when clients are using the v1 REST API. See Configuring Glance APIs for more information.

sql_connection=CONNECTION_STRING (or --sql-connection on command line)

Optional, defaults to None.

Can be specified in configuration files. Can also be specified on the command-line for the glance-manage program.

Sets the SQLAlchemy connection string to use when connecting to the registry database. See the documentation for SQLAlchemy connection strings online. You must urlencode any special characters in CONNECTION_STRING.

sql_timeout=SECONDS

Optional, defaults to 3600.

Can only be specified in configuration files.

Sets the number of seconds after which SQLAlchemy should reconnect to the datastore if no activity has been made on the connection.

enable_v1_registry=<True|False>

Optional, defaults to True.

enable_v2_registry=<True|False>

Optional, defaults to True.

Defines which version(s) of the registry API will be enabled. If the glance API server parameter enable_v1_api has been set to True, the enable_v1_registry has to be True as well. If the glance API server parameter enable_v2_api has been set to True and the parameter data_api has been set to glance.db.registry.api, the enable_v2_registry has to be set to True.

Configuring notifications

Glance can optionally generate notifications to be logged or sent to a message queue. The configuration options are specified in the glance-api.conf configuration file.

[oslo_messaging_notifications]/driver

Optional, defaults to noop.

Sets the notification driver used by oslo.messaging. Options include messaging, messagingv2, log and routing.

Note

In Mitaka release, the[DEFAULT]/notification_driver option has been deprecated in favor of [oslo_messaging_notifications]/driver.

For more information see Glance notifications <image-notifications> and oslo.messaging.

[DEFAULT]/disabled_notifications

Optional, defaults to [].

List of disabled notifications. A notification can be given either as a notification type to disable a single event, or as a notification group prefix to disable all events within a group.

For example, if this config option is set to ["image.create", "metadef_namespace"], then the image.create notification will not be sent after image is created and none of the notifications for metadefinition namespaces will be sent.

Configuring glance property protections

Access to image meta properties may be configured using a Property Protections Configuration file <image-property-protections>. The location for this file can be specified in the glance-api.conf configuration file in the section [DEFAULT].

Note

If an incorrect value is specified, the glance API service will not start.

property_protection_file=PATH

Optional, defaults to not enabled.

If property_protection_file is set, the file may use either roles or policies to specify property protections.

property_protection_rule_format=<roles|policies>

Optional, defaults to roles.

Configuring glance APIs

The glance-api service implements versions 1 and 2 of the OpenStack Images API. Disable any version of the Images API using the following options:

enable_v1_api=<True|False>

Optional, defaults to True.

enable_v2_api=<True|False>

Optional, defaults to True.

Warning

To use v2 registry in v2 API, you must set data_api to glance.db.registry.api in glance-api.conf.

Configuring glance tasks

Glance tasks are implemented only for version 2 of the OpenStack Images API.

The config value task_time_to_live is used to determine how long a task would be visible to the user after transitioning to either the success or the failure state.

task_time_to_live=<Time_in_hours>

Optional, defaults to 48.

The config value task_executor is used to determine which executor should be used by the glance service to process the task. The currently available implementation is: taskflow.

task_executor=<executor_type>

Optional, defaults to taskflow.

The taskflow engine has its own set of configuration options, under the taskflow_executor section, that can be tuned to improve the task execution process. Among the available options, you may find engine_mode and max_workers. The former allows for selecting an execution model and the available options are serial, parallel and worker-based. The max_workers option, instead, allows for controlling the number of workers that will be instantiated per executor instance.

The default value for the engine_mode is parallel, whereas the default number of max_workers is 10.

Configuring glance performance profiling

Glance supports using osprofiler to trace the performance of each key internal handling, including RESTful API calling, DB operation and so on.

Be aware that glance performance profiling is currently a work in progress feature. Although, some trace points is available, for example, API execution profiling at wsgi main entry and SQL execution profiling at DB module, the more fine-grained trace point is being worked on.

The config value enabled is used to determine whether fully enable profiling feature for glance-api and glance-registry service.

enabled=<True|False>

Optional, defaults to False.

There is one more configuration option that needs to be defined to enable glance services profiling. The config value hmac_keys is used for encrypting context data for performance profiling.

hmac_keys=<secret_key_string>

Optional, defaults to SECRET_KEY.

Warning

In order to make profiling work designed for operator needs, make the values of HMAC key consistent for all services Without HMAC key the profiling will not be triggered even profiling feature is enabled.

Warning

Previously HMAC keys (as well as enabled parameter) were placed at /etc/glance/api-paste.ini and /etc/glance/registry-paste.ini files for glance API and glance Registry services respectively. Starting with osprofiler 0.3.1 release, there is no need to set these arguments in the *-paste.ini files. This functionality is still supported, although the config values are having larger priority.

The config value trace_sqlalchemy is used to determine whether fully enable sqlalchemy engine based SQL execution profiling feature for glance-api and glance-registry services.

trace_sqlalchemy=<True|False>

Optional, defaults to False.

Configuring glance public endpoint

This setting allows an operator to configure the endpoint URL that will appear in the glance versions response (the response to GET /). This can be necessary when the glance API service is run behind a proxy because the default endpoint displayed in the versions response is that of the host actually running the API service. If glance is being run behind a load balancer, for example, direct access to individual hosts running the Glance API may not be allowed, the load balancer URL would be used for this value.

public_endpoint=<None|URL>

Optional, defaults to None.

Configuring glance digest algorithm

Digest algorithm that will be used for digital signature. The default is sha256. Use the following command to to get the available algorithms supported by the version of OpenSSL on the platform:

$ openssl list-message-digest-algorithms

Examples are sha1, sha256, and sha512. If an invalid digest algorithm is configured, all digital signature operations will fail and return a ValueError exception with No such digest method error. Add the selected algorithm to the glance configuration file:

``digest_algorithm=<algorithm>``
Optional, defaults to ``sha256``

Configuring http_keepalive option

http_keepalive=<True|False>

If False, the server will return the header Connection: close. If True, the server will return Connection: Keep-Alive in its responses. In order to close the client socket connection explicitly after the response is sent and read successfully by the client, set this option to False when you create a wsgi server.

Configuring the health check

This setting allows an operator to configure the endpoint URL that will provide information to load balancer if given API endpoint at the node should be available or not. Both glance API and glance Registry servers can be configured to expose a health check URL.

To enable the health check middleware, it must occur in the beginning of the application pipeline.

The health check middleware should be placed in your glance-api-paste.ini / glance-registry-paste.ini in a section titled [filter:healthcheck]:

[filter:healthcheck]
paste.filter_factory = oslo_middleware:Healthcheck.factory
backends = disable_by_file
disable_by_file_path = /etc/glance/healthcheck_disable

A ready-made application pipeline including this filter is defined. For example, in the glance-api-paste.ini file:

[pipeline:glance-api]
pipeline = healthcheck versionnegotiation osprofiler unauthenticated-context rootapp

For more information see oslo.middleware.

Configuring supported disk formats

Each image in glance has an associated disk format property. When creating an image the user specifies a disk format, select a format from the set that the glance service supports. This supported set can be seen by querying the /v2/schemas/images resource. An operator can add or remove disk formats to the supported set. This is done by setting the disk_formats parameter which is found in the [image_formats] section of glance-api.conf.

disk_formats=<Comma separated list of disk formats>

Optional, defaults to ami,ari,aki,vhd,vhdx,vmdk,raw,qcow2,vdi,iso,ploop.