| '\" t |
| .\" Title: git-daemon |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 11/21/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0.rc1 |
| .\" Language: English |
| .\" |
| .TH "GIT\-DAEMON" "1" "11/21/2018" "Git 2\&.20\&.0\&.rc1" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-daemon \- A really simple server for Git repositories |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit daemon\fR [\-\-verbose] [\-\-syslog] [\-\-export\-all] |
| [\-\-timeout=<n>] [\-\-init\-timeout=<n>] [\-\-max\-connections=<n>] |
| [\-\-strict\-paths] [\-\-base\-path=<path>] [\-\-base\-path\-relaxed] |
| [\-\-user\-path | \-\-user\-path=<path>] |
| [\-\-interpolated\-path=<pathtemplate>] |
| [\-\-reuseaddr] [\-\-detach] [\-\-pid\-file=<file>] |
| [\-\-enable=<service>] [\-\-disable=<service>] |
| [\-\-allow\-override=<service>] [\-\-forbid\-override=<service>] |
| [\-\-access\-hook=<path>] [\-\-[no\-]informative\-errors] |
| [\-\-inetd | |
| [\-\-listen=<host_or_ipaddr>] [\-\-port=<n>] |
| [\-\-user=<user> [\-\-group=<group>]]] |
| [\-\-log\-destination=(stderr|syslog|none)] |
| [<directory>\&...] |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" aka 9418\&. It waits for a connection asking for a service, and will serve that service if it is enabled\&. |
| .sp |
| It verifies that the directory has the magic file "git\-daemon\-export\-ok", and it will refuse to export any Git directory that hasn\(cqt explicitly been marked for export this way (unless the \fB\-\-export\-all\fR parameter is specified)\&. If you pass some directory paths as \fIgit daemon\fR arguments, you can further restrict the offers to a whitelist comprising of those\&. |
| .sp |
| By default, only \fBupload\-pack\fR service is enabled, which serves \fIgit fetch\-pack\fR and \fIgit ls\-remote\fR clients, which are invoked from \fIgit fetch\fR, \fIgit pull\fR, and \fIgit clone\fR\&. |
| .sp |
| This is ideally suited for read\-only updates, i\&.e\&., pulling from Git repositories\&. |
| .sp |
| An \fBupload\-archive\fR also exists to serve \fIgit archive\fR\&. |
| .SH "OPTIONS" |
| .PP |
| \-\-strict\-paths |
| .RS 4 |
| Match paths exactly (i\&.e\&. don\(cqt allow "/foo/repo" when the real path is "/foo/repo\&.git" or "/foo/repo/\&.git") and don\(cqt do user\-relative paths\&. |
| \fIgit daemon\fR |
| will refuse to start when this option is enabled and no whitelist is specified\&. |
| .RE |
| .PP |
| \-\-base\-path=<path> |
| .RS 4 |
| Remap all the path requests as relative to the given path\&. This is sort of "Git root" \- if you run |
| \fIgit daemon\fR |
| with |
| \fI\-\-base\-path=/srv/git\fR |
| on example\&.com, then if you later try to pull |
| \fIgit://example\&.com/hello\&.git\fR, |
| \fIgit daemon\fR |
| will interpret the path as |
| \fI/srv/git/hello\&.git\fR\&. |
| .RE |
| .PP |
| \-\-base\-path\-relaxed |
| .RS 4 |
| If \-\-base\-path is enabled and repo lookup fails, with this option |
| \fIgit daemon\fR |
| will attempt to lookup without prefixing the base path\&. This is useful for switching to \-\-base\-path usage, while still allowing the old paths\&. |
| .RE |
| .PP |
| \-\-interpolated\-path=<pathtemplate> |
| .RS 4 |
| To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths\&. The template supports %H for the target hostname as supplied by the client but converted to all lowercase, %CH for the canonical hostname, %IP for the server\(cqs IP address, %P for the port number, and %D for the absolute path of the named repository\&. After interpolation, the path is validated against the directory whitelist\&. |
| .RE |
| .PP |
| \-\-export\-all |
| .RS 4 |
| Allow pulling from all directories that look like Git repositories (have the |
| \fIobjects\fR |
| and |
| \fIrefs\fR |
| subdirectories), even if they do not have the |
| \fIgit\-daemon\-export\-ok\fR |
| file\&. |
| .RE |
| .PP |
| \-\-inetd |
| .RS 4 |
| Have the server run as an inetd service\&. Implies \-\-syslog (may be overridden with |
| \fB\-\-log\-destination=\fR)\&. Incompatible with \-\-detach, \-\-port, \-\-listen, \-\-user and \-\-group options\&. |
| .RE |
| .PP |
| \-\-listen=<host_or_ipaddr> |
| .RS 4 |
| Listen on a specific IP address or hostname\&. IP addresses can be either an IPv4 address or an IPv6 address if supported\&. If IPv6 is not supported, then \-\-listen=hostname is also not supported and \-\-listen must be given an IPv4 address\&. Can be given more than once\&. Incompatible with |
| \fB\-\-inetd\fR |
| option\&. |
| .RE |
| .PP |
| \-\-port=<n> |
| .RS 4 |
| Listen on an alternative port\&. Incompatible with |
| \fB\-\-inetd\fR |
| option\&. |
| .RE |
| .PP |
| \-\-init\-timeout=<n> |
| .RS 4 |
| Timeout (in seconds) between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate)\&. |
| .RE |
| .PP |
| \-\-timeout=<n> |
| .RS 4 |
| Timeout (in seconds) for specific client sub\-requests\&. This includes the time it takes for the server to process the sub\-request and the time spent waiting for the next client\(cqs request\&. |
| .RE |
| .PP |
| \-\-max\-connections=<n> |
| .RS 4 |
| Maximum number of concurrent clients, defaults to 32\&. Set it to zero for no limit\&. |
| .RE |
| .PP |
| \-\-syslog |
| .RS 4 |
| Short for |
| \fB\-\-log\-destination=syslog\fR\&. |
| .RE |
| .PP |
| \-\-log\-destination=<destination> |
| .RS 4 |
| Send log messages to the specified destination\&. Note that this option does not imply \-\-verbose, thus by default only error conditions will be logged\&. The <destination> must be one of: |
| .PP |
| stderr |
| .RS 4 |
| Write to standard error\&. Note that if |
| \fB\-\-detach\fR |
| is specified, the process disconnects from the real standard error, making this destination effectively equivalent to |
| \fBnone\fR\&. |
| .RE |
| .PP |
| syslog |
| .RS 4 |
| Write to syslog, using the |
| \fBgit\-daemon\fR |
| identifier\&. |
| .RE |
| .PP |
| none |
| .RS 4 |
| Disable all logging\&. |
| .RE |
| .sp |
| The default destination is |
| \fBsyslog\fR |
| if |
| \fB\-\-inetd\fR |
| or |
| \fB\-\-detach\fR |
| is specified, otherwise |
| \fBstderr\fR\&. |
| .RE |
| .PP |
| \-\-user\-path, \-\-user\-path=<path> |
| .RS 4 |
| Allow ~user notation to be used in requests\&. When specified with no parameter, requests to git://host/~alice/foo is taken as a request to access |
| \fIfoo\fR |
| repository in the home directory of user |
| \fBalice\fR\&. If |
| \fB\-\-user\-path=path\fR |
| is specified, the same request is taken as a request to access |
| \fBpath/foo\fR |
| repository in the home directory of user |
| \fBalice\fR\&. |
| .RE |
| .PP |
| \-\-verbose |
| .RS 4 |
| Log details about the incoming connections and requested files\&. |
| .RE |
| .PP |
| \-\-reuseaddr |
| .RS 4 |
| Use SO_REUSEADDR when binding the listening socket\&. This allows the server to restart without waiting for old connections to time out\&. |
| .RE |
| .PP |
| \-\-detach |
| .RS 4 |
| Detach from the shell\&. Implies \-\-syslog\&. |
| .RE |
| .PP |
| \-\-pid\-file=<file> |
| .RS 4 |
| Save the process id in |
| \fIfile\fR\&. Ignored when the daemon is run under |
| \fB\-\-inetd\fR\&. |
| .RE |
| .PP |
| \-\-user=<user>, \-\-group=<group> |
| .RS 4 |
| Change daemon\(cqs uid and gid before entering the service loop\&. When only |
| \fB\-\-user\fR |
| is given without |
| \fB\-\-group\fR, the primary group ID for the user is used\&. The values of the option are given to |
| \fBgetpwnam(3)\fR |
| and |
| \fBgetgrnam(3)\fR |
| and numeric IDs are not supported\&. |
| .sp |
| Giving these options is an error when used with |
| \fB\-\-inetd\fR; use the facility of inet daemon to achieve the same before spawning |
| \fIgit daemon\fR |
| if needed\&. |
| .sp |
| Like many programs that switch user id, the daemon does not reset environment variables such as |
| \fB$HOME\fR |
| when it runs git programs, e\&.g\&. |
| \fBupload\-pack\fR |
| and |
| \fBreceive\-pack\fR\&. When using this option, you may also want to set and export |
| \fBHOME\fR |
| to point at the home directory of |
| \fB<user>\fR |
| before starting the daemon, and make sure any Git configuration files in that directory are readable by |
| \fB<user>\fR\&. |
| .RE |
| .PP |
| \-\-enable=<service>, \-\-disable=<service> |
| .RS 4 |
| Enable/disable the service site\-wide per default\&. Note that a service disabled site\-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item\&. |
| .RE |
| .PP |
| \-\-allow\-override=<service>, \-\-forbid\-override=<service> |
| .RS 4 |
| Allow/forbid overriding the site\-wide default with per repository configuration\&. By default, all the services may be overridden\&. |
| .RE |
| .PP |
| \-\-[no\-]informative\-errors |
| .RS 4 |
| When informative errors are turned on, git\-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported"\&. This is more convenient for clients, but may leak information about the existence of unexported repositories\&. When informative errors are not enabled, all errors report "access denied" to the client\&. The default is \-\-no\-informative\-errors\&. |
| .RE |
| .PP |
| \-\-access\-hook=<path> |
| .RS 4 |
| Every time a client connects, first run an external command specified by the <path> with service name (e\&.g\&. "upload\-pack"), path to the repository, hostname (%H), canonical hostname (%CH), IP address (%IP), and TCP port (%P) as its command\-line arguments\&. The external command can decide to decline the service by exiting with a non\-zero status (or to allow it by exiting with a zero status)\&. It can also look at the $REMOTE_ADDR and |
| \fB$REMOTE_PORT\fR |
| environment variables to learn about the requestor when making this decision\&. |
| .sp |
| The external command can optionally write a single line to its standard output to be sent to the requestor as an error message when it declines the service\&. |
| .RE |
| .PP |
| <directory> |
| .RS 4 |
| A directory to add to the whitelist of allowed directories\&. Unless \-\-strict\-paths is specified this will also include subdirectories of each named directory\&. |
| .RE |
| .SH "SERVICES" |
| .sp |
| These services can be globally enabled/disabled using the command\-line options of this command\&. If finer\-grained control is desired (e\&.g\&. to allow \fIgit archive\fR to be run against only in a few selected repositories the daemon serves), the per\-repository configuration file can be used to enable or disable them\&. |
| .PP |
| upload\-pack |
| .RS 4 |
| This serves |
| \fIgit fetch\-pack\fR |
| and |
| \fIgit ls\-remote\fR |
| clients\&. It is enabled by default, but a repository can disable it by setting |
| \fBdaemon\&.uploadpack\fR |
| configuration item to |
| \fBfalse\fR\&. |
| .RE |
| .PP |
| upload\-archive |
| .RS 4 |
| This serves |
| \fIgit archive \-\-remote\fR\&. It is disabled by default, but a repository can enable it by setting |
| \fBdaemon\&.uploadarch\fR |
| configuration item to |
| \fBtrue\fR\&. |
| .RE |
| .PP |
| receive\-pack |
| .RS 4 |
| This serves |
| \fIgit send\-pack\fR |
| clients, allowing anonymous push\&. It is disabled by default, as there is |
| \fIno\fR |
| authentication in the protocol (in other words, anybody can push anything into the repository, including removal of refs)\&. This is solely meant for a closed LAN setting where everybody is friendly\&. This service can be enabled by setting |
| \fBdaemon\&.receivepack\fR |
| configuration item to |
| \fBtrue\fR\&. |
| .RE |
| .SH "EXAMPLES" |
| .PP |
| We assume the following in /etc/services |
| .RS 4 |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ grep 9418 /etc/services |
| git 9418/tcp # Git Version Control System |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .PP |
| \fIgit daemon\fR as inetd server |
| .RS 4 |
| To set up |
| \fIgit daemon\fR |
| as an inetd service that handles any repository under the whitelisted set of directories, /pub/foo and /pub/bar, place an entry like the following into /etc/inetd all on one line: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| git stream tcp nowait nobody /usr/bin/git |
| git daemon \-\-inetd \-\-verbose \-\-export\-all |
| /pub/foo /pub/bar |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .PP |
| \fIgit daemon\fR as inetd server for virtual hosts |
| .RS 4 |
| To set up |
| \fIgit daemon\fR |
| as an inetd service that handles repositories for different virtual hosts, |
| \fBwww\&.example\&.com\fR |
| and |
| \fBwww\&.example\&.org\fR, place an entry like the following into |
| \fB/etc/inetd\fR |
| all on one line: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| git stream tcp nowait nobody /usr/bin/git |
| git daemon \-\-inetd \-\-verbose \-\-export\-all |
| \-\-interpolated\-path=/pub/%H%D |
| /pub/www\&.example\&.org/software |
| /pub/www\&.example\&.com/software |
| /software |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| In this example, the root\-level directory |
| \fB/pub\fR |
| will contain a subdirectory for each virtual host name supported\&. Further, both hosts advertise repositories simply as |
| \fBgit://www\&.example\&.com/software/repo\&.git\fR\&. For pre\-1\&.4\&.0 clients, a symlink from |
| \fB/software\fR |
| into the appropriate default repository could be made as well\&. |
| .RE |
| .PP |
| \fIgit daemon\fR as regular daemon for virtual hosts |
| .RS 4 |
| To set up |
| \fIgit daemon\fR |
| as a regular, non\-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| git daemon \-\-verbose \-\-export\-all |
| \-\-interpolated\-path=/pub/%IP/%D |
| /pub/192\&.168\&.1\&.200/software |
| /pub/10\&.10\&.220\&.23/software |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| In this example, the root\-level directory |
| \fB/pub\fR |
| will contain a subdirectory for each virtual host IP address supported\&. Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses\&. |
| .RE |
| .PP |
| selectively enable/disable services per repository |
| .RS 4 |
| To enable |
| \fIgit archive \-\-remote\fR |
| and disable |
| \fIgit fetch\fR |
| against a repository, have the following in the configuration file in the repository (that is the file |
| \fIconfig\fR |
| next to |
| \fBHEAD\fR, |
| \fIrefs\fR |
| and |
| \fIobjects\fR)\&. |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| [daemon] |
| uploadpack = false |
| uploadarch = true |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .SH "ENVIRONMENT" |
| .sp |
| \fIgit daemon\fR will set REMOTE_ADDR to the IP address of the client that connected to it, if the IP address is available\&. REMOTE_ADDR will be available in the environment of hooks called when services are performed\&. |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |