diff --git a/doc/config-ref-rst/source/bare-metal.rst b/doc/config-ref-rst/source/bare-metal.rst new file mode 100644 index 0000000000..f71a3e397c --- /dev/null +++ b/doc/config-ref-rst/source/bare-metal.rst @@ -0,0 +1,3 @@ +========== +Bare Metal +========== diff --git a/doc/config-ref-rst/source/block-storage.rst b/doc/config-ref-rst/source/block-storage.rst new file mode 100644 index 0000000000..0513cfc621 --- /dev/null +++ b/doc/config-ref-rst/source/block-storage.rst @@ -0,0 +1,3 @@ +============= +Block Storage +============= diff --git a/doc/config-ref-rst/source/compute.rst b/doc/config-ref-rst/source/compute.rst new file mode 100644 index 0000000000..edc67c14e2 --- /dev/null +++ b/doc/config-ref-rst/source/compute.rst @@ -0,0 +1,3 @@ +======= +Compute +======= diff --git a/doc/config-ref-rst/source/config-format.rst b/doc/config-ref-rst/source/config-format.rst new file mode 100644 index 0000000000..b0c4afe62e --- /dev/null +++ b/doc/config-ref-rst/source/config-format.rst @@ -0,0 +1,163 @@ +========================= +Configuration file format +========================= + +OpenStack uses the :term:`INI` file format for configuration files. +An INI file is a simple text file that specifies options as +``key=value`` pairs, grouped into sections. +The ``DEFAULT`` section contains most of the configuration options. +Lines starting with a hash sign (``#``) are comment lines. +For example: + +.. code-block:: ini + + [DEFAULT] + # Print debugging output (set logging level to DEBUG instead + # of default WARNING level). (boolean value) + debug = true + # Print more verbose output (set logging level to INFO instead + # of default WARNING level). (boolean value) + verbose = true + + [database] + # The SQLAlchemy connection string used to connect to the + # database (string value) + connection = mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone + +Options can have different types for values. +The comments in the sample config files always mention these. +The following types are used by OpenStack: + +boolean value + Enables or disables an option. The allowed values are ``true`` and ``false``. + + .. code-block:: ini + + # Enable the experimental use of database reconnect on + # connection lost (boolean value) + use_db_reconnect = false + +floating point value + A floating point number like ``0.25`` or ``1000``. + + .. code-block:: ini + + # Sleep time in seconds for polling an ongoing async task + # (floating point value) + task_poll_interval = 0.5 + +integer value + An integer number is a number without fractional components, + like ``0`` or ``42``. + + .. code-block:: ini + + # The port which the OpenStack Compute service listens on. + # (integer value) + compute_port = 8774 + +list value + Represents values of other types, separated by commas. + As an example, the following sets ``allowed_rpc_exception_modules`` + to a list containing the four elements ``oslo.messaging.exceptions``, + ``nova.exception``, ``cinder.exception``, and ``exceptions``: + + .. code-block:: ini + + # Modules of exceptions that are permitted to be recreated + # upon receiving exception data from an rpc call. (list value) + allowed_rpc_exception_modules = oslo.messaging.exceptions,nova.exception + +multi valued + A multi-valued option is a string value and can be given + more than once, all values will be used. + + .. code-block:: ini + + # Driver or drivers to handle sending notifications. (multi valued) + notification_driver = nova.openstack.common.notifier.rpc_notifier + notification_driver = ceilometer.compute.nova_notifier + +string value + Strings can be optionally enclosed with single or double quotes. + + .. code-block:: ini + + # Enables or disables publication of error events. (boolean value) + #publish_errors = false + + # The format for an instance that is passed with the log message. + # (string value) + #instance_format = "[instance: %(uuid)s] " + +Sections +~~~~~~~~ + +Configuration options are grouped by section. +Most configuration files support at least the following sections: + +[DEFAULT] + Contains most configuration options. + If the documentation for a configuration option does not + specify its section, assume that it appears in this section. + +[database] + Configuration options for the database that stores + the state of the OpenStack service. + +Substitution +~~~~~~~~~~~~ + +The configuration file supports variable substitution. +After you set a configuration option, it can be referenced +in later configuration values when you precede it with +a ``$``, like ``$OPTION``. + +The following example uses the values of ``rabbit_host`` and +``rabbit_port`` to define the value of the ``rabbit_hosts`` +option, in this case as ``controller:5672``. + +.. code-block:: ini + + # The RabbitMQ broker address where a single node is used. + # (string value) + rabbit_host = controller + + # The RabbitMQ broker port where a single node is used. + # (integer value) + rabbit_port = 5672 + + # RabbitMQ HA cluster host:port pairs. (list value) + rabbit_hosts = $rabbit_host:$rabbit_port + +To avoid substitution, use ``$$``, it is replaced by a single ``$``. +For example, if your LDAP DNS password is ``$xkj432``, specify it, as follows: + +.. code-block:: ini + + ldap_dns_password = $$xkj432 + +The code uses the Python ``string.Template.safe_substitute()`` +method to implement variable substitution. +For more details on how variable substitution is resolved, see +http://docs.python.org/2/library/string.html#template-strings +and `PEP 292 `_. + +Whitespace +~~~~~~~~~~ + +To include whitespace in a configuration value, use a quoted string. +For example: + +.. code-block:: ini + + ldap_dns_passsword='a password with spaces' + +Define an alternate location for a config file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most services and the ``*-manage`` command-line clients load +the configuration file. +To define an alternate location for the configuration file, +pass the ``--config-file CONFIG_FILE`` parameter +when you start a service or call a ``*-manage`` command. diff --git a/doc/config-ref-rst/source/config-overview.rst b/doc/config-ref-rst/source/config-overview.rst new file mode 100644 index 0000000000..6ab535b24b --- /dev/null +++ b/doc/config-ref-rst/source/config-overview.rst @@ -0,0 +1,29 @@ +================================ +OpenStack configuration overview +================================ + +.. toctree:: + :maxdepth: 1 + + common/conventions.rst + config-format.rst + +OpenStack is a collection of open source project components +that enable setting up cloud services. Each component uses similar +configuration techniques and a common framework for INI file options. + +This guide pulls together multiple references and configuration +options for the following OpenStack components: + +* Bare metal service +* OpenStack Block Storage +* OpenStack Compute +* OpenStack dashboard +* Database service for OpenStack +* Data processing service +* OpenStack Identity +* OpenStack Image service +* OpenStack Networking +* OpenStack Object Storage +* Orchestration +* Telemetry diff --git a/doc/config-ref-rst/source/dashboard.rst b/doc/config-ref-rst/source/dashboard.rst new file mode 100644 index 0000000000..331e2b8d6a --- /dev/null +++ b/doc/config-ref-rst/source/dashboard.rst @@ -0,0 +1,3 @@ +========= +Dashboard +========= diff --git a/doc/config-ref-rst/source/data-processing-service.rst b/doc/config-ref-rst/source/data-processing-service.rst new file mode 100644 index 0000000000..3030558d07 --- /dev/null +++ b/doc/config-ref-rst/source/data-processing-service.rst @@ -0,0 +1,3 @@ +======================= +Data processing service +======================= diff --git a/doc/config-ref-rst/source/database-service.rst b/doc/config-ref-rst/source/database-service.rst new file mode 100644 index 0000000000..0319a876d2 --- /dev/null +++ b/doc/config-ref-rst/source/database-service.rst @@ -0,0 +1,3 @@ +================ +Database service +================ diff --git a/doc/config-ref-rst/source/firewalls-default-ports.rst b/doc/config-ref-rst/source/firewalls-default-ports.rst new file mode 100644 index 0000000000..69589515c6 --- /dev/null +++ b/doc/config-ref-rst/source/firewalls-default-ports.rst @@ -0,0 +1,3 @@ +=========================== +Firewalls and default ports +=========================== diff --git a/doc/config-ref-rst/source/identity.rst b/doc/config-ref-rst/source/identity.rst new file mode 100644 index 0000000000..da04177add --- /dev/null +++ b/doc/config-ref-rst/source/identity.rst @@ -0,0 +1,3 @@ +======== +Identity +======== diff --git a/doc/config-ref-rst/source/image-service.rst b/doc/config-ref-rst/source/image-service.rst new file mode 100644 index 0000000000..3a6e20a374 --- /dev/null +++ b/doc/config-ref-rst/source/image-service.rst @@ -0,0 +1,3 @@ +============= +Image service +============= diff --git a/doc/config-ref-rst/source/index.rst b/doc/config-ref-rst/source/index.rst index f79e8a0f3c..f456290ebb 100644 --- a/doc/config-ref-rst/source/index.rst +++ b/doc/config-ref-rst/source/index.rst @@ -1,8 +1,3 @@ -.. meta:: - :description: This guide targets OpenStack Architects - for architectural design - :keywords: Architecture, OpenStack - ================================= OpenStack Configuration Reference ================================= @@ -12,7 +7,7 @@ Abstract This document is for system administrators who want to look up configuration options. It contains lists of configuration options available with OpenStack -and uses auto-generation to generate options and the d escriptions from the +and uses auto-generation to generate options and the descriptions from the code for each project. It includes sample configuration files. .. warning:: This guide is a work-in-progress. @@ -23,8 +18,24 @@ Contents .. toctree:: :maxdepth: 2 - common/conventions.rst + config-overview.rst + bare-metal.rst + block-storage.rst + compute.rst + dashboard.rst + database-service.rst + data-processing-service.rst + identity.rst + image-service.rst + networking.rst + object-storage.rst + orchestration.rst + telemetry.rst + shared-file-systems.rst + + policy-json-file.rst + firewalls-default-ports.rst common/app_support.rst common/glossary.rst diff --git a/doc/config-ref-rst/source/networking.rst b/doc/config-ref-rst/source/networking.rst new file mode 100644 index 0000000000..e40965eb99 --- /dev/null +++ b/doc/config-ref-rst/source/networking.rst @@ -0,0 +1,3 @@ +========== +Networking +========== diff --git a/doc/config-ref-rst/source/object-storage.rst b/doc/config-ref-rst/source/object-storage.rst new file mode 100644 index 0000000000..ea202b689c --- /dev/null +++ b/doc/config-ref-rst/source/object-storage.rst @@ -0,0 +1,3 @@ +============== +Object Storage +============== diff --git a/doc/config-ref-rst/source/orchestration.rst b/doc/config-ref-rst/source/orchestration.rst new file mode 100644 index 0000000000..36d45058b8 --- /dev/null +++ b/doc/config-ref-rst/source/orchestration.rst @@ -0,0 +1,3 @@ +============= +Orchestration +============= diff --git a/doc/config-ref-rst/source/policy-json-file.rst b/doc/config-ref-rst/source/policy-json-file.rst new file mode 100644 index 0000000000..3471f7df62 --- /dev/null +++ b/doc/config-ref-rst/source/policy-json-file.rst @@ -0,0 +1,3 @@ +==================== +The policy.json file +==================== diff --git a/doc/config-ref-rst/source/shared-file-systems.rst b/doc/config-ref-rst/source/shared-file-systems.rst new file mode 100644 index 0000000000..4d6d14aa2c --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems.rst @@ -0,0 +1,3 @@ +=================== +Shared File Systems +=================== diff --git a/doc/config-ref-rst/source/telemetry.rst b/doc/config-ref-rst/source/telemetry.rst new file mode 100644 index 0000000000..01eabec66c --- /dev/null +++ b/doc/config-ref-rst/source/telemetry.rst @@ -0,0 +1,3 @@ +========= +Telemetry +=========