You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/06/14 10:25:00 UTC
[03/32] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 11fd32a
Split configuring.rst into the set of articles.
Key idea is to provides complete description of all available CouchDB
configuration options grouped by their ini sections and the single place to
keep other related configuring stuff.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fba2826e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fba2826e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fba2826e
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: fba2826ee390d755df17d582b3da1baa98b7a45d
Parents: 04dfe67
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Jun 10 16:04:36 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Tue Jun 11 18:54:06 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 33 +-
share/doc/src/config/admins.rst | 92 ++++
share/doc/src/config/cors.rst | 163 ++++++
share/doc/src/config/httpd.rst | 211 ++++++++
share/doc/src/config/index.rst | 59 +++
share/doc/src/config/os-daemons.rst | 54 ++
share/doc/src/config/proxying.rst | 98 ++++
share/doc/src/config/ssl.rst | 181 +++++++
share/doc/src/config/update-notification.rst | 64 +++
share/doc/src/config/vhosts.rst | 56 ++
share/doc/src/config_reference.rst | 319 -----------
share/doc/src/configuring.rst | 619 ----------------------
share/doc/src/index.rst | 3 +-
share/doc/src/intro.rst | 2 +-
14 files changed, 1007 insertions(+), 947 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 97fef79..632f6ac 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -53,11 +53,18 @@ html_files = \
html/_sources/api/local.txt \
html/_sources/api/misc.txt \
html/_sources/api/reference.txt \
+ html/_sources/config/admins.txt \
+ html/_sources/config/cors.txt \
+ html/_sources/config/httpd.txt \
+ html/_sources/config/index.txt \
+ html/_sources/config/os-daemons.txt \
+ html/_sources/config/ssl.txt \
+ html/_sources/config/update-notification.txt \
+ html/_sources/config/vhosts.txt \
+ html/_sources/config/proxying.txt \
html/_sources/api-basics.txt \
html/_sources/changelog.txt \
html/_sources/changes.txt \
- html/_sources/config_reference.txt \
- html/_sources/configuring.txt \
html/_sources/contributing.txt \
html/_sources/ddocs.txt \
html/_sources/index.txt \
@@ -97,11 +104,18 @@ html_files = \
html/api/local.html \
html/api/misc.html \
html/api/reference.html \
+ html/config/admins.html \
+ html/config/cors.html \
+ html/config/httpd.html \
+ html/config/index.html \
+ html/config/os-daemons.html \
+ html/config/ssl.html \
+ html/config/update-notification.html \
+ html/config/vhosts.html \
+ html/config/proxying.html \
html/api-basics.html \
html/changelog.html \
html/changes.html \
- html/config_reference.html \
- html/configuring.html \
html/ddocs.html \
html/index.html \
html/intro.html \
@@ -139,11 +153,18 @@ src_files = \
../src/api/local.rst \
../src/api/misc.rst \
../src/api/reference.rst \
+ ../src/config/admins.rst \
+ ../src/config/cors.rst \
+ ../src/config/httpd.rst \
+ ../src/config/index.rst \
+ ../src/config/os-daemons.rst \
+ ../src/config/ssl.rst \
+ ../src/config/update-notification.rst \
+ ../src/config/vhosts.rst \
+ ../src/config/proxying.rst \
../src/api-basics.rst \
../src/changelog.rst \
../src/changes.rst \
- ../src/config_reference.rst \
- ../src/configuring.rst \
../src/contributing.rst \
../src/ddocs.rst \
../src/index.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/admins.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/admins.rst b/share/doc/src/config/admins.rst
new file mode 100644
index 0000000..f7880bc
--- /dev/null
+++ b/share/doc/src/config/admins.rst
@@ -0,0 +1,92 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _config/admins:
+
+``[admins]`` :: Configuring Server Administrators
+=================================================
+
+A default CouchDB install provides admin-level access to all connecting users.
+This configuration is known as `Admin Party`, and is not recommended for
+in-production usage. You can crash the party simply by creating the first
+admin account. CouchDB server administrators and passwords are not stored
+in the ``_users`` database, but in the ``local.ini`` file, which should be
+appropriately secured and readable only by system administrators::
+
+ [admins]
+ ;admin = mysecretpassword
+ admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
+ architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
+
+Administrators can be added directly to the ``[admins]`` section, and when
+CouchDB is restarted, the passwords will be salted and encrypted. You may
+also use the HTTP interface to create administrator accounts; this way,
+you don't need to restart CouchDB, and there's no need to temporarily store
+or transmit passwords in plaintext. The HTTP ``_config/admins`` endpoint
+supports querying, deleting or creating new admin accounts:
+
+.. code-block:: http
+
+ GET /_config/admins HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 196
+ Content-Type: application/json
+ Date: Fri, 30 Nov 2012 11:37:18 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+.. code-block:: json
+
+ {
+ "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
+ "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ }
+
+If you already have a salted, encrypted password string (for example,
+from an old ``local.ini`` file, or from a different CouchDB server), then
+you can store the "raw" encrypted string, without having CouchDB doubly
+encrypt it.
+
+.. code-block:: http
+
+ PUT /_config/admins/architect?raw=true HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Content-Length: 89
+ Host: localhost:5984
+
+ "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 89
+ Content-Type: application/json
+ Date: Fri, 30 Nov 2012 11:39:18 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+
+ "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+
+Further details are available in `security`, including configuring the
+work factor for ``PBKDF2``, and the algorithm itself at
+`PBKDF2 (RFC-2898) <http://tools.ietf.org/html/rfc2898>`_.
+
+.. versionchanged:: 1.3 `PBKDF2` server-side hashed salted password support
+ added, now as a synchronous call for the ``_config/admins`` API.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/cors.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/cors.rst b/share/doc/src/config/cors.rst
new file mode 100644
index 0000000..15559e8
--- /dev/null
+++ b/share/doc/src/config/cors.rst
@@ -0,0 +1,163 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _cors:
+.. _config/cors:
+
+``[cors]`` :: CORS
+==================
+
+.. versionadded:: 1.3 added CORS support, see JIRA :issue:`431`
+
+`CORS`, or "Cross-Origin Resource Sharing", allows a resource such as a web
+page running JavaScript inside a browser, to make AJAX requests
+(XMLHttpRequests) to a different domain, without compromising the security
+of either party.
+
+A typical use case is to have a static website hosted on a CDN make
+requests to another resource, such as a hosted CouchDB instance. This
+avoids needing an intermediary proxy, using `JSONP` or similar workarounds
+to retrieve and host content.
+
+While CouchDB's integrated HTTP server has support for document attachments
+makes this less of a constraint for pure CouchDB projects, there are many
+cases where separating the static content from the database access is
+desirable, and CORS makes this very straightforward.
+
+By supporting CORS functionality, a CouchDB instance can accept direct
+connections to protected databases and instances, without the browser
+functionality being blocked due to same-origin constraints. CORS is
+supported today on over 90% of recent browsers.
+
+CORS support is provided as experimental functionality in 1.3, and as such
+will need to be enabled specifically in CouchDB's configuration. While all
+origins are forbidden from making requests by default, support is available
+for simple requests, preflight requests and per-vhost configuration.
+
+This section requires :ref:`enable_cors <config/httpd/enable_cors>` option have
+``true`` value::
+
+ [httpd]
+ enable_cors = true
+
+
+Global Setup
+------------
+
+These options are under ``[cors]`` section. They are have global affect for
+all CORS-enabled instances.
+
+
+.. _config/cors/credentials:
+
+``credentials``
+^^^^^^^^^^^^^^^
+
+By default, neither authentication headers nor cookies are included in
+requests and responses. To do so requires both setting
+``XmlHttpRequest.withCredentials = true`` on the request object in the
+browser and enabling credentials support in CouchDB.
+
+::
+
+ [cors]
+ credentials = true
+
+CouchDB will respond to a credentials-enabled CORS request with an additional
+header, ``Access-Control-Allow-Credentials=true``.
+
+
+.. _config/cors/origins:
+
+``origins``
+^^^^^^^^^^^
+
+List of origins separated by a comma, ``*`` means accept all.
+You can’t set ``origins = *`` and ``credentials = true`` option at the same
+time::
+
+ [cors]
+ origins = *
+
+Access can be restricted by protocol, host and optionally by port. Origins must
+follow the scheme: http://example.com:80::
+
+ [cors]
+ origins = http://localhost, https://localhost, http://couch.mydev.name:8080
+
+Note that by default, no origins are accepted. You must define them explicitly.
+
+
+.. _config/cors/headers:
+
+``headers``
+^^^^^^^^^^^
+
+List of accepted headers separated by a comma::
+
+ [cors]
+ headers = X-Couch-Id, X-Couch-Rev
+
+
+.. _config/cors/methods:
+
+``methods``
+^^^^^^^^^^^
+
+List of accepted methods::
+
+ [cors]
+ methods = GET,POST
+
+
+.. _config/cors/vhost:
+
+Per Virtual Host Configuration
+------------------------------
+
+To set the options for a :ref:`config/vhosts`, you will need to create a section
+with the vhost name prefixed by ``cors:`` .
+Example case for the vhost `example.com`::
+
+ [cors:example.com]
+ credentials = false
+ ; List of origins separated by a comma
+ origins = *
+ ; List of accepted headers separated by a comma
+ headers = X-CouchDB-Header
+ ; List of accepted methods
+ methods = HEAD, GET
+
+.. seealso::
+
+ Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
+
+ Standards and References:
+
+ - IETF RFCs relating to methods: :rfc:`2618`, :rfc:`2817`, :rfc:`5789`
+ - IETF RFC for Web Origins: :rfc:`6454`
+ - W3C `CORS standard <http://www.w3.org/TR/cors>`_
+
+ Mozilla Developer Network Resources:
+
+ - `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_
+ - `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_
+ - `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_
+ - `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
+
+ Client-side CORS support and usage:
+
+ - `CORS browser support matrix <http://caniuse.com/cors>`_
+ - `COS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_
+ - `XHR with CORS <http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/>`_
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/httpd.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/httpd.rst b/share/doc/src/config/httpd.rst
new file mode 100644
index 0000000..2996add
--- /dev/null
+++ b/share/doc/src/config/httpd.rst
@@ -0,0 +1,211 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _config/httpd:
+
+``[httpd]`` :: HTTP Server Options
+==================================
+
+These options are under ``[httpd]`` section.
+
+
+.. _config/httpd/bind_address:
+
+``bind_address`` :: Listen IP address
+-------------------------------------
+
+Defines the IP address by which CouchDB will be accessible::
+
+ [httpd]
+ bind_address = 127.0.0.1
+
+To let CouchDB listen any available IP address, just setup ``0.0.0.0`` value::
+
+ [httpd]
+ bind_address = 0.0.0.0
+
+For IPv6 support you need to set ``::1`` if you want to let CouchDB listen local
+address::
+
+ [httpd]
+ bind_address = ::1
+
+or ``::`` for any available::
+
+ [httpd]
+ bind_address = ::
+
+
+.. _config/httpd/port:
+
+``port`` :: Listen port
+-----------------------
+
+Defined the port number to listen::
+
+ [httpd]
+ port = 5984
+
+To let CouchDB handle any free port, set this option to ``0``::
+
+ [httpd]
+ port = 0
+
+After that, CouchDB URI could be located within the URI file.
+
+
+.. _config/httpd/authentication_handlers:
+
+``authentication_handlers`` :: Authentication handlers
+------------------------------------------------------
+
+List of used authentication handlers that used by CouchDB. You may extend them
+via third-party plugins or remove some of them if you won't let users to use one
+of provided methods::
+
+ [httpd]
+ authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}
+
+* ``{couch_httpd_oauth, oauth_authentication_handler}`` - handles OAuth;
+* ``{couch_httpd_auth, cookie_authentication_handler}`` - used for Cookie auth;
+* ``{couch_httpd_auth, default_authentication_handler}`` - used for Basic auth;
+
+
+.. _config/httpd/default_handler:
+
+``default_handler`` :: Default request handler
+----------------------------------------------
+
+Specifies default HTTP requests handler::
+
+ [httpd]
+ default_handler = {couch_httpd_db, handle_request}
+
+
+.. _config/httpd/secure_rewrites:
+
+``secure_rewrites`` :: Default request handler
+----------------------------------------------
+
+This option allow to isolate databases via subdomains::
+
+ [httpd]
+ secure_rewrites = true
+
+
+.. _config/httpd/vhost_global_handlers:
+
+``vhost_global_handlers`` :: Virtual hosts global handlers
+----------------------------------------------------------
+
+List of global handlers that are available for
+:ref:`virtual hosts <config/vhosts>`::
+
+ [httpd]
+ vhost_global_handlers = _utils, _uuids, _session, _oauth, _users
+
+
+.. _config/httpd/allow_jsonp:
+
+``allow_jsonp`` :: Enables JSONP support
+----------------------------------------
+
+::
+
+ [httpd]
+ allow_jsonp = false
+
+
+.. _config/httpd/server_options:
+
+``server_options`` :: MochiWeb Server Options
+---------------------------------------------
+
+Server options for the `MochiWeb`_ component of CouchDB can be added to the
+configuration files::
+
+ [httpd]
+ server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
+
+
+.. _MochiWeb: https://github.com/mochi/mochiweb
+
+
+.. _config/httpd/socket_options:
+
+``socket_options`` :: Socket Options
+------------------------------------
+
+The socket options for the listening socket in CouchDB can be specified as a
+list of tuples. For example::
+
+ [httpd]
+ socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
+
+The options supported are a subset of full options supported by the
+TCP/IP stack. A list of the supported options are provided in the
+`Erlang inet`_ documentation.
+
+.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
+
+
+.. _config/httpd/log_max_chunk_size:
+
+``log_max_chunk_size`` :: Logs chunk size
+-----------------------------------------
+
+Defines maximum chunk size in bytes for :ref:`_log <api/misc/log>` resource::
+
+ [httpd]
+ log_max_chunk_size = 1000000
+
+
+.. _config/httpd/enable_cors:
+
+``enable_cors`` :: Activates CORS
+---------------------------------
+
+.. versionadded:: 1.3
+
+Controls :ref:`CORS <config/cors>` feature::
+
+ [httpd]
+ enable_cors = false
+
+
+.. _config/httpd/WWW-Authenticate:
+
+``WWW-Authenticate`` :: Force basic auth
+----------------------------------------
+
+Set this option to trigger basic-auth popup on unauthorized requests::
+
+ [httpd]
+ WWW-Authenticate = Basic realm="Welcome to the Couch!"
+
+
+.. _config/httpd/config_whitelist:
+
+``config_whitelist`` :: Config options while list
+-------------------------------------------------
+
+Sets the configuration modification whitelist. Only whitelisted values may be
+changed via the :ref:`config API <api/config>`. To allow the admin to change
+this value over HTTP, remember to include ``{httpd,config_whitelist}`` itself.
+Excluding it from the list would require editing this file to update the
+whitelist::
+
+ [httpd]
+ config_whitelist = [{httpd,config_whitelist}, {log,level}, {etc,etc}]
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/index.rst b/share/doc/src/config/index.rst
new file mode 100644
index 0000000..a89979a
--- /dev/null
+++ b/share/doc/src/config/index.rst
@@ -0,0 +1,59 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _config:
+
+===================
+Configuring CouchDB
+===================
+
+CouchDB reads files from the following locations, in the following
+order.
+
+1. ``PREFIX/default.ini``
+
+2. ``PREFIX/default.d/*``
+
+3. ``PREFIX/local.ini``
+
+4. ``PREFIX/local.d/*``
+
+Settings in successive documents override the settings in earlier
+entries. For example, setting the
+:ref:`bind_address <config/httpd/bind_address>` parameter in ``local.ini``
+would override any setting in ``default.ini``.
+
+.. warning::
+ The ``default.ini`` file may be overwritten during an upgrade or
+ re-installation, so localised changes should be made to the
+ ``local.ini`` file or files within the ``local.d`` directory.
+
+Content:
+
+.. CouchDB configuration sections goes first.
+ Please keep them sorted to simplify eye searching.
+ After them - custom configuration tips and tricks.
+
+.. toctree::
+ :maxdepth: 2
+ :glob:
+
+ admins
+ cors
+ httpd
+ os-daemons
+ ssl
+ update-notification
+ vhosts
+
+ proxying
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/os-daemons.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/os-daemons.rst b/share/doc/src/config/os-daemons.rst
new file mode 100644
index 0000000..ae0d500
--- /dev/null
+++ b/share/doc/src/config/os-daemons.rst
@@ -0,0 +1,54 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _config/os_daemons:
+
+``[os_daemons]`` :: OS Daemons
+==============================
+
+CouchDB now supports starting external processes. The support is simple
+and enables CouchDB to start each configured OS daemon. If the daemon
+stops at any point, CouchDB will restart it (with protection to ensure
+regularly failing daemons are not repeatedly restarted).
+
+The daemon starting process is one-to-one; for each each configured
+daemon in the configuration file, CouchDB will start exactly one
+instance. If you need to run multiple instances, then you must create
+separate individual configurations. Daemons are configured within the
+``[os_daemons]`` section of your configuration file (``local.ini``). The
+format of each configured daemon is:
+
+.. code-block:: ini
+
+ NAME = PATH ARGS
+
+Where ``NAME`` is an arbitrary (and unique) name to identify the daemon;
+``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any
+required arguments to the daemon.
+
+For example:
+
+.. code-block:: ini
+
+ [os_daemons]
+ basic_responder = /usr/local/bin/responder.js
+
+There is no interactivity between CouchDB and the running process, but
+you can use the OS Daemons service to create new HTTP servers and
+responders and then use the new proxy service to redirect requests and
+output to the CouchDB managed service. For more information on proxying,
+see :ref:`http-proxying`. For further background on the OS Daemon service, see
+`CouchDB Externals API`_.
+
+.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/proxying.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/proxying.rst b/share/doc/src/config/proxying.rst
new file mode 100644
index 0000000..863311e
--- /dev/null
+++ b/share/doc/src/config/proxying.rst
@@ -0,0 +1,98 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _config/proxy:
+
+======================
+Proxying Configuration
+======================
+
+.. _http-proxying:
+.. _config/proxy/couchdb:
+
+CouchDB As Proxy
+================
+
+The HTTP proxy feature makes it easy to map and redirect different
+content through your CouchDB URL. The proxy works by mapping a pathname
+and passing all content after that prefix through to the configured
+proxy address.
+
+Configuration of the proxy redirect is handled through the
+``[httpd_global_handlers]`` section of the CouchDB configuration file
+(typically ``local.ini``). The format is::
+
+ [httpd_global_handlers]
+ PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}
+
+
+Where:
+
+- ``PREFIX``
+
+ Is the string that will be matched. The string can be any valid
+ qualifier, although to ensure that existing database names are not
+ overridden by a proxy configuration, you can use an underscore
+ prefix.
+
+- ``DESTINATION``
+
+ The fully-qualified URL to which the request should be sent. The
+ destination must include the ``http`` prefix. The content is used
+ verbatim in the original request, so you can also forward to servers
+ on different ports and to specific paths on the target host.
+
+The proxy process then translates requests of the form:
+
+.. code-block:: text
+
+ http://couchdb:5984/PREFIX/path
+
+To:
+
+.. code-block:: text
+
+ DESTINATION/path
+
+.. note::
+ Everything after ``PREFIX`` including the required forward slash
+ will be appended to the ``DESTINATION``.
+
+The response is then communicated back to the original client.
+
+For example, the following configuration::
+
+ [httpd_global_handlers]
+ _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}
+
+Would forward all requests for ``http://couchdb:5984/_google`` to the
+Google website.
+
+The service can also be used to forward to related CouchDB services,
+such as `Lucene`::
+
+ [httpd_global_handlers]
+ _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
+
+.. note::
+ The proxy service is basic. If the request is not identified by the
+ ``DESTINATION``, or the remainder of the ``PATH`` specification is
+ incomplete, the original request URL is interpreted as if the
+ ``PREFIX`` component of that URL does not exist.
+
+ For example, requesting ``http://couchdb:5984/_intranet/media`` when
+ ``/media`` on the proxy destination does not exist, will cause the
+ request URL to be interpreted as ``http://couchdb:5984/media``. Care
+ should be taken to ensure that both requested URLs and destination
+ URLs are able to cope.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/ssl.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/ssl.rst b/share/doc/src/config/ssl.rst
new file mode 100644
index 0000000..a31f7f7
--- /dev/null
+++ b/share/doc/src/config/ssl.rst
@@ -0,0 +1,181 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _config/ssl:
+
+``[ssl]`` :: Secure Socket Level Options
+========================================
+
+CouchDB supports SSL natively. All your secure connection needs can
+now be served without needing to setup and maintain a separate proxy server
+that handles SSL.
+
+SSL setup can be tricky, but the configuration in CouchDB was designed
+to be as easy as possible. All you need is two files; a certificate and
+a private key. If you bought an official SSL certificate from a
+certificate authority, both should be in your possession already.
+
+If you just want to try this out and don't want to pay anything upfront,
+you can create a self-signed certificate. Everything will work the same,
+but clients will get a warning about an insecure certificate.
+
+You will need the `OpenSSL`_ command line tool installed. It probably
+already is.
+
+.. code-block:: bash
+
+ shell> mkdir /etc/couchdb/cert
+ shell> cd /etc/couchdb/cert
+ shell> openssl genrsa > privkey.pem
+ shell> openssl req -new -x509 -key privkey.pem -out couchdb.pem -days 1095
+ shell> chmod 600 privkey.pem couchdb.pem
+ shell> chown couchdb privkey.pem couchdb.pem
+
+Now, you need to edit CouchDB's configuration, either by editing your
+``local.ini`` file or using the ``/_config`` API calls or the
+configuration screen in Futon. Here is what you need to do in
+``local.ini``, you can infer what needs doing in the other places.
+
+At first, enable HTTPS daemon::
+
+ [daemons]
+ httpsd = {couch_httpd, start_link, [https]}
+
+Next, under ``[ssl]`` section setup newly generated certificates::
+
+ [ssl]
+ cert_file = /etc/couchdb/cert/couchdb.pem
+ key_file = /etc/couchdb/cert/privkey.pem
+
+For more information please read `certificates HOWTO`_.
+
+Now start (or restart) CouchDB. You should be able to connect to it
+using HTTPS on port 6984:
+
+.. code-block:: bash
+
+ shell> curl https://127.0.0.1:6984/
+ curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
+ error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
+ More details here: http://curl.haxx.se/docs/sslcerts.html
+
+ curl performs SSL certificate verification by default, using a "bundle"
+ of Certificate Authority (CA) public keys (CA certs). If the default
+ bundle file isn't adequate, you can specify an alternate file
+ using the --cacert option.
+ If this HTTPS server uses a certificate signed by a CA represented in
+ the bundle, the certificate verification probably failed due to a
+ problem with the certificate (it might be expired, or the name might
+ not match the domain name in the URL).
+ If you'd like to turn off curl's verification of the certificate, use
+ the -k (or --insecure) option.
+
+Oh no what happened?! — Remember, clients will notify their users that
+your certificate is self signed. ``curl`` is the client in this case and
+it notifies you. Luckily you trust yourself (don't you?) and you can
+specify the ``-k`` option as the message reads:
+
+.. code-block:: bash
+
+ shell> curl -k https://127.0.0.1:6984/
+ {"couchdb":"Welcome","version":"1.3.0"}
+
+All done.
+
+.. _`certificates HOWTO`: http://www.openssl.org/docs/HOWTO/certificates.txt
+.. _OpenSSL: http://www.openssl.org/
+
+There are more options are under ``[ssl]`` section.
+
+.. _config/ssl/cacert_file:
+
+``cacert_file`` :: CA Certificate file
+--------------------------------------
+
+Path to file containing PEM encoded CA certificates (trusted certificates used
+for verifying a peer certificate). May be omitted if you do not want to verify
+the peer::
+
+ [ssl]
+ cacert_file = /etc/ssl/certs/ca-certificates.crt
+
+
+.. _config/ssl/cert_file:
+
+``cert_file`` :: Certificate file
+---------------------------------
+
+Path to a file containing the user's certificate::
+
+ [ssl]
+ cert_file = /etc/couchdb/cert/couchdb.pem
+
+
+.. _config/ssl/key_file:
+
+``key_file`` :: Certificate key file
+------------------------------------
+
+Path to file containing user's private PEM encoded key::
+
+ [ssl]
+ key_file = /etc/couchdb/cert/privkey.pem
+
+
+.. _config/ssl/password:
+
+``password`` :: Certificate key password
+----------------------------------------
+
+String containing the user's password. Only used if the private keyfile is
+password protected::
+
+ [ssl]
+ password = somepassword
+
+
+.. _config/ssl/ssl_certificate_max_depth:
+
+``ssl_certificate_max_depth`` :: Maximum peer certificate depth
+---------------------------------------------------------------
+
+Maximum peer certificate depth (must be set even if certificate validation is
+off)::
+
+ [ssl]
+ ssl_certificate_max_depth = 1
+
+
+.. _config/ssl/verify_fun:
+
+``verify_fun`` :: SSL verification function
+-------------------------------------------
+
+The verification fun (optional) if not specified, the default
+verification fun will be used::
+
+ [ssl]
+ verify_fun = {Module, VerifyFun}
+
+
+.. _config/ssl/verify_ssl_certificates:
+
+``verify_ssl_certificates`` :: Enable certificate verification
+--------------------------------------------------------------
+
+Set to `true` to validate peer certificates::
+
+ [ssl]
+ verify_ssl_certificates = false
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/update-notification.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/update-notification.rst b/share/doc/src/config/update-notification.rst
new file mode 100644
index 0000000..9f4b1ef
--- /dev/null
+++ b/share/doc/src/config/update-notification.rst
@@ -0,0 +1,64 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. TODO: move `update-notification` reference to special article about this
+ feature
+
+.. _update-notifications:
+.. _config/update-notification:
+
+``[update_notification]`` :: Update notifications
+=================================================
+
+CouchDB is able to spawn OS processes to notify them about recent databases
+updates. The notifications are in form of JSON messages sent as a line of text,
+terminated by ``CR`` (``\n``) character, to the OS processes through `stdout`::
+
+ [update_notification]
+ ;unique notifier name=/full/path/to/exe -with "cmd line arg"
+ index_updater = ruby /usr/local/bin/index_updater.rb
+
+
+The update notification messages are depend upon of event type:
+
+- **Database created**:
+
+ .. code-block:: javascript
+
+ {"type":"created","db":"dbname"}
+
+
+- **Database updated**: this event raises when any document gets updated for
+ specified database:
+
+ .. code-block:: javascript
+
+ {"type":"updated","db":"dbname"}
+
+
+- **Design document updated**: for design document updates there is special
+ event raised in additional to regular db update one:
+
+ .. code-block:: javascript
+
+ {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
+
+
+- **Database deleted**:
+
+ .. code-block:: javascript
+
+ {"type":"deleted","db":"dbname"}
+
+.. note:: New line (``\n``) trailing character was removed from examples.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config/vhosts.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/vhosts.rst b/share/doc/src/config/vhosts.rst
new file mode 100644
index 0000000..6140012
--- /dev/null
+++ b/share/doc/src/config/vhosts.rst
@@ -0,0 +1,56 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. highlight:: ini
+
+.. _config/vhosts:
+
+``[vhosts]`` :: Virtual Hosts
+=============================
+
+CouchDB can map requests to different locations based on the ``Host`` header,
+even if they arrive on the some inbound IP address.
+
+This allows different virtual hosts on the same machine to map to different
+databases or design documents, etc. The most common use case is to map a
+virtual host to a Rewrite Handler, to provide full control over the
+application's URIs.
+
+To add a virtual host, add a CNAME pointer to the DNS for your domain
+name. For development and testing, it is sufficient to add an entry in
+the hosts file, typically `/etc/hosts`` on Unix-like operating systems:
+
+.. code-block:: text
+
+ # CouchDB vhost definitions, refer to local.ini for further details
+ 127.0.0.1 sofa.couchdb
+
+Test that this is working:
+
+.. code-block:: bash
+
+ $ ping -n 2 sofa.couchdb
+ PING sofa.couchdb (127.0.0.1) 56(84) bytes of data.
+ 64 bytes from localhost (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
+ 64 bytes from localhost (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms
+
+Finally, add an entry to your :ref:`configuration file <config>` in the
+``[vhosts]`` section::
+
+ [vhosts]
+ sofa.couchdb:5984 = /sofa/_design/sofa/_rewrite
+
+If your CouchDB is listening on the default HTTP port, or is sitting
+behind a proxy, then don't specify a port number in the `vhost` key.
+
+With the above setup, a request to ``http://sofa.couchdb:5984/sweet-o``
+will be mapped to ``http://127.0.0.1:5984/sofa/_design/sofa/_rewrite/sweet-o``
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/config_reference.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config_reference.rst b/share/doc/src/config_reference.rst
deleted file mode 100644
index d3df311..0000000
--- a/share/doc/src/config_reference.rst
+++ /dev/null
@@ -1,319 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-Configuration Reference
-=======================
-
-
-Configuration Groups
---------------------
-
-+----------------------------------+-------------------------------------------+
-| Section | Description |
-+==================================+===========================================+
-| attachments | Attachment options |
-+----------------------------------+-------------------------------------------+
-| couchdb | CouchDB specific options |
-+----------------------------------+-------------------------------------------+
-| couch_httpd_auth | HTTPD Authentication options |
-+----------------------------------+-------------------------------------------+
-| daemons | Daemons and background processes |
-+----------------------------------+-------------------------------------------+
-| httpd | HTTPD Server options |
-+----------------------------------+-------------------------------------------+
-| httpd_db_handlers | Database Operation handlers |
-+----------------------------------+-------------------------------------------+
-| httpd_design_handlers | Handlers for design document operations |
-+----------------------------------+-------------------------------------------+
-| httpd_global_handlers | Handlers for global operations |
-+----------------------------------+-------------------------------------------+
-| log | Logging options |
-+----------------------------------+-------------------------------------------+
-| query_servers | Query Server options |
-+----------------------------------+-------------------------------------------+
-| query_server_config | Query server options |
-+----------------------------------+-------------------------------------------+
-| replicator | Replicator Options |
-+----------------------------------+-------------------------------------------+
-| ssl | SSL (Secure Sockets Layer) Options |
-+----------------------------------+-------------------------------------------+
-| stats | Statistics options |
-+----------------------------------+-------------------------------------------+
-| uuids | UUID generation options |
-+----------------------------------+-------------------------------------------+
-| cors | Cross Origin Resource Sharing settings |
-+----------------------------------+-------------------------------------------+
-
-attachments Configuration Options
----------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| compressible_types | compressible_types |
-+--------------------------------------+---------------------------------------+
-| compression_level | compression_level |
-+--------------------------------------+---------------------------------------+
-
-couchdb Configuration Options
------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| database_dir | database_dir |
-+--------------------------------------+---------------------------------------+
-| delayed_commits | delayed_commits |
-+--------------------------------------+---------------------------------------+
-| max_attachment_chunk_size | max_attachment_chunk_size |
-+--------------------------------------+---------------------------------------+
-| max_dbs_open | max_dbs_open |
-+--------------------------------------+---------------------------------------+
-| max_document_size | max_document_size |
-+--------------------------------------+---------------------------------------+
-| os_process_timeout | os_process_timeout |
-+--------------------------------------+---------------------------------------+
-| uri_file | uri_file |
-+--------------------------------------+---------------------------------------+
-| util_driver_dir | util_driver_dir |
-+--------------------------------------+---------------------------------------+
-| view_index_dir | view_index_dir |
-+--------------------------------------+---------------------------------------+
-
-daemons Configuration Options
------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| auth_cache | auth_cache |
-+--------------------------------------+---------------------------------------+
-| db_update_notifier | db_update_notifier |
-+--------------------------------------+---------------------------------------+
-| external_manager | external_manager |
-+--------------------------------------+---------------------------------------+
-| httpd | httpd |
-+--------------------------------------+---------------------------------------+
-| httpsd | Enabled HTTPS service |
-+--------------------------------------+---------------------------------------+
-| query_servers | query_servers |
-+--------------------------------------+---------------------------------------+
-| stats_aggregator | stats_aggregator |
-+--------------------------------------+---------------------------------------+
-| stats_collector | stats_collector |
-+--------------------------------------+---------------------------------------+
-| uuids | uuids |
-+--------------------------------------+---------------------------------------+
-| view_manager | view_manager |
-+--------------------------------------+---------------------------------------+
-
-httpd_db_handlers Configuration Options
----------------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| _changes | _changes |
-+--------------------------------------+---------------------------------------+
-| _compact | _compact |
-+--------------------------------------+---------------------------------------+
-| _design | _design |
-+--------------------------------------+---------------------------------------+
-| _temp_view | _temp_view |
-+--------------------------------------+---------------------------------------+
-| _view_cleanup | _view_cleanup |
-+--------------------------------------+---------------------------------------+
-
-couch_httpd_auth Configuration Options
---------------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| auth_cache_size | auth_cache_size |
-+--------------------------------------+---------------------------------------+
-| authentication_db | authentication_db |
-+--------------------------------------+---------------------------------------+
-| authentication_redirect | authentication_redirect |
-+--------------------------------------+---------------------------------------+
-| require_valid_user | require_valid_user |
-+--------------------------------------+---------------------------------------+
-| timeout | timeout |
-+--------------------------------------+---------------------------------------+
-| iterations | Password key derivation iterations |
-+--------------------------------------+---------------------------------------+
-
-httpd Configuration Options
----------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| allow_jsonp | allow_jsonp |
-+--------------------------------------+---------------------------------------+
-| authentication_handlers | authentication_handlers |
-+--------------------------------------+---------------------------------------+
-| bind_address | bind_address |
-+--------------------------------------+---------------------------------------+
-| default_handler | default_handler |
-+--------------------------------------+---------------------------------------+
-| max_connections | max_connections |
-+--------------------------------------+---------------------------------------+
-| nodelay | Enable TCP_NODELAY |
-+--------------------------------------+---------------------------------------+
-| port | port |
-+--------------------------------------+---------------------------------------+
-| secure_rewrites | secure_rewrites |
-+--------------------------------------+---------------------------------------+
-| vhost_global_handlers | vhost_global_handlers |
-+--------------------------------------+---------------------------------------+
-| enable_cors | enables CORS functionality when true |
-+--------------------------------------+---------------------------------------+
-
-httpd_design_handlers Configuration Options
--------------------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| _info | _info |
-+--------------------------------------+---------------------------------------+
-| _list | _list |
-+--------------------------------------+---------------------------------------+
-| _rewrite | _rewrite |
-+--------------------------------------+---------------------------------------+
-| _show | _show |
-+--------------------------------------+---------------------------------------+
-| _update | _update |
-+--------------------------------------+---------------------------------------+
-| _view | _view |
-+--------------------------------------+---------------------------------------+
-
-httpd_global_handlers Configuration Options
--------------------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| / | / |
-+--------------------------------------+---------------------------------------+
-| _active_tasks | _active_tasks |
-+--------------------------------------+---------------------------------------+
-| _all_dbs | _all_dbs |
-+--------------------------------------+---------------------------------------+
-| _config | _config |
-+--------------------------------------+---------------------------------------+
-| _log | _log |
-+--------------------------------------+---------------------------------------+
-| _oauth | _oauth |
-+--------------------------------------+---------------------------------------+
-| _replicate | _replicate |
-+--------------------------------------+---------------------------------------+
-| _restart | _restart |
-+--------------------------------------+---------------------------------------+
-| _session | _session |
-+--------------------------------------+---------------------------------------+
-| _stats | _stats |
-+--------------------------------------+---------------------------------------+
-| _utils | _utils |
-+--------------------------------------+---------------------------------------+
-| _uuids | _uuids |
-+--------------------------------------+---------------------------------------+
-| favicon.ico | favicon.ico |
-+--------------------------------------+---------------------------------------+
-
-log Configuration Options
--------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| file | file |
-+--------------------------------------+---------------------------------------+
-| include_sasl | include_sasl |
-+--------------------------------------+---------------------------------------+
-| level | level |
-+--------------------------------------+---------------------------------------+
-
-query_servers Configuration Options
------------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| javascript | javascript |
-+--------------------------------------+---------------------------------------+
-
-query_server_config Configuration Options
------------------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| reduce_limit | reduce_limit |
-+--------------------------------------+---------------------------------------+
-
-replicator Configuration Options
---------------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| max_http_pipeline_size | max_http_pipeline_size |
-+--------------------------------------+---------------------------------------+
-| max_http_sessions | max_http_sessions |
-+--------------------------------------+---------------------------------------+
-
-stats Configuration Options
----------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| rate | rate |
-+--------------------------------------+---------------------------------------+
-| samples | samples |
-+--------------------------------------+---------------------------------------+
-
-uuids Configuration Options
----------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| algorithm | algorithm |
-+--------------------------------------+---------------------------------------+
-
-
-cors Configuration Options
----------------------------
-
-+--------------------------------------+---------------------------------------+
-| Option | Description |
-+======================================+=======================================+
-| origins | List of origins, separated by a comma |
-| | (protocol, host, optional port) |
-+--------------------------------------+---------------------------------------+
-| methods | accepted HTTP methods |
-+--------------------------------------+---------------------------------------+
-| credentials | `true` sends additional header |
-| | Access-Control-Allow-Credentials=true |
-+--------------------------------------+---------------------------------------+
-
-Note that `credentials=true` and `origins=*` are mutually exclusive.
-
-cors vhost Configuration
-------------------------
-
-The same configuration options for `cors` overall may be applied to an
-individual vhost, within a specific section header, for `example.com` the
-appropriate section would be: `[cors:http://example.com]`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/configuring.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/configuring.rst b/share/doc/src/configuring.rst
deleted file mode 100644
index 8d3e704..0000000
--- a/share/doc/src/configuring.rst
+++ /dev/null
@@ -1,619 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _configuring:
-
-=============
-Configuration
-=============
-
-.. todo:: Configuring CouchDB
-
-CouchDB Configuration Files
-===========================
-
-.. todo:: CouchDB Configuration Files
-
-Configuration File Locations
-============================
-
-CouchDB reads files from the following locations, in the following
-order.
-
-1. ``PREFIX/default.ini``
-
-2. ``PREFIX/default.d/*``
-
-3. ``PREFIX/local.ini``
-
-4. ``PREFIX/local.d/*``
-
-Settings in successive documents override the settings in earlier
-entries. For example, setting the ``bind_address`` parameter in
-``local.ini`` would override any setting in ``default.ini``.
-
-.. warning::
- The ``default.ini`` file may be overwritten during an upgrade or
- re-installation, so localised changes should be made to the
- ``local.ini`` file or files within the ``local.d`` directory.
-
-.. _update-notifications:
-
-Update Notifications
-====================
-
-.. todo:: Update Notifications
-
-
-MochiWeb Server Options
-=======================
-
-Server options for the MochiWeb component of CouchDB can be added to the
-configuration files. Settings should be added to the ``server_options``
-option of the ``[httpd]`` section of ``local.ini``. For example:
-
-.. code-block:: ini
-
- [httpd]
- server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
-
-Socket Options Configuration Setting
-====================================
-
-The socket options for the listening socket in CouchDB can now be set
-within the CouchDB configuration file. The setting should be added to
-the ``[httpd]`` section of the file using the option name
-``socket_options``. The specification is as a list of tuples. For
-example:
-
-.. code-block:: ini
-
- [httpd]
- socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
-
-The options supported are a subset of full options supported by the
-TCP/IP stack. A list of the supported options are provided in the
-`Erlang inet`_ documentation.
-
-.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
-
-Virtual Hosts
-=============
-
-CouchDB, since 0.11.0, can map requests to different locations based on
-the ``Host`` header, even if they arrive on the some inbound IP address.
-
-This allows different virtual hosts on the same machine to map to different
-databases or design documents, etc. The most common use case is to map a
-virtual host to a Rewrite Handler, to provide full control over the
-application's URIs.
-
-To add a virtual host, add a CNAME pointer to the DNS for your domain
-name. For development and testing, it is sufficient to add an entry in
-the hosts file, typically `/etc/hosts`` on Unix-like operating systems:
-
-.. code-block:: bash
-
- # CouchDB vhost definitions, refer to local.ini for further details
- 127.0.0.1 sofa.couchdb
-
-Test that this is working:
-
-.. code-block:: bash
-
- $ ping sofa.couchdb
- PING sofa.couchdb (127.0.0.1) 56(84) bytes of data.
- 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
- 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms
- ^C
-
-Finally, add an entry to your :ref:`configuration file <configuring>` in the ``[vhosts]``
-section:
-
-.. code-block:: ini
-
- [vhosts]
- sofa.couchdb:5984 = /sofa/_design/sofa/_rewrite
-
-If your CouchDB is listening on the default HTTP port, or is sitting
-behind a proxy, then don't specify a port number in the vhost key.
-
-With the above setup, a request to ``http://sofa.couchdb:5984/sweet-o``
-will be mapped to
-``http://127.0.0.1:5984/sofa/_design/sofa/_rewrite/sweet-o``
-
-.. versionadded:: 0.11.0 added `vhosts` functionality
-
-HTTP Rewrite Handler
-====================
-
-Following on from `virtual hosts`_, CouchDB includes a custom URL rewriter.
-All rewriting is done from ``/dbname/_design/ddocname/_rewrite`` by default.
-
-The rewriter is flexible, and can handle methods and custom query formats.
-
-Each rule should be in the ``rewrites`` top-level key of the design doc.
-Example of a complete rule :
-
-.. code-block:: json
-
- {
- ....
- "rewrites": [
- {
- "from": "",
- "to": "index.html",
- "method": "GET",
- "query": {}
- }
- ]
- }
-
-
-**from**: is the path rule used to bind current uri to the rule. It
-uses pattern matching for that.
-
-**to**: rule to rewrite an url. It can contain variables depending on
-binding variables discovered during pattern matching and query args
-(url args and from the query member.)
-
-**method**: method to bind the request method to the rule. If method
-is missing, any method will be matched in the rewrite.
-
-**query**: optional query arguments, that may contain dynamic variables,
-by binding keys in the to be used with the matching URL.
-
-``to`` and ``from`` are paths with patterns. The pattern can be strings starting
-with ``:`` or ``*``, for example ``/somepath/:var/*``.
-
-The pattern matching is done by first matching the request method to a
-rule. Then it will try to match the path to one specific rule. If no rule
-match, then a 404 error is displayed.
-
-The path is converted into an erlang list, by regex splitting on ``/``. Each
-variable is converted into an atom. The subsequent pattern matching step is
-done by splitting ``/`` in the request url into a list of atoms. A string
-pattern will match the equivalent token. The ``*`` atom will match any number
-of tokens, but may only be present as the last pattern in the path. If all
-tokens are matched, and all path terms have been consumed, then the overall
-path specification matches.
-
-Once a matching ``from`` rule is found we rewrite the request url using the
-``from``, ``to``, and ``query`` members. Each identified token will be reused
-within the rule, and in the subsequent query if required. The identified
-tokens are matched to the rule and will replace var. If ``*`` is found in
-the rule it will contain any remaining suffix.
-
-The rewriter is re-entrant, and has a configurable recursion limit, set
-by default at 100.
-
-Configuring Server Administrators
-=================================
-
-A default CouchDB install provides admin-level access to all connecting users.
-This configuration is known as ``Admin Party``, and is not recommended for
-in-production usage. You can crash the party simply by creating the first
-admin account. CouchDB server administrators and passwords are not stored
-in the ``_users`` database, but in the ``local.ini`` file, which should be
-appropriately secured and readable only by system administrators.
-
-.. code-block:: ini
-
- [admins]
- ;admin = mysecretpassword
- admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
- architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
-
-Administrators can be added directly to the ``[admins]`` section, and when
-CouchDB is restarted, the passwords will be salted and encrypted. You may
-also use the HTTP interface to create administrator accounts; this way,
-you don't need to restart CouchDB, and there's no need to temporarily store
-or transmit passwords in plaintext. The HTTP ``_config/admins`` endpoint
-supports querying, deleting or creating new admin accounts:
-
-.. code-block:: bash
-
- shell> GET /_config/admins HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 196
- Content-Type: application/json
- Date: Fri, 30 Nov 2012 11:37:18 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
-
-.. code-block:: json
-
- {
- "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
- "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
- }
-
-If you already have a salted, encrypted password string (for example,
-from an old ``local.ini`` file, or from a different CouchDB server), then
-you can store the "raw" encrypted string, without having CouchDB doubly
-encrypt it.
-
-.. code-block:: bash
-
- shell> PUT /_config/admins/architect?raw=true HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Content-Length: 89
- Host: localhost:5984
-
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 89
- Content-Type: application/json
- Date: Fri, 30 Nov 2012 11:39:18 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
-
-.. code-block:: json
-
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-
-Further details are available in ``security_``, including configuring the
-work factor for ``PBKDF2``, and the algorithm itself at
-`PBKDF2 (RFC-2898) <http://tools.ietf.org/html/rfc2898>`_.
-
-.. versionadded::
- 1.3.0 ``PBKDF2`` server-side hashed salted password support added,
- now as a synchronous call for the ``_config/admins`` API.
-
-OS Daemons
-==========
-
-CouchDB now supports starting external processes. The support is simple
-and enables CouchDB to start each configured OS daemon. If the daemon
-stops at any point, CouchDB will restart it (with protection to ensure
-regularly failing daemons are not repeatedly restarted).
-
-The daemon starting process is one-to-one; for each each configured
-daemon in the configuration file, CouchDB will start exactly one
-instance. If you need to run multiple instances, then you must create
-separate individual configurations. Daemons are configured within the
-``[os_daemons]`` section of your configuration file (``local.ini``). The
-format of each configured daemon is:
-
-.. code-block:: ini
-
- NAME = PATH ARGS
-
-Where ``NAME`` is an arbitrary (and unique) name to identify the daemon;
-``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any
-required arguments to the daemon.
-
-For example:
-
-.. code-block:: ini
-
- [os_daemons]
- basic_responder = /usr/local/bin/responder.js
-
-There is no interactivity between CouchDB and the running process, but
-you can use the OS Daemons service to create new HTTP servers and
-responders and then use the new proxy service to redirect requests and
-output to the CouchDB managed service. For more information on proxying,
-see :ref:`http-proxying`. For further background on the OS Daemon service, see
-`CouchDB Externals API`_.
-
-.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
-
-Native SSL Support
-==================
-
-CouchDB |version| supports SSL natively. All your secure connection needs can
-now be served without needing to setup and maintain a separate proxy server
-that handles SSL.
-
-SSL setup can be tricky, but the configuration in CouchDB was designed
-to be as easy as possible. All you need is two files; a certificate and
-a private key. If you bought an official SSL certificate from a
-certificate authority, both should be in your possession already.
-
-If you just want to try this out and don't want to pay anything upfront,
-you can create a self-signed certificate. Everything will work the same,
-but clients will get a warning about an insecure certificate.
-
-You will need the OpenSSL command line tool installed. It probably
-already is.
-
-::
-
- shell> mkdir cert && cd cert
- shell> openssl genrsa > privkey.pem
- shell> openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095
- shell> ls
- mycert.pem privkey.pem
-
-Now, you need to edit CouchDB's configuration, either by editing your
-``local.ini`` file or using the ``/_config`` API calls or the
-configuration screen in Futon. Here is what you need to do in
-``local.ini``, you can infer what needs doing in the other places.
-
-Be sure to make these edits. Under ``[daemons]`` you should see:
-
-::
-
- ; enable SSL support by uncommenting the following line and supply the PEM's below.
- ; the default ssl port CouchDB listens on is 6984
- ;httpsd = {couch_httpd, start_link, [https]}
-
-Here uncomment the last line:
-
-::
-
- httpsd = {couch_httpd, start_link, [https]}
-
-Next, under ``[ssl]`` you will see:
-
-::
-
- ;cert_file = /full/path/to/server_cert.pem
- ;key_file = /full/path/to/server_key.pem
-
-Uncomment and adjust the paths so it matches your system's paths:
-
-::
-
- cert_file = /home/jan/cert/mycert.pem
- key_file = /home/jan/cert/privkey.pem
-
-For more information please read
-`http://www.openssl.org/docs/HOWTO/certificates.txt`_.
-
-Now start (or restart) CouchDB. You should be able to connect to it
-using HTTPS on port 6984:
-
-::
-
- shell> curl https://127.0.0.1:6984/
- curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
- error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
- More details here: http://curl.haxx.se/docs/sslcerts.html
-
- curl performs SSL certificate verification by default, using a "bundle"
- of Certificate Authority (CA) public keys (CA certs). If the default
- bundle file isn't adequate, you can specify an alternate file
- using the --cacert option.
- If this HTTPS server uses a certificate signed by a CA represented in
- the bundle, the certificate verification probably failed due to a
- problem with the certificate (it might be expired, or the name might
- not match the domain name in the URL).
- If you'd like to turn off curl's verification of the certificate, use
- the -k (or --insecure) option.
-
-Oh no what happened?! — Remember, clients will notify their users that
-your certificate is self signed. ``curl`` is the client in this case and
-it notifies you. Luckily you trust yourself (don't you?) and you can
-specify the ``-k`` option as the message reads:
-
-::
-
- shell> curl -k https://127.0.0.1:6984/
- {"couchdb":"Welcome","version":"|version|"}
-
-All done.
-
-.. _`http://www.openssl.org/docs/HOWTO/certificates.txt`: http://www.openssl.org/docs/HOWTO/certificates.txt
-
-.. _http-proxying:
-
-HTTP Proxying
-=============
-
-The HTTP proxy feature makes it easy to map and redirect different
-content through your CouchDB URL. The proxy works by mapping a pathname
-and passing all content after that prefix through to the configured
-proxy address.
-
-Configuration of the proxy redirect is handled through the
-``[httpd_global_handlers]`` section of the CouchDB configuration file
-(typically ``local.ini``). The format is:
-
-.. code-block:: ini
-
- [httpd_global_handlers]
- PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}
-
-
-Where:
-
-- ``PREFIX``
-
- Is the string that will be matched. The string can be any valid
- qualifier, although to ensure that existing database names are not
- overridden by a proxy configuration, you can use an underscore
- prefix.
-
-- ``DESTINATION``
-
- The fully-qualified URL to which the request should be sent. The
- destination must include the ``http`` prefix. The content is used
- verbatim in the original request, so you can also forward to servers
- on different ports and to specific paths on the target host.
-
-The proxy process then translates requests of the form:
-
-.. code-block:: text
-
- http://couchdb:5984/PREFIX/path
-
-To:
-
-.. code-block:: text
-
- DESTINATION/path
-
-.. note::
- Everything after ``PREFIX`` including the required forward slash
- will be appended to the ``DESTINATION``.
-
-The response is then communicated back to the original client.
-
-For example, the following configuration:
-
-.. code-block:: ini
-
- _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}
-
-Would forward all requests for ``http://couchdb:5984/_google`` to the
-Google website.
-
-The service can also be used to forward to related CouchDB services,
-such as Lucene:
-
-.. code-block:: ini
-
- [httpd_global_handlers]
- _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
-
-.. note::
- The proxy service is basic. If the request is not identified by the
- ``DESTINATION``, or the remainder of the ``PATH`` specification is
- incomplete, the original request URL is interpreted as if the
- ``PREFIX`` component of that URL does not exist.
-
- For example, requesting ``http://couchdb:5984/_intranet/media`` when
- ``/media`` on the proxy destination does not exist, will cause the
- request URL to be interpreted as ``http://couchdb:5984/media``. Care
- should be taken to ensure that both requested URLs and destination
- URLs are able to cope.
-
-.. _cors:
-
-Cross-Origin Resource Sharing
-=============================
-
-CORS, or "Cross-Origin Resource Sharing", allows a resource such as a web
-page running JavaScript inside a browser, to make AJAX requests
-(XMLHttpRequests) to a different domain, without compromising the security
-of either party.
-
-A typical use case is to have a static website hosted on a CDN make
-requests to another resource, such as a hosted CouchDB instance. This
-avoids needing an intermediary proxy, using JSONP or similar workarounds
-to retrieve and host content.
-
-While CouchDB's integrated HTTP server and support for document attachments
-makes this less of a constraint for pure CouchDB projects, there are many
-cases where separating the static content from the database access is
-desirable, and CORS makes this very straightforward.
-
-By supporting CORS functionality, a CouchDB instance can accept direct
-connections to protected databases and instances, without the browser
-functionality being blocked due to same-origin constraints. CORS is
-supported today on over 90% of recent browsers.
-
-CORS support is provided as experimental functionality in 1.3.0, and as such
-will need to be enabled specifically in CouchDB's configuration. While all
-origins are forbidden from making requests by default, support is available
-for simple requests, preflight requests and per-vhost configuration.
-
-.. versionadded:: 1.3.0
-
-Enabling CORS
--------------
-
-To enable CORS support, you need to set the ``enable_cors = true`` option
-in the ``[httpd]`` section of ``local.ini``, and add a ``[cors]`` section
-containing a ``origins = *`` setting. Note that by default, no origins are
-accepted; you must either use a wildcard or whitelist.
-
-.. code-block:: ini
-
- [httpd]
- enable_cors = true
-
- [cors]
- origins = *
-
-Passing Credentials
--------------------
-
-By default, neither authentication headers nor cookies are included in
-requests and responses. To do so requires both setting
-`XmlHttpRequest.withCredentials = true` on the request object in the
-browser and enabling credentials support in CouchDB.
-
-.. code-block:: ini
-
- [cors]
- credentials = true
-
-CouchDB will respond to a credentials-enabled CORS request with an additional
-header, `Access-Control-Allow-Credentials=true`.
-
-Tightening Access
------------------
-
-Access can be restricted by protocol, host and optionally by port:
-
-.. code-block:: ini
-
- [cors]
- ; List of origins, separated by a comma (protocol, host, optional port)
- ; refer to http://tools.ietf.org/html/rfc6454 for specification
- origins = http://localhost, https://localhost, http://www.number10.gov.uk:80
-
-Specific HTTP methods may also be restricted:
-
-.. code-block:: ini
-
- [cors]
- ; List of accepted methods, comma-separated
- ; refer to http://tools.ietf.org/html/rfc2616, rfc2817, rfc5789
- methods = GET, POST, PUT, DELETE
-
-Configuration per vhost
------------------------
-
-All CORS-related settings may be configured on a per-vhost basis. For example,
-the configuration section for `http://example.com/` would be contained in:
-
-.. code-block:: ini
-
- [cors:http://example.com]
- credentials = false
- origins = *
- methods = GET, PUT, HEAD
-
-Useful References
------------------
-
-- Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
-
-Standards and References:
-
-- IETF RFCs relating to methods `RFC 2618 <http://tools.ietf.org/html/rfc2616>`_,
- `RFC 2817 <http://tools.ietf.org/html/rfc2817>`_, and
- `RFC 5789 <http://tools.ietf.org/html/rfc5789>`_
-- IETF RFC 6454 for `Web Origins <http://tools.ietf.org/html/rfc6454>`_
-- W3C `CORS standard <http://www.w3.org/TR/cors>`_
-
-Mozilla Developer Network Resources:
-
-- `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_
-- `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_
-- `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_
-- `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
-
-Client-side CORS support and usage:
-
-- `CORS browser support matrix <http://caniuse.com/cors>`_
-- `CORS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_
-- `Cross-Site XMLHttpRequests with CORS <http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors>`_
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 014450c..b51c853 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -29,7 +29,7 @@ Contents
intro
api-basics
- configuring
+ config/index
replication
replicator
ddocs
@@ -37,7 +37,6 @@ Contents
changes
api/reference
json-structure
- config_reference
contributing
changelog
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fba2826e/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
index dd5a985..8a831ee 100644
--- a/share/doc/src/intro.rst
+++ b/share/doc/src/intro.rst
@@ -68,7 +68,7 @@ The main sections are:
An interface into the configuration of your CouchDB installation. The
interface allows you to edit the different configurable parameters.
- For more details on configuration, see :ref:`configuring`.
+ For more details on configuration, see :ref:`config` section.
- Replicator