1 files changed, 132 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..718a9218d
--- /dev/null
+++ b/doc/tips/peer_to_peer_network_with_tor.mdwn
@@ -0,0 +1,132 @@
+git-annex has recently gotten support for running as a
+[Tor](http://http://torproject.org/) hidden service. This is a nice secure
+and easy to use way to connect repositories between peers in different
+locations, without needing any central server.
+
+## setting up 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 $(id -u)
+	git annex remotedaemon
+	git annex p2p --gen-addresses
+
+The p2p 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 $(id -u)
+	git annex remotedaemon
+
+Now, tell the new peer about the address of the first peer.
+This will make a git remote named "peer1", which connects,
+through Tor, to the repository on the other peer.
+
+	git annex p2p --link peer1
+
+That command will prompt for an address; paste in the address that was
+generated on the first peer, and then press Enter.
+
+Now you can run any commands you normally would to sync with the
+peer1 remote:
+
+	git annex sync --content peer1
+
+You can also generate an address for this new peer, by running `git annex
+p2p --gen-addresses`, and link other peers to that address using `git annex
+p2p --link`. 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. For security, 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-addresses` 
+combine the onion address with the authentication data.
+
+When you run `git annex peer --link`, it sets up a git remote using
+the onion address, and it stashes the authentication data away in a file in
+`.git/annex/creds/`
+
+## security
+
+Tor hidden services can be quite secure. But this doesn't mean that using
+git-annex over Tor is automatically perfectly secure. Here are some things
+to consider:
+
+* Anyone who learns the address of a peer can connect to that peer,
+  download the whole history of the git repository, and any available
+  annexed files. They can also upload new files to the peer, and even
+  remove annexed files from the peer. So consider ways that the address
+  of a peer might be exposed.
+
+* While Tor can be used to anonymize who you are, git defaults to including
+  your name and email address in git commit messages. So if you want an
+  anonymous git-annex repository, you'll need to configure git not to do
+  that.
+
+* Using Tor prevents listeners from decrypting your traffic. But, they'll
+  probably still know you're using Tor. Also, by traffic analysis,
+  they may be able to guess if you're using git-annex over tor, and even
+  make guesses about the sizes and types of files that you're exchanging
+  with peers.
+
+* There have been past attacks on the Tor network that have exposed
+  who was running Tor hidden services.
+  <https://blog.torproject.org/blog/tor-security-advisory-relay-early-traffic-confirmation-attack>
+
+* An attacker who can connect to the git-annex Tor hidden service, even
+  without authenticating, can try to perform denial of service attacks.