197 lines
6 KiB
Markdown
197 lines
6 KiB
Markdown
# NAME
|
|
|
|
git-annex-p2phttp - HTTP server for the git-annex API
|
|
|
|
# SYNOPSIS
|
|
|
|
git-annex p2phttp
|
|
|
|
# DESCRIPTION
|
|
|
|
This is a HTTP server for the git-annex API.
|
|
It is the git-annex equivilant of git-http-backend(1), for serving
|
|
a repository over HTTP with write access for authenticated users.
|
|
|
|
This does not serve a git repository over HTTP, only the git-annex
|
|
API.
|
|
|
|
By default, this serves the git-annex API for the git-annex repository
|
|
in the current working directory. It can also serve more than one
|
|
repository, see the `--directory` parameter.
|
|
|
|
Typically a remote will have `remote.name.url` set to a http url
|
|
as usual, and `remote.name.annexUrl` set to an annex+http url such as
|
|
"annex+http://example.com/git-annex/". The annex+http url is
|
|
served by this server, and uses port 9417 by default.
|
|
|
|
Note that, when `remote.name.url` and `remote.name.annexUrl`
|
|
contain the same hostname, they are assumed by git-annex to
|
|
support the same users and passwords. So, git-annex will use
|
|
the password for the `remote.name.url` to log into the
|
|
`remote.name.annexUrl`.
|
|
|
|
As well as serving the git-annex HTTP API, this server provides a
|
|
convenient way to download the content of any key, by using the path
|
|
"/git-annex/$uuid/$key". For example:
|
|
|
|
$ curl http://example.com:9417/git-annex/f11773f0-11e1-45b2-9805-06db16768efe/key/SHA256E-s6--5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
|
|
hello
|
|
|
|
# OPTIONS
|
|
|
|
* `--directory=path`
|
|
|
|
Serve each git-annex repository found in a directory. This does not
|
|
recurse into subdirectories.
|
|
|
|
This option can be provided more than once to serve serveral directories
|
|
full of git-annex repositories.
|
|
|
|
New git-annex repositories can be added to the directory, and will be
|
|
noticed and served immediately. There is no need to restart the server.
|
|
|
|
When a git-annex repository is removed from the directory, the server
|
|
will stop serving it as well. This may not be immediate, as some files
|
|
in the deleted repository may still be open.
|
|
|
|
* `--jobs=N` `-JN`
|
|
|
|
This or annex.jobs must be set to configure the number of worker
|
|
threads, per repository served, that serve connections to the webserver.
|
|
|
|
Since the webserver itself also uses one of these threads,
|
|
this needs to be set to 2 or more.
|
|
|
|
A good choice is often one worker per CPU core: `--jobs=cpus`
|
|
|
|
* `--proxyconnections=N`
|
|
|
|
When serving a repository that is configured to act as a proxy for some
|
|
of its remotes, this is the maximum number of idle connections to keep
|
|
open to proxied remotes.
|
|
|
|
The default is 1.
|
|
|
|
* `--clusterjobs=N`
|
|
|
|
When serving a repository that is a gateway for a cluster,
|
|
this is the number of concurrent jobs to use to access nodes of the
|
|
cluster, per connection to the webserver.
|
|
|
|
The default is 1.
|
|
|
|
A good choice for this will be a balance between the number of nodes
|
|
in the cluster and the value of `--jobs`.
|
|
|
|
For example, if the cluster has 4 nodes, and `--jobs=4`, using
|
|
`--clusterjobs=4` will make all nodes in the cluster be accessed
|
|
concurrently, which is often optimal. But around 20 cores can be needed
|
|
when the webserver is busy.
|
|
|
|
* `--port=N`
|
|
|
|
Port to listen on. The default is port 9417, which is the default
|
|
port used for an annex+http or annex+https url.
|
|
|
|
It is not recommended to run this command as root in order to
|
|
use a low port like port 80. It will not drop permissions when run as
|
|
root.
|
|
|
|
* `--bind=address`
|
|
|
|
What address to bind to. The default is to bind to all addresses.
|
|
|
|
* `--certfile=filename`
|
|
|
|
TLS certificate file to use. Combining this with `--privatekeyfile`
|
|
makes the server use HTTPS.
|
|
|
|
* `--privatekeyfile=filename`
|
|
|
|
TLS private key file to use. Combining this with `--certfile`
|
|
makes the server use HTTPS.
|
|
|
|
* `--chainfile=filename`
|
|
|
|
TLS chain file to use. This option can be repeated any number of times.
|
|
|
|
* `--authenv`
|
|
|
|
Allows users to be authenticated with a username and password.
|
|
For security, this only allows authentication when the user connects over
|
|
HTTPS.
|
|
|
|
To configure the passwords, set environment variables
|
|
like `GIT_ANNEX_P2PHTTP_PASSWORD_alice=foo123`
|
|
|
|
The permissions of users can also be configured by setting
|
|
environment variables like
|
|
`GIT_ANNEX_P2PHTTP_PERMISSIONS_alice=readonly`. The value
|
|
can be either "readonly" or "appendonly". When this is not set,
|
|
the default is to give the user full read+write+remove access.
|
|
|
|
* `--authenv-http`
|
|
|
|
Like `--authenv`, but allows authentication when the user connects
|
|
over HTTP. This is not secure, since HTTP basic authentication is not
|
|
encrypted.
|
|
|
|
* `--unauth-readonly`
|
|
|
|
Allows unauthenticated users to read the repository, but not make
|
|
modifications to it.
|
|
|
|
This can be combined with `--authenv` or `--authenv-http` to allow
|
|
anonymous readonly access, and authenticated write access.
|
|
|
|
* `--unauth-appendonly`
|
|
|
|
Allows unauthenticated users to read the repository, and store data in
|
|
it, but not remove data from it.
|
|
|
|
This can be combined with `--authenv` or `--authenv-http` to allow
|
|
anonymous appendonly access, and authenticated remove access.
|
|
|
|
* `--unauth-nolocking`
|
|
|
|
By default, when `--unauth-readonly` or `--unauth-appendonly` is used,
|
|
unauthenticated users are allowed to lock content in the repository.
|
|
This option prevents that.
|
|
|
|
Locking content prevents it from being dropped from the repository
|
|
so it may be that an unauthenticated user abuses that, and this option
|
|
can be used in such a situation.
|
|
|
|
Note that enabling this option will prevent unauthenticated users from
|
|
dropping content from their other remotes in some cases.
|
|
|
|
* `--wideopen`
|
|
|
|
Gives unauthenticated users full read+write+remove access to the
|
|
repository.
|
|
|
|
Please think carefully before enabling this option.
|
|
|
|
# SEE ALSO
|
|
|
|
[[git-annex]](1)
|
|
|
|
git-http-backend(1)
|
|
|
|
[[git-annex-shell]](1)
|
|
|
|
[[git-annex-updateproxy]](1)
|
|
|
|
[[git-annex-initcluster]](1)
|
|
|
|
[[git-annex-updatecluster]](1)
|
|
|
|
<https://git-annex.branchable.com/design/p2p_protocol_over_http/>
|
|
|
|
# AUTHOR
|
|
|
|
Joey Hess <id@joeyh.name>
|
|
|
|
<http://git-annex.branchable.com/>
|
|
|
|
Warning: Automatically converted into a man page by mdwn2man. Edit with care
|