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/10/01 11:39:25 UTC
[3/3] git commit: updated refs/heads/master to 6f31ffd
Add configuration domain.
:config:section:`httpd` to point on specific section.
:config:option:`httpd/port` to point on specific option.
You have to use section-option pair for that due to clash of option
names (ssl and replicator for example).
As bonus provides complete configuration reference by section names.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6f31ffd9
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6f31ffd9
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6f31ffd9
Branch: refs/heads/master
Commit: 6f31ffd97c443e3d7712eaaa7b06353600f4eb95
Parents: b144050
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Oct 1 13:38:45 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Tue Oct 1 13:38:45 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 2 +
share/doc/ext/configdomain.py | 127 +++++
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/changes.rst | 2 +-
share/doc/src/api/database/common.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 2 +-
share/doc/src/api/document/attachments.rst | 14 +-
share/doc/src/api/document/common.rst | 10 +-
share/doc/src/api/server/authn.rst | 21 +-
share/doc/src/api/server/common.rst | 4 +-
share/doc/src/conf.py | 3 +-
share/doc/src/config/auth.rst | 469 +++++++--------
share/doc/src/config/compaction.rst | 199 ++++---
share/doc/src/config/couchdb.rst | 253 ++++-----
share/doc/src/config/externals.rst | 190 +++----
share/doc/src/config/http-handlers.rst | 310 +++++-----
share/doc/src/config/http.rst | 725 +++++++++++-------------
share/doc/src/config/intro.rst | 20 +-
share/doc/src/config/logging.rst | 94 +--
share/doc/src/config/misc.rst | 364 ++++++------
share/doc/src/config/query-servers.rst | 187 +++---
share/doc/src/config/replicator.rst | 172 +++---
share/doc/src/config/services.rst | 151 ++---
share/doc/src/cve/2012-5641.rst | 4 +-
share/doc/src/externals.rst | 12 +-
share/doc/src/intro/security.rst | 18 +-
share/doc/src/maintenance/compaction.rst | 8 +-
share/doc/src/maintenance/performance.rst | 8 +-
share/doc/src/query-server/protocol.rst | 2 +-
share/doc/src/whatsnew/0.11.rst | 4 +-
share/doc/src/whatsnew/1.4.rst | 2 +-
31 files changed, 1624 insertions(+), 1757 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index ef98bde..fab82a6 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -262,6 +262,7 @@ html_files = \
html/whatsnew/1.5.html \
html/whatsnew/index.html \
html/about.html \
+ html/config-ref.html \
html/contents.html \
html/externals.html \
html/json-structure.html \
@@ -422,6 +423,7 @@ src_files_html = \
../templates/utilities.html
sphinx_extensions = \
+ ../ext/configdomain.py \
../ext/github.py \
../ext/httpdomain.py \
../ext/http-api-descr.json
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/ext/configdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/configdomain.py b/share/doc/ext/configdomain.py
new file mode 100644
index 0000000..a02938b
--- /dev/null
+++ b/share/doc/ext/configdomain.py
@@ -0,0 +1,127 @@
+## 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.
+
+from sphinx import addnodes
+from sphinx.roles import XRefRole
+from sphinx.domains import Domain, ObjType, Index
+from sphinx.directives import ObjectDescription
+from sphinx.util.nodes import make_refnode
+
+
+class ConfigObject(ObjectDescription):
+
+ def handle_signature(self, sig, signode):
+ if '::' in sig:
+ name, descr = map(lambda i: i.strip(), sig.split('::'))
+ else:
+ name, descr = sig.strip(), ''
+
+ signode['name'] = name
+ signode['descr'] = descr
+
+ domain, objtype = self.name.split(':')
+ if objtype == 'section':
+ self.env.temp_data['section'] = signode['name']
+ name = '[%s]' % signode['name']
+
+ signode += addnodes.desc_name(name, name)
+
+ return signode['name']
+
+ def needs_arglist(self):
+ return False
+
+ def add_target_and_index(self, name, sig, signode):
+ section = self.env.temp_data['section']
+ domain, objtype = self.name.split(':')
+ data = self.env.domaindata[domain][objtype]
+ if objtype == 'section':
+ data[name] = (self.env.docname, signode['descr'])
+ signode['ids'].append(signode['name'])
+ elif objtype == 'option':
+ idx = '%s/%s' % (section, signode['name'])
+ data[idx] = (self.env.docname, signode['descr'])
+ signode['ids'].append(idx)
+ else:
+ assert 'unknown object type %r' % objtype
+
+
+class ConfigIndex(Index):
+
+ name = 'ref'
+ localname = 'Configuration Reference'
+ shortname = 'Config Reference'
+
+ def generate(self, docnames=None):
+ content = dict(
+ (name, [(name, 1, info[0], name, '', '', info[1])])
+ for name, info in self.domain.data['section'].items()
+ )
+
+ options = self.domain.data['option']
+ for idx, info in sorted(options.items()):
+ path, descr = info
+ section, name = idx.split('/', 1)
+ content[section].append((
+ name, 2, path,
+ '%s/%s' % (section, name),
+ '', '', descr
+ ))
+
+ return (sorted(content.items()), False)
+
+
+class ConfigDomain(Domain):
+
+ name = 'config'
+ label = 'CONFIG'
+
+ object_types = {
+ 'section': ObjType('section', 'section', 'obj'),
+ 'option': ObjType('option', 'option', 'obj'),
+ }
+
+ directives = {
+ 'section': ConfigObject,
+ 'option': ConfigObject,
+ }
+
+ roles = {
+ 'section': XRefRole(),
+ 'option': XRefRole(),
+ }
+
+ initial_data = {
+ 'section': {},
+ 'option': {}
+ }
+
+ indices = [ConfigIndex]
+
+ def resolve_xref(self, env, fromdocname, builder, typ, target,
+ node, contnode):
+ if typ == 'section':
+ info = self.data[typ][target]
+ title = '[%s]' % target
+ elif typ == 'option':
+ assert '/' in target, 'option without section: %r' % target
+ section, option = target.split('/', 1)
+ info = self.data[typ][target]
+ title = option
+ else:
+ assert 'unknown role %r for target %r' % (typ, target)
+ return make_refnode(builder, fromdocname, info[0], target, contnode,
+ title)
+
+
+def setup(app):
+ app.add_domain(ConfigDomain)
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index 87233df..1c88fbf 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -210,7 +210,7 @@
- :mimetype:`text/plain`
:<header Content-Type: :mimetype:`application/json`
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*.
:<json boolean all_or_nothing: Sets the database commit mode to use
`all-or-nothing` semantics. Default is ``false``. *Optional*.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index f2ad9b7..db6af63 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -70,7 +70,7 @@
before the response is sent, even if there are no results. Only applicable
for :ref:`longpoll <changes/longpoll>` or :ref:`continuous
<changes/continuous>` feeds. Default value is specified by
- :ref:`changes_timeout <config/httpd/changes_timeout>` configuration option.
+ :config:option:`httpd/changes_timeout` configuration option.
Note that ``60000`` value is also the default maximum timeout to prevent
undetected dead connections.
:query string view: Allows to use view functions as filters. Documents
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index c374625..4d4d24c 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -268,7 +268,7 @@
- :mimetype:`text/plain`
:<header Content-Type: :mimetype:`application/json`
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*.
:query string batch: Stores document in :ref:`batch mode
<api/doc/batch-writes>` Possible values: ``ok``. *Optional*
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index 16cfffc..af37e61 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -46,7 +46,7 @@
Currently it is the next:
* **language** (*string*): Defines :ref:`Query Server <query-server>`
- :ref:`key <config/query_servers>` to process design document functions
+ :config:section:`key <query_servers>` to process design document functions
* **options** (*object*): View's default options
* **filters** (*object*): :ref:`Filter functions <filterfun>` definition
* **lists** (*object*): :ref:`List functions <listfun>` definition
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index c26b561..8514993 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -34,8 +34,8 @@
:>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
Used for attachments with :mimetype:`application/octet-stream` content type
:>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
:>header Content-Length: Attachment size. If compression codec was used,
this value is about compressed size, not actual
:>header Content-MD5: Base64 encoded MD5 binary digest
@@ -87,8 +87,8 @@
:>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
Used for attachments with :mimetype:`application/octet-stream`
:>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
:>header Content-Length: Attachment size. If compression codec is used,
this value is about compressed size, not actual
:>header Content-MD5: Base64 encoded MD5 binary digest
@@ -127,8 +127,8 @@
:>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
Used for attachments with :mimetype:`application/octet-stream`
:>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
:>header Content-Length: Attachment size. If compression codec is used,
this value is about compressed size, not actual
:>header Content-MD5: Base64 encoded MD5 binary digest
@@ -197,7 +197,7 @@
- :mimetype:`text/plain`
:<header If-Match: Document revision. Alternative to `rev` query parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string rev: Document revision. *Required*
:query string batch: Store changes in :ref:`batch mode
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 6687ebc..49ffe42 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -177,7 +177,7 @@
:<header Content-Type: :mimetype:`application/json`
:<header If-Match: Document's revision. Alternative to `rev` query parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string batch: Stores document in :ref:`batch mode
<api/doc/batch-writes>` Possible values: ``ok``. *Optional*
@@ -253,7 +253,7 @@
- :mimetype:`text/plain`
:<header If-Match: Document's revision. Alternative to `rev` query parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string rev: Actual document's revision
:query string batch: Stores document in :ref:`batch mode
@@ -325,7 +325,7 @@
:<header If-Match: Source document's revision. Alternative to `rev` query
parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string rev: Revision to copy from. *Optional*
:query string batch: Stores document in :ref:`batch mode
@@ -397,8 +397,8 @@ information objects with next structure:
Base64-encoded hash digest
- **encoded_length** (*number*): Compressed attachment size in bytes
Available when query parameter ``att_encoding_info=true`` was specified and
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
- **encoding** (*string*): Compression codec. Available when query parameter
``att_encoding_info=true`` was specified
- **length** (*number*): Real attachment size in bytes. Not available if attachment
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index ce08277..a3ac3ea 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -75,13 +75,13 @@ For cookie authentication (:rfc:`2109`) CouchDB generates a token that the
client can use for the next few requests to CouchDB. Tokens are valid until
a timeout. When CouchDB sees a valid token in a subsequent request, it will
authenticate user by this token without requesting the password again. By
-default, cookies are valid for 10 minutes, but it's :ref:`adjustable
-<config/couch_httpd_auth/timeout>`. Also it's possible to make cookies
-:ref:`persistent <config/couch_httpd_auth/allow_persistent_cookies>`
+default, cookies are valid for 10 minutes, but it's :config:option:`adjustable
+<couch_httpd_auth/timeout>`. Also it's possible to make cookies
+:config:option:`persistent <couch_httpd_auth/allow_persistent_cookies>`
To obtain the first token and thus authenticate a user for the first time, the
-`username` and `password` must be sent to the
-:ref:`_session API <api/auth/session>`.
+`username` and `password` must be sent to the :ref:`_session API
+<api/auth/session>`.
.. _api/auth/session:
@@ -271,8 +271,7 @@ Proxy Authentication
.. note::
To use this authentication method make sure that the
``{couch_httpd_auth, proxy_authentication_handler}`` value in added to
- the list of the active
- :ref:`authentication handlers <config/httpd/authentication_handlers>`:
+ the list of the active :config:option:`httpd/authentication_handlers`:
.. code-block:: ini
@@ -288,13 +287,13 @@ This authentication method allows creation of a :ref:`userctx_object` for
remotely authenticated user. By default, the client just need to pass specific
headers to CouchDB with related request:
-- :ref:`X-Auth-CouchDB-UserName <config/couch_httpd_auth/x_auth_username>`:
+- :config:option:`X-Auth-CouchDB-UserName <couch_httpd_auth/x_auth_username>`:
username;
-- :ref:`X-Auth-CouchDB-Roles <config/couch_httpd_auth/x_auth_roles>`:
+- :config:option:`X-Auth-CouchDB-Roles <couch_httpd_auth/x_auth_roles>`:
list of user roles separated by a comma (``,``);
-- :ref:`X-Auth-CouchDB-Token <config/couch_httpd_auth/x_auth_token>`:
+- :config:option:`X-Auth-CouchDB-Token <couch_httpd_auth/x_auth_token>`:
authentication token. Optional, but strongly recommended to
- :ref:`force token be required <config/couch_httpd_auth/proxy_use_secret>`
+ :config:option:`force token be required <couch_httpd_auth/proxy_use_secret>`
to prevent requests from untrusted sources.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index fda74f5..2c14fee 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -956,8 +956,8 @@ structure is as follows:
]
}
-The UUID type is determined by the :ref:`UUID algorithm <config/uuids/algorithm>`
-setting in the CouchDB configuration.
+The UUID type is determined by the :config:option:`UUID algorithm
+<uuids/algorithm>` setting in the CouchDB configuration.
The UUID type may be changed at any time through the
:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 805f87d..b3f8325 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -17,7 +17,8 @@ import sys
sys.path.insert(0, os.path.abspath('../ext'))
-extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks", 'github', 'httpdomain']
+extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks", 'github',
+ 'httpdomain', 'configdomain']
_info = {}
_regex = re.compile('m4_define\(\[(.+)\],\s+\[(.+)\]\)')
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 85d0dbb..4127288 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -10,8 +10,9 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. highlight:: ini
+.. default-domain:: config
+.. highlight:: ini
================================
Authentication and Authorization
@@ -19,383 +20,341 @@ Authentication and Authorization
.. _config/admins:
-``[admins]`` :: Server Administrators
-=====================================
+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::
+.. config:section:: admins :: Server Administrators
- [admins]
- ;admin = mysecretpassword
- admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
- architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
+ 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::
-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:
+ [admins]
+ ;admin = mysecretpassword
+ admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
+ architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
-.. code-block:: http
+ 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:
- GET /_config/admins HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ .. code-block:: http
-.. code-block:: http
+ 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 (Erlang/OTP)
+ .. code-block:: http
-.. code-block:: json
+ 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 (Erlang/OTP)
- {
- "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
- "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
- }
+ .. code-block:: json
-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.
+ {
+ "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
+ "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ }
-.. code-block:: http
+ 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.
- PUT /_config/admins/architect?raw=true HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Content-Length: 89
- Host: localhost:5984
+ .. code-block:: http
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ PUT /_config/admins/architect?raw=true HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Content-Length: 89
+ Host: localhost:5984
-.. code-block:: http
+ "-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 (Erlang/OTP)
+ .. code-block:: http
- "-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 (Erlang/OTP)
-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>`_.
+ "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-.. versionchanged:: 1.4 `PBKDF2` server-side hashed salted password support
- added, now as a synchronous call for the ``_config/admins`` API.
+ 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.4 `PBKDF2` server-side hashed salted password support
+ added, now as a synchronous call for the ``_config/admins`` API.
.. _config/couch_httpd_auth:
-``[couch_httpd_auth]`` :: Authentication Configuration
-======================================================
-
-.. _config/couch_httpd_auth/allow_persistent_cookies:
+Authentication Configuration
+============================
-``allow_persistent_cookies`` :: Persistent cookies
---------------------------------------------------
+.. config:section:: couch_httpd_auth :: Authentication Configuration
-Makes cookies persistent if ``true``.
-::
+ .. config:option:: allow_persistent_cookies :: Persistent cookies
- [couch_httpd_auth]
- allow_persistent_cookies = false
+ Makes cookies persistent if ``true``.
+ ::
-.. _config/couch_httpd_auth/auth_cache_size:
+ [couch_httpd_auth]
+ allow_persistent_cookies = false
-``auth_cache_size`` :: Authentication cache
--------------------------------------------
-Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
+ .. config:option:: auth_cache_size :: Authentication cache
-::
+ Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
- [couch_httpd_auth]
- auth_cache_size = 50
+ ::
+ [couch_httpd_auth]
+ auth_cache_size = 50
-.. _config/couch_httpd_auth/authentication_db:
-``authentication_db`` :: Users database
----------------------------------------
+ .. config:option:: authentication_db :: Users database
-Specifies the name of the system database for storing CouchDB users.
+ Specifies the name of the system database for storing CouchDB users.
-::
+ ::
- [couch_httpd_auth]
- authentication_db = _users
+ [couch_httpd_auth]
+ authentication_db = _users
-.. warning:: If you change the database name, do not forget to remove or clean
- up the old database, since it will no longer be protected by CouchDB.
+ .. warning::
+ If you change the database name, do not forget to remove or clean
+ up the old database, since it will no longer be protected by CouchDB.
-.. _config/couch_httpd_auth/authentication_redirect:
+ .. config:option:: authentication_redirect :: Default redirect for authentication requests
-``authentication_redirect`` :: Default redirect for authentication requests
----------------------------------------------------------------------------
+ Specifies the location for redirection on successful authentication if a
+ ``text/html`` response is accepted by the client (via an ``Accept`` header).
-Specifies the location for redirection on successful authentication if a
-``text/html`` response is accepted by the client (via an ``Accept`` header).
+ ::
-::
+ [couch_httpd_auth]
+ authentication_redirect = /_utils/session.html
- [couch_httpd_auth]
- authentication_redirect = /_utils/session.html
+ .. config:option:: iterations :: PBKDF2 iterations count
-.. _config/couch_httpd_auth/iterations:
+ .. versionadded:: 1.3
-``iterations`` :: PBKDF2 iterations count
------------------------------------------
+ The number of iterations for password hashing by the PBKDF2 algorithm.
+ A higher number provides better hash durability, but comes at a cost in
+ performance for each request that requires authentication.
-.. versionadded:: 1.3
+ ::
-The number of iterations for password hashing by the PBKDF2 algorithm. A higher
-number provides better hash durability, but comes at a cost in performance for
-each request that requires authentication.
+ [couch_httpd_auth]
+ iterations = 10000
-::
- [couch_httpd_auth]
- iterations = 10000
+ .. config:option:: proxy_use_secret :: Force proxy auth use secret token
+ When this option is set to ``true``, the :option:`couch_httpd_auth/secret`
+ option is required for :ref:`api/auth/proxy`.
-.. _config/couch_httpd_auth/proxy_use_secret:
+ ::
-``proxy_use_secret`` :: Force proxy auth use secret token
----------------------------------------------------------
+ [couch_httpd_auth]
+ proxy_use_secret = false
-When this option is set to ``true``, the
-:ref:`secret <config/couch_httpd_auth/secret>` option is required for
-:ref:`api/auth/proxy`.
-::
+ .. config:option:: public_fields :: User documents public fields
- [couch_httpd_auth]
- proxy_use_secret = false
+ .. versionadded:: 1.4
+ A comma-separated list of field names in user documents (in
+ :option:`couch_httpd_auth/authentication_db`) that can
+ be read by any user. If unset or not specified, authenticated users can only
+ retrieve their own document.
-.. _config/couch_httpd_auth/public_fields:
+ ::
-``public_fields`` :: User documents public fields
--------------------------------------------------
+ [couch_httpd_auth]
+ public_fields = first_name, last_name, contacts, url
-.. versionadded:: 1.4
+ .. note::
+ Using the ``public_fields`` whitelist for user document properties
+ requires setting the :option:`couch_httpd_auth/users_db_public`
+ option to ``true`` (the latter option has no other purpose)::
-A comma-separated list of field names in user documents (in
-:ref:`authentication_db <config/couch_httpd_auth/authentication_db>`) that can
-be read by any user. If unset or not specified, authenticated users can only
-retrieve their own document.
+ [couch_httpd_auth]
+ users_db_public = true
-::
- [couch_httpd_auth]
- public_fields = first_name, last_name, contacts, url
+ .. config:option:: require_valid_user :: Force user authentication
-.. note::
- Using the ``public_fields`` whitelist for user document properties requires
- setting the :ref:`users_db_public <config/couch_httpd_auth/users_db_public>`
- option to ``true`` (the latter option has no other purpose)::
+ When this option is set to ``true``, no requests are allowed from anonymous
+ users. Everyone must be authenticated.
- [couch_httpd_auth]
- users_db_public = true
+ ::
-.. _config/couch_httpd_auth/require_valid_user:
+ [couch_httpd_auth]
+ require_valid_user = false
-``require_valid_user`` :: Force user authentication
----------------------------------------------------
-When this option is set to ``true``, no requests are allowed from anonymous
-users. Everyone must be authenticated.
+ .. config:option:: secret :: Proxy Auth secret token
-::
+ The secret token used for :ref:`api/auth/proxy` method.
- [couch_httpd_auth]
- require_valid_user = false
+ ::
+ [couch_httpd_auth]
+ secret = 92de07df7e7a3fe14808cef90a7cc0d91
-.. _config/couch_httpd_auth/secret:
-``secret`` :: Proxy Auth secret token
--------------------------------------
+ .. config:option:: timeout :: Session timeout
-The secret token used for :ref:`api/auth/proxy` method.
+ Number of seconds since the last request before sessions will be expired.
-::
+ ::
- [couch_httpd_auth]
- secret = 92de07df7e7a3fe14808cef90a7cc0d91
+ [couch_httpd_auth]
+ timeout = 600
-.. _config/couch_httpd_auth/timeout:
+ .. config:option:: users_db_public :: Publish user documents
-``timeout`` :: Session timeout
-------------------------------
+ .. versionadded:: 1.4
-Number of seconds since the last request before sessions will be expired.
+ Allow all users to view user documents. By default, only admins may browse
+ all users documents, while users may browse only their own document.
-::
+ ::
- [couch_httpd_auth]
- timeout = 600
+ [couch_httpd_auth]
+ users_db_public = false
+ .. config:option:: x_auth_roles :: Proxy Auth roles header
-.. _config/couch_httpd_auth/users_db_public:
+ The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
+ list of a user's roles, separated by a comma. Used for
+ :ref:`api/auth/proxy`.
-``users_db_public`` :: Publish user documents
----------------------------------------------
+ ::
-.. versionadded:: 1.4
+ [couch_httpd_auth]
+ x_auth_roles = X-Auth-CouchDB-Roles
-Allow all users to view user documents. By default, only admins may browse
-all users documents, while users may browse only their own document.
-::
+ .. config:option:: x_auth_token :: Proxy Auth token header
- [couch_httpd_auth]
- users_db_public = false
+ The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
+ token used to authenticate the authorization. This token is an `HMAC-SHA1`
+ created from the :option:`couch_httpd_auth/secret` and
+ :option:`couch_httpd_auth/x_auth_username`. The secret key should be
+ the same on the client and the CouchDB node. This token is optional if
+ the value of the :option:`couch_httpd_auth/proxy_use_secret` option is not
+ ``true``. Used for :ref:`api/auth/proxy`.
+ ::
-.. _config/couch_httpd_auth/x_auth_roles:
+ [couch_httpd_auth]
+ x_auth_roles = X-Auth-CouchDB-Token
-``x_auth_roles`` :: Proxy Auth roles header
--------------------------------------------
-The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
-list of a user's roles, separated by a comma. Used for :ref:`api/auth/proxy`.
+ .. config:option:: x_auth_username :: Proxy Auth username header
-::
+ The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
+ username. Used for :ref:`api/auth/proxy`.
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Roles
+ ::
+ [couch_httpd_auth]
+ x_auth_username = X-Auth-CouchDB-UserName
-.. _config/couch_httpd_auth/x_auth_token:
-``x_auth_token`` :: Proxy Auth token header
--------------------------------------------
-
-The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
-token used to authenticate the authorization. This token is an `HMAC-SHA1`
-created from :ref:`secret key <config/couch_httpd_auth/secret>` and
-:ref:`username <config/couch_httpd_auth/x_auth_username>`. The secret key
-should be the same on the client and the CouchDB node. This token is optional
-if the value of the
-:ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
-option is not ``true``. Used for :ref:`api/auth/proxy`.
+.. _config/couch_httpd_oauth:
-::
+HTTP OAuth Configuration
+========================
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Token
+.. config:section:: couch_httpd_oauth :: HTTP OAuth Configuration
+ .. versionadded:: 1.2
-.. _config/couch_httpd_auth/x_auth_username:
+ .. config:option:: use_users_db
-``x_auth_username`` :: Proxy Auth username header
--------------------------------------------------
+ CouchDB is able to store OAuth credentials within user documents instead of
+ config file by using this option::
-The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
-username. Used for :ref:`api/auth/proxy`.
+ [couch_httpd_oauth]
+ use_users_db = true
-::
+ If set to ``true``, OAuth token and consumer secrets will be looked up in the
+ :option:`authentication database <couch_httpd_auth/authentication_db>`.
+ These secrets are stored in a top level field named ``"oauth"`` in user
+ documents, as below.
- [couch_httpd_auth]
- x_auth_username = X-Auth-CouchDB-UserName
+ .. code-block:: javascript
+ {
+ "_id": "org.couchdb.user:joe",
+ "type": "user",
+ "name": "joe",
+ "password_sha": "fe95df1ca59a9b567bdca5cbaf8412abd6e06121",
+ "salt": "4e170ffeb6f34daecfd814dfb4001a73"
+ "roles": ["foo", "bar"],
+ "oauth": {
+ "consumer_keys": {
+ "consumerKey1": "key1Secret",
+ "consumerKey2": "key2Secret"
+ },
+ "tokens": {
+ "token1": "token1Secret",
+ "token2": "token2Secret"
+ }
+ }
+ }
.. _config/oauth:
-``[oauth]`` :: OAuth Configuration
-==================================
+OAuth Configuration
+===================
-.. _config/oauth/oauth_consumer_secrets:
-.. _config/oauth/oauth_token_secrets:
-.. _config/oauth/oauth_token_users:
+.. config:section:: oauth_* :: OAuth Configuration
-Store credentials within config
--------------------------------
+ To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
+ special sections must be set up in the :ref:`configuration <config>` file:
-To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
-special sections must be set up in the :ref:`configuration <config>` file:
+ 1. The Consumer secret:
-1. The Consumer secret:
+ ::
-::
+ [oauth_consumer_secrets]
+ consumer1 = sekr1t
- [oauth_consumer_secrets]
- consumer1 = sekr1t
+ 2. Token secrets:
-2. Token secrets:
+ ::
-::
+ [oauth_token_secrets]
+ token1 = tokensekr1t
- [oauth_token_secrets]
- token1 = tokensekr1t
+ 3. A mapping from tokens to users:
-3. A mapping from tokens to users:
-
-::
-
- [oauth_token_users]
- token1 = couchdb_username
-
-
-.. _config/couch_httpd_oauth:
-.. _config/couch_httpd_oauth/use_users_db:
-
-Store OAuth credentials within auth database
---------------------------------------------
-
-.. versionadded:: 1.2
-
-CouchDB is able to store OAuth credentials within user documents instead of
-config file by using this option::
-
- [couch_httpd_oauth]
- use_users_db = true
-
-If set to ``true``, OAuth token and consumer secrets will be looked up in the
-:ref:`authentication database <config/couch_httpd_auth/authentication_db>`.
-These secrets are stored in a top level field named ``"oauth"`` in user
-documents, as below.
-
-.. code-block:: javascript
-
- {
- "_id": "org.couchdb.user:joe",
- "type": "user",
- "name": "joe",
- "password_sha": "fe95df1ca59a9b567bdca5cbaf8412abd6e06121",
- "salt": "4e170ffeb6f34daecfd814dfb4001a73"
- "roles": ["foo", "bar"],
- "oauth": {
- "consumer_keys": {
- "consumerKey1": "key1Secret",
- "consumerKey2": "key2Secret"
- },
- "tokens": {
- "token1": "token1Secret",
- "token2": "token2Secret"
- }
- }
- }
+ ::
+ [oauth_token_users]
+ token1 = couchdb_username
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/compaction.rst b/share/doc/src/config/compaction.rst
index 0393d8c..5e1e10d 100644
--- a/share/doc/src/config/compaction.rst
+++ b/share/doc/src/config/compaction.rst
@@ -10,172 +10,165 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
========================
Compaction Configuration
========================
-.. _config/database_compaction:
-
-``[database_compaction]`` :: Database Compaction Options
-========================================================
-
-.. _config/database_compaction/doc_buffer_size:
+.. _conifg/database_compaction:
-``doc_buffer_size`` :: Documents buffer size
---------------------------------------------
+Database Compaction Options
+===========================
-Specifies the copy buffer's maximum size in bytes::
+.. config:section:: database_compaction :: Database Compaction Options
- [database_compaction]
- doc_buffer_size = 524288
+ .. config:option:: doc_buffer_size :: Documents buffer size
+ Specifies the copy buffer's maximum size in bytes::
-.. _config/database_compaction/checkpoint_after:
+ [database_compaction]
+ doc_buffer_size = 524288
-``checkpoint_after`` :: Checkpoint trigger
-------------------------------------------
-Triggers a checkpoint after the specified amount of bytes were successfully
-copied to the compacted database::
+ .. config:option:: checkpoint_after :: Checkpoint trigger
- [database_compaction]
- checkpoint_after = 5242880
+ Triggers a checkpoint after the specified amount of bytes were successfully
+ copied to the compacted database::
+ [database_compaction]
+ checkpoint_after = 5242880
.. _config/compactions:
-``[compactions]`` :: Compaction Daemon Rules
-============================================
+Compaction Daemon Rules
+=======================
-Automatic compaction rules definition.
-The :ref:`compaction daemon <config/daemons/compaction_daemon>` compacts
-databases and their respective view groups when all the condition parameters are
-satisfied. Configuration can be per database or global, and it has the following
-format::
+.. config:section:: compactions :: Compaction Daemon Rules
- [compactions]
- database_name = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
- _default = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
+ Automatic compaction rules definition. The :option:`daemons/compaction_daemon`
+ compacts databases and their respective view groups when all the condition
+ parameters are satisfied. Configuration can be per database or global, and it
+ has the following format::
+ [compactions]
+ database_name = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
+ _default = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
-For example::
- [compactions]
- _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
+ For example::
-Possible parameters:
+ [compactions]
+ _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
-- ``db_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in the database file size is equal to or greater then this
- value, this database compaction condition is satisfied. The percentage is
- expressed as an integer percentage. This value is computed as::
+ Possible parameters:
- (file_size - data_size) / file_size * 100
+ - ``db_fragmentation``: If the ratio of legacy data, including metadata, to
+ current data in the database file size is equal to or greater then this
+ value, this database compaction condition is satisfied. The percentage is
+ expressed as an integer percentage. This value is computed as::
- The data_size and file_size values can be obtained when
- querying :get:`/{db}`.
+ (file_size - data_size) / file_size * 100
-- ``view_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in a view index file size is equal to or greater then this
- value, this database compaction condition is satisfied. The percentage is
- expressed as an integer percentage. This value is computed as::
+ The data_size and file_size values can be obtained when
+ querying :http:get:`/{db}`.
- (file_size - data_size) / file_size * 100
+ - ``view_fragmentation``: If the ratio of legacy data, including metadata, to
+ current data in a view index file size is equal to or greater then this
+ value, this database compaction condition is satisfied. The percentage is
+ expressed as an integer percentage. This value is computed as::
- The data_size and file_size values can be obtained when querying a
- :ref:`view group's information URI <api/ddoc/info>`.
+ (file_size - data_size) / file_size * 100
-- ``from`` and ``to``: The period for which a database (and its view groups)
- compaction is allowed. The value for these parameters must obey the format::
+ The data_size and file_size values can be obtained when querying a
+ :ref:`view group's information URI <api/ddoc/info>`.
- HH:MM - HH:MM (HH in [0..23], MM in [0..59])
+ - ``from`` and ``to``: The period for which a database (and its view groups)
+ compaction is allowed. The value for these parameters must obey the format::
-- ``strict_window``: If a compaction is still running after the end of the
- allowed period, it will be canceled if this parameter is set to `true`.
- It defaults to `false` and it's meaningful only if the *period* parameter is
- also specified.
+ HH:MM - HH:MM (HH in [0..23], MM in [0..59])
-- ``parallel_view_compaction``: If set to `true`, the database and its views are
- compacted in parallel. This is only useful on certain setups, like for example
- when the database and view index directories point to different disks.
- It defaults to `false`.
+ - ``strict_window``: If a compaction is still running after the end of the
+ allowed period, it will be canceled if this parameter is set to `true`.
+ It defaults to `false` and it's meaningful only if the *period* parameter
+ is also specified.
-Before a compaction is triggered, an estimation of how much free disk space is
-needed is computed. This estimation corresponds to two times the data size of
-the database or view index. When there's not enough free disk space to compact
-a particular database or view index, a warning message is logged.
+ - ``parallel_view_compaction``: If set to `true`, the database and its views
+ are compacted in parallel. This is only useful on certain setups, like
+ for example when the database and view index directories point to different
+ disks. It defaults to `false`.
-Examples:
+ Before a compaction is triggered, an estimation of how much free disk space is
+ needed is computed. This estimation corresponds to two times the data size of
+ the database or view index. When there's not enough free disk space to compact
+ a particular database or view index, a warning message is logged.
-#. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}]``
+ Examples:
- The `foo` database is compacted if its fragmentation is 70% or more.
- Any view index of this database is compacted only if its fragmentation
- is 60% or more.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}]``
-#. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}]``
+ The `foo` database is compacted if its fragmentation is 70% or more.
+ Any view index of this database is compacted only if its fragmentation
+ is 60% or more.
- Similar to the preceding example but a compaction (database or view index)
- is only triggered if the current time is between midnight and 4 AM.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}]``
-#. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}]``
+ Similar to the preceding example but a compaction (database or view index)
+ is only triggered if the current time is between midnight and 4 AM.
- Similar to the preceding example - a compaction (database or view index)
- is only triggered if the current time is between midnight and 4 AM. If at
- 4 AM the database or one of its views is still compacting, the compaction
- process will be canceled.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}]``
-#. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}, {parallel_view_compaction, true}]``
+ Similar to the preceding example - a compaction (database or view index)
+ is only triggered if the current time is between midnight and 4 AM. If at
+ 4 AM the database or one of its views is still compacting, the compaction
+ process will be canceled.
- Similar to the preceding example, but a database and its views can be
- compacted in parallel.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}, {parallel_view_compaction, true}]``
+ Similar to the preceding example, but a database and its views can be
+ compacted in parallel.
-.. _config/compaction_daemon:
-``[compaction_daemon]`` :: Configuration of Compaction Daemon
-=============================================================
+.. _config/compaction_daemon:
-.. _config/compaction_daemon/check_interval:
+Configuration of Compaction Daemon
+==================================
-``check_interval``
-------------------
+.. config:section:: compaction_daemon :: Configuration of Compaction Daemon
-The delay, in seconds, between each check for which database and view indexes
-need to be compacted::
+ .. config:option:: check_interval
- [compaction_daemon]
- check_interval = 300
+ The delay, in seconds, between each check for which database and view
+ indexes need to be compacted::
+ [compaction_daemon]
+ check_interval = 300
-.. _config/compaction_daemon/min_file_size:
-``min_file_size``
------------------
+ .. config:option:: min_file_size
-If a database or view index file is smaller then this value (in bytes),
-compaction will not happen. Very small files always have a very high
-fragmentation therefore it's not worth to compact them::
+ If a database or view index file is smaller then this value (in bytes),
+ compaction will not happen. Very small files always have a very high
+ fragmentation therefore it's not worth to compact them::
- [compaction_daemon]
- min_file_size = 131072
+ [compaction_daemon]
+ min_file_size = 131072
.. _config/view_compaction:
-``[view_compaction]`` :: Views Compaction Options
-=================================================
+Views Compaction Options
+========================
-.. _config/view_compaction/keyvalue_buffer_size:
+.. config:section:: view_compaction :: Views Compaction Options
-``keyvalue_buffer_size`` :: Key-Values buffer size
---------------------------------------------------
-Specifies maximum copy buffer size in bytes used during compaction::
+ .. config:option:: keyvalue_buffer_size :: Key-Values buffer size
- [view_compaction]
- keyvalue_buffer_size = 2097152
+ Specifies maximum copy buffer size in bytes used during compaction::
+ [view_compaction]
+ keyvalue_buffer_size = 2097152
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index d42e5b8..6f3c022 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
==================
@@ -18,212 +20,181 @@ Base Configuration
.. _config/couchdb:
-``[couchdb]`` :: Base CouchDB Options
-=====================================
-
-.. _config/couchdb/attachment_stream_buffer_size:
-
-``attachment_stream_buffer_size`` :: Attachment streaming buffer
-----------------------------------------------------------------
-
-Higher values may result in better read performance due to fewer read
-operations and/or more OS page cache hits. However, they can also increase
-overall response time for writes when there are many attachment write
-requests in parallel.
-
-::
-
- [couchdb]
- attachment_stream_buffer_size = 4096
-
-
-.. _config/couchdb/database_dir:
-
-``database_dir`` :: Databases location directory
-------------------------------------------------
-
-Specifies location of CouchDB database files (``*.couch`` named). This location
-should be writable and readable for the user the CouchDB service runs as
-(``couchdb`` by default).
-
-::
-
- [couchdb]
- database_dir = /var/lib/couchdb
+Base CouchDB Options
+====================
+.. config:section:: couchdb :: Base CouchDB Options
-.. _config/couchdb/delayed_commits:
-``delayed_commits`` :: Delayed commits
---------------------------------------
+ .. config:option:: attachment_stream_buffer_size :: Attachment streaming buffer
-When this config value as ``false`` the CouchDB provides guaranty of fsync call
-before return ``HTTP 201 Created`` response on each document saving. Setting
-this config value as ``true`` may raise some overall performance with cost of
-losing durability - it's strongly not recommended to do such in production::
+ Higher values may result in better read performance due to fewer read
+ operations and/or more OS page cache hits. However, they can also increase
+ overall response time for writes when there are many attachment write
+ requests in parallel.
- [couchdb]
- delayed_commits = false
+ ::
-.. warning::
+ [couchdb]
+ attachment_stream_buffer_size = 4096
- Delayed commits are a feature of CouchDB that allows it to achieve better
- write performance for some workloads while sacrificing a small amount of
- durability. The setting causes CouchDB to wait up to a full second before
- committing new data after an update. If the server crashes before the header
- is written then any writes since the last commit are lost.
+ .. config:option:: database_dir :: Databases location directory
-.. _config/couchdb/file_compression:
+ Specifies location of CouchDB database files (``*.couch`` named).
+ This location should be writable and readable for the user the CouchDB
+ service runs as (``couchdb`` by default).
-``file_compression`` :: Compression method for documents
------------------------------------------------------------
+ ::
-.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
+ [couchdb]
+ database_dir = /var/lib/couchdb
-Method used to compress everything that is appended to database and view index
-files, except for attachments (see the :ref:`[attachments] <config/attachments>`
-section). Available methods are:
-* ``none``: no compression
-* ``snappy``: use Google Snappy, a very fast compressor/decompressor
-* ``deflate_N``: use zlib's deflate; ``N`` is the compression level which ranges
- from 1 (fastest, lowest compression ratio) to 9 (slowest, highest compression
- ratio)
+ .. config:option:: delayed_commits :: Delayed commits
-::
+ When this config value as ``false`` the CouchDB provides guaranty of `fsync`
+ call before return :http:statuscode:`201` response on each document saving.
+ Setting this config value as ``true`` may raise some overall performance
+ with cost of losing durability - it's strongly not recommended to do such
+ in production::
- [couchdb]
- file_compression = snappy
+ [couchdb]
+ delayed_commits = false
-.. _Google Snappy: http://code.google.com/p/snappy/
+ .. warning::
+ Delayed commits are a feature of CouchDB that allows it to achieve better
+ write performance for some workloads while sacrificing a small amount of
+ durability. The setting causes CouchDB to wait up to a full second before
+ committing new data after an update. If the server crashes before
+ the header is written then any writes since the last commit are lost.
-.. _config/couchdb/fsync_options:
-``fsync_options`` :: Fsync options
-----------------------------------
+ .. config:option:: file_compression :: Compression method for documents
-Specifies when to make `fsync` calls. `fsync` makes sure that the contents of
-any file system buffers kept by the operating system are flushed to disk.
-There is generally no need to modify this parameter.
+ .. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
-::
+ Method used to compress everything that is appended to database and
+ view index files, except for attachments (see the :section:`attachments`
+ section). Available methods are:
- [couchdb]
- fsync_options = [before_header, after_header, on_file_open]
+ * ``none``: no compression
+ * ``snappy``: use Google Snappy, a very fast compressor/decompressor
+ * ``deflate_N``: use zlib's deflate; ``N`` is the compression level which
+ ranges from ``1`` (fastest, lowest compression ratio) to ``9`` (slowest,
+ highest compression ratio)
+ ::
-.. _config/couchdb/max_dbs_open:
+ [couchdb]
+ file_compression = snappy
-``max_dbs_open`` :: Limit of simultaneously opened databases
-------------------------------------------------------------
+ .. _Google Snappy: http://code.google.com/p/snappy/
-This option places an upper bound on the number of databases that can be open
-at once. CouchDB reference counts database accesses internally and will close
-idle databases as needed. Sometimes it is necessary to keep more than the
-default open at once, such as in deployments where many databases will be
-replicating continuously.
-::
+ .. config:option:: fsync_options :: Fsync options
- [couchdb]
- max_dbs_open = 100
+ Specifies when to make `fsync` calls. `fsync` makes sure that
+ the contents of any file system buffers kept by the operating system are
+ flushed to disk. There is generally no need to modify this parameter.
+ ::
-.. _config/couchdb/max_document_size:
+ [couchdb]
+ fsync_options = [before_header, after_header, on_file_open]
-``max_document_size`` :: Maximum document size
-----------------------------------------------
-.. versionchanged:: 1.3 This option now actually works.
+ .. config:option:: max_dbs_open :: Limit of simultaneously opened databases
-Defines a maximum size for JSON documents, in bytes. This limit does not
-apply to attachments, since they are transferred as a stream of chunks. If you
-set this to a small value, you might be unable to modify configuration options,
-database security and other larger documents until a larger value is restored
-by editing the configuration file.
+ This option places an upper bound on the number of databases that can be
+ open at once. CouchDB reference counts database accesses internally and will
+ close idle databases as needed. Sometimes it is necessary to keep more than
+ the default open at once, such as in deployments where many databases will
+ be replicating continuously.
-::
+ ::
- [couchdb]
- max_document_size = 4294967296 ; 4 GB
+ [couchdb]
+ max_dbs_open = 100
-.. _config/couchdb/os_process_timeout:
+ .. config:option:: max_document_size :: Maximum document size
-``os_process_timeout`` :: External processes time limit
--------------------------------------------------------
+ .. versionchanged:: 1.3 This option now actually works.
-If an external process, such as a query server or external process, runs for
-this amount of microseconds without returning any results, it will be
-terminated. Keeping this value smaller ensures you get expedient errors, but
-you may want to tweak it for your specific needs.
+ Defines a maximum size for JSON documents, in bytes. This limit does not
+ apply to attachments, since they are transferred as a stream of chunks.
+ If you set this to a small value, you might be unable to modify
+ configuration options, database security and other larger documents until
+ a larger value is restored by editing the configuration file.
-::
+ ::
- [couchdb]
- os_process_timeout = 5000 ; 5 sec
+ [couchdb]
+ max_document_size = 4294967296 ; 4 GB
-.. _config/couchdb/uri_file:
+ .. config:option:: os_process_timeout :: External processes time limit
-``uri_file`` :: Discovery CouchDB help file
--------------------------------------------
+ If an external process, such as a query server or external process, runs for
+ this amount of microseconds without returning any results, it will be
+ terminated. Keeping this value smaller ensures you get expedient errors, but
+ you may want to tweak it for your specific needs.
-This file contains the full `URI`_ that can be used to access this instance of
-CouchDB. It is used to help discover the port CouchDB is running on (if it was
-set to ``0`` (e.g. automatically assigned any free one). This file should be
-writable and readable for the user that runs the CouchDB service (``couchdb``
-by default).
+ ::
-::
+ [couchdb]
+ os_process_timeout = 5000 ; 5 sec
- [couchdb]
- uri_file = /var/run/couchdb/couchdb.uri
-.. _URI: http://en.wikipedia.org/wiki/URI
+ .. config:option:: uri_file :: Discovery CouchDB help file
+ This file contains the full `URI`_ that can be used to access this
+ instance of CouchDB. It is used to help discover the port CouchDB is running
+ on (if it was set to ``0`` (e.g. automatically assigned any free one).
+ This file should be writable and readable for the user that runs the CouchDB
+ service (``couchdb`` by default).
-.. _config/couchdb/util_driver_dir:
+ ::
-``util_driver_dir`` :: CouchDB binary utility drivers
------------------------------------------------------
+ [couchdb]
+ uri_file = /var/run/couchdb/couchdb.uri
-Specifies location of binary drivers (`icu`, `ejson`, etc.). This location and
-its contents should be readable for the user that runs the CouchDB service.
+ .. _URI: http://en.wikipedia.org/wiki/URI
-::
- [couchdb]
- util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
+ .. config:option:: util_driver_dir :: CouchDB binary utility drivers
+ Specifies location of binary drivers (`icu`, `ejson`, etc.). This location
+ and its contents should be readable for the user that runs the CouchDB
+ service.
-.. _config/couchdb/uuid:
+ ::
-``uuid`` :: CouchDB server UUID
--------------------------------
+ [couchdb]
+ util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
-.. versionadded:: 1.3
-Unique identifier for this CouchDB server instance.
+ .. config:option:: uuid :: CouchDB server UUID
-::
+ .. versionadded:: 1.3
- [couchdb]
- uuid = 0a959b9b8227188afc2ac26ccdf345a6
+ Unique identifier for this CouchDB server instance.
+ ::
-.. _config/couchdb/view_index_dir:
+ [couchdb]
+ uuid = 0a959b9b8227188afc2ac26ccdf345a6
-``view_index_dir`` :: View indexes location directory
------------------------------------------------------
-Specifies location of CouchDB view index files. This location should be writable
-and readable for the user that runs the CouchDB service (``couchdb`` by default).
+ .. config:option:: view_index_dir :: View indexes location directory
-::
+ Specifies location of CouchDB view index files. This location should be
+ writable and readable for the user that runs the CouchDB service
+ (``couchdb`` by default).
- [couchdb]
- view_index_dir = /var/lib/couchdb
+ ::
+ [couchdb]
+ view_index_dir = /var/lib/couchdb
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/externals.rst b/share/doc/src/config/externals.rst
index d4a8eab..c05fe05 100644
--- a/share/doc/src/config/externals.rst
+++ b/share/doc/src/config/externals.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
==================
@@ -18,162 +20,160 @@ External Processes
.. _config/os_daemons:
-``[os_daemons]`` :: OS Daemons
-==============================
+OS Daemons
+==========
-This is a simple feature that allows users to configure CouchDB so that it
-maintains a given OS level process alive. If the process dies for any reason,
-CouchDB will restart it. If the process restarts too often, then CouchDB will
-mark it has halted and not attempt to restart it. The default max restart rate
-is ``3`` times in the last ``5`` seconds. These parameters are
-:ref:`adjustable <config/os_daemon_settings>`.
+.. config:section:: os_daemons :: OS Daemons
-Commands that are started in this manner will have access to a simple
-API over stdio to request configuration parameters or to add log
-statements to CouchDB's logs.
+ This is a simple feature that allows users to configure CouchDB so that it
+ maintains a given OS level process alive. If the process dies for any reason,
+ CouchDB will restart it. If the process restarts too often, then CouchDB will
+ mark it has halted and not attempt to restart it. The default max restart rate
+ is ``3`` times in the last ``5`` seconds. These parameters are
+ :section:`adjustable <os_daemon_settings>`.
-To configure an OS process as a CouchDB os_daemon, create a section
-in your `local.ini` like such::
+ Commands that are started in this manner will have access to a simple
+ API over stdio to request configuration parameters or to add log
+ statements to CouchDB's logs.
- [os_daemons]
- daemon_name = /path/to/command -with args
+ To configure an OS process as a CouchDB os_daemon, create a section
+ in your `local.ini` like such::
-This will make CouchDB bring up the command and attempt to keep it
-alive. To request a configuration parameter, an `os_daemon` can write
-a simple JSON message to stdout like such::
+ [os_daemons]
+ daemon_name = /path/to/command -with args
- ["get", "os_daemons"]\n
+ This will make CouchDB bring up the command and attempt to keep it
+ alive. To request a configuration parameter, an `os_daemon` can write
+ a simple JSON message to stdout like such::
-which would return::
+ ["get", "os_daemons"]\n
- {"daemon_name": "/path/to/command -with args"}\n
+ which would return::
-Or::
+ {"daemon_name": "/path/to/command -with args"}\n
- ["get", "os_daemons", "daemon_name"]\n
+ Or::
-which would return::
+ ["get", "os_daemons", "daemon_name"]\n
- "/path/to/command -with args"\n
+ which would return::
-There's no restriction on what configuration variables are visible.
-There's also no method for altering the configuration.
+ "/path/to/command -with args"\n
-If you would like your OS daemon to be restarted in the event that
-the configuration changes, you can send the following messages::
+ There's no restriction on what configuration variables are visible.
+ There's also no method for altering the configuration.
- ["register", $(SECTION)]\n
+ If you would like your OS daemon to be restarted in the event that
+ the configuration changes, you can send the following messages::
-When anything in that section changes, your OS process will be
-rebooted so it can pick up the new configuration settings. If you
-want to listen for changes on a specific key, you can send something
-like::
+ ["register", $(SECTION)]\n
- ["register", $(SECTION), $(KEY)]\n
+ When anything in that section changes, your OS process will be
+ rebooted so it can pick up the new configuration settings. If you
+ want to listen for changes on a specific key, you can send something
+ like::
-In this case, CouchDB will only restart your daemon if that exact
-section/key pair changes, instead of anything in that entire section.
+ ["register", $(SECTION), $(KEY)]\n
-Logging commands look like::
+ In this case, CouchDB will only restart your daemon if that exact
+ section/key pair changes, instead of anything in that entire section.
- ["log", $(JSON_MESSAGE)]\n
+ Logging commands look like::
-Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are
-logged at the 'info' level. If you want to log at a different level
-you can pass messages like such::
+ ["log", $(JSON_MESSAGE)]\n
- ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n
+ Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are
+ logged at the 'info' level. If you want to log at a different level
+ you can pass messages like such::
-Where ``$(LEVEL)`` is one of "debug", "info", or "error".
+ ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n
-When implementing a daemon process to be managed by CouchDB you
-should remember to use a method like checking the parent process
-id or if stdin has been closed. These flags can tell you if
-your daemon process has been orphaned so you can exit cleanly.
+ Where ``$(LEVEL)`` is one of "debug", "info", or "error".
-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`_.
+ When implementing a daemon process to be managed by CouchDB you
+ should remember to use a method like checking the parent process
+ id or if stdin has been closed. These flags can tell you if
+ your daemon process has been orphaned so you can exit cleanly.
-.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
+ 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 :ref:`externals`.
.. _config/os_daemon_settings:
-``[os_daemon_settings]`` :: OS Daemons settings
-===============================================
-
-.. _config/os_daemons_settings/max_retries:
+OS Daemons settings
+===================
-``max_retries`` :: Maximum restart retries
-------------------------------------------
+.. config:section:: os_daemon_settings :: OS Daemons settings
-Specifies maximum attempts to run :ref:`os_daemon <config/os_daemons>` before
-mark them halted::
- [os_daemon_settings]
- max_retries = 3
+ .. config:option:: max_retries :: Maximum restart retries
+ Specifies maximum attempts to run :section:`os_daemons` before
+ mark them halted::
-.. _config/os_daemons_settings/retry_time:
+ [os_daemon_settings]
+ max_retries = 3
-``retry_time`` :: Delay between restart attempts
-------------------------------------------------
-Delay in seconds between :ref:`os_daemon <config/os_daemons>` restarts::
+ .. config:option:: retry_time :: Delay between restart attempts
- [os_daemon_settings]
- retry_time = 5
+ Delay in seconds between :section:`os_daemons` restarts::
+ [os_daemon_settings]
+ retry_time = 5
.. _update-notifications:
.. _config/update_notification:
-``[update_notification]`` :: Update notifications
-=================================================
+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`::
+.. config:section:: update_notification :: Update notifications
- [update_notification]
- ;unique notifier name=/full/path/to/exe -with "cmd line arg"
- index_updater = ruby /usr/local/bin/index_updater.rb
+ 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:
+ The update notification messages are depend upon of event type:
-- **Database created**:
+ - **Database created**:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"created","db":"dbname"}
+ {"type":"created","db":"dbname"}
-- **Database updated**: this event raises when any document gets updated for
- specified database:
+ - **Database updated**: this event raises when any document gets updated for
+ specified database:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"updated","db":"dbname"}
+ {"type":"updated","db":"dbname"}
-- **Design document updated**: for design document updates there is special
- event raised in additional to regular db update one:
+ - **Design document updated**: for design document updates there is special
+ event raised in additional to regular db update one:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
+ {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
-- **Database deleted**:
+ - **Database deleted**:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"deleted","db":"dbname"}
+ {"type":"deleted","db":"dbname"}
-.. note:: New line (``\n``) trailing character was removed from examples.
+ .. note:: New line (``\n``) trailing character was removed from examples.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/http-handlers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http-handlers.rst b/share/doc/src/config/http-handlers.rst
index 7da653d..e4a1f41 100644
--- a/share/doc/src/config/http-handlers.rst
+++ b/share/doc/src/config/http-handlers.rst
@@ -18,324 +18,274 @@ HTTP Resource Handlers
.. _config/httpd_global_handlers:
-``[httpd_global_handlers]`` :: Global HTTP Handlers
-===================================================
+Global HTTP Handlers
+====================
-These HTTP resources are provided for CouchDB server root level.
+.. config:section:: httpd_global_handlers :: Global HTTP Handlers
-.. _config/httpd_global_handlers/root:
+ These HTTP resources are provided for CouchDB server root level.
-:ref:`/ <api/server/root>`
---------------------------
+ .. config:option:: /
-::
+ ::
- [httpd_global_handlers]
- / = {couch_httpd_misc_handlers, handle_welcome_req, <<"Welcome">>}
+ [httpd_global_handlers]
+ / = {couch_httpd_misc_handlers, handle_welcome_req, <<"Welcome">>}
-.. _config/httpd_global_handlers/favicon.ico:
-:ref:`favicon.ico <api/server/favicon>`
----------------------------------------
+ .. config:option:: favicon.ico
-The favicon handler looks for `favicon.ico` file within specified directory::
+ The favicon handler looks for `favicon.ico` file within specified directory::
- [httpd_global_handlers]
- favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}
+ [httpd_global_handlers]
+ favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}
-.. _config/httpd_global_handlers/_active_tasks:
-:ref:`_active_tasks <api/server/active_tasks>`
-----------------------------------------------
+ .. config:option:: _active_tasks
-::
+ ::
- [httpd_global_handlers]
- _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}
+ [httpd_global_handlers]
+ _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}
-.. _config/httpd_global_handlers/_all_dbs:
-:ref:`_all_dbs <api/server/all_dbs>`
-------------------------------------
+ .. config:option:: _all_dbs
-Provides a list of all server's databases::
+ Provides a list of all server's databases::
- [httpd_global_handlers]
- _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
+ [httpd_global_handlers]
+ _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
-.. note::
+ .. note::
- Sometimes you don't want to disclose database names for everyone, but you
- also don't like/want/able to setup any proxies in front of CouchDB. Removing
- this handler disables ``_all_dbs`` resource and there will be no way to get
- list of available databases.
+ Sometimes you don't want to disclose database names for everyone, but
+ you also don't like/want/able to setup any proxies in front of CouchDB.
+ Removing this handler disables ``_all_dbs`` resource and there will be
+ no way to get list of available databases.
- The s`ame also is true for other resource handlers.
+ The same also is true for other resource handlers.
-.. _config/httpd_global_handlers/_config:
-:ref:`_config <api/config>`
----------------------------
+ .. config:option:: _config
-Provides resource to work with CouchDB config :ref:`remotely <api/config>`.
-Any config changes that was made via HTTP API are applied automatically on fly
-and doesn't requires server instance to be restarted::
+ Provides resource to work with CouchDB config :ref:`remotely <api/config>`.
+ Any config changes that was made via HTTP API are applied automatically on
+ fly and doesn't requires server instance to be restarted::
- [httpd_global_handlers]
- _config = {couch_httpd_misc_handlers, handle_config_req}
+ [httpd_global_handlers]
+ _config = {couch_httpd_misc_handlers, handle_config_req}
-.. _config/httpd_global_handlers/_log:
-:ref:`_log <api/server/log>`
-----------------------------
+ .. config:option:: _log
-::
+ ::
- [httpd_global_handlers]
- _log = {couch_httpd_misc_handlers, handle_log_req}
+ [httpd_global_handlers]
+ _log = {couch_httpd_misc_handlers, handle_log_req}
-.. _config/httpd_global_handlers/_oauth:
-``_oauth``
-----------
+ .. config:option:: _oauth
-::
+ ::
- [httpd_global_handlers]
- _oauth = {couch_httpd_oauth, handle_oauth_req}
+ [httpd_global_handlers]
+ _oauth = {couch_httpd_oauth, handle_oauth_req}
-.. _config/httpd_global_handlers/_replicate:
-:ref:`_replicate <api/server/replicate>`
-----------------------------------------
+ .. config:option:: _replicate
-Provides an API to run :ref:`temporary replications <api/server/replicate>`::
+ Provides an API to run :ref:`temporary replications <api/server/replicate>`::
- [httpd_global_handlers]
- _replicate = {couch_replicator_httpd, handle_req}
+ [httpd_global_handlers]
+ _replicate = {couch_replicator_httpd, handle_req}
-.. _config/httpd_global_handlers/_restart:
-:ref:`_restart <api/server/restart>`
-------------------------------------
+ .. config:option:: _restart
-::
+ ::
- [httpd_global_handlers]
- _restart = {couch_httpd_misc_handlers, handle_restart_req}
+ [httpd_global_handlers]
+ _restart = {couch_httpd_misc_handlers, handle_restart_req}
-.. _config/httpd_global_handlers/_session:
-``_session``
-------------
+ .. config:option:: _session
-Provides a resource with information about the current user's session::
+ Provides a resource with information about the current user's session::
- [httpd_global_handlers]
- _session = {couch_httpd_auth, handle_session_req}
+ [httpd_global_handlers]
+ _session = {couch_httpd_auth, handle_session_req}
-.. _config/httpd_global_handlers/_stats:
+ .. config:option:: _stats
-:ref:`_stats <api/server/stats>`
---------------------------------
+ ::
-::
+ [httpd_global_handlers]
+ _stats = {couch_httpd_stats_handlers, handle_stats_req}
- [httpd_global_handlers]
- _stats = {couch_httpd_stats_handlers, handle_stats_req}
+ .. config:option:: _utils
-.. _config/httpd_global_handlers/_utils:
+ The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web administration
+ page::
-:ref:`_utils <api/server/utils>`
---------------------------------
+ [httpd_global_handlers]
+ _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}
-The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web administration
-page::
+ In similar way, you may setup custom handler to let CouchDB serve any static
+ files.
- [httpd_global_handlers]
- _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}
-In similar way, you may setup custom handler to let CouchDB serve any static
-files.
+ .. config:option:: _uuids
+ Provides a resource to get UUIDs generated by CouchDB::
-.. _config/httpd_global_handlers/_uuids:
+ [httpd_global_handlers]
+ _uuids = {couch_httpd_misc_handlers, handle_uuids_req}
-:ref:`_uuids <api/server/uuids>`
---------------------------------
+ This is useful when your client environment isn't capable of providing truly
+ random IDs (web browsers e.g.).
-Provides a resource to get UUIDs generated by CouchDB::
-
- [httpd_global_handlers]
- _uuids = {couch_httpd_misc_handlers, handle_uuids_req}
-
-This is useful when your client environment isn't capable of providing truly
-random IDs (web browsers e.g.).
.. _config/httpd_db_handlers:
-``[httpd_db_handlers]`` :: Database HTTP Handlers
-=================================================
+Database HTTP Handlers
+======================
+
+.. config:section:: httpd_db_handlers :: Database HTTP Handlers
-These HTTP resources are available on every CouchDB database.
+ These HTTP resources are available on every CouchDB database.
-.. _config/httpd_db_handlers/_all_docs:
-:ref:`_all_docs <api/db/all_docs>`
-----------------------------------
+ .. config:option:: _all_docs
-::
+ ::
- [httpd_db_handlers]
- _all_docs = {couch_mrview_http, handle_all_docs_req}
+ [httpd_db_handlers]
+ _all_docs = {couch_mrview_http, handle_all_docs_req}
-.. _config/httpd_db_handlers/_changes:
-:ref:`_changes <changes>`
--------------------------
+ .. config:option:: _changes
-::
+ ::
- [httpd_db_handlers]
- _changes = {couch_httpd_db, handle_changes_req}
+ [httpd_db_handlers]
+ _changes = {couch_httpd_db, handle_changes_req}
-.. _config/httpd_db_handlers/_compact:
-:ref:`_compact <api/db/compact>`
---------------------------------
+ .. config:option:: _compact
-::
+ ::
- [httpd_db_handlers]
- _compact = {couch_httpd_db, handle_compact_req}
+ [httpd_db_handlers]
+ _compact = {couch_httpd_db, handle_compact_req}
-.. _config/httpd_db_handlers/_design:
-:ref:`_design <api/ddoc>`
--------------------------
+ .. config:option:: _design
-::
+ ::
- [httpd_db_handlers]
- _design = {couch_httpd_db, handle_design_req}
+ [httpd_db_handlers]
+ _design = {couch_httpd_db, handle_design_req}
-.. _config/httpd_db_handlers/_temp_view:
-:ref:`_temp_view <api/db/temp_view>`
-------------------------------------
+ .. config:option:: _temp_view
-::
+ ::
- [httpd_db_handlers]
- _temp_view = {couch_mrview_http, handle_temp_view_req}
+ [httpd_db_handlers]
+ _temp_view = {couch_mrview_http, handle_temp_view_req}
-.. _config/httpd_db_handlers/_view_cleanup:
-:ref:`_view_cleanup <api/db/view_cleanup>`
-------------------------------------------
+ .. config:option:: _view_cleanup
-::
+ ::
- [httpd_db_handlers]
- _view_cleanup = {couch_mrview_http, handle_cleanup_req}
+ [httpd_db_handlers]
+ _view_cleanup = {couch_mrview_http, handle_cleanup_req}
.. _config/httpd_design_handlers:
-``[httpd_design_handlers]`` :: Design Documents HTTP Handlers
-=============================================================
+Design Documents HTTP Handlers
+==============================
-These HTTP resources are provided for design documents.
+.. config:section:: httpd_design_handlers :: Design Documents HTTP Handlers
-.. _config/httpd_design_handlers/_compact:
+These HTTP resources are provided for design documents.
-:ref:`_compact <api/db/compact/ddoc>`
--------------------------------------
-::
+ .. config:option:: _compact
- [httpd_design_handlers]
- _compact = {couch_mrview_http, handle_compact_req}
+ ::
+ [httpd_design_handlers]
+ _compact = {couch_mrview_http, handle_compact_req}
-.. _config/httpd_design_handlers/_info:
-:ref:`_info <api/ddoc/info>`
-----------------------------
-::
+ .. config:option:: _info
- [httpd_design_handlers]
- _info = {couch_mrview_http, handle_info_req}
+ ::
+ [httpd_design_handlers]
+ _info = {couch_mrview_http, handle_info_req}
-.. _config/httpd_design_handlers/_list:
-:ref:`_list <api/ddoc/list>`
-----------------------------
-::
+ .. config:option:: _list
- [httpd_design_handlers]
- _list = {couch_mrview_show, handle_view_list_req}
+ ::
+ [httpd_design_handlers]
+ _list = {couch_mrview_show, handle_view_list_req}
-.. _config/httpd_design_handlers/_rewrite:
-:ref:`_rewrite <api/ddoc/rewrite>`
-----------------------------------
-::
+ .. config:option:: _rewrite
- [httpd_design_handlers]
- _rewrite = {couch_httpd_rewrite, handle_rewrite_req}
+ ::
+ [httpd_design_handlers]
+ _rewrite = {couch_httpd_rewrite, handle_rewrite_req}
-.. _config/httpd_design_handlers/_show:
-:ref:`_show <api/ddoc/show>`
-----------------------------
-::
+ .. config:option:: _show
- [httpd_design_handlers]
- _show = {couch_mrview_show, handle_doc_show_req}
+ ::
+ [httpd_design_handlers]
+ _show = {couch_mrview_show, handle_doc_show_req}
-.. _config/httpd_design_handlers/_update:
-:ref:`_update <api/ddoc/update>`
---------------------------------
-::
+ .. config:option:: _update
- [httpd_design_handlers]
- _update = {couch_mrview_show, handle_doc_update_req}
+ ::
+ [httpd_design_handlers]
+ _update = {couch_mrview_show, handle_doc_update_req}
-.. _config/httpd_design_handlers/_view:
-:ref:`_view <api/ddoc/view>`
-----------------------------
-::
+ .. config:option:: _view
- [httpd_design_handlers]
- _view = {couch_mrview_http, handle_view_req}
+ ::
+ [httpd_design_handlers]
+ _view = {couch_mrview_http, handle_view_req}