couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [08/32] git commit: updated refs/heads/1781-reorganize-and-improve-docs to 11fd32a
Date Fri, 14 Jun 2013 08:25:05 GMT
Use Paul J. Davis commit message as os_daemons docs.


Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: a0ea37692696a372d5569d3eb791764c32481e95
Parents: 0097a53
Author: Alexander Shorin <>
Authored: Tue Jun 11 20:49:48 2013 +0400
Committer: Alexander Shorin <>
Committed: Tue Jun 11 21:28:43 2013 +0400

 share/doc/src/config/os-daemons.rst | 80 ++++++++++++++++++++++++--------
 1 file changed, 61 insertions(+), 19 deletions(-)
diff --git a/share/doc/src/config/os-daemons.rst b/share/doc/src/config/os-daemons.rst
index ae0d500..3bde3aa 100644
--- a/share/doc/src/config/os-daemons.rst
+++ b/share/doc/src/config/os-daemons.rst
@@ -17,32 +17,74 @@
 ``[os_daemons]`` :: OS Daemons
-CouchDB now supports starting external processes. The support is simple
-and enables CouchDB to start each configured OS daemon. If the daemon
-stops at any point, CouchDB will restart it (with protection to ensure
-regularly failing daemons are not repeatedly restarted).
+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 adjustable.
-The daemon starting process is one-to-one; for each each configured
-daemon in the configuration file, CouchDB will start exactly one
-instance. If you need to run multiple instances, then you must create
-separate individual configurations. Daemons are configured within the
-``[os_daemons]`` section of your configuration file (``local.ini``). The
-format of each configured daemon is:
+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.
-.. code-block:: ini
+To configure an OS process as a CouchDB os_daemon, create a section
+in your `local.ini` like such::
+  [os_daemons]
+  daemon_name = /path/to/command -with args
-Where ``NAME`` is an arbitrary (and unique) name to identify the daemon;
-``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any
-required arguments to the daemon.
+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::
-For example:
+  ["get", "os_daemons"]\n
-.. code-block:: ini
+which would return::
-    [os_daemons]
-    basic_responder = /usr/local/bin/responder.js
+  {"daemon_name": "/path/to/command -with args"}\n
+  ["get", "os_daemons", "daemon_name"]\n
+which would return::
+  "/path/to/command -with args"\n
+There's no restriction on what configuration variables are visible.
+There's also no method for altering the configuration.
+If you would like your OS daemon to be restarted in the event that
+the configuration changes, you can send the following messages::
+  ["register", $(SECTION)]\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
+  ["register", $(SECTION), $(KEY)]\n
+In this case, CouchDB will only restart your daemon if that exact
+section/key pair changes, instead of anything in that entire section.
+Logging commands look like::
+  ["log", $(JSON_MESSAGE)]\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::
+  ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n
+Where ``$(LEVEL)`` is one of "debug", "info", or "error".
+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.
 There is no interactivity between CouchDB and the running process, but
 you can use the OS Daemons service to create new HTTP servers and

View raw message