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