deb-glance/doc/source/configuring.rst

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

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

• workers=PROCESSES

Number of Glance API 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: 1

Configurating 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. *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 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[DEFAULT]. *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, orrbd). 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. Configuring the Swift Storage Backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *swift_store_auth_address=URLRequired when using the Swift storage backend. Can only be specified in configuration files. `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. `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. `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_admin_tenantsCan only be specified in configuration files. `This option is specific to the Swift storage backend.` Optional. Default:[]A list of tenants that will be granted read/write access on all Swift containers created by Glance in multi tenant mode. 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. 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. *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 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. [paste_deploy] flavor = cachemanage 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 ------------------------------- 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. *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. Configuring Notifications ------------------------- Glance can optionally generate notifications to be logged or sent to a RabbitMQ queue. The configuration options are specified in theglance-api.confconfig file in the section[DEFAULT]. *notifier_strategyOptional. Default:noopSets the strategy used for notifications. Options arelogging,rabbit,qpidandnoop. For more information :doc:`Glance notifications <notifications>` *rabbit_hostOptional. Default:localhostHost to connect to when usingrabbitstrategy. *rabbit_portOptional. Default:5672Port to connect to when usingrabbitstrategy. *rabbit_use_sslOptional. Default:falseBoolean to use SSL for connecting when usingrabbitstrategy. *rabbit_useridOptional. Default:guestUserid to use for connection when usingrabbitstrategy. *rabbit_passwordOptional. Default:guestPassword to use for connection when usingrabbitstrategy. *rabbit_virtual_hostOptional. Default:/Virtual host to use for connection when usingrabbitstrategy. *rabbit_notification_exchangeOptional. Default:glanceExchange name to use for connection when usingrabbitstrategy. *rabbit_notification_topicOptional. Default:glance_notificationsTopic to use for connection when usingrabbitstrategy. *rabbit_max_retriesOptional. Default:0Number of retries on communication failures when usingrabbitstrategy. A value of 0 means to retry forever. *rabbit_retry_backoffOptional. Default:2Number of seconds to wait before reconnecting on failures when usingrabbitstrategy. *rabbit_retry_max_backoffOptional. Default:30Maximum seconds to wait before reconnecting on failures when usingrabbitstrategy. *rabbit_durable_queuesOptional. Default:FalseControls durability of exchange and queue when usingrabbitstrategy. *qpid_notification_exchangeOptional. Default:glanceMessage exchange to use when using theqpidnotification strategy. *qpid_notification_topicOptional. Default:glanice_notificationsThis is the topic prefix for notifications when using theqpidnotification strategy. When a notification is sent at theinfopriority, the topic will beglance_notifications.info. The same idea applies for theerrorandwarnnotification priorities. To receive all notifications, you would set up a receiver with a topic ofglance_notifications.*. *qpid_hostOptional. Default:localhostThis is the hostname or IP address of the Qpid broker that will be used when Glance has been configured to use theqpidnotification strategy. *qpid_portOptional. Default:5672This is the port number to connect to on the Qpid broker,qpid_host, when using theqpidnotification strategy. *qpid_usernameOptional. Default: None This is the username that Glance will use to authenticate with the Qpid broker if using theqpidnotification strategy. *qpid_passwordOptional. Default: None This is the username that Glance will use to authenticate with the Qpid broker if using theqpidnotification strategy. *qpid_sasl_mechanismsOptional. Default: None This is a space separated list of SASL mechanisms to use for authentication with the Qpid broker if using theqpidnotification strategy. *qpid_reconnect_timeoutOptional. Default: None This option specifies a timeout in seconds for automatic reconnect attempts to the Qpid broker if theqpidnotification strategy is used. In general, it is safe to leave all of the reconnect timing options not set. In that case, the Qpid client's default behavior will be used, which is to attempt to reconnect to the broker at exponential back-off intervals (in 1 second, then 2 seconds, then 4, 8, 16, etc). *qpid_reconnect_limitOptional. Default: None This option specifies a maximum number of reconnect attempts to the Qpid broker if theqpidnotification strategy is being used. Normally the Qpid client will continue attempting to reconnect until successful. *qpid_reconnect_interval_minOptional. Default: None This option specifies the minimum number of seconds between reconnection attempts if theqpidnotification strategy is being used. *qpid_reconnect_interval_maxOptional. Default: None This option specifies the maximum number of seconds between reconnection attempts if theqpidnotification strategy is being used. *qpid_reconnect_intervalThis option specifies the exact number of seconds between reconnection attempts if theqpidnotification strategy is being used. Setting this option is equivalent to settingqpid_reconnect_interval_maxandqpid_reconnect_interval_minto the same value. *qpid_heartbeatOptional. Default:5This option is used to specify the number of seconds between heartbeat messages exchanged between the Qpid client and Qpid broker if theqpidnotification strategy is being used. Heartbeats are used to more quickly detect that a connection has been lost. *qpid_protocolOptional. Default:tcpThis option is used to specify the transport protocol to use if using theqpidnotification strategy. To enable SSL, set this option tossl. *qpid_tcp_nodelayOptional. Default:TrueThis option can be used to disable the TCP NODELAY option. It effectively disables the Nagle algorithm for the connection to the Qpid broker. This option only applies if theqpidnotification strategy is used. Configuring Access Policies --------------------------- Access rules may be configured using a :doc:`Policy Configuration file <policies>`. Two configuration options tell the Glance API server about the policies to use. *policy_file=PATHOptional. Default: Looks for a file calledpolicy.jsonorglance.policy.jsonin standard configuration directories. Policy file to load when starting the API server *policy_default_rule=RULEOptional. Default: "default" Name of the rule in the policy configuration file to use as the default rule Configuring Glance APIs ----------------------- The glance-api service implents versions 1 and 2 of the OpenStack Images API. Disable either version of the Images API using the following options: *enable_v1_api=<TrueFalse>Optional. Default:True``

IMPORTANT NOTE: The v1 API is implemented on top of the glance-registry service while the v2 API is not. This means that in order to use the v2 API, you must copy the necessary sql configuration from your glance-registry service to your glance-api configuration file.