git-annex/doc/design/generic_p2p_transport.mdwn
2025-08-01 13:51:25 -04:00

60 lines
2.7 KiB
Markdown

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.
[[special_remotes/p2p/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 [[special_remotes/p2p]].