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