doc/source/en/TortoiseGit/git_doc/git-daemon.html.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-daemon(1)">\r
   5 <articleinfo>\r
   6     <title>git-daemon(1)</title>\r
   7         <indexterm>\r
   8                 <primary>git-daemon(1)</primary>\r
   9         </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-daemon - A really simple server for git repositories</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git daemon</emphasis> [--verbose] [--syslog] [--export-all]\r
  19              [--timeout=n] [--init-timeout=n] [--max-connections=n]\r
  20              [--strict-paths] [--base-path=path] [--base-path-relaxed]\r
  21              [--user-path | --user-path=path]\r
  22              [--interpolated-path=pathtemplate]\r
  23              [--reuseaddr] [--detach] [--pid-file=file]\r
  24              [--enable=service] [--disable=service]\r
  25              [--allow-override=service] [--forbid-override=service]\r
  26              [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]\r
  27              [directory&#8230;]</literallayout>\r
  28 </blockquote>\r
  29 </simplesect>\r
  30 <simplesect id="_description">\r
  31 <title>DESCRIPTION</title>\r
  32 <simpara>A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT"\r
  33 aka 9418.  It waits for a connection asking for a service, and will serve\r
  34 that service if it is enabled.</simpara>\r
  35 <simpara>It verifies that the directory has the magic file "git-daemon-export-ok", and\r
  36 it will refuse to export any git directory that hasn&#8217;t explicitly been marked\r
  37 for export this way (unless the <emphasis>--export-all</emphasis> parameter is specified). If you\r
  38 pass some directory paths as <emphasis>git-daemon</emphasis> arguments, you can further restrict\r
  39 the offers to a whitelist comprising of those.</simpara>\r
  40 <simpara>By default, only <literal>upload-pack</literal> service is enabled, which serves\r
  41 <emphasis>git-fetch-pack</emphasis> and <emphasis>git-ls-remote</emphasis> clients, which are invoked\r
  42 from <emphasis>git-fetch</emphasis>, <emphasis>git-pull</emphasis>, and <emphasis>git-clone</emphasis>.</simpara>\r
  43 <simpara>This is ideally suited for read-only updates, i.e., pulling from\r
  44 git repositories.</simpara>\r
  45 <simpara>An <literal>upload-archive</literal> also exists to serve <emphasis>git-archive</emphasis>.</simpara>\r
  46 </simplesect>\r
  47 <simplesect id="_options">\r
  48 <title>OPTIONS</title>\r
  49 <variablelist>\r
  50 <varlistentry>\r
  51 <term>\r
  52 --strict-paths\r
  53 </term>\r
  54 <listitem>\r
  55 <simpara>\r
  56         Match paths exactly (i.e. don&#8217;t allow "/foo/repo" when the real path is\r
  57         "/foo/repo.git" or "/foo/repo/.git") and don&#8217;t do user-relative paths.\r
  58         <emphasis>git-daemon</emphasis> will refuse to start when this option is enabled and no\r
  59         whitelist is specified.\r
  60 </simpara>\r
  61 </listitem>\r
  62 </varlistentry>\r
  63 <varlistentry>\r
  64 <term>\r
  65 --base-path\r
  66 </term>\r
  67 <listitem>\r
  68 <simpara>\r
  69         Remap all the path requests as relative to the given path.\r
  70         This is sort of "GIT root" - if you run <emphasis>git-daemon</emphasis> with\r
  71         <emphasis>--base-path=/srv/git</emphasis> on example.com, then if you later try to pull\r
  72         <emphasis>git://example.com/hello.git</emphasis>, <emphasis>git-daemon</emphasis> will interpret the path\r
  73         as <emphasis>/srv/git/hello.git</emphasis>.\r
  74 </simpara>\r
  75 </listitem>\r
  76 </varlistentry>\r
  77 <varlistentry>\r
  78 <term>\r
  79 --base-path-relaxed\r
  80 </term>\r
  81 <listitem>\r
  82 <simpara>\r
  83         If --base-path is enabled and repo lookup fails, with this option\r
  84         <emphasis>git-daemon</emphasis> will attempt to lookup without prefixing the base path.\r
  85         This is useful for switching to --base-path usage, while still\r
  86         allowing the old paths.\r
  87 </simpara>\r
  88 </listitem>\r
  89 </varlistentry>\r
  90 <varlistentry>\r
  91 <term>\r
  92 --interpolated-path=pathtemplate\r
  93 </term>\r
  94 <listitem>\r
  95 <simpara>\r
  96         To support virtual hosting, an interpolated path template can be\r
  97         used to dynamically construct alternate paths.  The template\r
  98         supports %H for the target hostname as supplied by the client but\r
  99         converted to all lowercase, %CH for the canonical hostname,\r
 100         %IP for the server&#8217;s IP address, %P for the port number,\r
 101         and %D for the absolute path of the named repository.\r
 102         After interpolation, the path is validated against the directory\r
 103         whitelist.\r
 104 </simpara>\r
 105 </listitem>\r
 106 </varlistentry>\r
 107 <varlistentry>\r
 108 <term>\r
 109 --export-all\r
 110 </term>\r
 111 <listitem>\r
 112 <simpara>\r
 113         Allow pulling from all directories that look like GIT repositories\r
 114         (have the <emphasis>objects</emphasis> and <emphasis>refs</emphasis> subdirectories), even if they\r
 115         do not have the <emphasis>git-daemon-export-ok</emphasis> file.\r
 116 </simpara>\r
 117 </listitem>\r
 118 </varlistentry>\r
 119 <varlistentry>\r
 120 <term>\r
 121 --inetd\r
 122 </term>\r
 123 <listitem>\r
 124 <simpara>\r
 125         Have the server run as an inetd service. Implies --syslog.\r
 126         Incompatible with --port, --listen, --user and --group options.\r
 127 </simpara>\r
 128 </listitem>\r
 129 </varlistentry>\r
 130 <varlistentry>\r
 131 <term>\r
 132 --listen=host_or_ipaddr\r
 133 </term>\r
 134 <listitem>\r
 135 <simpara>\r
 136         Listen on an a specific IP address or hostname.  IP addresses can\r
 137         be either an IPv4 address or an IPV6 address if supported.  If IPv6\r
 138         is not supported, then --listen=hostname is also not supported and\r
 139         --listen must be given an IPv4 address.\r
 140         Incompatible with <emphasis>--inetd</emphasis> option.\r
 141 </simpara>\r
 142 </listitem>\r
 143 </varlistentry>\r
 144 <varlistentry>\r
 145 <term>\r
 146 --port=n\r
 147 </term>\r
 148 <listitem>\r
 149 <simpara>\r
 150         Listen on an alternative port.  Incompatible with <emphasis>--inetd</emphasis> option.\r
 151 </simpara>\r
 152 </listitem>\r
 153 </varlistentry>\r
 154 <varlistentry>\r
 155 <term>\r
 156 --init-timeout\r
 157 </term>\r
 158 <listitem>\r
 159 <simpara>\r
 160         Timeout between the moment the connection is established and the\r
 161         client request is received (typically a rather low value, since\r
 162         that should be basically immediate).\r
 163 </simpara>\r
 164 </listitem>\r
 165 </varlistentry>\r
 166 <varlistentry>\r
 167 <term>\r
 168 --timeout\r
 169 </term>\r
 170 <listitem>\r
 171 <simpara>\r
 172         Timeout for specific client sub-requests. This includes the time\r
 173         it takes for the server to process the sub-request and time spent\r
 174         waiting for next client&#8217;s request.\r
 175 </simpara>\r
 176 </listitem>\r
 177 </varlistentry>\r
 178 <varlistentry>\r
 179 <term>\r
 180 --max-connections\r
 181 </term>\r
 182 <listitem>\r
 183 <simpara>\r
 184         Maximum number of concurrent clients, defaults to 32.  Set it to\r
 185         zero for no limit.\r
 186 </simpara>\r
 187 </listitem>\r
 188 </varlistentry>\r
 189 <varlistentry>\r
 190 <term>\r
 191 --syslog\r
 192 </term>\r
 193 <listitem>\r
 194 <simpara>\r
 195         Log to syslog instead of stderr. Note that this option does not imply\r
 196         --verbose, thus by default only error conditions will be logged.\r
 197 </simpara>\r
 198 </listitem>\r
 199 </varlistentry>\r
 200 <varlistentry>\r
 201 <term>\r
 202 --user-path\r
 203 </term>\r
 204 <term>\r
 205 --user-path=path\r
 206 </term>\r
 207 <listitem>\r
 208 <simpara>\r
 209         Allow &#126;user notation to be used in requests.  When\r
 210         specified with no parameter, requests to\r
 211         git://host/&#126;alice/foo is taken as a request to access\r
 212         <emphasis>foo</emphasis> repository in the home directory of user <literal>alice</literal>.\r
 213         If <literal>--user-path=path</literal> is specified, the same request is\r
 214         taken as a request to access <literal>path/foo</literal> repository in\r
 215         the home directory of user <literal>alice</literal>.\r
 216 </simpara>\r
 217 </listitem>\r
 218 </varlistentry>\r
 219 <varlistentry>\r
 220 <term>\r
 221 --verbose\r
 222 </term>\r
 223 <listitem>\r
 224 <simpara>\r
 225         Log details about the incoming connections and requested files.\r
 226 </simpara>\r
 227 </listitem>\r
 228 </varlistentry>\r
 229 <varlistentry>\r
 230 <term>\r
 231 --reuseaddr\r
 232 </term>\r
 233 <listitem>\r
 234 <simpara>\r
 235         Use SO_REUSEADDR when binding the listening socket.\r
 236         This allows the server to restart without waiting for\r
 237         old connections to time out.\r
 238 </simpara>\r
 239 </listitem>\r
 240 </varlistentry>\r
 241 <varlistentry>\r
 242 <term>\r
 243 --detach\r
 244 </term>\r
 245 <listitem>\r
 246 <simpara>\r
 247         Detach from the shell. Implies --syslog.\r
 248 </simpara>\r
 249 </listitem>\r
 250 </varlistentry>\r
 251 <varlistentry>\r
 252 <term>\r
 253 --pid-file=file\r
 254 </term>\r
 255 <listitem>\r
 256 <simpara>\r
 257         Save the process id in <emphasis>file</emphasis>.  Ignored when the daemon\r
 258         is run under <literal>--inetd</literal>.\r
 259 </simpara>\r
 260 </listitem>\r
 261 </varlistentry>\r
 262 <varlistentry>\r
 263 <term>\r
 264 --user=user\r
 265 </term>\r
 266 <term>\r
 267 --group=group\r
 268 </term>\r
 269 <listitem>\r
 270 <simpara>\r
 271         Change daemon&#8217;s uid and gid before entering the service loop.\r
 272         When only <literal>--user</literal> is given without <literal>--group</literal>, the\r
 273         primary group ID for the user is used.  The values of\r
 274         the option are given to <literal>getpwnam(3)</literal> and <literal>getgrnam(3)</literal>\r
 275         and numeric IDs are not supported.\r
 276 </simpara>\r
 277 <simpara>Giving these options is an error when used with <literal>--inetd</literal>; use\r
 278 the facility of inet daemon to achieve the same before spawning\r
 279 <emphasis>git-daemon</emphasis> if needed.</simpara>\r
 280 </listitem>\r
 281 </varlistentry>\r
 282 <varlistentry>\r
 283 <term>\r
 284 --enable=service\r
 285 </term>\r
 286 <term>\r
 287 --disable=service\r
 288 </term>\r
 289 <listitem>\r
 290 <simpara>\r
 291         Enable/disable the service site-wide per default.  Note\r
 292         that a service disabled site-wide can still be enabled\r
 293         per repository if it is marked overridable and the\r
 294         repository enables the service with an configuration\r
 295         item.\r
 296 </simpara>\r
 297 </listitem>\r
 298 </varlistentry>\r
 299 <varlistentry>\r
 300 <term>\r
 301 --allow-override=service\r
 302 </term>\r
 303 <term>\r
 304 --forbid-override=service\r
 305 </term>\r
 306 <listitem>\r
 307 <simpara>\r
 308         Allow/forbid overriding the site-wide default with per\r
 309         repository configuration.  By default, all the services\r
 310         are overridable.\r
 311 </simpara>\r
 312 </listitem>\r
 313 </varlistentry>\r
 314 <varlistentry>\r
 315 <term>\r
 316 &lt;directory&gt;\r
 317 </term>\r
 318 <listitem>\r
 319 <simpara>\r
 320         A directory to add to the whitelist of allowed directories. Unless\r
 321         --strict-paths is specified this will also include subdirectories\r
 322         of each named directory.\r
 323 </simpara>\r
 324 </listitem>\r
 325 </varlistentry>\r
 326 </variablelist>\r
 327 </simplesect>\r
 328 <simplesect id="_services">\r
 329 <title>SERVICES</title>\r
 330 <simpara>These services can be globally enabled/disabled using the\r
 331 command line options of this command.  If a finer-grained\r
 332 control is desired (e.g. to allow <emphasis>git-archive</emphasis> to be run\r
 333 against only in a few selected repositories the daemon serves),\r
 334 the per-repository configuration file can be used to enable or\r
 335 disable them.</simpara>\r
 336 <variablelist>\r
 337 <varlistentry>\r
 338 <term>\r
 339 upload-pack\r
 340 </term>\r
 341 <listitem>\r
 342 <simpara>\r
 343         This serves <emphasis>git-fetch-pack</emphasis> and <emphasis>git-ls-remote</emphasis>\r
 344         clients.  It is enabled by default, but a repository can\r
 345         disable it by setting <literal>daemon.uploadpack</literal> configuration\r
 346         item to <literal>false</literal>.\r
 347 </simpara>\r
 348 </listitem>\r
 349 </varlistentry>\r
 350 <varlistentry>\r
 351 <term>\r
 352 upload-archive\r
 353 </term>\r
 354 <listitem>\r
 355 <simpara>\r
 356         This serves <emphasis>git-archive --remote</emphasis>.  It is disabled by\r
 357         default, but a repository can enable it by setting\r
 358         <literal>daemon.uploadarch</literal> configuration item to <literal>true</literal>.\r
 359 </simpara>\r
 360 </listitem>\r
 361 </varlistentry>\r
 362 <varlistentry>\r
 363 <term>\r
 364 receive-pack\r
 365 </term>\r
 366 <listitem>\r
 367 <simpara>\r
 368         This serves <emphasis>git-send-pack</emphasis> clients, allowing anonymous\r
 369         push.  It is disabled by default, as there is <emphasis>no</emphasis>\r
 370         authentication in the protocol (in other words, anybody\r
 371         can push anything into the repository, including removal\r
 372         of refs).  This is solely meant for a closed LAN setting\r
 373         where everybody is friendly.  This service can be\r
 374         enabled by <literal>daemon.receivepack</literal> configuration item to\r
 375         <literal>true</literal>.\r
 376 </simpara>\r
 377 </listitem>\r
 378 </varlistentry>\r
 379 </variablelist>\r
 380 </simplesect>\r
 381 <simplesect id="_examples">\r
 382 <title>EXAMPLES</title>\r
 383 <variablelist>\r
 384 <varlistentry>\r
 385 <term>\r
 386 We assume the following in /etc/services\r
 387 </term>\r
 388 <listitem>\r
 389 <literallayout>$ grep 9418 /etc/services\r
 390 git             9418/tcp                # Git Version Control System</literallayout>\r
 391 </listitem>\r
 392 </varlistentry>\r
 393 <varlistentry>\r
 394 <term>\r
 395 <emphasis>git-daemon</emphasis> as inetd server\r
 396 </term>\r
 397 <listitem>\r
 398 <simpara>\r
 399         To set up <emphasis>git-daemon</emphasis> as an inetd service that handles any\r
 400         repository under the whitelisted set of directories, /pub/foo\r
 401         and /pub/bar, place an entry like the following into\r
 402         /etc/inetd all on one line:\r
 403 </simpara>\r
 404 <literallayout>        git stream tcp nowait nobody  /usr/bin/git\r
 405                 git daemon --inetd --verbose --export-all\r
 406                 /pub/foo /pub/bar</literallayout>\r
 407 </listitem>\r
 408 </varlistentry>\r
 409 <varlistentry>\r
 410 <term>\r
 411 <emphasis>git-daemon</emphasis> as inetd server for virtual hosts\r
 412 </term>\r
 413 <listitem>\r
 414 <simpara>\r
 415         To set up <emphasis>git-daemon</emphasis> as an inetd service that handles\r
 416         repositories for different virtual hosts, <literal>www.example.com</literal>\r
 417         and <literal>www.example.org</literal>, place an entry like the following into\r
 418         <literal>/etc/inetd</literal> all on one line:\r
 419 </simpara>\r
 420 <literallayout>        git stream tcp nowait nobody /usr/bin/git\r
 421                 git daemon --inetd --verbose --export-all\r
 422                 --interpolated-path=/pub/%H%D\r
 423                 /pub/www.example.org/software\r
 424                 /pub/www.example.com/software\r
 425                 /software</literallayout>\r
 426 <simpara>In this example, the root-level directory <literal>/pub</literal> will contain\r
 427 a subdirectory for each virtual host name supported.\r
 428 Further, both hosts advertise repositories simply as\r
 429 <literal>git://www.example.com/software/repo.git</literal>.  For pre-1.4.0\r
 430 clients, a symlink from <literal>/software</literal> into the appropriate\r
 431 default repository could be made as well.</simpara>\r
 432 </listitem>\r
 433 </varlistentry>\r
 434 <varlistentry>\r
 435 <term>\r
 436 <emphasis>git-daemon</emphasis> as regular daemon for virtual hosts\r
 437 </term>\r
 438 <listitem>\r
 439 <simpara>\r
 440         To set up <emphasis>git-daemon</emphasis> as a regular, non-inetd service that\r
 441         handles repositories for multiple virtual hosts based on\r
 442         their IP addresses, start the daemon like this:\r
 443 </simpara>\r
 444 <literallayout>        git daemon --verbose --export-all\r
 445                 --interpolated-path=/pub/%IP/%D\r
 446                 /pub/192.168.1.200/software\r
 447                 /pub/10.10.220.23/software</literallayout>\r
 448 <simpara>In this example, the root-level directory <literal>/pub</literal> will contain\r
 449 a subdirectory for each virtual host IP address supported.\r
 450 Repositories can still be accessed by hostname though, assuming\r
 451 they correspond to these IP addresses.</simpara>\r
 452 </listitem>\r
 453 </varlistentry>\r
 454 <varlistentry>\r
 455 <term>\r
 456 selectively enable/disable services per repository\r
 457 </term>\r
 458 <listitem>\r
 459 <simpara>\r
 460         To enable <emphasis>git-archive --remote</emphasis> and disable <emphasis>git-fetch</emphasis> against\r
 461         a repository, have the following in the configuration file in the\r
 462         repository (that is the file <emphasis>config</emphasis> next to <emphasis>HEAD</emphasis>, <emphasis>refs</emphasis> and\r
 463         <emphasis>objects</emphasis>).\r
 464 </simpara>\r
 465 <literallayout>        [daemon]\r
 466                 uploadpack = false\r
 467                 uploadarch = true</literallayout>\r
 468 </listitem>\r
 469 </varlistentry>\r
 470 </variablelist>\r
 471 </simplesect>\r
 472 <simplesect id="_environment">\r
 473 <title>ENVIRONMENT</title>\r
 474 <simpara><emphasis>git-daemon</emphasis> will set REMOTE_ADDR to the IP address of the client\r
 475 that connected to it, if the IP address is available. REMOTE_ADDR will\r
 476 be available in the environment of hooks called when\r
 477 services are performed.</simpara>\r
 478 </simplesect>\r
 479 <simplesect id="_author">\r
 480 <title>Author</title>\r
 481 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt;, YOSHIFUJI Hideaki\r
 482 &lt;<ulink url="mailto:yoshfuji@linux-ipv6.org">yoshfuji@linux-ipv6.org</ulink>&gt; and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;</simpara>\r
 483 </simplesect>\r
 484 <simplesect id="_documentation">\r
 485 <title>Documentation</title>\r
 486 <simpara>Documentation by Junio C Hamano and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>\r
 487 </simplesect>\r
 488 <simplesect id="_git">\r
 489 <title>GIT</title>\r
 490 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 491 </simplesect>\r
 492 </article>\r