docs for stuff not fully implemented yet

doc/git-annex-enable-tor.mdwn

@@ -10,17 +10,21 @@ git annex enable-tor userid uuid
 
 This plumbing-level command enables a tor hidden service for git-annex,
 using the specified repository uuid and userid. 
-It outputs the address of the hidden service to stdout.
 
 This command has to be run by root, since it modifies `/etc/tor/torrc`.
 
 After this command is run, `git annex remotedaemon` can be run to serve the
-hidden service.
+tor hidden service.
+
+Use the `git-annex p2p --gen-address` command to give other users access
+to your repository via the tor hidden service.
 
 # SEE ALSO
 
 [[git-annex]](1)
 
+[[git-annex-p2p-auth]](1)
+
 [[git-annex-remotedaemon]](1)
 
 # AUTHOR

doc/git-annex-p2p.mdwn

@@ -0,0 +1,54 @@
+# NAME
+
+git-annex p2p - manage peer-to-peer connections
+
+# SYNOPSIS
+
+git annex p2p [options]
+
+# DESCRIPTION
+
+When using git-annex with peer-to-peer communication, this manages
+connections between the peers.
+
+Currently, git-annex supports peer-to-peer communication over Tor.
+
+# OPTIONS
+
+* `--gen-address [name]`
+
+  Generates one or more addresses, which allow whoever knows them to access
+  your repository. The addresses are output on standard output, one per
+  supported P2P network.
+
+  You can re-run this command repeatedly to generate as many addresses
+  as you like.
+
+  The name is an optional parameter, the name of the person or device you
+  intend to give this address to. Providig it makes it easier to use
+  `--remove-address`
+
+* `--link-remote name address`
+
+  Link the local repository to a remote repository. This sets up a git remote
+  with the specified name. The address is one generated by `--gen-address`
+  run on the remote repository.
+
+* `--remove-address [address|name]`
+
+  If you've given out an address to someone, and don't want to accept
+  connections from them anymore, this can be used to remove it.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-enable-tor]](1)
+
+[[git-annex-remotedaemon]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.

doc/tips/peer_to_peer_network_with_tor.mdwn

@@ -0,0 +1,101 @@
+git-annex has recently gotten support for running as a
+[Tor](http://http://torproject.org/) hidden service. This is a great, and
+very secure way to connect repositories between computers in different
+locations, without needing any central server.
+
+## the first peer
+
+First, you need to get Tor installed and running. See
+[their website](http://http://torproject.org/), or try a command like:
+
+	sudo apt-get install tor
+
+To make git-annex use Tor, run these commands in your git-annex repository:
+
+	sudo git annex enable-tor
+	git annex remotedaemon
+	git annex p2p --gen-address
+
+The p2p-auth command will output a long address, such as:
+
+	tor-annex::eeaytkuhaupbarfi.onion:4412:7f53c5b65b8957ef626fd461ceaae8056e3dbc459ae715e4
+
+At this point, git-annex is running as a tor hidden service, but
+it will only talk to peers who know that address.
+
+## adding additional peers
+
+To add a peer, get tor installed and running on it.
+
+	sudo apt-get install tor
+
+You need a git-annex repository on the new peer. It's fine to start
+with a new empty repository:
+
+	git init annex
+	cd annex
+	git annex init
+
+And make git-annex use Tor, by running these commands in the git-annex
+repository:
+
+	sudo git annex enable-tor
+	git annex remotedaemon
+
+Now, tell the new peer about the address of the first peer:
+
+	git annex p2p --link-remote peer1 tor-annnex::eeaytkuhaupbarfi.onion:4412:7f53c5b65b8957ef626fd461ceaae8056e3dbc459ae715e4
+
+(Of course, you should paste in the address you generated earlier, 
+not the example one shown above.)
+
+Now this git-annex repository will have a remote named "peer1"
+which connects, through Tor, to the repository on the other peer.
+You can run any commands you normally would to sync with that remote:
+
+	git annex sync --content peer1
+
+You can also generate an address for this new peer, by running
+`git annex p2p --gen`, and add that address to other peers using `git annex
+p2p --link-remote`. It's often useful to link peers up in both directions,
+so peer1 is a remote of peer2 and peer2 is a remote of peer1.
+
+Any number of peers can be connected this way, within reason.
+
+## git-annex remotedaemon
+
+Notice the `git annex remotedaemon` being run in the above examples.
+That command runs the Tor hidden service so that other peers
+can connect to your repository over Tor.
+
+So, you may want to arrange for the remotedaemon to be started on boot.
+You can do that with a simple cron job:
+
+	@reboot cd myannexrepo && git annex remotedaemon
+
+If you use the git-annex assistant, and have it auto-starting on boot, it
+will take care of starting the remotedaemon for you.
+
+## onion addresses and authentication
+
+You don't need to know about this, but it might be helpful to understand
+how it works.
+
+git-annex's Tor support uses onion address as the address of a git remote.
+You can `git pull`, push, etc with those onion addresses:
+
+	git pull tor-annnex::eeaytkuhaupbarfi.onion:4412
+	git remote add peer1 tor-annnex::eeaytkuhaupbarfi.onion:4412
+
+Onion addresses are semi-public. When you add a remote, they appear in your
+`.git/config` file. So, there's a second level of authentication that
+git-annex uses to make sure that only people you want to can access your
+repository over Tor. That takes the form of a long string of numbers and
+letters, like "7f53c5b65b8957ef626fd461ceaae8056e3dbc459ae715e4".
+
+The addresses generated by `git annex peer --gen-address` 
+combine the onion address with the authentication data.
+
+When you run `git annex peer --link-remote`, it sets up a git remote using
+the onion address, and it stashes the authentication data away in a file in
+`.git/annex/creds/`