| blob | 1722ba7c3ed083e30d28676c9dae43b039134190 |
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-11-22
6 .\" Manual: Git Manual
7 .\" Source: Git 2.47.0.318.g04eaff62f2
8 .\" Language: English
9 .\"
10 .TH "GIT\-DAEMON" "1" "2024-11-22" "Git 2\&.47\&.0\&.318\&.g04eaff" "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=\fR\fI<path>\fR
188 is specified, the same request is taken as a request to access
189 \fI<path>\fR\fB/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\fR(\fB3\fR) and
223 \fBgetgrnam\fR(\fB3\fR) and numeric IDs are not supported\&.
224 .sp
225 Giving these options is an error when used with
226 \fB\-\-inetd\fR; use the facility of inet daemon to achieve the same before spawning
227 \fIgit daemon\fR
228 if needed\&.
229 .sp
230 Like many programs that switch user id, the daemon does not reset environment variables such as
231 \fB$HOME\fR
232 when it runs git programs, e\&.g\&.
233 \fBupload\-pack\fR
234 and
235 \fBreceive\-pack\fR\&. When using this option, you may also want to set and export
236 \fBHOME\fR
237 to point at the home directory of
238 \fI<user>\fR
239 before starting the daemon, and make sure any Git configuration files in that directory are readable by
240 \fI<user>\fR\&.
241 .RE
242 .PP
243 \-\-enable=<service>, \-\-disable=<service>
244 .RS 4
245 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\&.
246 .RE
247 .PP
248 \-\-allow\-override=<service>, \-\-forbid\-override=<service>
249 .RS 4
250 Allow/forbid overriding the site\-wide default with per repository configuration\&. By default, all the services may be overridden\&.
251 .RE
252 .PP
253 \-\-[no\-]informative\-errors
254 .RS 4
255 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\&.
256 .RE
257 .PP
258 \-\-access\-hook=<path>
259 .RS 4
260 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
261 \fB$REMOTE_PORT\fR
262 environment variables to learn about the requestor when making this decision\&.
263 .sp
264 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\&.
265 .RE
266 .PP
267 <directory>
268 .RS 4
269 The remaining arguments provide a list of directories\&. If any directories are specified, then the
270 \fBgit\-daemon\fR
271 process will serve a requested directory only if it is contained in one of these directories\&. If
272 \fB\-\-strict\-paths\fR
273 is specified, then the requested directory must match one of these directories exactly\&.
274 .RE
275 .SH "SERVICES"
276 .sp
277 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\&.
278 .PP
279 upload\-pack
280 .RS 4
281 This serves
282 \fIgit fetch\-pack\fR
283 and
284 \fIgit ls\-remote\fR
285 clients\&. It is enabled by default, but a repository can disable it by setting
286 \fBdaemon\&.uploadpack\fR
287 configuration item to
288 \fBfalse\fR\&.
289 .RE
290 .PP
291 upload\-archive
292 .RS 4
293 This serves
294 \fIgit archive \-\-remote\fR\&. It is disabled by default, but a repository can enable it by setting
295 \fBdaemon\&.uploadarch\fR
296 configuration item to
297 \fBtrue\fR\&.
298 .RE
299 .PP
300 receive\-pack
301 .RS 4
302 This serves
303 \fIgit send\-pack\fR
304 clients, allowing anonymous push\&. It is disabled by default, as there is
305 \fIno\fR
306 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
307 \fBdaemon\&.receivepack\fR
308 configuration item to
309 \fBtrue\fR\&.
310 .RE
311 .SH "EXAMPLES"
312 .PP
313 We assume the following in /etc/services
314 .RS 4
315 .sp
316 .if n \{\
317 .RS 4
318 .\}
319 .nf
320 $ grep 9418 /etc/services
321 git 9418/tcp # Git Version Control System
322 .fi
323 .if n \{\
324 .RE
325 .\}
326 .RE
327 .PP
328 \fIgit daemon\fR as inetd server
329 .RS 4
330 To set up
331 \fIgit daemon\fR
332 as an inetd service that handles any repository within
333 \fB/pub/foo\fR
334 or
335 \fB/pub/bar\fR, place an entry like the following into
336 \fB/etc/inetd\fR
337 all on one line:
338 .sp
339 .if n \{\
340 .RS 4
341 .\}
342 .nf
343 git stream tcp nowait nobody /usr/bin/git
344 git daemon \-\-inetd \-\-verbose \-\-export\-all
345 /pub/foo /pub/bar
346 .fi
347 .if n \{\
348 .RE
349 .\}
350 .RE
351 .PP
352 \fIgit daemon\fR as inetd server for virtual hosts
353 .RS 4
354 To set up
355 \fIgit daemon\fR
356 as an inetd service that handles repositories for different virtual hosts,
357 \fBwww\&.example\&.com\fR
358 and
359 \fBwww\&.example\&.org\fR, place an entry like the following into
360 \fB/etc/inetd\fR
361 all on one line:
362 .sp
363 .if n \{\
364 .RS 4
365 .\}
366 .nf
367 git stream tcp nowait nobody /usr/bin/git
368 git daemon \-\-inetd \-\-verbose \-\-export\-all
369 \-\-interpolated\-path=/pub/%H%D
370 /pub/www\&.example\&.org/software
371 /pub/www\&.example\&.com/software
372 /software
373 .fi
374 .if n \{\
375 .RE
376 .\}
377 .sp
378 In this example, the root\-level directory
379 \fB/pub\fR
380 will contain a subdirectory for each virtual host name supported\&. Further, both hosts advertise repositories simply as
381 \fBgit://www\&.example\&.com/software/repo\&.git\fR\&. For pre\-1\&.4\&.0 clients, a symlink from
382 \fB/software\fR
383 into the appropriate default repository could be made as well\&.
384 .RE
385 .PP
386 \fIgit daemon\fR as regular daemon for virtual hosts
387 .RS 4
388 To set up
389 \fIgit daemon\fR
390 as a regular, non\-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this:
391 .sp
392 .if n \{\
393 .RS 4
394 .\}
395 .nf
396 git daemon \-\-verbose \-\-export\-all
397 \-\-interpolated\-path=/pub/%IP/%D
398 /pub/192\&.168\&.1\&.200/software
399 /pub/10\&.10\&.220\&.23/software
400 .fi
401 .if n \{\
402 .RE
403 .\}
404 .sp
405 In this example, the root\-level directory
406 \fB/pub\fR
407 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\&.
408 .RE
409 .PP
410 selectively enable/disable services per repository
411 .RS 4
412 To enable
413 \fIgit archive \-\-remote\fR
414 and disable
415 \fIgit fetch\fR
416 against a repository, have the following in the configuration file in the repository (that is the file
417 \fIconfig\fR
418 next to
419 \fBHEAD\fR,
420 \fIrefs\fR
421 and
422 \fIobjects\fR)\&.
423 .sp
424 .if n \{\
425 .RS 4
426 .\}
427 .nf
428 [daemon]
429 uploadpack = false
430 uploadarch = true
431 .fi
432 .if n \{\
433 .RE
434 .\}
435 .RE
436 .SH "ENVIRONMENT"
437 .sp
438 \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\&.
439 .SH "GIT"
440 .sp
441 Part of the \fBgit\fR(1) suite