← Back to branch summary

~jderose/ubuntu/utopic/couchdb/1.6.0

« back to all changes in this revision

Viewing changes to share/doc/src/api/configuration.rst

  • Committer: Package Import Robot
  • Author(s): Jason Gerard DeRose
  • Date: 2013-08-28 16:28:32 UTC
  • mfrom: (1.3.4)
  • Revision ID: package-import@ubuntu.com-20130828162832-gp22vmgpfzhk2zyu
Tags: 1.4.0-0ubuntu1
https://launchpad.net/bugs/1212481
* New upstream release (LP: #1212481)
* Switch from CDBS to pure debhelper (compat 9)
* Bump Standards-Version to 3.9.4
* Use an Upstart job instead of the upstream SysV init.d script
* Remove Build-Depends: cdbs, libreadline-dev
* Add Build-Depends: erlang-os-mon, erlang-syntax-tools, python-sphinx,
  texlive-latex-base, texlive-latex-recommended, texlive-latex-extra,
  texlive-fonts-recommended, texinfo
* Remove couchdb-bin Depends: procps, lsb-base (needed for SysV init.d script)
* Remove couchdb-bin Depends: libjs-jquery (1.7.2 is in Saucy, but the
  internal CouchDB jquery is now at version 1.8.3)
* Simplify Erlang couchdb-bin Depends to just:
  ${erlang-abi:Depends}, ${erlang:Depends}
* Add couchdb Depends: upstart
* Remove deprecated couchdb-bin.postrm
* Thanks to the Upstart job, couchdb.postrm no longer needs `sleep 3` hack,
  nor needs to `rm -r -f "/var/run/couchdb"`
* Stop using versioned database_dir /var/lib/couchdb/VERSION as this isn't
  done upstream and CouchDB is no longer considered alpha software
* Remove README.Debian, README.source as they're no longer applicable
* Drop patches superseded upstream for CVE-2012-5649, CVE-2012-5650:
  - improve_parsing_of_mochiweb_relative_paths.patch
  - improve_script_url_validation.patch
  - include_a_comment_before_jsonp_output.patch
* Because of the switch to Upstart, drop unneeded SysV init.d script patches:
  - force-reload.patch
  - couchdb_own_rundir.patch
  - wait_for_couchdb_stop.patch
* Drop couchdb_sighup.patch, superseded upstream
* Drop logrotate_as_couchdb.patch as it doesn't make sense for the CouchDB
  daemon to be able to modify its own archived log files
* Move static data and docs in "/usr/share/couchdb" from `couchdb-bin` into
  new `couchdb-common` Architecture:all package
* Add couchdb-bin Depends: couchdb-common (= ${source:Version})
* debian/watch: point to current download location
* debian/rules: replace `get-orig-source` with `get-packaged-orig-source`

Show diffs side-by-side

added added

removed removed

Lines of Context:
share/doc/src/api/configuration.rst
 
1
.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
 
2
.. use this file except in compliance with the License. You may obtain a copy of
 
3
.. the License at
 
4
..
 
5
..   http://www.apache.org/licenses/LICENSE-2.0
 
6
..
 
7
.. Unless required by applicable law or agreed to in writing, software
 
8
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 
9
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 
10
.. License for the specific language governing permissions and limitations under
 
11
.. the License.
 
12
 
 
13
.. _api-config:
 
14
 
 
15
=====================
 
16
Configuration Methods
 
17
=====================
 
18
 
 
19
The CouchDB API Server Configuration Methods provide an interface to
 
20
query and update the various configuration values within a running
 
21
CouchDB instance.
 
22
 
 
23
A list of the available methods and URL paths are provided below:
 
24
 
 
25
+--------+-------------------------+-------------------------------------------+
 
26
| Method | Path                    | Description                               |
 
27
+========+=========================+===========================================+
 
28
| GET    | /_config                | Obtain a list of the entire server        |
 
29
|        |                         | configuration                             |
 
30
+--------+-------------------------+-------------------------------------------+
 
31
| GET    | /_config/section        | Get all the configuration values for the  |
 
32
|        |                         | specified section                         |
 
33
+--------+-------------------------+-------------------------------------------+
 
34
| GET    | /_config/section/key    | Get a specific section/configuration value|
 
35
+--------+-------------------------+-------------------------------------------+
 
36
| PUT    | /_config/section/key    | Set the specified configuration value     |
 
37
+--------+-------------------------+-------------------------------------------+
 
38
| DELETE | /_config/section/key    | Delete the current setting                |
 
39
+--------+-------------------------+-------------------------------------------+
 
40
 
 
41
``GET /_config``
 
42
================
 
43
 
 
44
* **Method**: ``GET /_config``
 
45
* **Request**: None
 
46
* **Response**: Returns a structure configuration name and value pairs,
 
47
  organized by section
 
48
* **Admin Privileges Required**: yes
 
49
* **Return Codes**:
 
50
 
 
51
  * **200**:
 
52
    Request completed successfully.
 
53
 
 
54
Returns the entire CouchDB server configuration as a JSON structure. The
 
55
structure is organized by different configuration sections, with
 
56
individual values.
 
57
 
 
58
For example, to get the configuration for a server:
 
59
 
 
60
.. code-block:: http
 
61
 
 
62
    GET http://couchdb:5984/_config
 
63
    Accept: application/json
 
64
 
 
65
The response is the JSON structure:
 
66
 
 
67
.. code-block:: javascript
 
68
 
 
69
    {
 
70
       "query_server_config" : {
 
71
          "reduce_limit" : "true"
 
72
       },
 
73
       "couchdb" : {
 
74
          "os_process_timeout" : "5000",
 
75
          "max_attachment_chunk_size" : "4294967296",
 
76
          "max_document_size" : "4294967296",
 
77
          "uri_file" : "/var/lib/couchdb/couch.uri",
 
78
          "max_dbs_open" : "100",
 
79
          "view_index_dir" : "/var/lib/couchdb",
 
80
          "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib",
 
81
          "database_dir" : "/var/lib/couchdb",
 
82
          "delayed_commits" : "true"
 
83
       },
 
84
       "attachments" : {
 
85
          "compressible_types" : "text/*, application/javascript, application/json,  application/xml",
 
86
          "compression_level" : "8"
 
87
       },
 
88
       "uuids" : {
 
89
          "algorithm" : "utc_random"
 
90
       },
 
91
       "daemons" : {
 
92
          "view_manager" : "{couch_view, start_link, []}",
 
93
          "auth_cache" : "{couch_auth_cache, start_link, []}",
 
94
          "uuids" : "{couch_uuids, start, []}",
 
95
          "stats_aggregator" : "{couch_stats_aggregator, start, []}",
 
96
          "query_servers" : "{couch_query_servers, start_link, []}",
 
97
          "httpd" : "{couch_httpd, start_link, []}",
 
98
          "stats_collector" : "{couch_stats_collector, start, []}",
 
99
          "db_update_notifier" : "{couch_db_update_notifier_sup, start_link, []}",
 
100
          "external_manager" : "{couch_external_manager, start_link, []}"
 
101
       },
 
102
       "stats" : {
 
103
          "samples" : "[0, 60, 300, 900]",
 
104
          "rate" : "1000"
 
105
       },
 
106
       "httpd" : {
 
107
          "vhost_global_handlers" : "_utils, _uuids, _session, _oauth, _users",
 
108
          "secure_rewrites" : "true",
 
109
          "authentication_handlers" : "{couch_httpd_oauth, oauth_authentication_handler},
 
110
                                       {couch_httpd_auth, cookie_authentication_handler},
 
111
                                       {couch_httpd_auth, default_authentication_handler}",
 
112
          "port" : "5984",
 
113
          "default_handler" : "{couch_httpd_db, handle_request}",
 
114
          "allow_jsonp" : "false",
 
115
          "bind_address" : "192.168.0.2",
 
116
          "max_connections" : "2048"
 
117
       },
 
118
       "query_servers" : {
 
119
          "javascript" : "/usr/bin/couchjs /usr/share/couchdb/server/main.js"
 
120
       },
 
121
       "couch_httpd_auth" : {
 
122
          "authentication_db" : "_users",
 
123
          "require_valid_user" : "false",
 
124
          "authentication_redirect" : "/_utils/session.html",
 
125
          "timeout" : "600",
 
126
          "auth_cache_size" : "50"
 
127
       },
 
128
       "httpd_db_handlers" : {
 
129
          "_design" : "{couch_httpd_db, handle_design_req}",
 
130
          "_compact" : "{couch_httpd_db, handle_compact_req}",
 
131
          "_view_cleanup" : "{couch_httpd_db, handle_view_cleanup_req}",
 
132
          "_temp_view" : "{couch_httpd_view, handle_temp_view_req}",
 
133
          "_changes" : "{couch_httpd_db, handle_changes_req}"
 
134
       },
 
135
       "replicator" : {
 
136
          "max_http_sessions" : "10",
 
137
          "max_http_pipeline_size" : "10"
 
138
       },
 
139
       "log" : {
 
140
          "include_sasl" : "true",
 
141
          "level" : "info",
 
142
          "file" : "/var/log/couchdb/couch.log"
 
143
       },
 
144
       "httpd_design_handlers" : {
 
145
          "_update" : "{couch_httpd_show, handle_doc_update_req}",
 
146
          "_show" : "{couch_httpd_show, handle_doc_show_req}",
 
147
          "_info" : "{couch_httpd_db,   handle_design_info_req}",
 
148
          "_list" : "{couch_httpd_show, handle_view_list_req}",
 
149
          "_view" : "{couch_httpd_view, handle_view_req}",
 
150
          "_rewrite" : "{couch_httpd_rewrite, handle_rewrite_req}"
 
151
       },
 
152
       "httpd_global_handlers" : {
 
153
          "_replicate" : "{couch_httpd_misc_handlers, handle_replicate_req}",
 
154
          "/" : "{couch_httpd_misc_handlers, handle_welcome_req, <<\"Welcome\">>}",
 
155
          "_config" : "{couch_httpd_misc_handlers, handle_config_req}",
 
156
          "_utils" : "{couch_httpd_misc_handlers, handle_utils_dir_req, \"/usr/share/couchdb/www\"}",
 
157
          "_active_tasks" : "{couch_httpd_misc_handlers, handle_task_status_req}",
 
158
          "_session" : "{couch_httpd_auth, handle_session_req}",
 
159
          "_log" : "{couch_httpd_misc_handlers, handle_log_req}",
 
160
          "favicon.ico" : "{couch_httpd_misc_handlers, handle_favicon_req, \"/usr/share/couchdb/www\"}",
 
161
          "_all_dbs" : "{couch_httpd_misc_handlers, handle_all_dbs_req}",
 
162
          "_oauth" : "{couch_httpd_oauth, handle_oauth_req}",
 
163
          "_restart" : "{couch_httpd_misc_handlers, handle_restart_req}",
 
164
          "_uuids" : "{couch_httpd_misc_handlers, handle_uuids_req}",
 
165
          "_stats" : "{couch_httpd_stats_handlers, handle_stats_req}"
 
166
       }
 
167
    }
 
168
        
 
169
 
 
170
``GET /_config/section``
 
171
========================
 
172
 
 
173
* **Method**: ``GET /_config/section``
 
174
* **Request**: None
 
175
* **Response**: All the configuration values within a specified section
 
176
* **Admin Privileges Required**: yes
 
177
* **Return Codes**:
 
178
 
 
179
  * **200**:
 
180
    Request completed successfully.
 
181
 
 
182
Gets the configuration structure for a single section. For example, to
 
183
retrieve the CouchDB configuration section values:
 
184
 
 
185
.. code-block:: http
 
186
 
 
187
    GET http://couchdb:5984/_config/couchdb
 
188
    Accept: application/json
 
189
 
 
190
The returned JSON contains just the configuration values for this
 
191
section:
 
192
 
 
193
.. code-block:: javascript
 
194
 
 
195
    {
 
196
       "os_process_timeout" : "5000",
 
197
       "max_attachment_chunk_size" : "4294967296",
 
198
       "max_document_size" : "4294967296",
 
199
       "uri_file" : "/var/lib/couchdb/couch.uri",
 
200
       "max_dbs_open" : "100",
 
201
       "view_index_dir" : "/var/lib/couchdb",
 
202
       "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib",
 
203
       "database_dir" : "/var/lib/couchdb",
 
204
       "delayed_commits" : "true"
 
205
    }
 
206
 
 
207
``GET /_config/section/key``
 
208
============================
 
209
 
 
210
* **Method**: ``GET /_config/section/key``
 
211
* **Request**: None
 
212
* **Response**: Value of the specified key/section
 
213
* **Admin Privileges Required**: yes
 
214
* **Return Codes**:
 
215
 
 
216
  * **200**:
 
217
    Request completed successfully.
 
218
 
 
219
Gets a single configuration value from within a specific configuration
 
220
section. For example, to obtain the current log level:
 
221
 
 
222
.. code-block:: http
 
223
 
 
224
    GET http://couchdb:5984/_config/log/level
 
225
    Accept: application/json
 
226
 
 
227
Returns the string of the log level:
 
228
 
 
229
.. code-block:: javascript
 
230
 
 
231
    "info"
 
232
 
 
233
.. note::
 
234
   The returned value will be the JSON of the value, which may be a
 
235
   string or numeric value, or an array or object. Some client
 
236
   environments may not parse simple strings or numeric values as valid JSON.
 
237
 
 
238
.. _api-put-config:
 
239
 
 
240
``PUT /_config/section/key``
 
241
============================
 
242
 
 
243
* **Method**: ``PUT /_config/section/key``
 
244
* **Request**: Value structure
 
245
* **Response**: Previous value
 
246
* **Admin Privileges Required**: yes
 
247
* **Return Codes**:
 
248
 
 
249
  * **200**:
 
250
    Configuration option updated successfully
 
251
 
 
252
  * **500**:
 
253
    Error setting configuration
 
254
 
 
255
Updates a configuration value. The new value should be supplied in the
 
256
request body in the corresponding JSON format. For example, if you are
 
257
setting a string value, you must supply a valid JSON string.
 
258
 
 
259
For example, to set the function used to generate UUIDs by the
 
260
``GET /_uuids`` API call to use the ``utc_random`` generator:
 
261
 
 
262
.. code-block:: http
 
263
 
 
264
    PUT http://couchdb:5984/_config/uuids/algorithm
 
265
    Content-Type: application/json
 
266
 
 
267
    "utc_random"
 
268
 
 
269
The return value will be empty, with the response code indicating the
 
270
success or failure of the configuration setting.
 
271
 
 
272
``DELETE /_config/section/key``
 
273
===============================
 
274
 
 
275
* **Method**: ``DELETE /_config/section/key``
 
276
* **Request**: None
 
277
* **Response**: Previous value
 
278
* **Admin Privileges Required**: yes
 
279
* **Return Codes**:
 
280
 
 
281
  * **409**:
 
282
    Supplied revision is incorrect or missing
 
283
 
 
284
Deletes a configuration value. The returned JSON will be the value of
 
285
the configuration parameter before it was deleted. For example, to
 
286
delete the UUID parameter:
 
287
 
 
288
.. code-block:: http
 
289
 
 
290
    DELETE http://couchdb:5984/_config/uuids/algorithm
 
291
    Content-Type: application/json
 
292
 
 
293
The returned value is the last configured UUID function:
 
294
 
 
295
.. code-block:: javascript
 
296
 
 
297
    "random"