diff options
| -rw-r--r-- | doc/git-annex-enable-tor.mdwn | 8 | ||||
| -rw-r--r-- | doc/git-annex-p2p.mdwn | 54 | ||||
| -rw-r--r-- | doc/tips/peer_to_peer_network_with_tor.mdwn | 101 |
3 files changed, 161 insertions, 2 deletions
diff --git a/doc/git-annex-enable-tor.mdwn b/doc/git-annex-enable-tor.mdwn index ceaa4b121..9fb55db5f 100644 --- a/doc/git-annex-enable-tor.mdwn +++ b/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 diff --git a/doc/git-annex-p2p.mdwn b/doc/git-annex-p2p.mdwn new file mode 100644 index 000000000..41e1967ee --- /dev/null +++ b/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. 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/` |