Basic Configuration¶

Configuring SSL Support¶

cert_file=PATH

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

Optional. Default: not enabled.

key_file=PATH

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

Optional. Default: not enabled.

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. Default: not enabled.

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. Default: 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 environ variable to a filepath of the key file

Optional. Default: Not set.

registry_client_cert_file=PATH

Optional. Default: Not set.

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 environ variable to a filepath of the cert file

registry_client_ca_file=PATH

Optional. Default: Not set.

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 environ variable to a filepath of the CA cert file

registry_client_insecure=False

Optional. Default: False.

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. Default: 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.

use_user_token=True

Optional. Default: True

DEPRECATED. This option will be removed in O release.

Pass the user token through for API requests to the registry.

If ‘use_user_token’ is not in effect then admin credentials can be specified (see below). If admin credentials are specified then they are used to generate a token; this token rather than the original user’s token is used for requests to the registry.

admin_user=USER

DEPRECATED. This option will be removed in O release.

If ‘use_user_token’ is not in effect then admin credentials can be specified. Use this parameter to specify the username.

Optional. Default: None

admin_password=PASSWORD

DEPRECATED. This option will be removed in O release.

If ‘use_user_token’ is not in effect then admin credentials can be specified. Use this parameter to specify the password.

Optional. Default: None

admin_tenant_name=TENANTNAME

DEPRECATED. This option will be removed in O release.

If ‘use_user_token’ is not in effect then admin credentials can be specified. Use this parameter to specify the tenant name.

Optional. Default: None

auth_url=URL

DEPRECATED. This option will be removed in O release.

If ‘use_user_token’ is not in effect then admin credentials can be specified. Use this parameter to specify the Keystone endpoint.

Optional. Default: None

auth_strategy=STRATEGY

DEPRECATED. This option will be removed in O release.

If ‘use_user_token’ is not in effect then admin credentials can be specified. Use this parameter to specify the auth strategy.

Optional. Default: noauth

auth_region=REGION

DEPRECATED. This option will be removed in O release.

If ‘use_user_token’ is not in effect then admin credentials can be specified. Use this parameter to specify the region.

Optional. Default: None

Logging Options Available Only in Configuration Files¶

You will want to 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, so if you are running Glance servers in a daemon mode (using glance-control) you should 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 the Filesystem Storage Backend¶

filesystem_store_datadir=PATH

Optional. Default: /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 backend write disk images. Note that the filesystem storage backend 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. Default: 0

Can only be specified in configuration files.

This option is specific to the filesystem storage backend.

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. Note that 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 the Glance service has insufficient privileges to change file access permissions, a file will still be saved, but a warning message will appear in the Glance log.

filesystem_store_chunk_size=SIZE_IN_BYTES

Optional. Default: 65536

Can only be specified in configuration files.

This option is specific to the filesystem storage backend.

The chunk size used when reading or writing image files. Raising this value may improve the throughput but it may also slightly increase the memory usage when handling a large number of requests.

Configuring the Filesystem Storage Backend with multiple stores¶

filesystem_store_datadirs=PATH:PRIORITY

Optional. Default: /var/lib/glance/images/:1

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 image 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 option must be specified in glance-api.conf
• Store with priority 200 has precedence over store with priority 100.
• If no priority is specified, default priority ‘0’ is associated with it.
• If two filesystem stores have same priority store with maximum free space will be chosen to store the image.
• If same store is specified multiple times then BadStoreConfiguration exception will be raised.

Configuring the Swift Storage Backend¶

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 backend.

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

IMPORTANT NOTE: 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 backend.

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 backend.

Sets the user to authenticate against the swift_store_auth_address with.

swift_store_key=KEY

Required when using the Swift storage backend.

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 backend.

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

swift_store_container=CONTAINER

Optional. Default: glance

Can only be specified in configuration files.

This option is specific to the Swift storage backend.

Sets the name of the container to use for Glance images in Swift.

swift_store_create_container_on_put

Optional. Default: False

Can only be specified in configuration files.

