logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-daemon.1 (15077B)


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