Skip to content
Permalink
Browse files
Moved some options from httpd to chttpd (#659)
  • Loading branch information
jiahuili430 committed Jun 7, 2021
1 parent 6b44278 commit b782172c7a9e1614a01930986ef3962f957acf6b
Showing 14 changed files with 205 additions and 97 deletions.
@@ -578,7 +578,7 @@ specific request types are provided in the corresponding API call reference.

A document exceeds the configured :config:option:`couchdb/max_document_size`
value or the entire request exceeds the
:config:option:`httpd/max_http_request_size` value.
:config:option:`chttpd/max_http_request_size` value.

- ``415 - Unsupported Media Type``

@@ -95,7 +95,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 :config:option:`httpd/changes_timeout`
Default value is specified by :config:option:`chttpd/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
@@ -74,8 +74,8 @@ 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 the user by this token without requesting the password again. By
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>`.
<chttpd_auth/timeout>`. Also it's possible to make cookies
:config:option:`persistent <chttpd_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
@@ -290,13 +290,13 @@ This authentication method allows creation of a :ref:`userctx_object` for
remotely authenticated user. By default, the client just needs to pass specific
headers to CouchDB with related requests:

- :config:option:`X-Auth-CouchDB-UserName <couch_httpd_auth/x_auth_username>`:
- :config:option:`X-Auth-CouchDB-UserName <chttpd_auth/x_auth_username>`:
username;
- :config:option:`X-Auth-CouchDB-Roles <couch_httpd_auth/x_auth_roles>`:
- :config:option:`X-Auth-CouchDB-Roles <chttpd_auth/x_auth_roles>`:
comma-separated (``,``) list of user roles;
- :config:option:`X-Auth-CouchDB-Token <couch_httpd_auth/x_auth_token>`:
- :config:option:`X-Auth-CouchDB-Token <chttpd_auth/x_auth_token>`:
authentication token. When
:config:option:`proxy_use_secret <couch_httpd_auth/proxy_use_secret>`
:config:option:`proxy_use_secret <chttpd_auth/proxy_use_secret>`
is set (which is strongly recommended!), this header provides an HMAC of the
username to authenticate and the secret token to prevent requests from
untrusted sources. (Use the SHA1 of the username and sign with the secret)
@@ -78,20 +78,20 @@ interact with the local node's configuration.
"view_index_dir": "/var/lib/couchdb"
},
"chttpd": {
"allow_jsonp": "false",
"backlog": "512",
"bind_address": "0.0.0.0",
"port": "5984",
"require_valid_user": "false",
"socket_options": "[{sndbuf, 262144}, {nodelay, true}]",
"server_options": "[{recbuf, undefined}]"
"server_options": "[{recbuf, undefined}]",
"secure_rewrites": "true"
},
"httpd": {
"allow_jsonp": "false",
"authentication_handlers": "{couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
"bind_address": "192.168.0.2",
"max_connections": "2048",
"port": "5984",
"secure_rewrites": "true"
},
"log": {
"writer": "file",
@@ -155,13 +155,10 @@ interact with the local node's configuration.
Server: CouchDB (Erlang/OTP)

{
"allow_jsonp": "false",
"authentication_handlers": "{couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
"bind_address": "127.0.0.1",
"default_handler": "{couch_httpd_db, handle_request}",
"enable_cors": "false",
"port": "5984",
"secure_rewrites": "true"
"port": "5984"
}

.. _api/config/section/key:
@@ -106,7 +106,7 @@ Server Administrators
1.4 `PBKDF2` server-side hashed salted password support added, now as a
synchronous call for the ``_config/admins`` API.

.. _config/couch_httpd_auth:
.. _config/chttpd_auth:

Authentication Configuration
============================
@@ -130,176 +130,210 @@ Authentication Configuration
[chttpd]
require_valid_user_except_for_up = false

.. config:section:: couch_httpd_auth :: Authentication Configuration
.. config:section:: chttpd_auth :: Authentication Configuration
.. versionchanged:: 3.2 These options were moved to [chttpd_auth] section:
`authentication_redirect`, `require_valid_user`, `timeout`,
`auth_cache_size`, `allow_persistent_cookies`, `iterations`,
`min_iterations`, `max_iterations`, `secret`, `users_db_public`,
`x_auth_roles`, `x_auth_token`, `x_auth_username`,
`cookie_domain`, `same_site`.

.. config:option:: allow_persistent_cookies :: Persistent cookies
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

When set to ``true``, CouchDB will set the Max-Age and Expires attributes
on the cookie, which causes user agents (like browsers) to preserve the cookie
over restarts. ::

[couch_httpd_auth]
[chttpd_auth]
allow_persistent_cookies = true

.. config:option:: cookie_domain :: Cookie Domain
.. versionadded:: 2.1.1
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

Configures the ``domain`` attribute of the ``AuthSession`` cookie. By default the
``domain`` attribute is empty, resulting in the cookie being set on CouchDB's domain. ::

[couch_httpd_auth]
[chttpd_auth]
cookie_domain = example.com

.. config:option:: same_site :: SameSite
.. versionadded:: 3.0.0
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

When this option is set to a non-empty value, a ``SameSite`` attribute is added to
the ``AuthSession`` cookie. Valid values are ``none``, ``lax`` or ``strict``.::

[couch_httpd_auth]
[chttpd_auth]
same_site = strict

.. config:option:: auth_cache_size :: Authentication cache
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

Number of :ref:`userctx_object` to cache in memory, to reduce disk
lookups. ::

[couch_httpd_auth]
[chttpd_auth]
auth_cache_size = 50

.. config:option:: authentication_redirect :: Default redirect for authentication requests
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

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]
[chttpd_auth]
authentication_redirect = /_utils/session.html

