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/09/28 14:42:52 UTC
[26/50] [abbrv] git commit: updated refs/heads/master to 17e0b7c
Improve grammar, text flow in new configuration docs.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/cf4a09bc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/cf4a09bc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/cf4a09bc
Branch: refs/heads/master
Commit: cf4a09bce2848f3cb0fe98bfe4e32d4a930da674
Parents: 738095b
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 14:37:59 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/server/common.rst | 8 +--
share/doc/src/config/auth.rst | 110 +++++++++++++++++++------------
share/doc/src/config/couchdb.rst | 88 +++++++++++++++----------
share/doc/src/config/http.rst | 6 +-
share/doc/src/config/misc.rst | 55 ++++++++--------
5 files changed, 160 insertions(+), 107 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/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 690c55d..22e312d 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -959,9 +959,9 @@ 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 could be changed in anytime through
-:ref:`Config API <api/config/section/key>`. For example, changing the UUID
-type to ``random`` use next HTTP request:
+The UUID type may be changed at any time through the
+:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
+could be changed to ``random`` by sending this HTTP request:
.. code-block:: http
@@ -971,7 +971,7 @@ type to ``random`` use next HTTP request:
"random"
-When obtaining a list of UUIDs you'll see the changes:
+You can verify the change by obtaining a list of UUIDs:
.. code-block:: javascript
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 410ae46..279e124 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -108,7 +108,9 @@ work factor for ``PBKDF2``, and the algorithm itself at
``allow_persistent_cookies`` :: Persistent cookies
--------------------------------------------------
-Makes cookies persistent if ``true``::
+Makes cookies persistent if ``true``.
+
+::
[couch_httpd_auth]
allow_persistent_cookies = false
@@ -119,7 +121,9 @@ Makes cookies persistent if ``true``::
``auth_cache_size`` :: Authentication cache
-------------------------------------------
-Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
+Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
+
+::
[couch_httpd_auth]
auth_cache_size = 50
@@ -130,14 +134,15 @@ Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
``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
-.. warning:: If there was any reasons to change this name for you, don't forget
- to remove/cleanup old database since it wouldn't be protected by CouchDB
- anymore.
+.. 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:
@@ -146,7 +151,9 @@ Specifies the name of the system database for storing CouchDB users::
---------------------------------------------------------------------------
Specifies the location for redirection on successful authentication if a
-``text/html`` response is accepted by the client (via ``Accept`` header)::
+``text/html`` response is accepted by the client (via an ``Accept`` header).
+
+::
[couch_httpd_auth]
authentication_redirect = /_utils/session.html
@@ -159,8 +166,11 @@ Specifies the location for redirection on successful authentication if a
.. versionadded:: 1.3
-The umbenr of iterations for password hashing by the PBKDF2 algorithm. A higher
-number provides better hash durability, but with cost of performance on each request that requires authentication::
+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
@@ -171,8 +181,11 @@ number provides better hash durability, but with cost of performance on each req
``proxy_use_secret`` :: Force proxy auth use secret token
---------------------------------------------------------
-When this option is ``true`` the :ref:`secret <config/couch_httpd_auth/secret>`
-is required for :ref:`api/auth/proxy`::
+When this option is set to ``true``, the
+:ref:`secret <config/couch_httpd_auth/secret>` option is required for
+:ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
proxy_use_secret = false
@@ -185,9 +198,10 @@ is required for :ref:`api/auth/proxy`::
.. versionadded:: 1.4
-Comma-separated list of field names that will be available to view for any user
-document in :ref:`authentication_db <config/couch_httpd_auth/authentication_db>`
-If unset or not specified, authenticated users may retrieve only their own docs.
+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.
::
@@ -204,11 +218,13 @@ If unset or not specified, authenticated users may retrieve only their own docs.
.. _config/couch_httpd_auth/require_valid_user:
-``require_valid_user`` :: Force users authentication
-----------------------------------------------------
+``require_valid_user`` :: Force user authentication
+---------------------------------------------------
+
+When this option is set to ``true``, no requests are allowed from anonymous
+users. Everyone must be authenticated.
-When this option ``true`` no requests allowed from anonymous users. Everyone
-must be authenticated::
+::
[couch_httpd_auth]
require_valid_user = false
@@ -219,7 +235,9 @@ must be authenticated::
``secret`` :: Proxy Auth secret token
-------------------------------------
-The secret token used for :ref:`api/auth/proxy` method::
+The secret token used for :ref:`api/auth/proxy` method.
+
+::
[couch_httpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91
@@ -230,7 +248,9 @@ The secret token used for :ref:`api/auth/proxy` method::
``timeout`` :: Session timeout
------------------------------
-Number of seconds since the last request before session will be expired::
+Number of seconds since the last request before sessions will be expired.
+
+::
[couch_httpd_auth]
timeout = 600
@@ -239,13 +259,15 @@ Number of seconds since the last request before session will be expired::
.. _config/couch_httpd_auth/users_db_public:
-``users_db_public`` :: Publish users info
------------------------------------------
+``users_db_public`` :: Publish user documents
+---------------------------------------------
.. versionadded:: 1.4
Allow all users to view user documents. By default, only admins may browse
-all users documents while users may browse only their own document::
+all users documents, while users may browse only their own document.
+
+::
[couch_httpd_auth]
users_db_public = false
@@ -256,8 +278,10 @@ all users documents while users may browse only their own document::
``x_auth_roles`` :: Proxy Auth roles header
-------------------------------------------
-HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the list of
-user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
+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`.
+
+::
[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Roles
@@ -268,13 +292,16 @@ user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
``x_auth_token`` :: Proxy Auth token header
-------------------------------------------
-HTTP header name (``X-Auth-CouchDB-Token`` by default) with token to
-authenticate the authorization. This token is an `HMAC-SHA1` created from
-:ref:`secret key <config/couch_httpd_auth/secret>` and
+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 in the client and CouchDB node. This token is optional
-if value of :ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
-option isn't ``true``. Used for :ref:`api/auth/proxy`::
+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`.
+
+::
[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Token
@@ -285,8 +312,10 @@ option isn't ``true``. Used for :ref:`api/auth/proxy`::
``x_auth_username`` :: Proxy Auth username header
-------------------------------------------------
-HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
-username. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
+username. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_username = X-Auth-CouchDB-UserName
@@ -305,11 +334,10 @@ username. Used for :ref:`api/auth/proxy`::
Store credentials within config
-------------------------------
-To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`) method
-there is need to setup three special sections in :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. Consumer secret:
+1. The Consumer secret:
::
@@ -323,7 +351,7 @@ file:
[oauth_token_secrets]
token1 = tokensekr1t
-3. Tokens to users mapping:
+3. A mapping from tokens to users:
::
@@ -339,8 +367,8 @@ Store OAuth credentials within auth database
.. versionadded:: 1.2
-CouchDB is able to store OAuth credentials within users documents instead of
-config file by using next option::
+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
@@ -348,7 +376,7 @@ config file by using next option::
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. Example:
+documents, as below.
.. code-block:: javascript
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index 053f7e9..c1bd182 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -26,9 +26,12 @@ Base Configuration
``attachment_stream_buffer_size`` :: Attachment streaming buffer
----------------------------------------------------------------
-Higher values may give better read performance due to less read operations
-and/or more OS page cache hits, but they can also increase overall response
-time for writes when there are many attachment write requests in parallel::
+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
@@ -39,9 +42,11 @@ time for writes when there are many attachment write requests in parallel::
``database_dir`` :: Databases location directory
------------------------------------------------
-Specifies location of CouchDB databases files (``*.couch`` named). This location
-should be writable and readable for user that runs CouchDB service (``couchdb``
-by default)::
+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
@@ -74,15 +79,15 @@ losing durability - it's strongly not recommended to do such in production::
``file_compression`` :: Compression method for documents
-----------------------------------------------------------
-.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm
+.. 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 :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
+* ``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)
@@ -99,9 +104,11 @@ section). Available methods are:
``fsync_options`` :: Fsync options
----------------------------------
-Specifies when to make `fsync` calls. `fsync` makes sure that any file system
-buffers kept by the operating system are written to disk. Normally, you have no
-need to edit this parameter::
+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.
+
+::
[couchdb]
fsync_options = [before_header, after_header, on_file_open]
@@ -112,11 +119,13 @@ need to edit this parameter::
``max_dbs_open`` :: Limit of simultaneously opened databases
------------------------------------------------------------
-This option places an upper bound on the number of databases that can be open at
-one time. CouchDB reference counts database accesses internally and will close
-idle databases when it must. Sometimes it is necessary to keep more than the
+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
-continuously replicating::
+replicating continuously.
+
+::
[couchdb]
max_dbs_open = 100
@@ -129,11 +138,13 @@ continuously replicating::
.. versionchanged:: 1.3 This option now actually works.
-Defines limit of size in bytes that document may has in JSON form. Doesn't
-applies for attachments since they are been transferred as stream of chunks.
-Do not set this value too small since you want be able to modify config options,
-database security and other options until you restore this value by edit config
-file::
+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]
max_document_size = 4294967296 ; 4 GB
@@ -144,10 +155,12 @@ file::
``os_process_timeout`` :: External processes time limit
-------------------------------------------------------
-Number of microseconds that external processes such as `query server` and
-`externals` may process CouchDB commands before return any result. Keeping
-this value smaller you'll be ensured that your services works fast, but you may
-tweak it depending on your needs::
+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.
+
+::
[couchdb]
os_process_timeout = 5000 ; 5 sec
@@ -158,10 +171,13 @@ tweak it depending on your needs::
``uri_file`` :: Discovery CouchDB help file
-------------------------------------------
-This file contains full `URI`_ that runs CouchDB. It's used to help discover
-CouchDB served port if it was set to ``0`` (e.g. automatically assigned any
-free one). This file should be writable and readable for user that runs CouchDB
-service (``couchdb`` by default)::
+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]
uri_file = /var/run/couchdb/couchdb.uri
@@ -174,8 +190,10 @@ service (``couchdb`` by default)::
``util_driver_dir`` :: CouchDB binary utility drivers
-----------------------------------------------------
-Specified location of binary drivers (`icu`, `ejson`, etc.). This location and
-his content should be readable for user that runs CouchDB service::
+Specifies location of binary drivers (`icu`, `ejson`, etc.). This location and
+its contents should be readable for the user that runs the CouchDB service.
+
+::
[couchdb]
util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.3.0/priv/lib
@@ -188,7 +206,9 @@ his content should be readable for user that runs CouchDB service::
.. versionadded:: 1.3
-Unique identifier of CouchDB server instance::
+Unique identifier for this CouchDB server instance.
+
+::
[couchdb]
uuid = 0a959b9b8227188afc2ac26ccdf345a6
@@ -200,7 +220,9 @@ Unique identifier of CouchDB server instance::
-----------------------------------------------------
Specifies location of CouchDB view index files. This location should be writable
-and readable for user that runs CouchDB service (``couchdb`` by default)::
+and readable for the user that runs the CouchDB service (``couchdb`` by default).
+
+::
[couchdb]
view_index_dir = /var/lib/couchdb
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index 3c86585..f225092 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -653,9 +653,9 @@ behind a proxy, then you don't need to specify a port number in the `vhost` key.
The first line will rewrite the request to display the content of the `example`
database. This rule works only if the ``Host`` header is ``couchdb.local`` and
-won't work for `CNAMEs`. The second rule on the other hand matches all
-`CNAMEs` to `example` db. So `www.couchdb.local` or `db.couchdb.local` will
-work.
+won't work for `CNAMEs`. The second rule, on the other hand, matches all
+`CNAMEs` to `example` db, so that both `www.couchdb.local` and `db.couchdb.local`
+will work.
.. _config/vhosts/rewriting:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index ffd9041..235142d 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -27,7 +27,7 @@ Miscellaneous Parameters
---------------------
Defines zlib compression level for the attachments from ``1`` (lowest, fastest)
-to ``9`` (highest, slowest). ``0`` value disables compression::
+to ``9`` (highest, slowest). A value of ``0`` disables compression::
[attachments]
compression_level = 8
@@ -38,8 +38,8 @@ to ``9`` (highest, slowest). ``0`` value disables compression::
``compressible_types``
----------------------
-While not all attached files could be compressed well, it is possible to let
-CouchDB compress only specific attachments identified by their MIME type::
+Since compression is ineffective for some types of files, it is possible to let
+CouchDB compress only some types of attachments, specified by their MIME type::
[attachments]
compressible_types = text/*, application/javascript, application/json, application/xml
@@ -81,8 +81,8 @@ intervals (in seconds)::
.. versionchanged:: 1.3 ``utc_id`` algorithm.
-CouchDB provides various algorithms to generate UUID value that will be used
-for document `_id` by default::
+CouchDB provides various algorithms to generate the UUID values that are used
+for document `_id`'s by default::
[uuids]
algorithm = sequential
@@ -109,9 +109,9 @@ Available algorithms:
}
- ``sequential``: Monotonically increasing ids with random increments.
- First 26 hex characters are random. Last 6 increment in random amounts until
- an overflow occurs. On overflow, the random prefix is regenerated and the
- process starts over:
+ The first 26 hex characters are random, the last 6 increment in random
+ amounts until an overflow occurs. On overflow, the random prefix is
+ regenerated and the process starts over.
.. code-block:: javascript
@@ -130,8 +130,8 @@ Available algorithms:
]
}
-- ``utc_random``: Time since Jan 1, 1970 UTC with microseconds. First 14
- characters are the time in hex. Last 18 are random:
+- ``utc_random``: The time since Jan 1, 1970 UTC, in microseconds. The first
+ 14 characters are the time in hex. The last 18 are random.
.. code-block:: javascript
@@ -150,9 +150,9 @@ Available algorithms:
]
}
-- ``utc_id``: Time since Jan 1, 1970 UTC with microseconds,
- plus ``utc_id_suffix`` string. First 14 characters are the time in hex.
- :ref:`config/uuids/utc_id_suffix` string value is appended to these:
+- ``utc_id``: The time since Jan 1, 1970 UTC, in microseconds, plus
+ the ``utc_id_suffix`` string. The first 14 characters are the time in hex.
+ The :ref:`config/uuids/utc_id_suffix` string value is appended to these.
.. code-block:: javascript
@@ -171,14 +171,15 @@ Available algorithms:
]
}
-.. note:: **Impact of UUID choices:**
- The choice of UUID has a significant impact on the layout of the B-tree,
- prior to compaction.
+.. note::
- For example, a sequential UUID algorithm during uploading thousands of
- documents, will avoid the need to rewrite many intermediate B-tree nodes.
+ **Impact of UUID choices:** the choice of UUID has a significant impact on
+ the layout of the B-tree, prior to compaction.
+
+ For example, using a sequential UUID algorithm while uploading a large batch
+ of documents will avoid the need to rewrite many intermediate B-tree nodes.
A random UUID algorithm may require rewriting intermediate nodes on a regular
- basis, with a corresponding decrease of throughput, and significant wasted
+ basis, resulting in significantly decreased throughput and wasted disk space
space due to the append-only B-tree design.
It is generally recommended to set your own UUIDs, or use the sequential
@@ -193,9 +194,11 @@ UTC ID Suffix
.. versionadded:: 1.3
-The utc_id_suffix value will be appended to UUIDs generated by the ``utc_id``
-algorithm. Replicating instances should have unique utc_id_suffix values to
-ensure uniqueness of ``utc_id`` ids::
+The ``utc_id_suffix`` value will be appended to UUIDs generated by the
+``utc_id`` algorithm. Replicating instances should have unique
+``utc_id_suffix`` values to ensure uniqueness of ``utc_id`` ids.
+
+::
[uuid]
utc_id_suffix = my-awesome-suffix
@@ -208,11 +211,11 @@ ensure uniqueness of ``utc_id`` ids::
.. versionadded:: 1.3
-For CouchDB distributors there is an option to customise CouchDB's welcome
-message which is returned when requesting ``GET /``.
+CouchDB distributors have the option of customizing CouchDB's welcome
+message. This is returned when requesting ``GET /``.
+
+::
[vendor]
name = The Apache Software Foundation
version = 1.3.0
-
-