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