# 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 the git repository over HTTP, only the git-annex
API.

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/$uuid`. The annex+http url is
served by this server, and uses port 9417 by default.

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

* `--jobs=N` `-JN`

  This or annex.jobs must be set to configure the number of worker
  threads.
  
  Since the webserver itself uses one thread, this needs to be set to
  2 or more.

  A good choice is one worker per CPU core: `--jobs=cpus`

* `--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.

* `--unauth-appendonly`

  Allows unauthenticated users to read the repository, and store data in
  it, but not remove data from it.

* `--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)

<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