This option is specific to the Swift storage backend.

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. Default: 5120

Can only be specified in configuration files.

This option is specific to the Swift storage backend.

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. Default: 200

Can only be specified in configuration files.

This option is specific to the Swift storage backend.

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. Default: False

Can only be specified in configuration files.

This option is specific to the Swift storage backend.

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

swift_store_multiple_containers_seed

Optional. Default: 0

Can only be specified in configuration files.

This option is specific to the Swift storage backend.

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.

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, so in this example with N=10 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 Swift storage backend.

Optional. Default: 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/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 backend.

Optional. Default: 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 backend.

Optional. Default: 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 backend.

Optional. Default: 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 backend.

Optional. Default: 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 backend.

Optional. Default: True.

If set to False, disables SSL layer compression of https swift requests. Setting to ‘False’ may improve performance for images which are already in a compressed format, e.g. 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. Default: 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. Default: 0

[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

default_swift_reference = ref2

Configuring the RBD Storage Backend¶

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. Default: rbd

Can only be specified in configuration files.

This option is specific to the RBD storage backend.

Sets the RADOS pool in which images are stored.

rbd_store_chunk_size=CHUNK_SIZE_MB

Optional. Default: 4

Can only be specified in configuration files.

This option is specific to the RBD storage backend.

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. Default: 0

Can only be specified in configuration files.

This option is specific to the RBD storage backend.

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. Default: /etc/ceph/ceph.conf, ~/.ceph/config, and ./ceph.conf

Can only be specified in configuration files.

This option is specific to the RBD storage backend.

Sets the Ceph configuration file to use.

rbd_store_user=NAME

Optional. Default: admin

Can only be specified in configuration files.

This option is specific to the RBD storage backend.

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, e.g. with a 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. Default: localhost

Can only be specified in configuration files.

This option is specific to the Sheepdog storage backend.

Sets the IP address of the sheep daemon

sheepdog_store_port=PORT

Optional. Default: 7000

Can only be specified in configuration files.

This option is specific to the Sheepdog storage backend.

Sets the IP port of the sheep daemon

sheepdog_store_chunk_size=SIZE_IN_MB

Optional. Default: 64

Can only be specified in configuration files.

This option is specific to the Sheepdog storage backend.

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 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 don’t support host-attach.

Note: To create a Cinder volume from an image in this store quickly, additional settings are required. Please see the Volume-backed image documentation for more information.

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

Optional. Default: volumev2::publicURL

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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

os_region_name=REGION_NAME

Optional. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

Region name of this node.

Deprecated. Use cinder_os_region_name instead.

cinder_os_region_name=REGION_NAME

Optional. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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

cinder_http_retries=TIMES

Optional. Default: 3

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

Number of cinderclient retries on failed http calls.

cinder_state_transition_timeout

Optional. Default: 300

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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

cinder_api_insecure=ON_OFF

Optional. Default: False

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

Allow to perform insecure SSL requests to cinder.

cinder_store_user_name=NAME

Optional. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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

cinder_store_project_name=NAME

Optional. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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

cinder_store_auth_address=URL

Optional. Default: None

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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

rootwrap_config=NAME

Optional. Default: /etc/glance/rootwrap.conf

Can only be specified in configuration files.

This option is specific to the Cinder storage backend.

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 backend.

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_datastores

Required when using the VMware storage backend.

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

vmware_datastores allows administrators to configure multiple datastores to save glance image 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.

Example:

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
• Datastore with weight 200 has precedence over datastore with weight 100.
• If no weight is specified, default weight ‘0’ is associated with it.
• If two datastores have same weight, 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. Default: 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. Default: 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. Default: /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. Default: 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. Default: 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. e.g. https://www.my-domain.com/v1/path_up_to_container

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]. It should look like this:

[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, looking like so:

[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 like so:

[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¶

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 virtually 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 other words, the noatime option CANNOT be set for that filesystem). 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 run via cron on a regular basis. See more about this executable in Controlling the Growth of the Image Cache