[torspec/master] Document the intended use of the ‘owning controller’ features

[nickm at torproject.org]

commit b91918eeada8b029dc677c3c5aa1326a6ee2cf9b
Author: Robert Ransom <rransom.8774 at gmail.com>
Date:   Sun May 22 21:46:20 2011 -0700

    Document the intended use of the ‘owning controller’ features
---
 control-spec.txt |   40 ++++++++++++++++++++++++++++++++++++++--
 1 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index d8889a8..1d5c341 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -931,7 +931,37 @@
 
   This command instructs Tor to shut down (as if it had received
   SIGINT or a "SIGNAL INT" controller command) when this control
-  connection is closed.
+  connection is closed.  This command affects each control connection
+  that sends it independently; if multiple control connections send
+  the TAKEOWNERSHIP command to a Tor instance, Tor will shut down when
+  any of those connections closes.
+
+  This command is intended to be used with the
+  __OwningControllerProcess configuration option.  A controller that
+  starts a Tor process which the user cannot easily control or stop
+  should 'own' that Tor process:
+
+    * When starting Tor, the controller should specify its PID in an
+      __OwningControllerProcess on Tor's command line.  This will
+      cause Tor to poll for the existence of a process with that PID,
+      and exit if it does not find such a process.  (This is not a
+      completely reliable way to detect whether the 'owning
+      controller' is still running, but it should work well enough in
+      most cases.)
+
+    * Once the controller has connected to Tor's control port, it
+      should send the TAKEOWNERSHIP command along its control
+      connection.  At this point, *both* the TAKEOWNERSHIP command and
+      the __OwningControllerProcess option are in effect: Tor will
+      exit when the control connection ends *and* Tor will exit if it
+      detects that there is no process with the PID specified in the
+      __OwningControllerProcess option.
+
+    * After the controller has sent the TAKEOWNERSHIP command, it
+      should send "RESETCONF __OwningControllerProcess" along its
+      control connection.  This will cause Tor to stop polling for the
+      existence of a process with its owning controller's PID; Tor
+      will still exit when the control connection ends.
 
   [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.]
 
@@ -1908,7 +1938,13 @@
 
     If this option is set to a process ID, Tor will periodically check
     whether a process with the specified PID exists, and exit if one
-    does not.  Added in Tor 0.2.2.28-beta.
+    does not.  Added in Tor 0.2.2.28-beta.  This option's intended use
+    is documented in section 3.23 with the related TAKEOWNERSHIP
+    command.
+
+    Note that this option can only specify a single process ID, unlike
+    the TAKEOWNERSHIP command which can be sent along multiple control
+    connections.
 
     (String.  Default: unset.)