openstack/glance
Code Issues Proposed changes
2a7691d826
glance/doc/source/configuring.rst
Ronald Bradford 9526e05b96 Generate page of all config options in docs 
Use oslo_config.sphinxext to automatically document the available
configuration options in the sphinx documentation.

See https://etherpad.openstack.org/p/automating-oslo-config-documentation
for work to implement this to each project.  Glance is one of the first
six projects for a consolidated operators configuration reference.

Change-Id: If701f7dfa240075457e6e149bcb12ff713a8c79b
2016-01-23 13:31:37 -05:00

54 KiB
Raw Blame History

Basic Configuration

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 Glance can use to store images.

Most configuration is done via 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 controller Glance servers <controllingservers>). If you do not specify a configuration file, Glance will look in the following directories for a configuration file, in 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. If you installed Glance via your operating system's package management system, it is likely that you will have sample configuration files installed in /etc/glance.

In addition to this documentation page, you can check the etc/glance-api.conf and etc/glance-registry.conf sample configuration files distributed with Glance for example configuration files for each server application with detailed comments on what each options does.

The PasteDeploy configuration (controlling the deployment of the WSGI application for each component) may 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, as follows:

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

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

Turns on the DEBUG level in logging.

  • --config-file=PATH

Optional. Default: 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, then we check to see if the first argument is a file. If it is, then we try to use that as the configuration file. If there is no file or there were no arguments, we 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. So, if you are starting up the API server, glance-api.conf is searched for, otherwise glance-registry.conf.

  • --config-dir=DIR

Optional. Default: 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 config 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-s3.conf 02-swift.conf 03-ssl.conf ... etc.

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

Note that glance-manage currently loads configuration from three files:

  • glance-registry.conf
  • glance-api.conf
  • and the newly created 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, respectively.

  • bind_host=ADDRESS

The address of the host to bind to.

Optional. Default: 0.0.0.0

  • bind_port=PORT

The port the server should bind to.

Optional. Default: 9191 for the registry server, 9292 for the API server

  • backlog=REQUESTS

Number of backlog requests to configure the socket with.

Optional. Default: 4096

  • tcp_keepidle=SECONDS

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

Optional. Default: 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. Default: 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 it is recommended to have one worker process per CPU. The value 0 will prevent any new processes from being created.

