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/`