This is an automated email from the ASF dual-hosted git repository. wohali pushed a commit to branch update-couchdb-defaults in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit 3611856368e1d0c89befac782eb8771343db7cde Author: Joan Touzet <[email protected]> AuthorDate: Tue Jan 28 13:48:55 2020 -0500 Incorporate new config default settings --- src/api/database/compact.rst | 2 ++ src/cluster/sharding.rst | 28 +++++++++++++++------------- src/cluster/theory.rst | 10 +++++----- src/config/auth.rst | 13 ++++++++++++- src/config/cluster.rst | 10 +++++----- src/config/couchdb.rst | 30 ++++++++++++++++++++++++++---- src/config/logging.rst | 2 ++ src/config/misc.rst | 37 +++++++++++++++++++++++++++++++++++++ src/whatsnew/3.0.rst | 3 +++ 9 files changed, 107 insertions(+), 28 deletions(-) diff --git a/src/api/database/compact.rst b/src/api/database/compact.rst index 4aa8811..5297183 100644 --- a/src/api/database/compact.rst +++ b/src/api/database/compact.rst @@ -149,6 +149,8 @@ :synopsis: Deprecated endpoint to support CouchDB versions < 3.0 replicators. + .. versionchanged:: 3.0.0 Deprecated; endpoint is a no-op. + Before 3.0 this was used to commit recent changes to the database in case the ``delayed_commits=true`` option was set. That option is always ``false`` now, so commits are never delayed. However, this endpoint is kept diff --git a/src/cluster/sharding.rst b/src/cluster/sharding.rst index b5cdec3..8eac181 100644 --- a/src/cluster/sharding.rst +++ b/src/cluster/sharding.rst @@ -44,33 +44,35 @@ level, or on a per-database basis. The relevant parameters are ``q`` and *q* is the number of database shards to maintain. *n* is the number of copies of each document to distribute. The default value for ``n`` is ``3``, -and for ``q`` is ``8``. With ``q=8``, the database is split into 8 shards. With +and for ``q`` is ``2``. With ``q=2``, the database is split into 2 shards. With ``n=3``, the cluster distributes three replicas of each shard. Altogether, -that's 24 shard replicas for a single database. In a default 3-node cluster, -each node would receive 8 shards. In a 4-node cluster, each node would -receive 6 shards. We recommend in the general case that the number of -nodes in your cluster should be a multiple of ``n``, so that shards are -distributed evenly. +that's 6 shard replicas for a single database. -CouchDB nodes have a ``etc/local.ini`` file with a section named +In a 3-node cluster with ``q=8``, each node would receive 8 shards. In a 4-node +cluster, each node would receive 6 shards. We recommend in the general case +that the number of nodes in your cluster should be a multiple of ``n``, so that +shards are distributed evenly. + +CouchDB nodes have a ``etc/default.ini`` file with a section named `cluster <../config/cluster.html>`__ which looks like this: :: [cluster] - q=8 + q=2 n=3 -These settings can be modified to set sharding defaults for all -databases, or they can be set on a per-database basis by specifying the -``q`` and ``n`` query parameters when the database is created. For -example: +These settings specify the default sharding parameters for newly created +databases. These can be overridden in the ``etc/local.ini`` file by copying the +text above, and replacing the values with your new defaults. The values can +also be set on a per-database basis by specifying the ``q`` and ``n`` query +parameters when the database is created. For example: .. code-block:: bash $ curl -X PUT "$COUCH_URL:5984/database-name?q=4&n=2" -That creates a database that is split into 4 shards and 2 replicas, +This creates a database that is split into 4 shards and 2 replicas, yielding 8 shard replicas distributed throughout the cluster. Quorum diff --git a/src/cluster/theory.rst b/src/cluster/theory.rst index ca54d6b..bbe9f43 100644 --- a/src/cluster/theory.rst +++ b/src/cluster/theory.rst @@ -23,7 +23,7 @@ As you see in ``etc/default.ini`` there is a section called [cluster] .. code-block:: text [cluster] - q=8 + q=2 n=3 * ``q`` - The number of shards. @@ -55,10 +55,10 @@ copies of a shard, the more you can scale out. If you have 4 replicas, that means that all 4 copies of this specific shard will live on at most 4 nodes. With one replica you can have only one node, just as with CouchDB 1.x. No node can have more than one copy of each shard replica. The default for -CouchDB since 2.0.0 is ``q=8`` and ``n=3``, meaning each database (and secondary -index) is split into 8 shards, with 3 replicas per shard, for a total of 24 +CouchDB since 3.0.0 is ``q=2`` and ``n=3``, meaning each database (and secondary +index) is split into 2 shards, with 3 replicas per shard, for a total of 6 shard replica files. For a CouchDB cluster only hosting a single database with -these default values, a maximum of 24 nodes can be used to scale horizontally. +these default values, a maximum of 6 nodes can be used to scale horizontally. Replicas add failure resistance, as some nodes can be offline without everything crashing down. @@ -74,7 +74,7 @@ of ``n`` adds servers and complexity without any real benefit. The sweet spot is at ``n=3``. Say that we have a database with 3 replicas and 4 shards. That would give us a -maximum of 12 nodes. 4*3=12 Every shard have 3 copies. +maximum of 12 nodes: 4*3=12. We can lose any 2 nodes and still read and write all documents. diff --git a/src/config/auth.rst b/src/config/auth.rst index 5dad23a..3efccda 100644 --- a/src/config/auth.rst +++ b/src/config/auth.rst @@ -124,6 +124,17 @@ Authentication Configuration To make the same change for the node-local port (5986 by default), set the ``[couch_httpd_auth]`` setting of the same name. + .. config:option:: require_valid_user_except_for_up :: Force user auth (mostly) + + When this option is set to ``true``, no requests are allowed from + anonymous users, *except* for the ``/_up`` endpoint. Everyone else must + be authenticated. :: + + [chttpd] + require_valid_user_except_for_up = false + + + .. config:section:: couch_httpd_auth :: Authentication Configuration .. config:option:: allow_persistent_cookies :: Persistent cookies @@ -132,7 +143,7 @@ Authentication Configuration the session is nearing expiration. :: [couch_httpd_auth] - allow_persistent_cookies = false + allow_persistent_cookies = true .. config:option:: cookie_domain :: Cookie Domain diff --git a/src/config/cluster.rst b/src/config/cluster.rst index 15ceaf7..e0772b3 100644 --- a/src/config/cluster.rst +++ b/src/config/cluster.rst @@ -27,14 +27,14 @@ Cluster Options .. config:option:: q Sets the default number of shards for newly created databases. The - default value, ``8``, splits a database into 8 separate partitions. :: + default value, ``2``, splits a database into 2 separate partitions. :: [cluster] - q = 8 + q = 2 - For systems with lots of small, infrequently accessed databases, or - for servers with fewer CPU cores, consider reducing this value to - ``1`` or ``2``. + For systems with only a few, heavily accessed, large databases, or + for servers with many CPU cores, consider increasing this value to + ``4`` or ``8``. The value of ``q`` can also be overridden on a per-DB basis, at DB creation time. diff --git a/src/config/couchdb.rst b/src/config/couchdb.rst index 67061c0..3acfd5b 100644 --- a/src/config/couchdb.rst +++ b/src/config/couchdb.rst @@ -45,10 +45,16 @@ Base CouchDB Options .. config:option:: default_security :: Default security - Default security object for databases if not explicitly set. When set to ``everyone``, anyone can performs reads and writes. When set to ``admin_only``, only admins can read and write. When set to ``admin_local``, sharded databases can be read and written by anyone but the shards can only be read and written by admins. + .. versionchanged:: 3.0 ``admin_only`` is now the default. + + Default security object for databases if not explicitly set. When set + to ``everyone``, anyone can performs reads and writes. When set to + ``admin_only``, only admins can read and write. When set to + ``admin_local``, sharded databases can be read and written by anyone + but the shards can only be read and written by admins. [couchdb] - default_security = admin_local + default_security = admin_only .. config:option:: file_compression :: Compression method for documents @@ -169,7 +175,7 @@ Base CouchDB Options .. config:option:: max_document_size :: Limit maximum document body size - .. versionchanged:: 2.1.0 + .. versionchanged:: 3.0.0 Limit maximum document body size. Size is calculated based on the serialized Erlang representation of the JSON document body, because @@ -184,7 +190,7 @@ Base CouchDB Options transformation and right before being inserted into the database. :: [couchdb] - max_document_size = 4294967296 ; 4 GB + max_document_size = 8000000 ; bytes .. warning:: Before version 2.1.0 this setting was implemented by simply checking @@ -194,3 +200,19 @@ Base CouchDB Options parameter was defined: :config:option:`httpd/max_http_request_size`, which can be used to limit maximum http request sizes. After upgrade, it is advisable to review those settings and adjust them accordingly. + + .. config:option:: single_node :: Start in single node mode. + + .. versionadded:: 3.0.0 + + When this configuration setting is set to ``true``, automatically + create the system databases on startup. Must be set ``false`` for a + clustered CouchDB installation. + + .. config:option:: users_db_security_editable :: Protect ``_users`` DB security obj + .. versionadded:: 3.0.0 + + When this configuration setting is set to ``false``, reject any attempts + to modify the ``_users`` database security object. Modification of this + object is deprecated in 3.x and will be completely disallowed in CouchDB + 4.x. diff --git a/src/config/logging.rst b/src/config/logging.rst index e1ae6d1..d9aae6a 100644 --- a/src/config/logging.rst +++ b/src/config/logging.rst @@ -34,6 +34,8 @@ Logging options - ``file``: Logs are sent to the file set in :option:`log file <log/file>`. - ``syslog``: Logs are sent to the syslog daemon. + - ``journald``: Logs are sent to stderr without timestamp and log + levels compatible with sd-daemon. You can also specify a full module name here if implement your own writer:: diff --git a/src/config/misc.rst b/src/config/misc.rst index 78e733c..60bfc75 100644 --- a/src/config/misc.rst +++ b/src/config/misc.rst @@ -233,3 +233,40 @@ Content-Security-Policy [csp] header_value = default-src 'self'; img-src *; font-src *; + +.. _config/purge: + +Configuration of Database Purge +=============================== + +.. config:section:: purge :: Configuration of Database Purge + + .. config:option:: max_document_id_number + + .. versionadded:: 3.0 + + Sets the maximum number of documents allowed in a single purge request:: + + [purge] + max_document_id_number = 100 + + .. config:option:: max_revisions_number + + .. versionadded:: 3.0 + + Sets the maximum number of accumulated revisions allowed in a single purge + request:: + + [purge] + max_revisions_number = 1000 + + .. config:option:: index_lag_warn_seconds + + .. versionadded:: 3.0 + + Sets the allowed duration when index is not updated for local purge checkpoint + document. Default is 24 hours:: + + [purge] + index_lag_warn_seconds = 86400 + diff --git a/src/whatsnew/3.0.rst b/src/whatsnew/3.0.rst index c7f9cf7..7414e8f 100644 --- a/src/whatsnew/3.0.rst +++ b/src/whatsnew/3.0.rst @@ -99,6 +99,9 @@ Upgrade Notes the ``query_limit`` and ``partition_query_limit`` values in the ini file ``[query_server_config]`` section. +* After upgrading all nodes in a cluster to 3.0, add ``[rexi] use_kill_all = true`` to + ``local.ini`` to save some intra-cluster network bandwidth. + Deprecated feature removal --------------------------
