1 files changed, 101 insertions, 0 deletions
diff --git a/doc/tips/peer_to_peer_network_with_tor.mdwn b/doc/tips/peer_to_peer_network_with_tor.mdwn
new file mode 100644
index 000000000..d7461a1e4
--- /dev/null
+++ b/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/`