| 1 | git-daemon(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-daemon - A really simple server for Git repositories |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [synopsis] |
| 11 | git daemon [--verbose] [--syslog] [--export-all] |
| 12 | [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] |
| 13 | [--strict-paths] [--base-path=<path>] [--base-path-relaxed] |
| 14 | [--user-path | --user-path=<path>] |
| 15 | [--interpolated-path=<pathtemplate>] |
| 16 | [--reuseaddr] [--detach] [--pid-file=<file>] |
| 17 | [--enable=<service>] [--disable=<service>] |
| 18 | [--allow-override=<service>] [--forbid-override=<service>] |
| 19 | [--access-hook=<path>] [--[no-]informative-errors] |
| 20 | [--inetd | |
| 21 | [--listen=<host-or-ipaddr>] [--port=<n>] |
| 22 | [--user=<user> [--group=<group>]]] |
| 23 | [--log-destination=(stderr|syslog|none)] |
| 24 | [<directory>...] |
| 25 | |
| 26 | DESCRIPTION |
| 27 | ----------- |
| 28 | A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" |
| 29 | aka 9418. It waits for a connection asking for a service, and will serve |
| 30 | that service if it is enabled. |
| 31 | |
| 32 | It verifies that the directory has the magic file "git-daemon-export-ok", and |
| 33 | it will refuse to export any Git directory that hasn't explicitly been marked |
| 34 | for export this way (unless the `--export-all` parameter is specified). If you |
| 35 | pass some directory paths as `git daemon` arguments, the offers are limited to |
| 36 | repositories within those directories. |
| 37 | |
| 38 | By default, only `upload-pack` service is enabled, which serves |
| 39 | `git fetch-pack` and `git ls-remote` clients, which are invoked |
| 40 | from `git fetch`, `git pull`, and `git clone`. |
| 41 | |
| 42 | This is ideally suited for read-only updates, i.e., pulling from |
| 43 | Git repositories. |
| 44 | |
| 45 | An `upload-archive` also exists to serve `git archive`. |
| 46 | |
| 47 | OPTIONS |
| 48 | ------- |
| 49 | `--strict-paths`:: |
| 50 | Match paths exactly (i.e. don't allow "/foo/repo" when the real path is |
| 51 | "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. |
| 52 | `git daemon` will refuse to start when this option is enabled and no |
| 53 | directory arguments are provided. |
| 54 | |
| 55 | `--base-path=<path>`:: |
| 56 | Remap all the path requests as relative to the given path. |
| 57 | This is sort of "Git root" - if you run `git daemon` with |
| 58 | `--base-path=/srv/git` on `example.com`, then if you later try |
| 59 | to pull from `git://example.com/hello.git`, `git daemon` will |
| 60 | interpret the path as `/srv/git/hello.git`. |
| 61 | |
| 62 | `--base-path-relaxed`:: |
| 63 | If `--base-path` is enabled and repo lookup fails, with this option |
| 64 | `git daemon` will attempt to lookup without prefixing the base path. |
| 65 | This is useful for switching to `--base-path` usage, while still |
| 66 | allowing the old paths. |
| 67 | |
| 68 | `--interpolated-path=<pathtemplate>`:: |
| 69 | To support virtual hosting, an interpolated path template can be |
| 70 | used to dynamically construct alternate paths. The template |
| 71 | supports `%H` for the target hostname as supplied by the client but |
| 72 | converted to all lowercase, `%CH` for the canonical hostname, |
| 73 | `%IP` for the server's IP address, `%P` for the port number, |
| 74 | and `%D` for the absolute path of the named repository. |
| 75 | After interpolation, the path is validated against the directory |
| 76 | list. |
| 77 | |
| 78 | `--export-all`:: |
| 79 | Allow pulling from all directories that look like Git repositories |
| 80 | (have the 'objects' and 'refs' subdirectories), even if they |
| 81 | do not have the `git-daemon-export-ok` file. |
| 82 | |
| 83 | `--inetd`:: |
| 84 | Have the server run as an inetd service. Implies `--syslog` (may |
| 85 | be overridden with `--log-destination=`). |
| 86 | Incompatible with `--detach`, `--port`, `--listen`, `--user` and |
| 87 | `--group` options. |
| 88 | |
| 89 | `--listen=<host-or-ipaddr>`:: |
| 90 | Listen on a specific IP address or hostname. IP addresses can |
| 91 | be either an IPv4 address or an IPv6 address if supported. If IPv6 |
| 92 | is not supported, then `--listen=<hostname>` is also not supported |
| 93 | and `--listen` must be given an IPv4 address. |
| 94 | Can be given more than once. |
| 95 | Incompatible with `--inetd` option. |
| 96 | |
| 97 | `--port=<n>`:: |
| 98 | Listen on an alternative port. Incompatible with `--inetd` option. |
| 99 | |
| 100 | `--init-timeout=<n>`:: |
| 101 | Timeout (in seconds) between the moment the connection is established |
| 102 | and the client request is received (typically a rather low value, since |
| 103 | that should be basically immediate). |
| 104 | |
| 105 | `--timeout=<n>`:: |
| 106 | Timeout (in seconds) for specific client sub-requests. This includes |
| 107 | the time it takes for the server to process the sub-request and the |
| 108 | time spent waiting for the next client's request. |
| 109 | |
| 110 | `--max-connections=<n>`:: |
| 111 | Maximum number of concurrent clients, defaults to 32. Set it to |
| 112 | zero for no limit. |
| 113 | |
| 114 | `--syslog`:: |
| 115 | Short for `--log-destination=syslog`. |
| 116 | |
| 117 | `--log-destination=<destination>`:: |
| 118 | Send log messages to the specified destination. |
| 119 | Note that this option does not imply `--verbose`, |
| 120 | thus by default only error conditions will be logged. |
| 121 | The _<destination>_ must be one of: |
| 122 | + |
| 123 | -- |
| 124 | `stderr`:: |
| 125 | Write to standard error. |
| 126 | Note that if `--detach` is specified, |
| 127 | the process disconnects from the real standard error, |
| 128 | making this destination effectively equivalent to `none`. |
| 129 | `syslog`:: |
| 130 | Write to syslog, using the `git-daemon` identifier. |
| 131 | `none`:: |
| 132 | Disable all logging. |
| 133 | -- |
| 134 | + |
| 135 | The default destination is `syslog` if `--inetd` or `--detach` is specified, |
| 136 | otherwise `stderr`. |
| 137 | |
| 138 | `--user-path`:: |
| 139 | `--user-path=<path>`:: |
| 140 | Allow {tilde}user notation to be used in requests. When |
| 141 | specified with no parameter, a request to |
| 142 | git://host/{tilde}alice/foo is taken as a request to access |
| 143 | 'foo' repository in the home directory of user `alice`. |
| 144 | If `--user-path=<path>` is specified, the same request is |
| 145 | taken as a request to access `<path>/foo` repository in |
| 146 | the home directory of user `alice`. |
| 147 | |
| 148 | `--verbose`:: |
| 149 | Log details about the incoming connections and requested files. |
| 150 | |
| 151 | `--reuseaddr`:: |
| 152 | Use `SO_REUSEADDR` when binding the listening socket. |
| 153 | This allows the server to restart without waiting for |
| 154 | old connections to time out. |
| 155 | |
| 156 | `--detach`:: |
| 157 | Detach from the shell. Implies `--syslog`. |
| 158 | |
| 159 | `--pid-file=<file>`:: |
| 160 | Save the process id in _<file>_. Ignored when the daemon |
| 161 | is run under `--inetd`. |
| 162 | |
| 163 | `--user=<user>`:: |
| 164 | `--group=<group>`:: |
| 165 | Change daemon's uid and gid before entering the service loop. |
| 166 | When only `--user` is given without `--group`, the |
| 167 | primary group ID for the user is used. The values of |
| 168 | the option are given to `getpwnam(3)` and `getgrnam(3)` |
| 169 | and numeric IDs are not supported. |
| 170 | + |
| 171 | Giving these options is an error when used with `--inetd`; use |
| 172 | the facility of inet daemon to achieve the same before spawning |
| 173 | `git daemon` if needed. |
| 174 | + |
| 175 | Like many programs that switch user id, the daemon does not reset |
| 176 | environment variables such as `HOME` when it runs git programs, |
| 177 | e.g. `upload-pack` and `receive-pack`. When using this option, you |
| 178 | may also want to set and export `HOME` to point at the home |
| 179 | directory of _<user>_ before starting the daemon, and make sure any |
| 180 | Git configuration files in that directory are readable by _<user>_. |
| 181 | |
| 182 | `--enable=<service>`:: |
| 183 | `--disable=<service>`:: |
| 184 | Enable/disable the service site-wide per default. Note |
| 185 | that a service disabled site-wide can still be enabled |
| 186 | per repository if it is marked overridable and the |
| 187 | repository enables the service with a configuration |
| 188 | item. |
| 189 | |
| 190 | `--allow-override=<service>`:: |
| 191 | `--forbid-override=<service>`:: |
| 192 | Allow/forbid overriding the site-wide default with per |
| 193 | repository configuration. By default, all the services |
| 194 | may be overridden. |
| 195 | |
| 196 | `--informative-errors`:: |
| 197 | `--no-informative-errors`:: |
| 198 | When informative errors are turned on, git-daemon will report |
| 199 | more verbose errors to the client, differentiating conditions |
| 200 | like "no such repository" from "repository not exported". This |
| 201 | is more convenient for clients, but may leak information about |
| 202 | the existence of unexported repositories. When informative |
| 203 | errors are not enabled, all errors report "access denied" to the |
| 204 | client. The default is `--no-informative-errors`. |
| 205 | |
| 206 | `--access-hook=<path>`:: |
| 207 | Every time a client connects, first run an external command |
| 208 | specified by the <path> with service name (e.g. "upload-pack"), |
| 209 | path to the repository, hostname (`%H`), canonical hostname |
| 210 | (`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line |
| 211 | arguments. The external command can decide to decline the |
| 212 | service by exiting with a non-zero status (or to allow it by |
| 213 | exiting with a zero status). It can also look at the $REMOTE_ADDR |
| 214 | and `$REMOTE_PORT` environment variables to learn about the |
| 215 | requestor when making this decision. |
| 216 | + |
| 217 | The external command can optionally write a single line to its |
| 218 | standard output to be sent to the requestor as an error message when |
| 219 | it declines the service. |
| 220 | |
| 221 | _<directory>_:: |
| 222 | The remaining arguments provide a list of directories. If any |
| 223 | directories are specified, then the `git-daemon` process will |
| 224 | serve a requested directory only if it is contained in one of |
| 225 | these directories. If `--strict-paths` is specified, then the |
| 226 | requested directory must match one of these directories exactly. |
| 227 | |
| 228 | SERVICES |
| 229 | -------- |
| 230 | |
| 231 | These services can be globally enabled/disabled using the |
| 232 | command-line options of this command. If finer-grained |
| 233 | control is desired (e.g. to allow `git archive` to be run |
| 234 | against only in a few selected repositories the daemon serves), |
| 235 | the per-repository configuration file can be used to enable or |
| 236 | disable them. |
| 237 | |
| 238 | upload-pack:: |
| 239 | This serves `git fetch-pack` and `git ls-remote` |
| 240 | clients. It is enabled by default, but a repository can |
| 241 | disable it by setting `daemon.uploadpack` configuration |
| 242 | item to `false`. |
| 243 | |
| 244 | upload-archive:: |
| 245 | This serves `git archive --remote`. It is disabled by |
| 246 | default, but a repository can enable it by setting |
| 247 | `daemon.uploadarch` configuration item to `true`. |
| 248 | |
| 249 | receive-pack:: |
| 250 | This serves `git send-pack` clients, allowing anonymous |
| 251 | push. It is disabled by default, as there is _no_ |
| 252 | authentication in the protocol (in other words, anybody |
| 253 | can push anything into the repository, including removal |
| 254 | of refs). This is solely meant for a closed LAN setting |
| 255 | where everybody is friendly. This service can be |
| 256 | enabled by setting `daemon.receivepack` configuration item to |
| 257 | `true`. |
| 258 | |
| 259 | EXAMPLES |
| 260 | -------- |
| 261 | We assume the following in /etc/services:: |
| 262 | + |
| 263 | ------------ |
| 264 | $ grep 9418 /etc/services |
| 265 | git 9418/tcp # Git Version Control System |
| 266 | ------------ |
| 267 | |
| 268 | 'git daemon' as inetd server:: |
| 269 | To set up 'git daemon' as an inetd service that handles any |
| 270 | repository within `/pub/foo` or `/pub/bar`, place an entry like |
| 271 | the following into `/etc/inetd` all on one line: |
| 272 | + |
| 273 | ------------------------------------------------ |
| 274 | git stream tcp nowait nobody /usr/bin/git |
| 275 | git daemon --inetd --verbose --export-all |
| 276 | /pub/foo /pub/bar |
| 277 | ------------------------------------------------ |
| 278 | |
| 279 | |
| 280 | 'git daemon' as inetd server for virtual hosts:: |
| 281 | To set up 'git daemon' as an inetd service that handles |
| 282 | repositories for different virtual hosts, `www.example.com` |
| 283 | and `www.example.org`, place an entry like the following into |
| 284 | `/etc/inetd` all on one line: |
| 285 | + |
| 286 | ------------------------------------------------ |
| 287 | git stream tcp nowait nobody /usr/bin/git |
| 288 | git daemon --inetd --verbose --export-all |
| 289 | --interpolated-path=/pub/%H%D |
| 290 | /pub/www.example.org/software |
| 291 | /pub/www.example.com/software |
| 292 | /software |
| 293 | ------------------------------------------------ |
| 294 | + |
| 295 | In this example, the root-level directory `/pub` will contain |
| 296 | a subdirectory for each virtual host name supported. |
| 297 | Further, both hosts advertise repositories simply as |
| 298 | `git://www.example.com/software/repo.git`. For pre-1.4.0 |
| 299 | clients, a symlink from `/software` into the appropriate |
| 300 | default repository could be made as well. |
| 301 | |
| 302 | |
| 303 | 'git daemon' as regular daemon for virtual hosts:: |
| 304 | To set up `git daemon` as a regular, non-inetd service that |
| 305 | handles repositories for multiple virtual hosts based on |
| 306 | their IP addresses, start the daemon like this: |
| 307 | + |
| 308 | ------------------------------------------------ |
| 309 | git daemon --verbose --export-all |
| 310 | --interpolated-path=/pub/%IP/%D |
| 311 | /pub/192.168.1.200/software |
| 312 | /pub/10.10.220.23/software |
| 313 | ------------------------------------------------ |
| 314 | + |
| 315 | In this example, the root-level directory `/pub` will contain |
| 316 | a subdirectory for each virtual host IP address supported. |
| 317 | Repositories can still be accessed by hostname though, assuming |
| 318 | they correspond to these IP addresses. |
| 319 | |
| 320 | selectively enable/disable services per repository:: |
| 321 | To enable `git archive --remote` and disable `git fetch` against |
| 322 | a repository, have the following in the configuration file in the |
| 323 | repository (that is the file 'config' next to `HEAD`, 'refs' and |
| 324 | 'objects'). |
| 325 | + |
| 326 | ---------------------------------------------------------------- |
| 327 | [daemon] |
| 328 | uploadpack = false |
| 329 | uploadarch = true |
| 330 | ---------------------------------------------------------------- |
| 331 | |
| 332 | |
| 333 | ENVIRONMENT |
| 334 | ----------- |
| 335 | `git daemon` will set `REMOTE_ADDR` to the IP address of the client |
| 336 | that connected to it, if the IP address is available. `REMOTE_ADDR` will |
| 337 | be available in the environment of hooks called when |
| 338 | services are performed. |
| 339 | |
| 340 | GIT |
| 341 | --- |
| 342 | Part of the linkgit:git[1] suite |