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