60 lines
2.7 KiB
Markdown
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]].
|