GIT 1.5.3-rc7
[git/git.git] / Documentation / git-daemon.txt
CommitLineData
7fc9d69f
JH
1git-daemon(1)
2=============
3
4NAME
5----
7bd7f280 6git-daemon - A really simple server for git repositories
7fc9d69f
JH
7
8SYNOPSIS
9--------
353ce815 10[verse]
dd467629 11'git-daemon' [--verbose] [--syslog] [--export-all]
b21c31c9 12 [--timeout=n] [--init-timeout=n] [--strict-paths]
603968d2 13 [--base-path=path] [--user-path | --user-path=path]
49ba83fb 14 [--interpolated-path=pathtemplate]
dd467629 15 [--reuseaddr] [--detach] [--pid-file=file]
355f5412
JH
16 [--enable=service] [--disable=service]
17 [--allow-override=service] [--forbid-override=service]
dd467629
JL
18 [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]
19 [directory...]
7fc9d69f
JH
20
21DESCRIPTION
22-----------
62cd033d 23A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT"
355f5412
JH
24aka 9418. It waits for a connection asking for a service, and will serve
25that service if it is enabled.
7fc9d69f 26
62cd033d
LAS
27It verifies that the directory has the magic file "git-daemon-export-ok", and
28it will refuse to export any git directory that hasn't explicitly been marked
2707da9c
PB
29for export this way (unless the '--export-all' parameter is specified). If you
30pass some directory paths as 'git-daemon' arguments, you can further restrict
31the offers to a whitelist comprising of those.
62cd033d 32
355f5412
JH
33By default, only `upload-pack` service is enabled, which serves
34`git-fetch-pack` and `git-peek-remote` clients that are invoked
35from `git-fetch`, `git-ls-remote`, and `git-clone`.
36
37This is ideally suited for read-only updates, i.e., pulling from
38git repositories.
7fc9d69f 39
e2b1d1cc
CC
40An `upload-archive` also exists to serve `git-archive`.
41
7fc9d69f
JH
42OPTIONS
43-------
ce335fe0 44--strict-paths::
4dbd1352
AE
45 Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
46 "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
47 git-daemon will refuse to start when this option is enabled and no
48 whitelist is specified.
49
b21c31c9
PB
50--base-path::
51 Remap all the path requests as relative to the given path.
52 This is sort of "GIT root" - if you run git-daemon with
53 '--base-path=/srv/git' on example.com, then if you later try to pull
54 'git://example.com/hello.git', `git-daemon` will interpret the path
603968d2 55 as '/srv/git/hello.git'.
b21c31c9 56
73a7a656
JA
57--base-path-relaxed::
58 If --base-path is enabled and repo lookup fails, with this option
59 `git-daemon` will attempt to lookup without prefixing the base path.
60 This is useful for switching to --base-path usage, while still
61 allowing the old paths.
62
49ba83fb
JL
63--interpolated-path=pathtemplate::
64 To support virtual hosting, an interpolated path template can be
65 used to dynamically construct alternate paths. The template
dd467629
JL
66 supports %H for the target hostname as supplied by the client but
67 converted to all lowercase, %CH for the canonical hostname,
68 %IP for the server's IP address, %P for the port number,
49ba83fb 69 and %D for the absolute path of the named repository.
dd467629
JL
70 After interpolation, the path is validated against the directory
71 whitelist.
49ba83fb 72
2707da9c
PB
73--export-all::
74 Allow pulling from all directories that look like GIT repositories
4dbd1352 75 (have the 'objects' and 'refs' subdirectories), even if they
2707da9c
PB
76 do not have the 'git-daemon-export-ok' file.
77
62cd033d 78--inetd::
bce8230d 79 Have the server run as an inetd service. Implies --syslog.
dd467629
JL
80 Incompatible with --port, --listen, --user and --group options.
81
82--listen=host_or_ipaddr::
83 Listen on an a specific IP address or hostname. IP addresses can
84 be either an IPv4 address or an IPV6 address if supported. If IPv6
85 is not supported, then --listen=hostname is also not supported and
86 --listen must be given an IPv4 address.
87 Incompatible with '--inetd' option.
7fc9d69f 88
dd467629
JL
89--port=n::
90 Listen on an alternative port. Incompatible with '--inetd' option.
7fc9d69f 91
2707da9c
PB
92--init-timeout::
93 Timeout between the moment the connection is established and the
94 client request is received (typically a rather low value, since
95 that should be basically immediate).
96
97--timeout::
98 Timeout for specific client sub-requests. This includes the time
99 it takes for the server to process the sub-request and time spent
100 waiting for next client's request.
101
9048fe1c
PB
102--syslog::
103 Log to syslog instead of stderr. Note that this option does not imply
104 --verbose, thus by default only error conditions will be logged.
105
603968d2
JH
106--user-path, --user-path=path::
107 Allow ~user notation to be used in requests. When
108 specified with no parameter, requests to
109 git://host/~alice/foo is taken as a request to access
110 'foo' repository in the home directory of user `alice`.
111 If `--user-path=path` is specified, the same request is
112 taken as a request to access `path/foo` repository in
113 the home directory of user `alice`.
114
b5cf3c8b
PB
115--verbose::
116 Log details about the incoming connections and requested files.
117
6c35119a
ML
118--reuseaddr::
119 Use SO_REUSEADDR when binding the listening socket.
120 This allows the server to restart without waiting for
121 old connections to time out.
122
123--detach::
124 Detach from the shell. Implies --syslog.
125
126--pid-file=file::
127 Save the process id in 'file'.
128
678dac6b
TS
129--user=user, --group=group::
130 Change daemon's uid and gid before entering the service loop.
131 When only `--user` is given without `--group`, the
132 primary group ID for the user is used. The values of
133 the option are given to `getpwnam(3)` and `getgrnam(3)`
134 and numeric IDs are not supported.
135+
136Giving these options is an error when used with `--inetd`; use
137the facility of inet daemon to achieve the same before spawning
138`git-daemon` if needed.
139
eda95d99 140--enable=service, --disable=service::
355f5412
JH
141 Enable/disable the service site-wide per default. Note
142 that a service disabled site-wide can still be enabled
143 per repository if it is marked overridable and the
144 repository enables the service with an configuration
145 item.
146
eda95d99 147--allow-override=service, --forbid-override=service::
355f5412
JH
148 Allow/forbid overriding the site-wide default with per
149 repository configuration. By default, all the services
150 are overridable.
151
4dbd1352
AE
152<directory>::
153 A directory to add to the whitelist of allowed directories. Unless
154 --strict-paths is specified this will also include subdirectories
155 of each named directory.
156
355f5412
JH
157SERVICES
158--------
159
160upload-pack::
161 This serves `git-fetch-pack` and `git-peek-remote`
162 clients. It is enabled by default, but a repository can
163 disable it by setting `daemon.uploadpack` configuration
164 item to `false`.
165
e2b1d1cc
CC
166upload-archive::
167 This serves `git-archive --remote`.
168
49ba83fb
JL
169EXAMPLES
170--------
f8a5da6d
CC
171We assume the following in /etc/services::
172+
173------------
174$ grep 9418 /etc/services
175git 9418/tcp # Git Version Control System
176------------
177
49ba83fb
JL
178git-daemon as inetd server::
179 To set up `git-daemon` as an inetd service that handles any
180 repository under the whitelisted set of directories, /pub/foo
181 and /pub/bar, place an entry like the following into
182 /etc/inetd all on one line:
183+
184------------------------------------------------
185 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 186 git-daemon --inetd --verbose --export-all
49ba83fb
JL
187 /pub/foo /pub/bar
188------------------------------------------------
189
190
191git-daemon as inetd server for virtual hosts::
192 To set up `git-daemon` as an inetd service that handles
193 repositories for different virtual hosts, `www.example.com`
194 and `www.example.org`, place an entry like the following into
195 `/etc/inetd` all on one line:
196+
197------------------------------------------------
198 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 199 git-daemon --inetd --verbose --export-all
49ba83fb
JL
200 --interpolated-path=/pub/%H%D
201 /pub/www.example.org/software
202 /pub/www.example.com/software
203 /software
204------------------------------------------------
205+
206In this example, the root-level directory `/pub` will contain
207a subdirectory for each virtual host name supported.
208Further, both hosts advertise repositories simply as
209`git://www.example.com/software/repo.git`. For pre-1.4.0
210clients, a symlink from `/software` into the appropriate
211default repository could be made as well.
212
213
dd467629
JL
214git-daemon as regular daemon for virtual hosts::
215 To set up `git-daemon` as a regular, non-inetd service that
216 handles repositories for multiple virtual hosts based on
217 their IP addresses, start the daemon like this:
218+
219------------------------------------------------
220 git-daemon --verbose --export-all
221 --interpolated-path=/pub/%IP/%D
222 /pub/192.168.1.200/software
223 /pub/10.10.220.23/software
224------------------------------------------------
225+
226In this example, the root-level directory `/pub` will contain
227a subdirectory for each virtual host IP address supported.
228Repositories can still be accessed by hostname though, assuming
229they correspond to these IP addresses.
230
231
7fc9d69f
JH
232Author
233------
4dbd1352
AE
234Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki
235<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org>
7fc9d69f
JH
236
237Documentation
238--------------
239Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
240
241GIT
242---
a7154e91 243Part of the gitlink:git[7] suite