]>
Commit | Line | Data |
---|---|---|
2f4038ab SP |
1 | git-http-backend(1) |
2 | =================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-http-backend - Server side implementation of Git over HTTP | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
0b444cdb | 11 | 'git http-backend' |
2f4038ab SP |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
15 | A simple CGI program to serve the contents of a Git repository to Git | |
16 | clients accessing the repository over http:// and https:// protocols. | |
6a5d0b0a | 17 | The program supports clients fetching using both the smart HTTP protocol |
b9af4ab3 | 18 | and the backwards-compatible dumb HTTP protocol, as well as clients |
295d81b9 JK |
19 | pushing using the smart HTTP protocol. It also supports Git's |
20 | more-efficient "v2" protocol if properly configured; see the | |
21 | discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below. | |
2f4038ab | 22 | |
8b2bd7cd | 23 | It verifies that the directory has the magic file |
2de9b711 | 24 | "git-daemon-export-ok", and it will refuse to export any Git directory |
8b2bd7cd | 25 | that hasn't explicitly been marked for export this way (unless the |
47d81b5c | 26 | `GIT_HTTP_EXPORT_ALL` environmental variable is set). |
8b2bd7cd | 27 | |
2f4038ab | 28 | By default, only the `upload-pack` service is enabled, which serves |
0b444cdb TR |
29 | 'git fetch-pack' and 'git ls-remote' clients, which are invoked from |
30 | 'git fetch', 'git pull', and 'git clone'. If the client is authenticated, | |
31 | the `receive-pack` service is enabled, which serves 'git send-pack' | |
32 | clients, which is invoked from 'git push'. | |
2f4038ab | 33 | |
556cfa3b SP |
34 | SERVICES |
35 | -------- | |
36 | These services can be enabled/disabled using the per-repository | |
37 | configuration file: | |
38 | ||
5abb013b | 39 | http.getanyfile:: |
09f53b16 | 40 | This serves Git clients older than version 1.6.6 that are unable to use the |
5abb013b SP |
41 | upload pack service. When enabled, clients are able to read |
42 | any file within the repository, including objects that are | |
43 | no longer reachable from a branch but are still present. | |
44 | It is enabled by default, but a repository can disable it | |
45 | by setting this configuration item to `false`. | |
46 | ||
556cfa3b | 47 | http.uploadpack:: |
0b444cdb | 48 | This serves 'git fetch-pack' and 'git ls-remote' clients. |
556cfa3b SP |
49 | It is enabled by default, but a repository can disable it |
50 | by setting this configuration item to `false`. | |
51 | ||
52 | http.receivepack:: | |
0b444cdb | 53 | This serves 'git send-pack' clients, allowing push. It is |
556cfa3b SP |
54 | disabled by default for anonymous users, and enabled by |
55 | default for users authenticated by the web server. It can be | |
56 | disabled by setting this item to `false`, or enabled for all | |
57 | users, including anonymous users, by setting it to `true`. | |
58 | ||
2f4038ab SP |
59 | URL TRANSLATION |
60 | --------------- | |
0b444cdb | 61 | To determine the location of the repository on disk, 'git http-backend' |
917adc03 ML |
62 | concatenates the environment variables PATH_INFO, which is set |
63 | automatically by the web server, and GIT_PROJECT_ROOT, which must be set | |
64 | manually in the web server configuration. If GIT_PROJECT_ROOT is not | |
0b444cdb | 65 | set, 'git http-backend' reads PATH_TRANSLATED, which is also set |
917adc03 | 66 | automatically by the web server. |
2f4038ab SP |
67 | |
68 | EXAMPLES | |
69 | -------- | |
d595bdc1 JK |
70 | All of the following examples map `http://$hostname/git/foo/bar.git` |
71 | to `/var/www/git/foo/bar.git`. | |
2f4038ab SP |
72 | |
73 | Apache 2.x:: | |
917adc03 ML |
74 | Ensure mod_cgi, mod_alias, and mod_env are enabled, set |
75 | GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and | |
76 | create a ScriptAlias to the CGI: | |
2f4038ab SP |
77 | + |
78 | ---------------------------------------------------------------- | |
917adc03 | 79 | SetEnv GIT_PROJECT_ROOT /var/www/git |
8b2bd7cd | 80 | SetEnv GIT_HTTP_EXPORT_ALL |
917adc03 | 81 | ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ |
295d81b9 JK |
82 | |
83 | # This is not strictly necessary using Apache and a modern version of | |
84 | # git-http-backend, as the webserver will pass along the header in the | |
85 | # environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into | |
86 | # GIT_PROTOCOL. But you may need this line (or something similar if you | |
87 | # are using a different webserver), or if you want to support older Git | |
88 | # versions that did not do that copying. | |
89 | # | |
90 | # Having the webserver set up GIT_PROTOCOL is perfectly fine even with | |
91 | # modern versions (and will take precedence over HTTP_GIT_PROTOCOL, | |
92 | # which means it can be used to override the client's request). | |
93 | SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0 | |
2f4038ab SP |
94 | ---------------------------------------------------------------- |
95 | + | |
556cfa3b | 96 | To enable anonymous read access but authenticated write access, |
b0808819 JK |
97 | require authorization for both the initial ref advertisement (which we |
98 | detect as a push via the service parameter in the query string), and the | |
99 | receive-pack invocation itself: | |
100 | + | |
101 | ---------------------------------------------------------------- | |
102 | RewriteCond %{QUERY_STRING} service=git-receive-pack [OR] | |
103 | RewriteCond %{REQUEST_URI} /git-receive-pack$ | |
104 | RewriteRule ^/git/ - [E=AUTHREQUIRED:yes] | |
105 | ||
106 | <LocationMatch "^/git/"> | |
107 | Order Deny,Allow | |
108 | Deny from env=AUTHREQUIRED | |
109 | ||
110 | AuthType Basic | |
111 | AuthName "Git Access" | |
112 | Require group committers | |
113 | Satisfy Any | |
114 | ... | |
115 | </LocationMatch> | |
116 | ---------------------------------------------------------------- | |
117 | + | |
118 | If you do not have `mod_rewrite` available to match against the query | |
119 | string, it is sufficient to just protect `git-receive-pack` itself, | |
120 | like: | |
556cfa3b SP |
121 | + |
122 | ---------------------------------------------------------------- | |
f5ba2d18 | 123 | <LocationMatch "^/git/.*/git-receive-pack$"> |
556cfa3b SP |
124 | AuthType Basic |
125 | AuthName "Git Access" | |
126 | Require group committers | |
127 | ... | |
128 | </LocationMatch> | |
129 | ---------------------------------------------------------------- | |
130 | + | |
fdae1910 JK |
131 | In this mode, the server will not request authentication until the |
132 | client actually starts the object negotiation phase of the push, rather | |
133 | than during the initial contact. For this reason, you must also enable | |
134 | the `http.receivepack` config option in any repositories that should | |
135 | accept a push. The default behavior, if `http.receivepack` is not set, | |
136 | is to reject any pushes by unauthenticated users; the initial request | |
137 | will therefore report `403 Forbidden` to the client, without even giving | |
138 | an opportunity for authentication. | |
139 | + | |
917adc03 | 140 | To require authentication for both reads and writes, use a Location |
2f4038ab SP |
141 | directive around the repository, or one of its parent directories: |
142 | + | |
143 | ---------------------------------------------------------------- | |
917adc03 | 144 | <Location /git/private> |
2f4038ab SP |
145 | AuthType Basic |
146 | AuthName "Private Git Access" | |
147 | Require group committers | |
148 | ... | |
917adc03 | 149 | </Location> |
2f4038ab | 150 | ---------------------------------------------------------------- |
8127f778 ML |
151 | + |
152 | To serve gitweb at the same url, use a ScriptAliasMatch to only | |
0b444cdb | 153 | those URLs that 'git http-backend' can handle, and forward the |
8127f778 ML |
154 | rest to gitweb: |
155 | + | |
156 | ---------------------------------------------------------------- | |
157 | ScriptAliasMatch \ | |
158 | "(?x)^/git/(.*/(HEAD | \ | |
159 | info/refs | \ | |
160 | objects/(info/[^/]+ | \ | |
161 | [0-9a-f]{2}/[0-9a-f]{38} | \ | |
162 | pack/pack-[0-9a-f]{40}\.(pack|idx)) | \ | |
163 | git-(upload|receive)-pack))$" \ | |
164 | /usr/libexec/git-core/git-http-backend/$1 | |
165 | ||
166 | ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ | |
167 | ---------------------------------------------------------------- | |
d49483f0 JT |
168 | + |
169 | To serve multiple repositories from different linkgit:gitnamespaces[7] in a | |
170 | single repository: | |
171 | + | |
172 | ---------------------------------------------------------------- | |
173 | SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1 | |
174 | ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1 | |
175 | ---------------------------------------------------------------- | |
2f4038ab SP |
176 | |
177 | Accelerated static Apache 2.x:: | |
178 | Similar to the above, but Apache can be used to return static | |
8d75a1d1 | 179 | files that are stored on disk. On many systems this may |
2f4038ab SP |
180 | be more efficient as Apache can ask the kernel to copy the |
181 | file contents from the file system directly to the network: | |
182 | + | |
183 | ---------------------------------------------------------------- | |
917adc03 | 184 | SetEnv GIT_PROJECT_ROOT /var/www/git |
2f4038ab | 185 | |
0ebb1fa7 ML |
186 | AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/www/git/$1 |
187 | AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1 | |
188 | ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ | |
2f4038ab | 189 | ---------------------------------------------------------------- |
8127f778 ML |
190 | + |
191 | This can be combined with the gitweb configuration: | |
192 | + | |
193 | ---------------------------------------------------------------- | |
194 | SetEnv GIT_PROJECT_ROOT /var/www/git | |
195 | ||
196 | AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/www/git/$1 | |
197 | AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1 | |
198 | ScriptAliasMatch \ | |
199 | "(?x)^/git/(.*/(HEAD | \ | |
200 | info/refs | \ | |
201 | objects/info/[^/]+ | \ | |
202 | git-(upload|receive)-pack))$" \ | |
203 | /usr/libexec/git-core/git-http-backend/$1 | |
204 | ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ | |
205 | ---------------------------------------------------------------- | |
2f4038ab | 206 | |
3813a33d | 207 | Lighttpd:: |
5df05146 | 208 | Ensure that `mod_cgi`, `mod_alias`, `mod_auth`, `mod_setenv` are |
3813a33d JK |
209 | loaded, then set `GIT_PROJECT_ROOT` appropriately and redirect |
210 | all requests to the CGI: | |
211 | + | |
212 | ---------------------------------------------------------------- | |
213 | alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" ) | |
214 | $HTTP["url"] =~ "^/git" { | |
215 | cgi.assign = ("" => "") | |
216 | setenv.add-environment = ( | |
217 | "GIT_PROJECT_ROOT" => "/var/www/git", | |
218 | "GIT_HTTP_EXPORT_ALL" => "" | |
219 | ) | |
220 | } | |
221 | ---------------------------------------------------------------- | |
222 | + | |
223 | To enable anonymous read access but authenticated write access: | |
224 | + | |
225 | ---------------------------------------------------------------- | |
226 | $HTTP["querystring"] =~ "service=git-receive-pack" { | |
227 | include "git-auth.conf" | |
228 | } | |
229 | $HTTP["url"] =~ "^/git/.*/git-receive-pack$" { | |
230 | include "git-auth.conf" | |
231 | } | |
232 | ---------------------------------------------------------------- | |
233 | + | |
234 | where `git-auth.conf` looks something like: | |
235 | + | |
236 | ---------------------------------------------------------------- | |
237 | auth.require = ( | |
238 | "/" => ( | |
239 | "method" => "basic", | |
240 | "realm" => "Git Access", | |
241 | "require" => "valid-user" | |
242 | ) | |
243 | ) | |
244 | # ...and set up auth.backend here | |
245 | ---------------------------------------------------------------- | |
246 | + | |
3813a33d JK |
247 | To require authentication for both reads and writes: |
248 | + | |
249 | ---------------------------------------------------------------- | |
250 | $HTTP["url"] =~ "^/git/private" { | |
251 | include "git-auth.conf" | |
252 | } | |
253 | ---------------------------------------------------------------- | |
254 | ||
2f4038ab SP |
255 | |
256 | ENVIRONMENT | |
257 | ----------- | |
47d81b5c | 258 | 'git http-backend' relies upon the `CGI` environment variables set |
2f4038ab SP |
259 | by the invoking web server, including: |
260 | ||
917adc03 | 261 | * PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) |
2f4038ab SP |
262 | * REMOTE_USER |
263 | * REMOTE_ADDR | |
264 | * CONTENT_TYPE | |
265 | * QUERY_STRING | |
266 | * REQUEST_METHOD | |
267 | ||
47d81b5c | 268 | The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to |
8b2bd7cd TC |
269 | 'git-http-backend' to bypass the check for the "git-daemon-export-ok" |
270 | file in each repository before allowing export of that repository. | |
271 | ||
6bc0cb51 JK |
272 | The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the |
273 | `http.maxRequestBuffer` config variable) may be set to change the | |
274 | largest ref negotiation request that git will handle during a fetch; any | |
275 | fetch requiring a larger buffer will not succeed. This value should not | |
276 | normally need to be changed, but may be helpful if you are fetching from | |
277 | a repository with an extremely large number of refs. The value can be | |
278 | specified with a unit (e.g., `100M` for 100 megabytes). The default is | |
279 | 10 megabytes. | |
280 | ||
295d81b9 JK |
281 | Clients may probe for optional protocol capabilities (like the v2 |
282 | protocol) using the `Git-Protocol` HTTP header. In order to support | |
283 | these, the contents of that header must appear in the `GIT_PROTOCOL` | |
284 | environment variable. Most webservers will pass this header to the CGI | |
285 | via the `HTTP_GIT_PROTOCOL` variable, and `git-http-backend` will | |
286 | automatically copy that to `GIT_PROTOCOL`. However, some webservers may | |
287 | be more selective about which headers they'll pass, in which case they | |
288 | need to be configured explicitly (see the mention of `Git-Protocol` in | |
289 | the Apache config from the earlier EXAMPLES section). | |
290 | ||
556cfa3b SP |
291 | The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and |
292 | GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}', | |
293 | ensuring that any reflogs created by 'git-receive-pack' contain some | |
294 | identifying information of the remote user who performed the push. | |
295 | ||
47d81b5c | 296 | All `CGI` environment variables are available to each of the hooks |
556cfa3b SP |
297 | invoked by the 'git-receive-pack'. |
298 | ||
2f4038ab SP |
299 | GIT |
300 | --- | |
301 | Part of the linkgit:git[1] suite |