Merge "import admin guide content from openstack-manuals"

4 files changed, 229 insertions, 0 deletions

diff --git a/doc/source/admin/cross-project-cors.rst b/doc/source/admin/cross-project-cors.rst
new file mode 100644
index 0000000..26a8c55
--- /dev/null
+++ b/doc/source/admin/cross-project-cors.rst
@@ -0,0 +1,195 @@
+.. _cross-project:
+
+=============================
+Cross-origin resource sharing
+=============================
+
+.. note::
+
+   This is a new feature in OpenStack Liberty.
+
+OpenStack supports :term:`Cross-Origin Resource Sharing (CORS)`, a W3C
+specification defining a contract by which the single-origin policy of a user
+agent (usually a browser) may be relaxed. It permits the javascript engine
+to access an API that does not reside on the same domain, protocol, or port.
+
+This feature is most useful to organizations which maintain one or more
+custom user interfaces for OpenStack, as it permits those interfaces to access
+the services directly, rather than requiring an intermediate proxy server. It
+can, however, also be misused by malicious actors; please review the
+security advisory below for more information.
+
+Enabling CORS with configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In most cases, CORS support is built directly into the service itself. To
+enable it, simply follow the configuration options exposed in the default
+configuration file, or add it yourself according to the pattern below.
+
+.. code-block:: ini
+
+   [cors]
+   allowed_origin = https://first_ui.example.com
+   max_age = 3600
+   allow_methods = GET,POST,PUT,DELETE
+   allow_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header
+   expose_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header
+
+Additional origins can be explicitly added. To express this in
+your configuration file, first begin with a ``[cors]`` group as above,
+into which you place your default configuration values. Then, add as many
+additional configuration groups as necessary, naming them
+``[cors.{something}]`` (each name must be unique). The purpose of the
+suffix to ``cors.`` is legibility, we recommend using a reasonable
+human-readable string:
+
+.. code-block:: ini
+
+   [cors.ironic_webclient]
+   # CORS Configuration for a hypothetical ironic webclient, which overrides
+   # authentication
+   allowed_origin = https://ironic.example.com:443
+   allow_credentials = True
+
+   [cors.horizon]
+   # CORS Configuration for horizon, which uses global options.
+   allowed_origin = https://horizon.example.com:443
+
+   [cors.wildcard]
+   # CORS Configuration for the CORS specified domain wildcard, which only
+   # permits HTTP GET requests.
+   allowed_origin = *
+   allow_methods = GET
+
+For more information about CORS configuration,
+see `cross-origin resource sharing
+<https://docs.openstack.org/ocata/config-reference/common-configurations/cors.html>`_
+in OpenStack Configuration Reference.
+
+Enabling CORS with PasteDeploy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CORS can also be configured using PasteDeploy. First of all, ensure that
+OpenStack's ``oslo_middleware`` package (version 2.4.0 or later) is
+available in the Python environment that is running the service. Then,
+add the following configuration block to your ``paste.ini`` file.
+
+.. code-block:: ini
+
+   [filter:cors]
+   paste.filter_factory = oslo_middleware.cors:filter_factory
+   allowed_origin = https://website.example.com:443
+   max_age = 3600
+   allow_methods = GET,POST,PUT,DELETE
+   allow_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header
+   expose_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header
+
+.. note::
+   To add an additional domain in oslo_middleware v2.4.0, add
+   another filter. In v3.0.0 and after, you may add multiple domains
+   in the above ``allowed_origin`` field, separated by commas.
+
+Security concerns
+~~~~~~~~~~~~~~~~~
+
+CORS specifies a wildcard character ``*``, which permits access to all user
+agents, regardless of domain, protocol, or host. While there are valid use
+cases for this approach, it also permits a malicious actor to create a
+convincing facsimile of a user interface, and trick users into revealing
+authentication credentials. Please carefully evaluate your use case and the
+relevant documentation for any risk to your organization.
+
+.. note::
+
+   The CORS specification does not support using this wildcard as
+   a part of a URI. Setting ``allowed_origin`` to ``*`` would work, while
+   ``*.openstack.org`` would not.
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+CORS is very easy to get wrong, as even one incorrect property will violate
+the prescribed contract. Here are some steps you can take to troubleshoot
+your configuration.
+
+Check the service log
+---------------------
+
+The CORS middleware used by OpenStack provides verbose debug logging that
+should reveal most configuration problems. Here are some example log
+messages, and how to resolve them.
+
+Problem
+-------
+
+``CORS request from origin 'http://example.com' not permitted.``
+
+Solution
+--------
+
+A request was received from the origin ``http://example.com``, however this
+origin was not found in the permitted list. The cause may be a superfluous
+port notation (ports 80 and 443 do not need to be specified). To correct,
+ensure that the configuration property for this host is identical to the
+host indicated in the log message.
+
+Problem
+-------
+
+``Request method 'DELETE' not in permitted list: GET,PUT,POST``
+
+Solution
+--------
+
+A user agent has requested permission to perform a DELETE request, however
+the CORS configuration for the domain does not permit this. To correct, add
+this method to the ``allow_methods`` configuration property.
+
+Problem
+-------
+
+``Request header 'X-Custom-Header' not in permitted list: X-Other-Header``
+
+Solution
+--------
+
+A request was received with the header ``X-Custom-Header``, which is not
+permitted. Add this header to the ``allow_headers`` configuration
+property.
+
+Open your browser's console log
+-------------------------------
+
+Most browsers provide helpful debug output when a CORS request is rejected.
+Usually this happens when a request was successful, but the return headers on
+the response do not permit access to a property which the browser is trying
+to access.
+
+Manually construct a CORS request
+---------------------------------
+
+By using ``curl`` or a similar tool, you can trigger a CORS response with a
+properly constructed HTTP request. An example request and response might look
+like this.
+
+Request example:
+
+.. code-block:: console
+
+   $ curl -I -X OPTIONS https://api.example.com/api -H "Origin: https://ui.example.com"
+
+Response example:
+
+.. code-block:: console
+
+   HTTP/1.1 204 No Content
+   Content-Length: 0
+   Access-Control-Allow-Origin: https://ui.example.com
+   Access-Control-Allow-Methods: GET,POST,PUT,DELETE
+   Access-Control-Expose-Headers: origin,authorization,accept,x-total,x-limit,x-marker,x-client,content-type
+   Access-Control-Allow-Headers: origin,authorization,accept,x-total,x-limit,x-marker,x-client,content-type
+   Access-Control-Max-Age: 3600
+
+If the service does not return any access control headers, check the service
+log, such as ``/var/log/upstart/ironic-api.log`` for an indication on what
+went wrong.
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
new file mode 100644
index 0000000..c90230c
--- /dev/null
+++ b/doc/source/admin/index.rst
@@ -0,0 +1,13 @@
+======================
+Cross-project features
+======================
+
+Many features are common to all the OpenStack services and are consistent in
+their configuration and deployment patterns. Unless explicitly noted, you can
+safely assume that the features in this chapter are supported and configured
+in a consistent manner.
+
+.. toctree::
+   :maxdepth: 2
+
+   cross-project-cors.rst
diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst
new file mode 100644
index 0000000..72e1759
--- /dev/null
+++ b/doc/source/glossary.rst
@@ -0,0 +1,19 @@
+========
+Glossary
+========
+
+This glossary offers a list of terms and definitions to define a
+vocabulary for OpenStack-related concepts.
+
+C
+~
+
+.. glossary::
+
+   Cross-Origin Resource Sharing (CORS)
+
+      A mechanism that allows many resources (for example,
+      fonts, JavaScript) on a web page to be requested from
+      another domain outside the domain from which the resource
+      originated. In particular, JavaScript's AJAX calls can use
+      the XMLHttpRequest mechanism.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4929168..5bf8ff0 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -9,7 +9,9 @@ Contents
    install/index
    contributor/index
    configuration/index
+   admin/index
    reference/index
+   glossary
 
 Release Notes
 =============