remotedaemon: Fork to background by default. Added --foreground switch to enable old behavior.

Groundwork for tor hidden services, which the remotedaemon will serve.

1 files changed, 31 insertions, 10 deletions

diff --git a/doc/git-annex-remotedaemon.mdwn b/doc/git-annex-remotedaemon.mdwn
index 69b516283..71dd32d30 100644
--- a/doc/git-annex-remotedaemon.mdwn
+++ b/doc/git-annex-remotedaemon.mdwn
@@ -1,6 +1,6 @@
 # NAME
 
-git-annex remotedaemon - detects when remotes have changed, and fetches from them
+git-annex remotedaemon - persistent communication with remotes
 
 # SYNOPSIS
 
@@ -8,18 +8,37 @@ git annex remotedaemon
 
 # DESCRIPTION
 
-This plumbing-level command is used by the assistant to detect
-when remotes have received git pushes, so the changes can be promptly
-fetched and the local repository updated.
+The remotedaemon provides persistent communication with remotes.
+This is useful to detect when remotes have received git pushes, so the
+changes can be promptly fetched and the local repository updated.
 
-This is a better alternative to the [[git-annex-xmppgit]](1)
-hack.
+The assistant runs the remotedaemon and communicates with it on
+stdio using a simple textual protocol.
 
-For the remotedaemon to work, the git remote must have
-[[git-annex-shell]](1) installed, with notifychanges support.
-The first version of git-annex-shell that supports it is 5.20140405.
+Several types of remotes are supported:
 
-It's normal for this process to be running when the assistant is running.
+For ssh remotes, the remotedaemon tries to maintain a connection to the
+remote git repository, and uses git-annex-shell notifychanges to detect
+when the remote git repository has changed, and fetch the changes from
+it. For this to work, the git remote must have [[git-annex-shell]](1)
+installed, with notifychanges support. The first version of git-annex-shell
+that supports it is 5.20140405.
+
+For tor-annex remotes, the remotedaemon runs as a tor hidden service,
+accepting connections from other nodes and serving up the contents of the
+repository. This is only done if you first run `git annex enable-tor`.
+
+# OPTIONS
+
+* `--foreground`
+
+Don't fork to the background, and communicate on stdin/stdout using a
+simple textual protocol. The assistant runs the remotedaemon this way.
+
+Commands in the protocol include LOSTNET, which tells the remotedaemon
+that the network connection has been lost, and causes it to stop any TCP
+connctions. That can be followed by RESUME when the network connection
+comes back up.
 
 # SEE ALSO
 
@@ -27,6 +46,8 @@ It's normal for this process to be running when the assistant is running.
 
 [[git-annex-assistant]](1)
 
+[[git-annex-enable-tor]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>