.. config:option:: iterations :: PBKDF2 iterations count
.. versionadded:: 1.3
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

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]
[chttpd_auth]
iterations = 10000

.. config:option:: min_iterations :: Minimum PBKDF2 iterations count
.. versionadded:: 1.6
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

The minimum number of iterations allowed for passwords hashed by the
PBKDF2 algorithm. Any user with fewer iterations is forbidden. ::

[couch_httpd_auth]
[chttpd_auth]
min_iterations = 100

.. config:option:: max_iterations :: Maximum PBKDF2 iterations count
.. versionadded:: 1.6
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

The maximum number of iterations allowed for passwords hashed by the
PBKDF2 algorithm. Any user with greater iterations is forbidden. ::

[couch_httpd_auth]
[chttpd_auth]
max_iterations = 100000

.. config:option:: proxy_use_secret :: Force proxy auth to use secret token
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

When this option is set to ``true``, the
:option:`couch_httpd_auth/secret` option is required for
:option:`chttpd_auth/secret` option is required for
:ref:`api/auth/proxy`. ::

[couch_httpd_auth]
[chttpd_auth]
proxy_use_secret = false

.. config:option:: public_fields :: User documents public fields
.. versionadded:: 1.4
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

A comma-separated list of field names in user documents (in
:option:`couchdb/users_db_suffix`) that can be read by any
user. If unset or not specified, authenticated users can only retrieve
their own document. ::

[couch_httpd_auth]
[chttpd_auth]
public_fields = first_name, last_name, contacts, url

.. note::
Using the ``public_fields`` allowlist for user document properties
requires setting the :option:`couch_httpd_auth/users_db_public`
requires setting the :option:`chttpd_auth/users_db_public`
option to ``true`` (the latter option has no other purpose)::

[couch_httpd_auth]
[chttpd_auth]
users_db_public = true

.. config:option:: require_valid_user :: Force user authentication
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

When this option is set to ``true``, no requests are allowed from
anonymous users. Everyone must be authenticated. ::

[couch_httpd_auth]
[chttpd_auth]
require_valid_user = false

.. config:option:: secret :: Authentication secret token
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

The secret token is used for :ref:`api/auth/proxy` and for :ref:`api/auth/cookie`. ::

[couch_httpd_auth]
[chttpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91

.. config:option:: timeout :: Session timeout
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

Number of seconds since the last request before sessions will be
expired. ::

[couch_httpd_auth]
[chttpd_auth]
timeout = 600

.. config:option:: users_db_public :: Publish user documents
.. versionadded:: 1.4
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

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]
[chttpd_auth]
users_db_public = false

.. config:option:: x_auth_roles :: Proxy Auth roles header
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

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]
[chttpd_auth]
x_auth_roles = X-Auth-CouchDB-Roles

.. config:option:: x_auth_token :: Proxy Auth token header
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

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
`HMAC-SHA1` created from the :option:`chttpd_auth/secret` and
:option:`chttpd_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
the value of the :option:`chttpd_auth/proxy_use_secret` option is
not ``true``. Used for :ref:`api/auth/proxy`. ::

[couch_httpd_auth]
[chttpd_auth]
x_auth_token = X-Auth-CouchDB-Token

.. config:option:: x_auth_username :: Proxy Auth username header
.. versionchanged:: 3.2 moved from [couch_httpd_auth] to [chttpd_auth] section

The HTTP header name (``X-Auth-CouchDB-UserName`` by default)
containing the username. Used for :ref:`api/auth/proxy`. ::

[couch_httpd_auth]
[chttpd_auth]
x_auth_username = X-Auth-CouchDB-UserName

.. config:section:: jwt_auth :: JWT Authentication
@@ -146,7 +146,7 @@ Base CouchDB Options
http request body sizes. For individual document updates via `PUT`
that approximation was close enough, however that is not the case
for `_bulk_docs` endpoint. After 2.1.0 a separate configuration
parameter was defined: :config:option:`httpd/max_http_request_size`,
parameter was defined: :config:option:`chttpd/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.

0 comments on commit b782172

Please sign in to comment.