Documentation: add upload-archive service to git-daemon.
[git/git.git] / Documentation / git-daemon.txt
CommitLineData
7fc9d69f
JH
1git-daemon(1)
2=============
3
4NAME
5----
7bd7f280 6git-daemon - A really simple server for git repositories
7fc9d69f
JH
7
8SYNOPSIS
9--------
353ce815 10[verse]
dd467629 11'git-daemon' [--verbose] [--syslog] [--export-all]
b21c31c9 12 [--timeout=n] [--init-timeout=n] [--strict-paths]
603968d2 13 [--base-path=path] [--user-path | --user-path=path]
49ba83fb 14 [--interpolated-path=pathtemplate]
dd467629 15 [--reuseaddr] [--detach] [--pid-file=file]
355f5412
JH
16 [--enable=service] [--disable=service]
17 [--allow-override=service] [--forbid-override=service]
dd467629
JL
18 [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]
19 [directory...]
7fc9d69f
JH
20
21DESCRIPTION
22-----------
62cd033d 23A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT"
355f5412
JH
24aka 9418. It waits for a connection asking for a service, and will serve
25that service if it is enabled.
7fc9d69f 26
62cd033d
LAS
27It verifies that the directory has the magic file "git-daemon-export-ok", and
28it will refuse to export any git directory that hasn't explicitly been marked
2707da9c
PB
29for export this way (unless the '--export-all' parameter is specified). If you
30pass some directory paths as 'git-daemon' arguments, you can further restrict
31the offers to a whitelist comprising of those.
62cd033d 32
355f5412
JH
33By default, only `upload-pack` service is enabled, which serves
34`git-fetch-pack` and `git-peek-remote` clients that are invoked
35from `git-fetch`, `git-ls-remote`, and `git-clone`.
36
37This is ideally suited for read-only updates, i.e., pulling from
38git repositories.
7fc9d69f 39
e2b1d1cc
CC
40An `upload-archive` also exists to serve `git-archive`.
41
7fc9d69f
JH
42OPTIONS
43-------
ce335fe0 44--strict-paths::
4dbd1352
AE
45 Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
46 "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
47 git-daemon will refuse to start when this option is enabled and no
48 whitelist is specified.
49
b21c31c9
PB
50--base-path::
51 Remap all the path requests as relative to the given path.
52 This is sort of "GIT root" - if you run git-daemon with
53 '--base-path=/srv/git' on example.com, then if you later try to pull
54 'git://example.com/hello.git', `git-daemon` will interpret the path
603968d2 55 as '/srv/git/hello.git'.
b21c31c9 56
49ba83fb
JL
57--interpolated-path=pathtemplate::
58 To support virtual hosting, an interpolated path template can be
59 used to dynamically construct alternate paths. The template
dd467629
JL
60 supports %H for the target hostname as supplied by the client but
61 converted to all lowercase, %CH for the canonical hostname,
62 %IP for the server's IP address, %P for the port number,
49ba83fb 63 and %D for the absolute path of the named repository.
dd467629
JL
64 After interpolation, the path is validated against the directory
65 whitelist.
49ba83fb 66
2707da9c
PB
67--export-all::
68 Allow pulling from all directories that look like GIT repositories
4dbd1352 69 (have the 'objects' and 'refs' subdirectories), even if they
2707da9c
PB
70 do not have the 'git-daemon-export-ok' file.
71
62cd033d 72--inetd::
bce8230d 73 Have the server run as an inetd service. Implies --syslog.
dd467629
JL
74 Incompatible with --port, --listen, --user and --group options.
75
76--listen=host_or_ipaddr::
77 Listen on an a specific IP address or hostname. IP addresses can
78 be either an IPv4 address or an IPV6 address if supported. If IPv6
79 is not supported, then --listen=hostname is also not supported and
80 --listen must be given an IPv4 address.
81 Incompatible with '--inetd' option.
7fc9d69f 82
dd467629
JL
83--port=n::
84 Listen on an alternative port. Incompatible with '--inetd' option.
7fc9d69f 85
2707da9c
PB
86--init-timeout::
87 Timeout between the moment the connection is established and the
88 client request is received (typically a rather low value, since
89 that should be basically immediate).
90
91--timeout::
92 Timeout for specific client sub-requests. This includes the time
93 it takes for the server to process the sub-request and time spent
94 waiting for next client's request.
95
9048fe1c
PB
96--syslog::
97 Log to syslog instead of stderr. Note that this option does not imply
98 --verbose, thus by default only error conditions will be logged.
99
603968d2
JH
100--user-path, --user-path=path::
101 Allow ~user notation to be used in requests. When
102 specified with no parameter, requests to
103 git://host/~alice/foo is taken as a request to access
104 'foo' repository in the home directory of user `alice`.
105 If `--user-path=path` is specified, the same request is
106 taken as a request to access `path/foo` repository in
107 the home directory of user `alice`.
108
b5cf3c8b
PB
109--verbose::
110 Log details about the incoming connections and requested files.
111
6c35119a
ML
112--reuseaddr::
113 Use SO_REUSEADDR when binding the listening socket.
114 This allows the server to restart without waiting for
115 old connections to time out.
116
117--detach::
118 Detach from the shell. Implies --syslog.
119
120--pid-file=file::
121 Save the process id in 'file'.
122
678dac6b
TS
123--user=user, --group=group::
124 Change daemon's uid and gid before entering the service loop.
125 When only `--user` is given without `--group`, the
126 primary group ID for the user is used. The values of
127 the option are given to `getpwnam(3)` and `getgrnam(3)`
128 and numeric IDs are not supported.
129+
130Giving these options is an error when used with `--inetd`; use
131the facility of inet daemon to achieve the same before spawning
132`git-daemon` if needed.
133
355f5412
JH
134--enable-service, --disable-service::
135 Enable/disable the service site-wide per default. Note
136 that a service disabled site-wide can still be enabled
137 per repository if it is marked overridable and the
138 repository enables the service with an configuration
139 item.
140
141--allow-override, --forbid-override::
142 Allow/forbid overriding the site-wide default with per
143 repository configuration. By default, all the services
144 are overridable.
145
4dbd1352
AE
146<directory>::
147 A directory to add to the whitelist of allowed directories. Unless
148 --strict-paths is specified this will also include subdirectories
149 of each named directory.
150
355f5412
JH
151SERVICES
152--------
153
154upload-pack::
155 This serves `git-fetch-pack` and `git-peek-remote`
156 clients. It is enabled by default, but a repository can
157 disable it by setting `daemon.uploadpack` configuration
158 item to `false`.
159
e2b1d1cc
CC
160upload-archive::
161 This serves `git-archive --remote`.
162
49ba83fb
JL
163EXAMPLES
164--------
165git-daemon as inetd server::
166 To set up `git-daemon` as an inetd service that handles any
167 repository under the whitelisted set of directories, /pub/foo
168 and /pub/bar, place an entry like the following into
169 /etc/inetd all on one line:
170+
171------------------------------------------------
172 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 173 git-daemon --inetd --verbose --export-all
49ba83fb
JL
174 /pub/foo /pub/bar
175------------------------------------------------
176
177
178git-daemon as inetd server for virtual hosts::
179 To set up `git-daemon` as an inetd service that handles
180 repositories for different virtual hosts, `www.example.com`
181 and `www.example.org`, place an entry like the following into
182 `/etc/inetd` all on one line:
183+
184------------------------------------------------
185 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 186 git-daemon --inetd --verbose --export-all
49ba83fb
JL
187 --interpolated-path=/pub/%H%D
188 /pub/www.example.org/software
189 /pub/www.example.com/software
190 /software
191------------------------------------------------
192+
193In this example, the root-level directory `/pub` will contain
194a subdirectory for each virtual host name supported.
195Further, both hosts advertise repositories simply as
196`git://www.example.com/software/repo.git`. For pre-1.4.0
197clients, a symlink from `/software` into the appropriate
198default repository could be made as well.
199
200
dd467629
JL
201git-daemon as regular daemon for virtual hosts::
202 To set up `git-daemon` as a regular, non-inetd service that
203 handles repositories for multiple virtual hosts based on
204 their IP addresses, start the daemon like this:
205+
206------------------------------------------------
207 git-daemon --verbose --export-all
208 --interpolated-path=/pub/%IP/%D
209 /pub/192.168.1.200/software
210 /pub/10.10.220.23/software
211------------------------------------------------
212+
213In this example, the root-level directory `/pub` will contain
214a subdirectory for each virtual host IP address supported.
215Repositories can still be accessed by hostname though, assuming
216they correspond to these IP addresses.
217
218
7fc9d69f
JH
219Author
220------
4dbd1352
AE
221Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki
222<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org>
7fc9d69f
JH
223
224Documentation
225--------------
226Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
227
228GIT
229---
a7154e91 230Part of the gitlink:git[7] suite
7fc9d69f 231