]>
Commit | Line | Data |
---|---|---|
7fc9d69f JH |
1 | git-daemon(1) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
7bd7f280 | 6 | git-daemon - A really simple server for git repositories |
7fc9d69f JH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
353ce815 | 10 | [verse] |
b1889c36 | 11 | 'git daemon' [--verbose] [--syslog] [--export-all] |
62b4698e ŠN |
12 | [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] |
13 | [--strict-paths] [--base-path=<path>] [--base-path-relaxed] | |
14 | [--user-path | --user-path=<path>] | |
15 | [--interpolated-path=<pathtemplate>] | |
16 | [--reuseaddr] [--detach] [--pid-file=<file>] | |
17 | [--enable=<service>] [--disable=<service>] | |
18 | [--allow-override=<service>] [--forbid-override=<service>] | |
93741e4a | 19 | [--access-hook=<path>] |
62b4698e ŠN |
20 | [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] |
21 | [<directory>...] | |
7fc9d69f JH |
22 | |
23 | DESCRIPTION | |
24 | ----------- | |
62cd033d | 25 | A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT" |
355f5412 JH |
26 | aka 9418. It waits for a connection asking for a service, and will serve |
27 | that service if it is enabled. | |
7fc9d69f | 28 | |
62cd033d LAS |
29 | It verifies that the directory has the magic file "git-daemon-export-ok", and |
30 | it will refuse to export any git directory that hasn't explicitly been marked | |
2707da9c | 31 | for export this way (unless the '--export-all' parameter is specified). If you |
0b444cdb | 32 | pass some directory paths as 'git daemon' arguments, you can further restrict |
2707da9c | 33 | the offers to a whitelist comprising of those. |
62cd033d | 34 | |
355f5412 | 35 | By default, only `upload-pack` service is enabled, which serves |
0b444cdb TR |
36 | 'git fetch-pack' and 'git ls-remote' clients, which are invoked |
37 | from 'git fetch', 'git pull', and 'git clone'. | |
355f5412 JH |
38 | |
39 | This is ideally suited for read-only updates, i.e., pulling from | |
40 | git repositories. | |
7fc9d69f | 41 | |
0b444cdb | 42 | An `upload-archive` also exists to serve 'git archive'. |
e2b1d1cc | 43 | |
7fc9d69f JH |
44 | OPTIONS |
45 | ------- | |
ce335fe0 | 46 | --strict-paths:: |
4dbd1352 AE |
47 | Match paths exactly (i.e. don't allow "/foo/repo" when the real path is |
48 | "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. | |
0b444cdb | 49 | 'git daemon' will refuse to start when this option is enabled and no |
4dbd1352 AE |
50 | whitelist is specified. |
51 | ||
62b4698e | 52 | --base-path=<path>:: |
b21c31c9 | 53 | Remap all the path requests as relative to the given path. |
0b444cdb | 54 | This is sort of "GIT root" - if you run 'git daemon' with |
b21c31c9 | 55 | '--base-path=/srv/git' on example.com, then if you later try to pull |
0b444cdb | 56 | 'git://example.com/hello.git', 'git daemon' will interpret the path |
603968d2 | 57 | as '/srv/git/hello.git'. |
b21c31c9 | 58 | |
73a7a656 JA |
59 | --base-path-relaxed:: |
60 | If --base-path is enabled and repo lookup fails, with this option | |
0b444cdb | 61 | 'git daemon' will attempt to lookup without prefixing the base path. |
73a7a656 JA |
62 | This is useful for switching to --base-path usage, while still |
63 | allowing the old paths. | |
64 | ||
62b4698e | 65 | --interpolated-path=<pathtemplate>:: |
49ba83fb JL |
66 | To support virtual hosting, an interpolated path template can be |
67 | used to dynamically construct alternate paths. The template | |
dd467629 JL |
68 | supports %H for the target hostname as supplied by the client but |
69 | converted to all lowercase, %CH for the canonical hostname, | |
70 | %IP for the server's IP address, %P for the port number, | |
49ba83fb | 71 | and %D for the absolute path of the named repository. |
dd467629 JL |
72 | After interpolation, the path is validated against the directory |
73 | whitelist. | |
49ba83fb | 74 | |
2707da9c PB |
75 | --export-all:: |
76 | Allow pulling from all directories that look like GIT repositories | |
4dbd1352 | 77 | (have the 'objects' and 'refs' subdirectories), even if they |
2707da9c PB |
78 | do not have the 'git-daemon-export-ok' file. |
79 | ||
62cd033d | 80 | --inetd:: |
bce8230d | 81 | Have the server run as an inetd service. Implies --syslog. |
9cddf56e EFL |
82 | Incompatible with --detach, --port, --listen, --user and --group |
83 | options. | |
dd467629 | 84 | |
62b4698e | 85 | --listen=<host_or_ipaddr>:: |
62854410 MH |
86 | Listen on a specific IP address or hostname. IP addresses can |
87 | be either an IPv4 address or an IPv6 address if supported. If IPv6 | |
dd467629 JL |
88 | is not supported, then --listen=hostname is also not supported and |
89 | --listen must be given an IPv4 address. | |
3a3a29c1 | 90 | Can be given more than once. |
dd467629 | 91 | Incompatible with '--inetd' option. |
7fc9d69f | 92 | |
62b4698e | 93 | --port=<n>:: |
dd467629 | 94 | Listen on an alternative port. Incompatible with '--inetd' option. |
7fc9d69f | 95 | |
62b4698e | 96 | --init-timeout=<n>:: |
b8843efc MS |
97 | Timeout (in seconds) between the moment the connection is established |
98 | and the client request is received (typically a rather low value, since | |
2707da9c PB |
99 | that should be basically immediate). |
100 | ||
62b4698e | 101 | --timeout=<n>:: |
b8843efc MS |
102 | Timeout (in seconds) for specific client sub-requests. This includes |
103 | the time it takes for the server to process the sub-request and the | |
104 | time spent waiting for the next client's request. | |
2707da9c | 105 | |
62b4698e | 106 | --max-connections=<n>:: |
3bd62c21 SB |
107 | Maximum number of concurrent clients, defaults to 32. Set it to |
108 | zero for no limit. | |
109 | ||
9048fe1c PB |
110 | --syslog:: |
111 | Log to syslog instead of stderr. Note that this option does not imply | |
112 | --verbose, thus by default only error conditions will be logged. | |
113 | ||
3240240f | 114 | --user-path:: |
62b4698e | 115 | --user-path=<path>:: |
4fce51cf | 116 | Allow {tilde}user notation to be used in requests. When |
603968d2 | 117 | specified with no parameter, requests to |
4fce51cf | 118 | git://host/{tilde}alice/foo is taken as a request to access |
603968d2 JH |
119 | 'foo' repository in the home directory of user `alice`. |
120 | If `--user-path=path` is specified, the same request is | |
121 | taken as a request to access `path/foo` repository in | |
122 | the home directory of user `alice`. | |
123 | ||
b5cf3c8b PB |
124 | --verbose:: |
125 | Log details about the incoming connections and requested files. | |
126 | ||
6c35119a ML |
127 | --reuseaddr:: |
128 | Use SO_REUSEADDR when binding the listening socket. | |
129 | This allows the server to restart without waiting for | |
130 | old connections to time out. | |
131 | ||
132 | --detach:: | |
133 | Detach from the shell. Implies --syslog. | |
134 | ||
62b4698e | 135 | --pid-file=<file>:: |
bdd73795 JH |
136 | Save the process id in 'file'. Ignored when the daemon |
137 | is run under `--inetd`. | |
6c35119a | 138 | |
62b4698e ŠN |
139 | --user=<user>:: |
140 | --group=<group>:: | |
678dac6b TS |
141 | Change daemon's uid and gid before entering the service loop. |
142 | When only `--user` is given without `--group`, the | |
143 | primary group ID for the user is used. The values of | |
144 | the option are given to `getpwnam(3)` and `getgrnam(3)` | |
145 | and numeric IDs are not supported. | |
146 | + | |
147 | Giving these options is an error when used with `--inetd`; use | |
148 | the facility of inet daemon to achieve the same before spawning | |
0b444cdb | 149 | 'git daemon' if needed. |
678dac6b | 150 | |
62b4698e ŠN |
151 | --enable=<service>:: |
152 | --disable=<service>:: | |
355f5412 JH |
153 | Enable/disable the service site-wide per default. Note |
154 | that a service disabled site-wide can still be enabled | |
155 | per repository if it is marked overridable and the | |
62854410 | 156 | repository enables the service with a configuration |
355f5412 JH |
157 | item. |
158 | ||
62b4698e ŠN |
159 | --allow-override=<service>:: |
160 | --forbid-override=<service>:: | |
355f5412 JH |
161 | Allow/forbid overriding the site-wide default with per |
162 | repository configuration. By default, all the services | |
163 | are overridable. | |
164 | ||
d5570f4d JK |
165 | --informative-errors:: |
166 | --no-informative-errors:: | |
167 | When informative errors are turned on, git-daemon will report | |
168 | more verbose errors to the client, differentiating conditions | |
169 | like "no such repository" from "repository not exported". This | |
170 | is more convenient for clients, but may leak information about | |
171 | the existence of unexported repositories. When informative | |
172 | errors are not enabled, all errors report "access denied" to the | |
173 | client. The default is --no-informative-errors. | |
174 | ||
93741e4a JH |
175 | --access-hook=<path>:: |
176 | Every time a client connects, first run an external command | |
177 | specified by the <path> with service name (e.g. "upload-pack"), | |
178 | path to the repository, hostname (%H), canonical hostname | |
179 | (%CH), ip address (%IP), and tcp port (%P) as its command line | |
180 | arguments. The external command can decide to decline the | |
181 | service by exiting with a non-zero status (or to allow it by | |
182 | exiting with a zero status). It can also look at the $REMOTE_ADDR | |
183 | and $REMOTE_PORT environment variables to learn about the | |
184 | requestor when making this decision. | |
185 | + | |
186 | The external command can optionally write a single line to its | |
187 | standard output to be sent to the requestor as an error message when | |
188 | it declines the service. | |
189 | ||
4dbd1352 AE |
190 | <directory>:: |
191 | A directory to add to the whitelist of allowed directories. Unless | |
192 | --strict-paths is specified this will also include subdirectories | |
193 | of each named directory. | |
194 | ||
355f5412 JH |
195 | SERVICES |
196 | -------- | |
197 | ||
bdd73795 JH |
198 | These services can be globally enabled/disabled using the |
199 | command line options of this command. If a finer-grained | |
0b444cdb | 200 | control is desired (e.g. to allow 'git archive' to be run |
bdd73795 JH |
201 | against only in a few selected repositories the daemon serves), |
202 | the per-repository configuration file can be used to enable or | |
203 | disable them. | |
204 | ||
355f5412 | 205 | upload-pack:: |
0b444cdb | 206 | This serves 'git fetch-pack' and 'git ls-remote' |
355f5412 JH |
207 | clients. It is enabled by default, but a repository can |
208 | disable it by setting `daemon.uploadpack` configuration | |
209 | item to `false`. | |
210 | ||
e2b1d1cc | 211 | upload-archive:: |
0b444cdb | 212 | This serves 'git archive --remote'. It is disabled by |
bdd73795 | 213 | default, but a repository can enable it by setting |
74190d23 | 214 | `daemon.uploadarch` configuration item to `true`. |
bdd73795 JH |
215 | |
216 | receive-pack:: | |
0b444cdb | 217 | This serves 'git send-pack' clients, allowing anonymous |
bdd73795 JH |
218 | push. It is disabled by default, as there is _no_ |
219 | authentication in the protocol (in other words, anybody | |
220 | can push anything into the repository, including removal | |
221 | of refs). This is solely meant for a closed LAN setting | |
222 | where everybody is friendly. This service can be | |
c6056fbc | 223 | enabled by setting `daemon.receivepack` configuration item to |
bdd73795 | 224 | `true`. |
e2b1d1cc | 225 | |
49ba83fb JL |
226 | EXAMPLES |
227 | -------- | |
f8a5da6d CC |
228 | We assume the following in /etc/services:: |
229 | + | |
230 | ------------ | |
231 | $ grep 9418 /etc/services | |
232 | git 9418/tcp # Git Version Control System | |
233 | ------------ | |
234 | ||
0b444cdb TR |
235 | 'git daemon' as inetd server:: |
236 | To set up 'git daemon' as an inetd service that handles any | |
49ba83fb JL |
237 | repository under the whitelisted set of directories, /pub/foo |
238 | and /pub/bar, place an entry like the following into | |
239 | /etc/inetd all on one line: | |
240 | + | |
241 | ------------------------------------------------ | |
963a653f JN |
242 | git stream tcp nowait nobody /usr/bin/git |
243 | git daemon --inetd --verbose --export-all | |
49ba83fb JL |
244 | /pub/foo /pub/bar |
245 | ------------------------------------------------ | |
246 | ||
247 | ||
0b444cdb TR |
248 | 'git daemon' as inetd server for virtual hosts:: |
249 | To set up 'git daemon' as an inetd service that handles | |
49ba83fb JL |
250 | repositories for different virtual hosts, `www.example.com` |
251 | and `www.example.org`, place an entry like the following into | |
252 | `/etc/inetd` all on one line: | |
253 | + | |
254 | ------------------------------------------------ | |
963a653f JN |
255 | git stream tcp nowait nobody /usr/bin/git |
256 | git daemon --inetd --verbose --export-all | |
49ba83fb JL |
257 | --interpolated-path=/pub/%H%D |
258 | /pub/www.example.org/software | |
259 | /pub/www.example.com/software | |
260 | /software | |
261 | ------------------------------------------------ | |
262 | + | |
263 | In this example, the root-level directory `/pub` will contain | |
264 | a subdirectory for each virtual host name supported. | |
265 | Further, both hosts advertise repositories simply as | |
266 | `git://www.example.com/software/repo.git`. For pre-1.4.0 | |
267 | clients, a symlink from `/software` into the appropriate | |
268 | default repository could be made as well. | |
269 | ||
270 | ||
0b444cdb TR |
271 | 'git daemon' as regular daemon for virtual hosts:: |
272 | To set up 'git daemon' as a regular, non-inetd service that | |
dd467629 JL |
273 | handles repositories for multiple virtual hosts based on |
274 | their IP addresses, start the daemon like this: | |
275 | + | |
276 | ------------------------------------------------ | |
963a653f | 277 | git daemon --verbose --export-all |
dd467629 JL |
278 | --interpolated-path=/pub/%IP/%D |
279 | /pub/192.168.1.200/software | |
280 | /pub/10.10.220.23/software | |
281 | ------------------------------------------------ | |
282 | + | |
283 | In this example, the root-level directory `/pub` will contain | |
284 | a subdirectory for each virtual host IP address supported. | |
285 | Repositories can still be accessed by hostname though, assuming | |
286 | they correspond to these IP addresses. | |
287 | ||
f368f5a6 | 288 | selectively enable/disable services per repository:: |
0b444cdb | 289 | To enable 'git archive --remote' and disable 'git fetch' against |
f368f5a6 JH |
290 | a repository, have the following in the configuration file in the |
291 | repository (that is the file 'config' next to 'HEAD', 'refs' and | |
292 | 'objects'). | |
bdd73795 JH |
293 | + |
294 | ---------------------------------------------------------------- | |
f368f5a6 JH |
295 | [daemon] |
296 | uploadpack = false | |
74190d23 | 297 | uploadarch = true |
bdd73795 JH |
298 | ---------------------------------------------------------------- |
299 | ||
300 | ||
53ffb878 JH |
301 | ENVIRONMENT |
302 | ----------- | |
0b444cdb | 303 | 'git daemon' will set REMOTE_ADDR to the IP address of the client |
53ffb878 JH |
304 | that connected to it, if the IP address is available. REMOTE_ADDR will |
305 | be available in the environment of hooks called when | |
306 | services are performed. | |
307 | ||
7fc9d69f JH |
308 | GIT |
309 | --- | |
9e1f0a85 | 310 | Part of the linkgit:git[1] suite |