4 <meta charset="utf-8"/>
5 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 <title>GOTD.CONF(5)</title>
9 <!-- This is an automatically generated file. Do not edit.
10 Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
12 Permission to use, copy, modify, and distribute this software for any
13 purpose with or without fee is hereby granted, provided that the above
14 copyright notice and this permission notice appear in all copies.
16 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 <div class="head" role="doc-pageheader" aria-label="Manual header
26 line"><span class="head-ltitle">GOTD.CONF(5)</span>
27 <span class="head-vol">File Formats Manual</span>
28 <span class="head-rtitle">GOTD.CONF(5)</span></div>
29 <main class="manual-text">
31 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 <p class="Pp"><code class="Nm">gotd.conf</code> —
33 <span class="Nd" role="doc-subtitle">gotd configuration file</span></p>
36 <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
37 <p class="Pp"><code class="Nm">gotd.conf</code> is the run-time configuration
38 file for <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>.</p>
39 <p class="Pp">The file format is line-based, with one configuration directive
40 per line. Any lines beginning with a ‘#’ are treated as
41 comments and ignored.</p>
44 <h2 class="Sh" id="GLOBAL_CONFIGURATION"><a class="permalink" href="#GLOBAL_CONFIGURATION">GLOBAL
45 CONFIGURATION</a></h2>
46 <p class="Pp">The available global configuration directives are as follows:</p>
48 <dt id="connection"><a class="permalink" href="#connection"><code class="Ic">connection</code></a>
49 <var class="Ar">option</var></dt>
50 <dd>Set the specified options and limits for connections to the
51 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> unix socket.
52 <p class="Pp">The <code class="Ic">connection</code> directive may be
53 specified multiple times, and multiple <var class="Ar">option</var>
54 arguments may be specified within curly braces:</p>
55 <p class="Pp"><code class="Ic">connection</code>
56 {<var class="Ar">...</var>}</p>
57 <p class="Pp">Each option should only be specified once. If a given option
58 is listed multiple times, the last line which sets this option wins.</p>
59 <p class="Pp">Valid connection options are:</p>
61 <dt id="request"><a class="permalink" href="#request"><code class="Ic">request
62 timeout</code></a> <var class="Ar">seconds</var></dt>
63 <dd>Specify the inactivity timeout for operations between client and
64 server. If this timeout is exceeded while a Git protocol request is
65 being processed, the request will be aborted and the connection will
67 <p class="Pp">The timeout value may also have a suffix indicating its
68 unit of measure. Supported suffixes are:</p>
70 <dl class="Bl-tag Bl-compact">
71 <dt><var class="Ar">s</var> <span class="No">or</span>
72 <var class="Ar">S</var></dt>
74 <dt><var class="Ar">m</var> <span class="No">or</span>
75 <var class="Ar">M</var></dt>
77 <dt><var class="Ar">h</var> <span class="No">or</span>
78 <var class="Ar">H</var></dt>
81 <p class="Pp">The default timeout is 1h (3600 seconds, one hour). This
82 should only be changed if legitimate requests are exceeding the
83 default timeout for some reason, such as the server spending an
84 extraordinary amount of time generating a pack file.</p>
86 <dt id="limit"><a class="permalink" href="#limit"><code class="Ic">limit</code></a>
87 <code class="Ic">user</code> <var class="Ar">identity</var>
88 <var class="Ar">number</var></dt>
89 <dd>Limit the maximum amount of concurrent connections by the user with
90 the username <var class="Ar">identity</var> to
91 <var class="Ar">number</var>. Numeric user IDs are also accepted.
92 <p class="Pp">The default per-user limit is 4. This should only be
93 changed if concurrent connections from a given user are expected to
94 exceed the default limit, for example if an anonymous user is
95 granted read access and many concurrent connections will share this
96 anonymous user identity.</p>
100 <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
101 on</code></a> <var class="Ar">path</var></dt>
102 <dd>Set the path to the unix socket which <a class="Xr" aria-label="gotd,
103 section 8">gotd(8)</a> should listen on. If not specified, the path
104 <span class="Pa">/var/run/gotd.sock</span> will be used.</dd>
105 <dt id="user"><a class="permalink" href="#user"><code class="Ic">user</code></a>
106 <var class="Ar">user</var></dt>
107 <dd>Set the <var class="Ar">user</var> which will run
108 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>. Initially,
109 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> requires root
110 privileges in order to create its unix socket. Afterwards,
111 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> drops privileges to
112 the specified <var class="Ar">user</var>. If not specified, the user _gotd
117 <h2 class="Sh" id="REPOSITORY_CONFIGURATION"><a class="permalink" href="#REPOSITORY_CONFIGURATION">REPOSITORY
118 CONFIGURATION</a></h2>
119 <p class="Pp">At least one repository context must exist for
120 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> to function. For each
121 repository, access rules must be configured using the
122 <code class="Ic">permit</code> and <code class="Ic">deny</code>
123 configuration directives. Multiple access rules can be specified, and the
124 last matching rule determines the action taken. If no rule matches, access
125 to the repository is denied.</p>
126 <p class="Pp">A repository context is declared with a unique
127 <var class="Ar">name</var>, followed by repository-specific configuration
128 directives inside curly braces:</p>
129 <p class="Pp"><code class="Ic">repository</code> <var class="Ar">name</var>
131 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a> and
132 <a class="Xr" aria-label="git, section 1">git(1)</a> clients can connect to
133 a repository by including the repository's unique <var class="Ar">name</var>
134 in the request URL. Clients appending the string “.git” to the
135 <var class="Ar">name</var> will also be accepted.</p>
136 <p class="Pp">If desired, the <var class="Ar">name</var> may contain
137 path-separators, “/”, to expose repositories as part of a
138 virtual client-visible directory hierarchy.</p>
139 <p class="Pp">The available repository configuration directives are as
142 <dt id="deny"><a class="permalink" href="#deny"><code class="Ic">deny</code></a>
143 <var class="Ar">identity</var></dt>
144 <dd>Deny repository access to users with the username
145 <var class="Ar">identity</var>. Group names may be matched by prepending a
146 colon (‘:’) to <var class="Ar">identity</var>. Numeric IDs
147 are also accepted.</dd>
148 <dt id="path"><a class="permalink" href="#path"><code class="Ic">path</code></a>
149 <var class="Ar">path</var></dt>
150 <dd>Set the path to the Git repository. Must be specified.</dd>
151 <dt id="permit"><a class="permalink" href="#permit"><code class="Ic">permit</code></a>
152 <var class="Ar">mode</var> <var class="Ar">identity</var></dt>
153 <dd>Permit repository access to users with the username
154 <var class="Ar">identity</var>. The <var class="Ar">mode</var> argument
155 must be set to either <code class="Ic">ro</code> for read-only access, or
156 <code class="Ic">rw</code> for read-write access. Group names may be
157 matched by prepending a colon (‘:’) to
158 <var class="Ar">identity</var>. Numeric IDs are also accepted.</dd>
159 <dt id="protect"><a class="permalink" href="#protect"><code class="Ic">protect</code></a>
160 {<var class="Ar">...</var>}</dt>
161 <dd>The <code class="Cm">protect</code> directive may be used to protect
162 branches and tags in a repository from being overwritten by potentially
163 destructive client-side commands, such as when <code class="Cm">got send
164 -f</code> and <code class="Cm">git push -f</code> are used to change the
166 <p class="Pp">To build a set of protected branches and tags, multiple
167 <code class="Ic">protect</code> directives may be specified per
168 repository and multiple <code class="Ic">protect</code> directive
169 parameters may be specified within curly braces.</p>
170 <p class="Pp">The available <code class="Cm">protect</code> parameters are
173 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
174 <var class="Ar">name</var></dt>
175 <dd>Protect the named branch. The branch may be created if it does not
176 exist yet. Attempts to delete the branch or change its history will be
178 <p class="Pp">If the <var class="Ar">name</var> does not already begin
179 with “refs/heads/” it will be looked up in the
180 “refs/heads/” reference namespace.</p>
182 <dt id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
183 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
184 <dd>Protect the given reference namespace, assuming that references in
185 this namespace represent branches. New branches may be created in the
186 namespace. Attempts to change the history of branches or delete them
188 <p class="Pp">The <var class="Ar">namespace</var> argument must be
189 absolute, starting with “refs/”.</p>
191 <dt id="tag"><a class="permalink" href="#tag"><code class="Ic">tag</code></a>
192 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
193 <dd>Protect the given reference namespace, assuming that references in
194 this namespace represent tags. New tags may be created in the
195 namespace. Attempts to change or delete existing tags will be denied.
196 <p class="Pp">The <var class="Ar">namespace</var> argument must be
197 absolute, starting with “refs/”.</p>
200 <p class="Pp">The special reference namespaces “refs/got/” and
201 “refs/remotes/” do not need to be listed in
202 <code class="Nm">gotd.conf</code>. These namespaces are always protected
203 and even attempts to create new references in these namespaces will
204 always be denied.</p>
206 <dt id="notify"><a class="permalink" href="#notify"><code class="Ic">notify</code></a>
207 {<var class="Ar">...</var>}</dt>
208 <dd>The <code class="Ic">notify</code> directive enables notifications about
209 new commits or tags added to the repository.
210 <p class="Pp">Notifications via email require an SMTP daemon which accepts
211 mail for forwarding without requiring client authentication or
212 encryption. On <span class="Ux">OpenBSD</span> the
213 <a class="Xr" aria-label="smtpd, section 8">smtpd(8)</a> daemon can be
214 used for this purpose. The default content of email notifications looks
215 similar to the output of the <code class="Cm">got log -d</code>
217 <p class="Pp">Notifications via HTTP require a HTTP or HTTPS server which is
218 accepting POST requests with or without HTTP Basic authentication.
219 Depending on the use case a custom server-side CGI script may be
220 required for the processing of notifications. HTTP notifications can
221 achieve functionality similar to Git's server-side post-receive hook
222 script with <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> by
223 triggering arbitrary post-commit actions via the HTTP server.</p>
224 <p class="Pp">The <code class="Ic">notify</code> directive expects
225 parameters which must be enclosed in curly braces. The available
226 parameters are as follows:</p>
228 <dt id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
229 <var class="Ar">name</var></dt>
230 <dd>Send notifications about commits to the named branch. The
231 <var class="Ar">name</var> will be looked up in the
232 “refs/heads/” reference namespace. This directive may be
233 specified multiple times to build a list of branches to send
234 notifications for. If neither a <code class="Ic">branch</code> nor a
235 <code class="Ic">reference namespace</code> are specified then changes
236 to any reference will trigger notifications.</dd>
237 <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
238 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
239 <dd>Send notifications about commits or tags within a reference namespace.
240 This directive may be specified multiple times to build a list of
241 namespaces to send notifications for. If neither a
242 <code class="Ic">branch</code> nor a <code class="Ic">reference
243 namespace</code> are specified then changes to any reference will
244 trigger notifications.</dd>
245 <dt id="email"><a class="permalink" href="#email"><code class="Ic">email</code></a>
246 [<code class="Ic">from</code> <var class="Ar">sender</var>]
247 <code class="Ic">to</code> <var class="Ar">recipient</var>
248 [<code class="Ic">reply to</code> <var class="Ar">responder</var>]
249 [<code class="Ic">relay</code> <var class="Ar">hostname</var>
250 [<code class="Ic">port</code> <var class="Ar">port</var>]]</dt>
251 <dd>Send notifications via email to the specified
252 <var class="Ar">recipient</var>. This directive may be specified
253 multiple times to build a list of recipients to send notifications to.
254 <p class="Pp">The <var class="Ar">recipient</var> must be an email
255 addresses that accepts mail. The <var class="Ar">sender</var> will
256 be used as the From address. If not specified, the sender defaults
257 to an email address composed of the user account running
258 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> and the local
260 <p class="Pp">If a <var class="Ar">responder</var> is specified via the
261 <code class="Ic">reply to</code> directive, the
262 <var class="Ar">responder</var> will be used as the Reply-to
263 address. Setting the Reply-to header can be useful if replies should
264 go to a mailing list instead of the <var class="Ar">sender</var>,
266 <p class="Pp">By default, mail will be sent to the SMTP server listening
267 on the loopback address 127.0.0.1 on port 25. The
268 <code class="Ic">relay</code> and <code class="Ic">port</code>
269 directives can be used to specify a different SMTP server address
272 <dt id="url"><a class="permalink" href="#url"><code class="Ic">url</code></a>
273 <var class="Ar">URL</var> [<code class="Ic">user</code>
274 <var class="Ar">user</var> <code class="Ic">password</code>
275 <var class="Ar">password</var> [<code class="Ic">insecure</code>]]</dt>
276 <dd>Send notifications via HTTP. This directive may be specified multiple
277 times to build a list of HTTP servers to send notifications to.
278 <p class="Pp">The notification will be sent as a POST request to the
279 given <var class="Ar">URL</var>, which must be a valid HTTP URL and
280 begin with either “http://” or
281 “https://”. If HTTPS is used, sending of notifications
282 will only succeed if no TLS errors occur.</p>
283 <p class="Pp">The optional <code class="Ic">user</code> and
284 <code class="Ic">password</code> directives enable HTTP Basic
285 authentication. If used, both a <var class="Ar">user</var> and a
286 <var class="Ar">password</var> must be specified. The
287 <var class="Ar">password</var> must not be an empty string. Unless
288 the <code class="Ic">insecure</code> option is specified the
289 notification target <var class="Ar">URL</var> must be a
290 “https://” URL to avoid leaking of authentication
292 <p class="Pp">The request body contains a JSON object with a
293 “notifications” property containing an array of
294 notification objects. Each notification object has a
295 ‘type’ property. Depending on the type, each
296 notification object has different fields. The types are:</p>
298 <dt id="commit"><a class="permalink" href="#commit"><code class="Dv">commit</code></a></dt>
299 <dd>The commit notification object has the following fields. Except
300 where noted, all are optional.
302 <dt id="short"><a class="permalink" href="#short"><code class="Dv">short</code></a></dt>
303 <dd>Boolean, indicates whether the object has all the fields set.
304 When several commits are batched in a single send operation,
305 not all of the fields are available for each commit
307 <dt id="repo"><a class="permalink" href="#repo"><code class="Dv">repo</code></a></dt>
308 <dd>The repository name as string.</dd>
309 <dt id="id"><a class="permalink" href="#id"><code class="Dv">id</code></a></dt>
310 <dd>The commit ID as string, may be abbreviated.</dd>
311 <dt id="committer"><a class="permalink" href="#committer"><code class="Dv">committer</code></a></dt>
312 <dd>An object with the committer information with the following
315 <dl class="Bl-tag Bl-compact">
316 <dt id="full"><a class="permalink" href="#full"><code class="Dv">full</code></a></dt>
317 <dd>Committer's full name.</dd>
318 <dt id="name"><a class="permalink" href="#name"><code class="Dv">name</code></a></dt>
319 <dd>Committer's name.</dd>
320 <dt id="mail"><a class="permalink" href="#mail"><code class="Dv">mail</code></a></dt>
321 <dd>Committer's mail address.</dd>
322 <dt id="user~2"><a class="permalink" href="#user~2"><code class="Dv">user</code></a></dt>
323 <dd>Committer's username. This is the only field guaranteed to
327 <dt id="author"><a class="permalink" href="#author"><code class="Dv">author</code></a></dt>
328 <dd>An object with the author information. Has the same fields as
329 the <code class="Dv">committer</code> but may be unset.</dd>
330 <dt id="date"><a class="permalink" href="#date"><code class="Dv">date</code></a></dt>
331 <dd>Number, representing the number of seconds since the Epoch in
333 <dt id="short_message"><a class="permalink" href="#short_message"><code class="Dv">short_message</code></a></dt>
334 <dd>The first line of the commit message. This field is always
336 <dt id="message"><a class="permalink" href="#message"><code class="Dv">message</code></a></dt>
337 <dd>The complete commit message, may be unset.</dd>
338 <dt id="diffstat"><a class="permalink" href="#diffstat"><code class="Dv">diffstat</code></a></dt>
339 <dd>An object with the summarized changes, may be unset. Contains
340 a <code class="Dv">files</code> field with an array of objects
341 describing the changes per-file and a
342 <code class="Dv">total</code> field with the cumulative
343 changes. The changes per-file contains the following fields:
345 <dl class="Bl-tag Bl-compact">
346 <dt id="action"><a class="permalink" href="#action"><code class="Dv">action</code></a></dt>
347 <dd>A string describing the action, can be
348 “added”, “deleted”,
349 “modified”, “mode changed”, or
350 “unknown”.</dd>
351 <dt id="file"><a class="permalink" href="#file"><code class="Dv">file</code></a></dt>
352 <dd>The file path.</dd>
353 <dt id="added"><a class="permalink" href="#added"><code class="Dv">added</code></a></dt>
354 <dd>The number of lines added.</dd>
355 <dt id="removed"><a class="permalink" href="#removed"><code class="Dv">removed</code></a></dt>
356 <dd>The number of lines removed.</dd>
358 <p class="Pp">The <code class="Dv">total</code> object contains
359 two fields: <code class="Dv">added</code> and
360 <code class="Dv">removed</code> which are the number of
361 added and removed lines respectively.</p>
365 <dt id="branch-deleted"><a class="permalink" href="#branch-deleted"><code class="Dv">branch-deleted</code></a></dt>
366 <dd>The branch deleted notifications has the following fields, all
367 guaranteed to be set:
368 <dl class="Bl-tag Bl-compact">
369 <dt id="repo~2"><a class="permalink" href="#repo~2"><code class="Dv">repo</code></a></dt>
370 <dd>The repository name as string.</dd>
371 <dt id="ref"><a class="permalink" href="#ref"><code class="Dv">ref</code></a></dt>
372 <dd>The removed branch reference.</dd>
373 <dt id="id~2"><a class="permalink" href="#id~2"><code class="Dv">id</code></a></dt>
374 <dd>The hash of the commit pointed by the deleted branch.</dd>
377 <dt id="tag~2"><a class="permalink" href="#tag~2"><code class="Dv">tag</code></a></dt>
378 <dd>The tag notification has the following fields, all guaranteed to
382 <dd>The repository name as string.</dd>
384 <dd>The tag reference.</dd>
386 <dd>The user information, with the same format of the
387 <code class="Dv">committer</code> field for the
388 <code class="Dv">commit</code> notification but with all the
389 field guaranteed to be set.</dd>
390 <dt id="date~2"><a class="permalink" href="#date~2"><code class="Dv">date</code></a></dt>
391 <dd>Number, representing the number of seconds since the Epoch in
393 <dt id="object"><a class="permalink" href="#object"><code class="Dv">object</code></a></dt>
394 <dd>The object being tagged. It contains the fields
395 <code class="Dv">type</code> with the object type and
396 <code class="Dv">id</code> with the object id being
398 <dt id="message~2"><a class="permalink" href="#message~2"><code class="Dv">message</code></a></dt>
399 <dd>The tag message.</dd>
409 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
410 <dl class="Bl-tag Bl-compact">
411 <dt><span class="Pa">/etc/gotd.conf</span></dt>
412 <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
416 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
417 <div class="Bd Bd-indent Li">
418 <pre># Run as the default user:
421 # Listen on the default socket:
422 listen on "/var/run/gotd.sock"
424 # This repository can be accessed via ssh://user@example.com/src
425 repository "src" {
426 path "/var/git/src.git"
427 permit rw flan_hacker
428 permit rw :developers
431 protect branch "main"
432 protect tag namespace "refs/tags/"
435 # This repository can be accessed via
436 # ssh://user@example.com/openbsd/ports
437 repository "openbsd/ports" {
438 path "/var/git/ports.git"
444 branch "main"
445 tag namespace "refs/tags/"
449 branch "main"
450 reference namespace "refs/tags/"
451 email to openbsd-ports-changes@example.com
455 # Use a larger request timeout value:
456 connection request timeout 2h
458 # Some users are granted a higher concurrent connection limit:
460 limit user flan_hacker 16
461 limit user anonymous 32
466 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
468 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
469 <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
470 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a></p>
473 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
474 line"><span class="foot-left"></span><span class="foot-date">April 23,
475 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
