| blob | 6f7b56db3d70dd4b75f227f34b81a36826360ace |
1 '\" t
2 .\" Title: git-daemon
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2023-08-04
6 .\" Manual: Git Manual
7 .\" Source: Git 2.42.0.rc0
8 .\" Language: English
9 .\"
10 .TH "GIT\-DAEMON" "1" "2023\-08\-04" "Git 2\&.42\&.0\&.rc0" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-daemon \- A really simple server for Git repositories
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit daemon\fR [\-\-verbose] [\-\-syslog] [\-\-export\-all]
36 [\-\-timeout=<n>] [\-\-init\-timeout=<n>] [\-\-max\-connections=<n>]
37 [\-\-strict\-paths] [\-\-base\-path=<path>] [\-\-base\-path\-relaxed]
38 [\-\-user\-path | \-\-user\-path=<path>]
39 [\-\-interpolated\-path=<pathtemplate>]
40 [\-\-reuseaddr] [\-\-detach] [\-\-pid\-file=<file>]
41 [\-\-enable=<service>] [\-\-disable=<service>]
42 [\-\-allow\-override=<service>] [\-\-forbid\-override=<service>]
43 [\-\-access\-hook=<path>] [\-\-[no\-]informative\-errors]
44 [\-\-inetd |
45 [\-\-listen=<host_or_ipaddr>] [\-\-port=<n>]
46 [\-\-user=<user> [\-\-group=<group>]]]
47 [\-\-log\-destination=(stderr|syslog|none)]
48 [<directory>\&...]
49 .fi
50 .sp
51 .SH "DESCRIPTION"
52 .sp
53 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\&.
54 .sp
55 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\&.
56 .sp
57 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\&.
58 .sp
59 This is ideally suited for read\-only updates, i\&.e\&., pulling from Git repositories\&.
60 .sp
61 An \fBupload\-archive\fR also exists to serve \fIgit archive\fR\&.
62 .SH "OPTIONS"
63 .PP
64 \-\-strict\-paths
65 .RS 4
66 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\&.
67 \fIgit daemon\fR
68 will refuse to start when this option is enabled and no directory arguments are provided\&.
69 .RE
70 .PP
71 \-\-base\-path=<path>
72 .RS 4
73 Remap all the path requests as relative to the given path\&. This is sort of "Git root" \- if you run
74 \fIgit daemon\fR
75 with
76 \fI\-\-base\-path=/srv/git\fR
77 on example\&.com, then if you later try to pull
78 \fIgit://example\&.com/hello\&.git\fR,
79 \fIgit daemon\fR
80 will interpret the path as
81 \fB/srv/git/hello\&.git\fR\&.
82 .RE
83 .PP
84 \-\-base\-path\-relaxed
85 .RS 4
86 If \-\-base\-path is enabled and repo lookup fails, with this option
87 \fIgit daemon\fR
88 will attempt to lookup without prefixing the base path\&. This is useful for switching to \-\-base\-path usage, while still allowing the old paths\&.
89 .RE
90 .PP
91 \-\-interpolated\-path=<pathtemplate>
92 .RS 4
93 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\&.
94 .RE
95 .PP
96 \-\-export\-all
97 .RS 4
98 Allow pulling from all directories that look like Git repositories (have the
99 \fIobjects\fR
100 and
101 \fIrefs\fR
102 subdirectories), even if they do not have the
103 \fIgit\-daemon\-export\-ok\fR
104 file\&.
105 .RE
106 .PP
107 \-\-inetd
108 .RS 4
109 Have the server run as an inetd service\&. Implies \-\-syslog (may be overridden with
110 \fB\-\-log\-destination=\fR)\&. Incompatible with \-\-detach, \-\-port, \-\-listen, \-\-user and \-\-group options\&.
111 .RE
112 .PP
113 \-\-listen=<host_or_ipaddr>
114 .RS 4
115 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
116 \fB\-\-inetd\fR
117 option\&.
118 .RE
119 .PP
120 \-\-port=<n>
121 .RS 4
122 Listen on an alternative port\&. Incompatible with
123 \fB\-\-inetd\fR
124 option\&.
125 .RE
126 .PP
127 \-\-init\-timeout=<n>
128 .RS 4
129 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)\&.
130 .RE
131 .PP
132 \-\-timeout=<n>
133 .RS 4
134 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\&.
135 .RE
136 .PP
137 \-\-max\-connections=<n>
138 .RS 4
139 Maximum number of concurrent clients, defaults to 32\&. Set it to zero for no limit\&.
140 .RE
141 .PP
142 \-\-syslog
143 .RS 4
144 Short for
145 \fB\-\-log\-destination=syslog\fR\&.
146 .RE
147 .PP
148 \-\-log\-destination=<destination>
149 .RS 4
150 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:
151 .PP
152 stderr
153 .RS 4
154 Write to standard error\&. Note that if
155 \fB\-\-detach\fR
156 is specified, the process disconnects from the real standard error, making this destination effectively equivalent to
157 \fBnone\fR\&.
158 .RE
159 .PP
160 syslog
161 .RS 4
162 Write to syslog, using the
163 \fBgit\-daemon\fR
164 identifier\&.
165 .RE
166 .PP
167 none
168 .RS 4
169 Disable all logging\&.
170 .RE
171 .sp
172 The default destination is
173 \fBsyslog\fR
174 if
175 \fB\-\-inetd\fR
176 or
177 \fB\-\-detach\fR
178 is specified, otherwise
179 \fBstderr\fR\&.
180 .RE
181 .PP
182 \-\-user\-path, \-\-user\-path=<path>
183 .RS 4
184 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
185 \fIfoo\fR
186 repository in the home directory of user
187 \fBalice\fR\&. If
188 \fB\-\-user\-path=path\fR
189 is specified, the same request is taken as a request to access
190 \fBpath/foo\fR
191 repository in the home directory of user
192 \fBalice\fR\&.
193 .RE
194 .PP
195 \-\-verbose
196 .RS 4
197 Log details about the incoming connections and requested files\&.
198 .RE
199 .PP
200 \-\-reuseaddr
201 .RS 4
202 Use SO_REUSEADDR when binding the listening socket\&. This allows the server to restart without waiting for old connections to time out\&.
203 .RE
204 .PP
205 \-\-detach
206 .RS 4
207 Detach from the shell\&. Implies \-\-syslog\&.
208 .RE
209 .PP
210 \-\-pid\-file=<file>
211 .RS 4
212 Save the process id in
213 \fIfile\fR\&. Ignored when the daemon is run under
214 \fB\-\-inetd\fR\&.
215 .RE
216 .PP
217 \-\-user=<user>, \-\-group=<group>
218 .RS 4
219 Change daemon\(cqs uid and gid before entering the service loop\&. When only
220 \fB\-\-user\fR
221 is given without
222 \fB\-\-group\fR, the primary group ID for the user is used\&. The values of the option are given to
223 \fBgetpwnam(3)\fR
224 and
225 \fBgetgrnam(3)\fR
226 and numeric IDs are not supported\&.
227 .sp
228 Giving these options is an error when used with
229 \fB\-\-inetd\fR; use the facility of inet daemon to achieve the same before spawning
230 \fIgit daemon\fR
231 if needed\&.
232 .sp
233 Like many programs that switch user id, the daemon does not reset environment variables such as
234 \fB$HOME\fR
235 when it runs git programs, e\&.g\&.
236 \fBupload\-pack\fR
237 and
238 \fBreceive\-pack\fR\&. When using this option, you may also want to set and export
239 \fBHOME\fR
240 to point at the home directory of
241 \fB<user>\fR
242 before starting the daemon, and make sure any Git configuration files in that directory are readable by
243 \fB<user>\fR\&.
244 .RE
245 .PP
246 \-\-enable=<service>, \-\-disable=<service>
247 .RS 4
248 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\&.
249 .RE
250 .PP
251 \-\-allow\-override=<service>, \-\-forbid\-override=<service>
252 .RS 4
253 Allow/forbid overriding the site\-wide default with per repository configuration\&. By default, all the services may be overridden\&.
254 .RE
255 .PP
256 \-\-[no\-]informative\-errors
257 .RS 4
258 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\&.
259 .RE
260 .PP
261 \-\-access\-hook=<path>
262 .RS 4
263 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
264 \fB$REMOTE_PORT\fR
265 environment variables to learn about the requestor when making this decision\&.
266 .sp
267 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\&.
268 .RE
269 .PP
270 <directory>
271 .RS 4
272 The remaining arguments provide a list of directories\&. If any directories are specified, then the
273 \fBgit\-daemon\fR
274 process will serve a requested directory only if it is contained in one of these directories\&. If
275 \fB\-\-strict\-paths\fR
276 is specified, then the requested directory must match one of these directories exactly\&.
277 .RE
278 .SH "SERVICES"
279 .sp
280 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\&.
281 .PP
282 upload\-pack
283 .RS 4
284 This serves
285 \fIgit fetch\-pack\fR
286 and
287 \fIgit ls\-remote\fR
288 clients\&. It is enabled by default, but a repository can disable it by setting
289 \fBdaemon\&.uploadpack\fR
290 configuration item to
291 \fBfalse\fR\&.
292 .RE
293 .PP
294 upload\-archive
295 .RS 4
296 This serves
297 \fIgit archive \-\-remote\fR\&. It is disabled by default, but a repository can enable it by setting
298 \fBdaemon\&.uploadarch\fR
299 configuration item to
300 \fBtrue\fR\&.
301 .RE
302 .PP
303 receive\-pack
304 .RS 4
305 This serves
306 \fIgit send\-pack\fR
307 clients, allowing anonymous push\&. It is disabled by default, as there is
308 \fIno\fR
309 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
310 \fBdaemon\&.receivepack\fR
311 configuration item to
312 \fBtrue\fR\&.
313 .RE
314 .SH "EXAMPLES"
315 .PP
316 We assume the following in /etc/services
317 .RS 4
318 .sp
319 .if n \{\
320 .RS 4
321 .\}
322 .nf
323 $ grep 9418 /etc/services
324 git 9418/tcp # Git Version Control System
325 .fi
326 .if n \{\
327 .RE
328 .\}
329 .sp
330 .RE
331 .PP
332 \fIgit daemon\fR as inetd server
333 .RS 4
334 To set up
335 \fIgit daemon\fR
336 as an inetd service that handles any repository within
337 \fB/pub/foo\fR
338 or
339 \fB/pub/bar\fR, place an entry like the following into
340 \fB/etc/inetd\fR
341 all on one line:
342 .sp
343 .if n \{\
344 .RS 4
345 .\}
346 .nf
347 git stream tcp nowait nobody /usr/bin/git
348 git daemon \-\-inetd \-\-verbose \-\-export\-all
349 /pub/foo /pub/bar
350 .fi
351 .if n \{\
352 .RE
353 .\}
354 .sp
355 .RE
356 .PP
357 \fIgit daemon\fR as inetd server for virtual hosts
358 .RS 4
359 To set up
360 \fIgit daemon\fR
361 as an inetd service that handles repositories for different virtual hosts,
362 \fBwww\&.example\&.com\fR
363 and
364 \fBwww\&.example\&.org\fR, place an entry like the following into
365 \fB/etc/inetd\fR
366 all on one line:
367 .sp
368 .if n \{\
369 .RS 4
370 .\}
371 .nf
372 git stream tcp nowait nobody /usr/bin/git
373 git daemon \-\-inetd \-\-verbose \-\-export\-all
374 \-\-interpolated\-path=/pub/%H%D
375 /pub/www\&.example\&.org/software
376 /pub/www\&.example\&.com/software
377 /software
378 .fi
379 .if n \{\
380 .RE
381 .\}
382 .sp
383 In this example, the root\-level directory
384 \fB/pub\fR
385 will contain a subdirectory for each virtual host name supported\&. Further, both hosts advertise repositories simply as
386 \fBgit://www\&.example\&.com/software/repo\&.git\fR\&. For pre\-1\&.4\&.0 clients, a symlink from
387 \fB/software\fR
388 into the appropriate default repository could be made as well\&.
389 .RE
390 .PP
391 \fIgit daemon\fR as regular daemon for virtual hosts
392 .RS 4
393 To set up
394 \fIgit daemon\fR
395 as a regular, non\-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this:
396 .sp
397 .if n \{\
398 .RS 4
399 .\}
400 .nf
401 git daemon \-\-verbose \-\-export\-all
402 \-\-interpolated\-path=/pub/%IP/%D
403 /pub/192\&.168\&.1\&.200/software
404 /pub/10\&.10\&.220\&.23/software
405 .fi
406 .if n \{\
407 .RE
408 .\}
409 .sp
410 In this example, the root\-level directory
411 \fB/pub\fR
412 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\&.
413 .RE
414 .PP
415 selectively enable/disable services per repository
416 .RS 4
417 To enable
418 \fIgit archive \-\-remote\fR
419 and disable
420 \fIgit fetch\fR
421 against a repository, have the following in the configuration file in the repository (that is the file
422 \fIconfig\fR
423 next to
424 \fBHEAD\fR,
425 \fIrefs\fR
426 and
427 \fIobjects\fR)\&.
428 .sp
429 .if n \{\
430 .RS 4
431 .\}
432 .nf
433 [daemon]
434 uploadpack = false
435 uploadarch = true
436 .fi
437 .if n \{\
438 .RE
439 .\}
440 .sp
441 .RE
442 .SH "ENVIRONMENT"
443 .sp
444 \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\&.
445 .SH "GIT"
446 .sp
447 Part of the \fBgit\fR(1) suite