]>
Commit | Line | Data |
---|---|---|
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] | |
11 | 'git http-backend' | |
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. | |
17 | The program supports clients fetching using both the smart HTTP protocol | |
18 | and the backwards-compatible dumb HTTP protocol, as well as clients | |
19 | pushing using the smart HTTP protocol. | |
20 | ||
21 | It verifies that the directory has the magic file | |
22 | "git-daemon-export-ok", and it will refuse to export any Git directory | |
23 | that hasn't explicitly been marked for export this way (unless the | |
24 | `GIT_HTTP_EXPORT_ALL` environmental variable is set). | |
25 | ||
26 | By default, only the `upload-pack` service is enabled, which serves | |
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'. | |
31 | ||
32 | SERVICES | |
33 | -------- | |
34 | These services can be enabled/disabled using the per-repository | |
35 | configuration file: | |
36 | ||
37 | http.getanyfile:: | |
38 | This serves Git clients older than version 1.6.6 that are unable to use the | |
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 | ||
45 | http.uploadpack:: | |
46 | This serves 'git fetch-pack' and 'git ls-remote' clients. | |
47 | It is enabled by default, but a repository can disable it | |
48 | by setting this configuration item to `false`. | |
49 | ||
50 | http.receivepack:: | |
51 | This serves 'git send-pack' clients, allowing push. It is | |
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 | ||
57 | URL TRANSLATION | |
58 | --------------- | |
59 | To determine the location of the repository on disk, 'git http-backend' | |
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 | |
63 | set, 'git http-backend' reads PATH_TRANSLATED, which is also set | |
64 | automatically by the web server. | |
65 | ||
66 | EXAMPLES | |
67 | -------- | |
68 | All of the following examples map `http://$hostname/git/foo/bar.git` | |
69 | to `/var/www/git/foo/bar.git`. | |
70 | ||
71 | Apache 2.x:: | |
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: | |
75 | + | |
76 | ---------------------------------------------------------------- | |
77 | SetEnv GIT_PROJECT_ROOT /var/www/git | |
78 | SetEnv GIT_HTTP_EXPORT_ALL | |
79 | ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ | |
80 | ---------------------------------------------------------------- | |
81 | + | |
82 | To enable anonymous read access but authenticated write access, | |
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: | |
107 | + | |
108 | ---------------------------------------------------------------- | |
109 | <LocationMatch "^/git/.*/git-receive-pack$"> | |
110 | AuthType Basic | |
111 | AuthName "Git Access" | |
112 | Require group committers | |
113 | ... | |
114 | </LocationMatch> | |
115 | ---------------------------------------------------------------- | |
116 | + | |
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 | + | |
126 | To require authentication for both reads and writes, use a Location | |
127 | directive around the repository, or one of its parent directories: | |
128 | + | |
129 | ---------------------------------------------------------------- | |
130 | <Location /git/private> | |
131 | AuthType Basic | |
132 | AuthName "Private Git Access" | |
133 | Require group committers | |
134 | ... | |
135 | </Location> | |
136 | ---------------------------------------------------------------- | |
137 | + | |
138 | To serve gitweb at the same url, use a ScriptAliasMatch to only | |
139 | those URLs that 'git http-backend' can handle, and forward the | |
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 | ---------------------------------------------------------------- | |
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 | ---------------------------------------------------------------- | |
162 | ||
163 | Accelerated static Apache 2.x:: | |
164 | Similar to the above, but Apache can be used to return static | |
165 | files that are stored on disk. On many systems this may | |
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 | ---------------------------------------------------------------- | |
170 | SetEnv GIT_PROJECT_ROOT /var/www/git | |
171 | ||
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/ | |
175 | ---------------------------------------------------------------- | |
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 | ---------------------------------------------------------------- | |
192 | ||
193 | Lighttpd:: | |
194 | Ensure that `mod_cgi`, `mod_alias`, `mod_auth`, `mod_setenv` are | |
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 | + | |
233 | To require authentication for both reads and writes: | |
234 | + | |
235 | ---------------------------------------------------------------- | |
236 | $HTTP["url"] =~ "^/git/private" { | |
237 | include "git-auth.conf" | |
238 | } | |
239 | ---------------------------------------------------------------- | |
240 | ||
241 | ||
242 | ENVIRONMENT | |
243 | ----------- | |
244 | 'git http-backend' relies upon the `CGI` environment variables set | |
245 | by the invoking web server, including: | |
246 | ||
247 | * PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) | |
248 | * REMOTE_USER | |
249 | * REMOTE_ADDR | |
250 | * CONTENT_TYPE | |
251 | * QUERY_STRING | |
252 | * REQUEST_METHOD | |
253 | ||
254 | The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to | |
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 | ||
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 | ||
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 | ||
272 | All `CGI` environment variables are available to each of the hooks | |
273 | invoked by the 'git-receive-pack'. | |
274 | ||
275 | GIT | |
276 | --- | |
277 | Part of the linkgit:git[1] suite |