path: root/man1/git-daemon.1

'\" t
.\"     Title: git-daemon
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-09
.\"    Manual: Git Manual
.\"    Source: Git 2.44.0.548.g91ec36f2cc
.\"  Language: English
.\"
.TH "GIT\-DAEMON" "1" "2024\-04\-09" "Git 2\&.44\&.0\&.548\&.g91ec36" "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, the offers are limited to repositories within those directories\&.
.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 directory arguments are provided\&.
.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
\fB/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 list\&.
.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, a request 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
\fB<path>/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
The remaining arguments provide a list of directories\&. If any directories are specified, then the
\fBgit\-daemon\fR
process will serve a requested directory only if it is contained in one of these directories\&. If
\fB\-\-strict\-paths\fR
is specified, then the requested directory must match one of these directories exactly\&.
.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 within
\fB/pub/foo\fR
or
\fB/pub/bar\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
                /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