'\" t
.\" Title: git-daemon
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 06/01/2011
.\" Manual: Git Manual
.\" Source: Git 1.7.5.4
.\" Language: English
.\"
.TH "GIT\-DAEMON" "1" "06/01/2011" "Git 1\&.7\&.5\&.4" "Git Manual"
.\" -----------------------------------------------------------------
.\" * 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>]
[\-\-inetd | [\-\-listen=<host_or_ipaddr>] [\-\-port=<n>] [\-\-user=<user> [\-\-group=<group>]]
[<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 \fI\-\-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 upload\-pack 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 upload\-archive 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\&. 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
\fI\-\-inetd\fR
option\&.
.RE
.PP
\-\-port=<n>
.RS 4
Listen on an alternative port\&. Incompatible with
\fI\-\-inetd\fR
option\&.
.RE
.PP
\-\-init\-timeout=<n>
.RS 4
Timeout 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 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
Log to syslog instead of stderr\&. Note that this option does not imply \-\-verbose, thus by default only error conditions will be logged\&.
.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
alice\&. If
\-\-user\-path=path
is specified, the same request is taken as a request to access
path/foo
repository in the home directory of user
alice\&.
.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
\-\-inetd\&.
.RE
.PP
\-\-user=<user>, \-\-group=<group>
.RS 4
Change daemon\(cqs uid and gid before entering the service loop\&. When only
\-\-user
is given without
\-\-group, the primary group ID for the user is used\&. The values of the option are given to
getpwnam(3)
and
getgrnam(3)
and numeric IDs are not supported\&.
.sp
Giving these options is an error when used with
\-\-inetd; use the facility of inet daemon to achieve the same before spawning
\fIgit daemon\fR
if needed\&.
.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 are overridable\&.
.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 a 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
daemon\&.uploadpack
configuration item to
false\&.
.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
daemon\&.uploadarch
configuration item to
true\&.
.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
daemon\&.receivepack
configuration item to
true\&.
.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,
www\&.example\&.com
and
www\&.example\&.org, 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
\-\-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
/pub
will contain a subdirectory for each virtual host name supported\&. Further, both hosts advertise repositories simply as
git://www\&.example\&.com/software/repo\&.git\&. For pre\-1\&.4\&.0 clients, a symlink from
/software
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
/pub
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
\fIHEAD\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