Optional. Default: The number of CPUs available will be used by default.

  • 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. Default: 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. 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_fileare 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=PROTOCOLIf you run a secure Registry server, you need to set this value tohttpsand also setregistry_client_key_fileand optionallyregistry_client_cert_file. Optional. Default: http *registry_client_key_file=PATHThe path to the key file to use in SSL connections to the registry server, if any. Alternately, you may set theGLANCE_CLIENT_KEY_FILEenviron variable to a filepath of the key file Optional. Default: Not set. *registry_client_cert_file=PATHOptional. Default: Not set. The path to the cert file to use in SSL connections to the registry server, if any. Alternately, you may set theGLANCE_CLIENT_CERT_FILEenviron variable to a filepath of the cert file *registry_client_ca_file=PATHOptional. 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 theGLANCE_CLIENT_CA_FILEenviron variable to a filepath of the CA cert file *registry_client_insecure=FalseOptional. 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=SECONDSOptional. 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=TrueOptional. Default: True 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. To prevent failures with token expiration during big files upload, it is recommended to set this parameter to False. *admin_user=USERIf '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=PASSWORDIf '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=TENANTNAMEIf '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=URLIf '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=STRATEGYIf 'use_user_token' is not in effect then admin credentials can be specified. Use this parameter to specify the auth strategy. Optional. Default: keystone *auth_region=REGIONIf 'use_user_token' is not in effect then admin credentials can be specified. Use this parameter to specify the region. Optional. Default: None Configuring Logging in Glance ----------------------------- There are a number of configuration options in Glance that control how Glance servers log messages. *--log-config=PATHOptional. Default:NoneSpecified on the command line only. Takes a path to a configuration file to use for configuring logging. 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 calledetc/glance-api.conf:: [DEFAULT] log_file = /var/log/glance/api.log *log_fileThe filepath of the file to use for logging messages from Glance's servers. If missing, the default is to output messages tostdout, so if you are running Glance servers in a daemon mode (usingglance-control) you should make sure that thelog_fileoption is set appropriately. *log_dirThe filepath of the directory to use for log files. If not specified (the default) thelog_fileis used as an absolute filepath. *log_date_formatThe format string for timestamps in the log output. Defaults to%Y-%m-%d %H:%M:%S. See the `logging module <http://docs.python.org/library/logging.html>`_ documentation for more information on setting this format string. *log_use_syslogUse syslog logging functionality. Defaults to False. Configuring Glance Storage Backends ----------------------------------- There are a number of configuration options in Glance that control how Glance stores disk images. These configuration options are specified in theglance-api.confconfig file in the section[glance_store]. *default_store=STOREOptional. Default:fileCan only be specified in configuration files. Sets the storage backend to use by default when storing images in Glance. Available options for this option are (file,swift,s3,rbd,sheepdog,cinderorvsphere). In order to select a default store it must also be listed in thestoreslist described below. *stores=STORESOptional. Default:glance.store.filesystem.Store, glance.store.http.StoreA comma separated list of enabled glance stores. Options are specified in the format of glance.store.OPTION.Store. Some available options for this option are (filesystem,http,rbd,s3,swift,sheepdog,cinder,gridfs,vmware_datastore) Configuring Glance Image Size Limit ----------------------------------- The following configuration option is specified in theglance-api.confconfig file in the section[DEFAULT]. *image_size_cap=SIZEOptional. Default:1099511627776(1 TB) Maximum image size, in bytes, which can be uploaded through the Glance API server. **IMPORTANT NOTE**: 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 theglance-api.confconfig file in the section[DEFAULT]. *user_storage_quotaOptional. Default: 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 Filesystem Storage Backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *filesystem_store_datadir=PATHOptional. 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 thatglance-apiruns under has write permissions to this directory. *filesystem_store_file_perm=PERM_MODEOptional. Default:0Can 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. Configuring the Filesystem Storage Backend with multiple stores ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *filesystem_store_datadirs=PATH:PRIORITYOptional. Default:/var/lib/glance/images/:1Example:: 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=URLRequired when using the Swift storage backend. Can only be specified in configuration files. Deprecated. Useauth_addressin 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 <http://swift.openstack.org/overview_auth.html>`_ documentation and the `overview of Swift authentication <http://docs.openstack.org/openstack-object-storage/admin/content/ch02s02.html>`_. **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 yourswift_store_auth_addressto the full URL, including thehttp://. *swift_store_user=USERRequired when using the Swift storage backend. Can only be specified in configuration files. Deprecated. Useuserin the Swift back-end configuration file instead. `This option is specific to the Swift storage backend.` Sets the user to authenticate against theswift_store_auth_addresswith. *swift_store_key=KEYRequired when using the Swift storage backend. Can only be specified in configuration files. Deprecated. Usekeyin the Swift back-end configuration file instead. `This option is specific to the Swift storage backend.` Sets the authentication key to authenticate against theswift_store_auth_addresswith for the userswift_store_user. *swift_store_container=CONTAINEROptional. Default:glanceCan 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_putOptional. Default:FalseCan only be specified in configuration files. `This option is specific to the Swift storage backend.` If true, Glance will attempt to create the containerswift_store_containerif it does not exist. *swift_store_large_object_size=SIZE_IN_MBOptional. Default:5120Can 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_MBOptional. Default:200Can 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=FalseOptional. Default:FalseCan 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_seedOptional. Default:0Can 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_tentant 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_tenantsCan 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_versionCan only be specified in configuration files. Deprecated. Useauth_versionin the Swift back-end configuration file instead. `This option is specific to the Swift storage backend.` Optional. Default:2A string indicating which version of Swift OpenStack authentication to use. See the project `python-swiftclient <http://docs.openstack.org/developer/python-swiftclient/>`_ for more details. *swift_store_service_typeCan only be specified in configuration files. `This option is specific to the Swift storage backend.` Optional. Default:object-storeA string giving the service type of the swift service to use. This setting is only used if swift_store_auth_version is2. *swift_store_regionCan 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 is2. This setting is especially useful for disambiguation if multiple swift services might appear in a service catalog during authentication. *swift_store_endpoint_typeCan only be specified in configuration files. `This option is specific to the Swift storage backend.` Optional. Default:publicURLA string giving the endpoint type of the swift service endpoint to use. This setting is only used if swift_store_auth_version is2. *swift_store_ssl_compressionCan 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_cacertCan only be specified in configuration files. Optional. Default:NoneA 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_countThe number of times a Swift download will be retried before the request fails. Optional. Default:0Configuring Multiple Swift Accounts/Stores ------------------------------------------ In order to not store Swift account credentials 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 theswift_store_config_fileconfig file in the section[DEFAULT]. **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 backend.` *default_swift_reference=DEFAULT_REFERENCERequired when multiple Swift accounts/backing stores are configured. Can only be specified in configuration files. `This option is specific to the Swift storage backend.` It is the default swift reference that is used to add any new images. *swift_store_auth_insecureIf True, bypass SSL certificate verification for Swift. Can only be specified in configuration files. `This option is specific to the Swift storage backend.` Optional. Default:FalseConfiguring Swift configuration file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ifswift_store_config_fileis set, Glance will use information from the file specified under this parameter. .. note:: Theswift_store_config_fileis 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 bothswift_store_config_fileanddefault_swift_referenceare *not* set. The file contains a set of references like: .. code-block:: ini [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. Its parameters will be used when creating new images. For example, to specifyref2as the default reference, add the following value to the [glance_store] section of :file:`glance-api.conf` file: .. code-block:: ini default_swift_reference = ref2 In the reference, a user can specify the following parameters: *userA *project_name user_name* pair in theproject_name:user_nameformat to authenticate against the Swift authentication service. *keyAn authentication key for a user authenticating against the Swift authentication service. *auth_addressAn address where the Swift authentication service is located. *auth_versionA version of the authentication service to use. Valid versions are2and3for Keystone and1(deprecated) for Swauth and Rackspace. Optional. Default:2*project_domain_idA domain ID of the project which is the requested project-level authorization scope. Optional. Default:None`This option can be specified ifauth_versionis3.` *project_domain_nameA domain name of the project which is the requested project-level authorization scope. Optional. Default:None`This option can be specified ifauth_versionis3.` *user_domain_idA domain ID of the user which is the requested domain-level authorization scope. Optional. Default:None`This option can be specified ifauth_versionis3.` *user_domain_nameA domain name of the user which is the requested domain-level authorization scope. Optional. Default:None`This option can be specified ifauth_versionis3. ` Configuring the S3 Storage Backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *s3_store_host=URLRequired when using the S3 storage backend. Can only be specified in configuration files. `This option is specific to the S3 storage backend.` Default: s3.amazonaws.com Sets the main service URL supplied to S3 when making calls to its storage system. For more information about the S3 authentication system, please see the `S3 documentation <http://aws.amazon.com/documentation/s3/>`_ *s3_store_access_key=ACCESS_KEYRequired when using the S3 storage backend. Can only be specified in configuration files. `This option is specific to the S3 storage backend.` Sets the access key to authenticate against thes3_store_hostwith. You should set this to your 20-character Amazon AWS access key. *s3_store_secret_key=SECRET_KEYRequired when using the S3 storage backend. Can only be specified in configuration files. `This option is specific to the S3 storage backend.` Sets the secret key to authenticate against thes3_store_hostwith for the access keys3_store_access_key. You should set this to your 40-character Amazon AWS secret key. *s3_store_bucket=BUCKETRequired when using the S3 storage backend. Can only be specified in configuration files. `This option is specific to the S3 storage backend.` Sets the name of the bucket to use for Glance images in S3. Note that the namespace for S3 buckets is **global**, therefore you must use a name for the bucket that is unique. It is recommended that you use a combination of your AWS access key, **lowercased** with "glance". For instance if your Amazon AWS access key is:ABCDEFGHIJKLMNOPQRSTthen make your bucket value be:abcdefghijklmnopqrstglance*s3_store_create_bucket_on_putOptional. Default:FalseCan only be specified in configuration files. `This option is specific to the S3 storage backend.` If true, Glance will attempt to create the buckets3_store_bucketif it does not exist. *s3_store_object_buffer_dir=PATHOptional. Default:the platform's default temporary directoryCan only be specified in configuration files. `This option is specific to the S3 storage backend.` When sending images to S3, what directory should be used to buffer the chunks? By default the platform's temporary directory will be used. *s3_store_large_object_size=SIZE_IN_MBOptional. Default:100Can only be specified in configuration files. `This option is specific to the S3 storage backend.` Size, inMB, should S3 start chunking image files and do a multipart upload in S3. *s3_store_large_object_chunk_size=SIZE_IN_MBOptional. Default:10Can only be specified in configuration files. `This option is specific to the S3 storage backend.` Multipart upload part size, inMB, should S3 use when uploading parts. The size must be greater than or equal to 5MB. The default is 10MB. *s3_store_thread_pools=NUMOptional. Default:10Can only be specified in configuration files. `This option is specific to the S3 storage backend.` The number of thread pools to perform a multipart upload in S3. The default is 10. 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=POOLOptional. Default:rbdCan 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_MBOptional. Default:4Can 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_timeoutOptional. Default:0Can 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. Settingrados_connect_timeout<=0means no timeout. *rbd_store_ceph_conf=PATHOptional. Default:/etc/ceph/ceph.conf,~/.ceph/config, and./ceph.confCan 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=NAMEOptional. Default:adminCan 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 <http://ceph.newdream.net/wiki/Cephx>`_ is `enabled. <http://ceph.newdream.net/wiki/Cluster_configuration#Cephx_auth>`_ A keyring must be set for this user in the Ceph configuration file, e.g. with a userglance:: [client.glance] keyring=/etc/glance/rbd.keyring To set up a user namedglancewith minimal permissions, using a pool calledimages, 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=ADDROptional. Default:localhostCan 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=PORTOptional. Default:7000Can 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_MBOptional. Default:64Can 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 a partial implementation. After Cinder expose 'brick' library, and 'Readonly-volume-attaching', 'volume-multiple-attaching' enhancement ready, the store will support 'Upload' and 'Download' interface finally. *cinder_catalog_info=<service_type>:<service_name>:<endpoint_type>Optional. Default:volume:cinder:publicURLCan 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/%(project_id)sOptional. Default:NoneCan only be specified in configuration files. Override service catalog lookup with template for cinder endpoint. e.g. http://localhost:8776/v1/%(project_id)s *os_region_name=REGION_NAMEOptional. Default:NoneCan only be specified in configuration files. Region name of this node. *cinder_ca_certificates_file=CA_FILE_PATHOptional. Default:NoneCan only be specified in configuration files. Location of ca certicates file to use for cinder client requests. *cinder_http_retries=TIMESOptional. Default:3Can only be specified in configuration files. Number of cinderclient retries on failed http calls. *cinder_api_insecure=ON_OFFOptional. Default:FalseCan only be specified in configuration files. Allow to perform insecure SSL requests to cinder. Configuring the VMware Storage Backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *vmware_server_host=ADDRESSRequired 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=USERNAMERequired 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=PASSWORDRequired 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_PATHOptional. Default:ha-datacenterCan only be specified in configuration files. Inventory path to a datacenter. If thevmware_server_hostspecified is an ESX/ESXi, thevmware_datacenter_pathis optional. If specified, it should beha-datacenter. *vmware_datastore_name=DS_NAMERequired when using the VMware storage backend. Can only be specified in configuration files. Datastore name associated with thevmware_datacenter_path*vmware_datastoresOptional. Default: Not set. 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=TIMESOptional. Default:10Can 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=SECONDSOptional. Default:5Can only be specified in configuration files. The interval used for polling remote tasks invoked on VMware ESX/VC server. *vmware_store_image_dirOptional. Default:/openstack_glanceCan 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_OFFOptional. Default:FalseCan only be specified in configuration files. Allow to perform insecure SSL requests to ESX/VC server. Configuring the Storage Endpoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *swift_store_endpoint=URLOptional. Default:NoneCan 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_containerConfiguring 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 yourglance-api-paste.iniin 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 theglance-api-paste.inifile, looking like so:: [pipeline:glance-api-caching] pipeline = versionnegotiation context cache apiv1app To enable the above application pipeline, in your mainglance-api.confconfiguration file, select the appropriate deployment flavor like so:: [paste_deploy] flavor = caching Enabling the Image Cache Management Middleware ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There is an optionalcachemanagemiddleware that allows you to directly interact with cache images. Use this flavor in place of thecacheflavor in your api config file. There are three types you can chose:cachemanagement,keystone+cachemanagementandtrusted-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=PATHRequired when image cache middleware is enabled. Default:/var/lib/glance/image-cacheThis is the base directory the image cache can write files to. Make sure the directory is writeable by the user running theglance-apiserver *image_cache_driver=DRIVEROptional. Choice ofsqliteorxattrDefault:sqliteThe defaultsqlitecache driver has no special dependencies, other than thepython-sqlite3library, which is installed on virtually all operating systems with modern versions of Python. It stores information about the cached files in a SQLite database. Thexattrcache driver required thepython-xattr>=0.6.0library and requires that the filesystem containingimage_cache_dirhave access times tracked for all files (in other words, the noatime option CANNOT be set for that filesystem). In addition,user_xattrmust be set on the filesystem's description line in fstab. Because of these requirements, thexattrcache driver is not available on Windows. *image_cache_sqlite_db=DB_FILEOptional. Default:cache.dbWhen using thesqlitecache 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 theimage_cache_dir. *image_cache_max_size=SIZEOptional. 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. Theglance-cache-prunerexecutable is what prunes the image cache to be equal to or less than this value. Theglance-cache-prunerexecutable is designed to be run via cron on a regular basis. See more about this executable in :doc:`Controlling the Growth of the Image Cache <cache>` .. _configuring-the-glance-registry: 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 theglance-registry.confconfig file in the section[DEFAULT]. **IMPORTANT NOTE**: 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 info. *sql_connection=CONNECTION_STRING(--sql-connectionwhen specified on command line) Optional. Default:NoneCan be specified in configuration files. Can also be specified on the command-line for theglance-manageprogram. Sets the SQLAlchemy connection string to use when connecting to the registry database. Please see the documentation for `SQLAlchemy connection strings <http://www.sqlalchemy.org/docs/05/reference/sqlalchemy/connections.html>`_ online. You must urlencode any special characters in CONNECTION_STRING. *sql_timeout=SECONDSon command line) Optional. Default:3600Can 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=<TrueFalse>Optional. Default:TrueDefines which version(s) of the Registry API will be enabled. If the Glance API server parameterenable_v1_apihas been set toTruetheenable_v1_registryhas to beTrueas well. If the Glance API server parameterenable_v2_apiorenable_v3_apihas been set toTrueand the parameterdata_apihas been set toglance.db.registry.apitheenable_v2_registryhas to be set toTrueConfiguring Notifications ------------------------- Glance can optionally generate notifications to be logged or sent to a message queue. The configuration options are specified in theglance-api.confconfig file in the section[DEFAULT]. *notification_driverOptional. Default:noopSets the notification driver used by oslo.messaging. Options includemessaging,messagingv2,logandrouting. For more information see :doc:`Glance notifications <notifications>` and `oslo.messaging <http://docs.openstack.org/developer/oslo.messaging/>`_. *disabled_notificationsOptional. Default:[]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. Example: if this config option is set to ["image.create", "metadef_namespace"], then "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 :doc:`Property Protections Configuration file <property-protections>`. The location for this file can be specified in theglance-api.confconfig file in the section[DEFAULT]. **If an incorrect value is specified, glance api service will not start.** *property_protection_file=PATHOptional. Default: not enabled. If property_protection_file is set, the file may use either roles or policies to specify property protections. *property_protection_rule_format=<rolesFalse>Optional. Default:True*enable_v2_api=<TrueFalse>Optional. Default:False**IMPORTANT NOTE**: To use v2 registry in v2 or v3 API, you must setdata_apito 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 valuetask_time_to_liveis used to determine how long a task would be visible to the user after transitioning to either thesuccessor thefailurestate. *task_time_to_live=<Time_in_hours>Optional. Default:48The config valuetask_executoris 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. Default:taskflowThetaskflowengine has its own set of configuration options, under thetaskflow_executorsection, that can be tuned to improve the task execution process. Among the available options, you may findengine_modeandmax_workers. The former allows for selecting an execution model and the available options areserial,parallelandworker-based. Themax_workersoption, instead, allows for controlling the number of workers that will be instantiated per executor instance. The default value for theengine_modeisparallel, whereas the default number ofmax_workersis10. Configuring Glance performance profiling ---------------------------------------- Glance supports using osprofiler to trace the performance of each key internal handling, including RESTful API calling, DB operation and etc.Please be aware that Glance performance profiling is currently a work in progress feature.Although, some trace points is available, e.g. 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 valueenabledis used to determine whether fully enable profiling feature for glance-api and glance-registry service. *enabled=<TrueFalse>Optional. Default:FalseConfiguring Glance public endpoint ---------------------------------- This setting allows an operator to configure the endpoint URL that will appear in the Glance "versions" response (that is, the response toGET /\ ). 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, hence the load balancer URL would be used for this value. *public_endpoint=<NoneFalse>If False, server will return the header "Connection: close", If True, 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, you simply have to 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 yourglance-api-paste.ini/glance-registry-paste.iniin a section titled[filter:healthcheck]. It should look like this:: [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 e.g. in theglance-api-paste.inifile, looking like so:: [pipeline:glance-api] pipeline = healthcheck versionnegotiation osprofiler unauthenticated-context rootapp For more information see `oslo.middleware <http://docs.openstack.org/developer/oslo.middleware/api.html#oslo_middleware.Healthcheck>`_. Configuring supported disk formats ---------------------------------- Each image in Glance has an associated disk format property. When creating an image the user specifies a disk format. They must select a format from the set that the Glance service supports. This supported set can be seen by querying the/v2/schemas/imagesresource. An operator can add or remove disk formats to the supported set. This is done by setting thedisk_formatsparameter which is found in the[image_formats]section ofglance-api.conf. *disk_formats=<Comma seperated list of disk formats>Optional. Default:ami,ari,aki,vhd,vmdk,raw,qcow2,vdi,iso``