git-annex/ design/ generic p2p transport

This is a generic interface that allows git-annex to use a P2P network. The P2P protocol is used, to allow accessing a peer's git-annex repository as a git remote.

Examples of such networks are tor, yggstack or fowl. (git-annex has a built-in integration with tor which does not use this interface.)

Such a P2P network has some form of address, which can be used to connect to a given peer by address across the network.

A git remote using the P2P network has an url of the form `p2p-annex::<netname>:<address>`

The program git-remote-p2p-annex is included in git-annex as a git remote helper program. git will use that program to handle `pull` and `push` with git remotes that use the `p2p-annex::` url scheme.

## program interface

To connect to a P2P remote, git-annex runs the command `git-annex-p2p-<netname>`, giving it the P2P network address as its only parameter. The command is responsible for connecting to that peer, and relaying data to it. Data fed into the command on stdin should be sent to the peer, and data received from the peer should be output to stdout. If it is unable to connect, the command can exit nonzero. When the peer closes connection, the command can exit zero.

To configure `git-annex remotedaemon` to listen on a given P2P network, the user runs `git-annex p2p --enable <netname>`. That also runs `git-annex-p2p-<netname>`, this time with the parameter "address". That should output one or more lines, the P2P network address (or addresses) that can be used by peers to connect to the repository. It can first do whatever it needs to do to set up the P2P network.

To handle incoming connections from peers, `git-annex remotedaemon` runs `git-annex-p2p-<netname>`, with two parameters. The first parameter is the P2P address of the local repository, obtained earlier as described above. The second parameter is the path to a unix socket file, which git-annex will have already created. git-annex listens for connections from peers that are made to the socket, and services them.

Note that, if the P2P network does not natively use a unix socket file, a command like `socat` can be run by `git-annex-p2p-<netname> socket` to convert the P2P network's own equivilant into a unix socket file.

## example

Here's a simple shell script example. While this avoids using any real P2P network and dummys it up by symlinking unix socket files together, its skeleton should be a good starting point.

git-annex-p2p-unix-sockets

## security

This is only as secure as the underlying P2P network. It is really designed with P2P networks in mind that are fully encrypted, and that use cryptography to validate the identities of peers.

See the security discussion on p2p.

Comments on this page are closed.