commit b91918eeada8b029dc677c3c5aa1326a6ee2cf9b
Author: Robert Ransom <rransom.8774(a)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.)