git-daemon(1): assorted improvements.
[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::
bdd73795
JH
127 Save the process id in 'file'. Ignored when the daemon
128 is run under `--inetd`.
6c35119a 129
678dac6b
TS
130--user=user, --group=group::
131 Change daemon's uid and gid before entering the service loop.
132 When only `--user` is given without `--group`, the
133 primary group ID for the user is used. The values of
134 the option are given to `getpwnam(3)` and `getgrnam(3)`
135 and numeric IDs are not supported.
136+
137Giving these options is an error when used with `--inetd`; use
138the facility of inet daemon to achieve the same before spawning
139`git-daemon` if needed.
140
eda95d99 141--enable=service, --disable=service::
355f5412
JH
142 Enable/disable the service site-wide per default. Note
143 that a service disabled site-wide can still be enabled
144 per repository if it is marked overridable and the
145 repository enables the service with an configuration
146 item.
147
eda95d99 148--allow-override=service, --forbid-override=service::
355f5412
JH
149 Allow/forbid overriding the site-wide default with per
150 repository configuration. By default, all the services
151 are overridable.
152
4dbd1352
AE
153<directory>::
154 A directory to add to the whitelist of allowed directories. Unless
155 --strict-paths is specified this will also include subdirectories
156 of each named directory.
157
355f5412
JH
158SERVICES
159--------
160
bdd73795
JH
161These services can be globally enabled/disabled using the
162command line options of this command. If a finer-grained
163control is desired (e.g. to allow `git-archive` to be run
164against only in a few selected repositories the daemon serves),
165the per-repository configuration file can be used to enable or
166disable them.
167
355f5412
JH
168upload-pack::
169 This serves `git-fetch-pack` and `git-peek-remote`
170 clients. It is enabled by default, but a repository can
171 disable it by setting `daemon.uploadpack` configuration
172 item to `false`.
173
e2b1d1cc 174upload-archive::
bdd73795
JH
175 This serves `git-archive --remote`. It is disabled by
176 default, but a repository can enable it by setting
177 `daemon.uploadarchive` configuration item to `true`.
178
179receive-pack::
180 This serves `git-send-pack` clients, allowing anonymous
181 push. It is disabled by default, as there is _no_
182 authentication in the protocol (in other words, anybody
183 can push anything into the repository, including removal
184 of refs). This is solely meant for a closed LAN setting
185 where everybody is friendly. This service can be
186 enabled by `daemon.receivepack` configuration item to
187 `true`.
e2b1d1cc 188
49ba83fb
JL
189EXAMPLES
190--------
f8a5da6d
CC
191We assume the following in /etc/services::
192+
193------------
194$ grep 9418 /etc/services
195git 9418/tcp # Git Version Control System
196------------
197
49ba83fb
JL
198git-daemon as inetd server::
199 To set up `git-daemon` as an inetd service that handles any
200 repository under the whitelisted set of directories, /pub/foo
201 and /pub/bar, place an entry like the following into
202 /etc/inetd all on one line:
203+
204------------------------------------------------
205 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 206 git-daemon --inetd --verbose --export-all
49ba83fb
JL
207 /pub/foo /pub/bar
208------------------------------------------------
209
210
211git-daemon as inetd server for virtual hosts::
212 To set up `git-daemon` as an inetd service that handles
213 repositories for different virtual hosts, `www.example.com`
214 and `www.example.org`, place an entry like the following into
215 `/etc/inetd` all on one line:
216+
217------------------------------------------------
218 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 219 git-daemon --inetd --verbose --export-all
49ba83fb
JL
220 --interpolated-path=/pub/%H%D
221 /pub/www.example.org/software
222 /pub/www.example.com/software
223 /software
224------------------------------------------------
225+
226In this example, the root-level directory `/pub` will contain
227a subdirectory for each virtual host name supported.
228Further, both hosts advertise repositories simply as
229`git://www.example.com/software/repo.git`. For pre-1.4.0
230clients, a symlink from `/software` into the appropriate
231default repository could be made as well.
232
233
dd467629
JL
234git-daemon as regular daemon for virtual hosts::
235 To set up `git-daemon` as a regular, non-inetd service that
236 handles repositories for multiple virtual hosts based on
237 their IP addresses, start the daemon like this:
238+
239------------------------------------------------
240 git-daemon --verbose --export-all
241 --interpolated-path=/pub/%IP/%D
242 /pub/192.168.1.200/software
243 /pub/10.10.220.23/software
244------------------------------------------------
245+
246In this example, the root-level directory `/pub` will contain
247a subdirectory for each virtual host IP address supported.
248Repositories can still be accessed by hostname though, assuming
249they correspond to these IP addresses.
250
251
bdd73795
JH
252To enable `git-archive --remote` and disable `git-fetch` against
253a repository, have the following in the configuration file in the
254repository (that is the file 'config' next to 'HEAD', 'refs' and
255'objects').
256+
257----------------------------------------------------------------
258[daemon]
259 uploadpack = false
260 uploadarchive = true
261----------------------------------------------------------------
262
263
7fc9d69f
JH
264Author
265------
4dbd1352
AE
266Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki
267<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org>
7fc9d69f
JH
268
269Documentation
270--------------
271Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
272
273GIT
274---
a7154e91 275Part of the gitlink:git[7] suite