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. Comments can be put anywhere in the file using a hash mark
41 (‘#’), and extend to the end of the current line. Arguments
42 names not beginning with a letter, digit or underscore, as well as reserved
43 words (such as <code class="Ic">listen</code>,
44 <code class="Ic">repository</code> <span class="No">or</span>
45 <code class="Ic">user</code>), must be quoted. Arguments containing
46 whitespace should be surrounded by double quotes (").</p>
47 <p class="Pp">Macros can be defined that are later expanded in context. Macro
48 names must start with a letter, digit, or underscore, and may contain any of
49 those characters, but may not be reserved words. Macros are not expanded
50 inside quotes. For example:</p>
51 <div class="Bd Pp Bd-indent Li">
52 <pre>path = "/var/run/gotd.sock"
57 <h2 class="Sh" id="GLOBAL_CONFIGURATION"><a class="permalink" href="#GLOBAL_CONFIGURATION">GLOBAL
58 CONFIGURATION</a></h2>
59 <p class="Pp">The available global configuration directives are as follows:</p>
61 <dt id="connection"><a class="permalink" href="#connection"><code class="Ic">connection</code></a>
62 <var class="Ar">option</var></dt>
63 <dd>Set the specified options and limits for connections to the
64 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> unix socket.
65 <p class="Pp">The <code class="Ic">connection</code> directive may be
66 specified multiple times, and multiple <var class="Ar">option</var>
67 arguments may be specified within curly braces:</p>
68 <p class="Pp"><code class="Ic">connection</code>
69 {<var class="Ar">...</var>}</p>
70 <p class="Pp">Each option should only be specified once. If a given option
71 is listed multiple times, the last line which sets this option wins.</p>
72 <p class="Pp">Valid connection options are:</p>
74 <dt id="request"><a class="permalink" href="#request"><code class="Ic">request
75 timeout</code></a> <var class="Ar">seconds</var></dt>
76 <dd>Specify the inactivity timeout for operations between client and
77 server. If this timeout is exceeded while a Git protocol request is
78 being processed, the request will be aborted and the connection will
80 <p class="Pp">The timeout value may also have a suffix indicating its
81 unit of measure. Supported suffixes are:</p>
83 <dl class="Bl-tag Bl-compact">
84 <dt><var class="Ar">s</var> <span class="No">or</span>
85 <var class="Ar">S</var></dt>
87 <dt><var class="Ar">m</var> <span class="No">or</span>
88 <var class="Ar">M</var></dt>
90 <dt><var class="Ar">h</var> <span class="No">or</span>
91 <var class="Ar">H</var></dt>
94 <p class="Pp">The default timeout is 1h (3600 seconds, one hour). This
95 should only be changed if legitimate requests are exceeding the
96 default timeout for some reason, such as the server spending an
97 extraordinary amount of time generating a pack file.</p>
99 <dt id="limit"><a class="permalink" href="#limit"><code class="Ic">limit</code></a>
100 <code class="Ic">user</code> <var class="Ar">identity</var>
101 <var class="Ar">number</var></dt>
102 <dd>Limit the maximum amount of concurrent connections by the user with
103 the username <var class="Ar">identity</var> to
104 <var class="Ar">number</var>. Numeric user IDs are also accepted.
105 <p class="Pp">The default per-user limit is 4. This should only be
106 changed if concurrent connections from a given user are expected to
107 exceed the default limit, for example if an anonymous user is
108 granted read access and many concurrent connections will share this
109 anonymous user identity.</p>
113 <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
114 on</code></a> <var class="Ar">path</var></dt>
115 <dd>Set the path to the unix socket which <a class="Xr" aria-label="gotd,
116 section 8">gotd(8)</a> should listen on. If not specified, the path
117 <span class="Pa">/var/run/gotd.sock</span> will be used.</dd>
118 <dt id="user"><a class="permalink" href="#user"><code class="Ic">user</code></a>
119 <var class="Ar">user</var></dt>
120 <dd>Set the <var class="Ar">user</var> which will run
121 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>. Initially,
122 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> requires root
123 privileges in order to create its unix socket. Afterwards,
124 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> drops privileges to
125 the specified <var class="Ar">user</var>. If not specified, the user _gotd
126 will be used. Numeric user IDs are also accepted.</dd>
130 <h2 class="Sh" id="REPOSITORY_CONFIGURATION"><a class="permalink" href="#REPOSITORY_CONFIGURATION">REPOSITORY
131 CONFIGURATION</a></h2>
132 <p class="Pp">At least one repository context must exist for
133 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> to function. For each
134 repository, access rules must be configured using the
135 <code class="Ic">permit</code> and <code class="Ic">deny</code>
136 configuration directives. Multiple access rules can be specified, and the
137 last matching rule determines the action taken. If no rule matches, access
138 to the repository is denied.</p>
139 <p class="Pp">A repository context is declared with a unique
140 <var class="Ar">name</var>, followed by repository-specific configuration
141 directives inside curly braces:</p>
142 <p class="Pp"><code class="Ic">repository</code> <var class="Ar">name</var>
144 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a> and
145 <a class="Xr" aria-label="git, section 1">git(1)</a> clients can connect to
146 a repository by including the repository's unique <var class="Ar">name</var>
147 in the request URL. Clients appending the string “.git” to the
148 <var class="Ar">name</var> will also be accepted.</p>
149 <p class="Pp">If desired, the <var class="Ar">name</var> may contain
150 path-separators, “/”, to expose repositories as part of a
151 virtual client-visible directory hierarchy.</p>
152 <p class="Pp">The available repository configuration directives are as
155 <dt id="deny"><a class="permalink" href="#deny"><code class="Ic">deny</code></a>
156 <var class="Ar">identity</var></dt>
157 <dd>Deny repository access to users with the username
158 <var class="Ar">identity</var>. Group names may be matched by prepending a
159 colon (‘:’) to <var class="Ar">identity</var>. Numeric IDs
160 are also accepted.</dd>
161 <dt id="path"><a class="permalink" href="#path"><code class="Ic">path</code></a>
162 <var class="Ar">path</var></dt>
163 <dd>Set the path to the Git repository. Must be specified.</dd>
164 <dt id="permit"><a class="permalink" href="#permit"><code class="Ic">permit</code></a>
165 <var class="Ar">mode</var> <var class="Ar">identity</var></dt>
166 <dd>Permit repository access to users with the username
167 <var class="Ar">identity</var>. The <var class="Ar">mode</var> argument
168 must be set to either <code class="Ic">ro</code> for read-only access, or
169 <code class="Ic">rw</code> for read-write access. Group names may be
170 matched by prepending a colon (‘:’) to
171 <var class="Ar">identity</var>. Numeric IDs are also accepted.</dd>
172 <dt id="protect"><a class="permalink" href="#protect"><code class="Ic">protect</code></a>
173 {<var class="Ar">...</var>}</dt>
174 <dd>The <code class="Cm">protect</code> directive may be used to protect
175 branches and tags in a repository from being overwritten by potentially
176 destructive client-side commands, such as when <code class="Cm">got send
177 -f</code> and <code class="Cm">git push -f</code> are used to change the
179 <p class="Pp">To build a set of protected branches and tags, multiple
180 <code class="Ic">protect</code> directives may be specified per
181 repository and multiple <code class="Ic">protect</code> directive
182 parameters may be specified within curly braces.</p>
183 <p class="Pp">The available <code class="Cm">protect</code> parameters are
186 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
187 <var class="Ar">name</var></dt>
188 <dd>Protect the named branch. The branch may be created if it does not
189 exist yet. Attempts to delete the branch or change its history will be
191 <p class="Pp">If the <var class="Ar">name</var> does not already begin
192 with “refs/heads/” it will be looked up in the
193 “refs/heads/” reference namespace.</p>
195 <dt id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
196 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
197 <dd>Protect the given reference namespace, assuming that references in
198 this namespace represent branches. New branches may be created in the
199 namespace. Attempts to change the history of branches or delete them
201 <p class="Pp">The <var class="Ar">namespace</var> argument must be
202 absolute, starting with “refs/”.</p>
204 <dt id="tag"><a class="permalink" href="#tag"><code class="Ic">tag</code></a>
205 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
206 <dd>Protect the given reference namespace, assuming that references in
207 this namespace represent tags. New tags may be created in the
208 namespace. Attempts to change or delete existing tags will be denied.
209 <p class="Pp">The <var class="Ar">namespace</var> argument must be
210 absolute, starting with “refs/”.</p>
213 <p class="Pp">The special reference namespaces “refs/got/” and
214 “refs/remotes/” do not need to be listed in
215 <code class="Nm">gotd.conf</code>. These namespaces are always protected
216 and even attempts to create new references in these namespaces will
217 always be denied.</p>
219 <dt id="notify"><a class="permalink" href="#notify"><code class="Ic">notify</code></a>
220 {<var class="Ar">...</var>}</dt>
221 <dd>The <code class="Ic">notify</code> directive enables notifications about
222 new commits or tags added to the repository.
223 <p class="Pp">Notifications via email require an SMTP daemon which accepts
224 mail for forwarding without requiring client authentication or
225 encryption. On <span class="Ux">OpenBSD</span> the
226 <a class="Xr" aria-label="smtpd, section 8">smtpd(8)</a> daemon can be
227 used for this purpose. The default content of email notifications looks
228 similar to the output of the <code class="Cm">got log -d</code>
230 <p class="Pp">Notifications via HTTP require a HTTP or HTTPS server which is
231 accepting POST requests with or without HTTP Basic authentication.
232 Depending on the use case a custom server-side CGI script may be
233 required for the processing of notifications. HTTP notifications can
234 achieve functionality similar to Git's server-side post-receive hook
235 script with <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> by
236 triggering arbitrary post-commit actions via the HTTP server.</p>
237 <p class="Pp">The <code class="Ic">notify</code> directive expects
238 parameters which must be enclosed in curly braces. The available
239 parameters are as follows:</p>
241 <dt id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
242 <var class="Ar">name</var></dt>
243 <dd>Send notifications about commits to the named branch. The
244 <var class="Ar">name</var> will be looked up in the
245 “refs/heads/” reference namespace. This directive may be
246 specified multiple times to build a list of branches to send
247 notifications for. If neither a <code class="Ic">branch</code> nor a
248 <code class="Ic">reference namespace</code> are specified then changes
249 to any reference will trigger notifications.</dd>
250 <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
251 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
252 <dd>Send notifications about commits or tags within a reference namespace.
253 This directive may be specified multiple times to build a list of
254 namespaces to send notifications for. If neither a
255 <code class="Ic">branch</code> nor a <code class="Ic">reference
256 namespace</code> are specified then changes to any reference will
257 trigger notifications.</dd>
258 <dt id="email"><a class="permalink" href="#email"><code class="Ic">email</code></a>
259 [<code class="Ic">from</code> <var class="Ar">sender</var>]
260 <code class="Ic">to</code> <var class="Ar">recipient</var>
261 [<code class="Ic">reply to</code> <var class="Ar">responder</var>]
262 [<code class="Ic">relay</code> <var class="Ar">hostname</var>
263 [<code class="Ic">port</code> <var class="Ar">port</var>]]</dt>
264 <dd>Send notifications via email to the specified
265 <var class="Ar">recipient</var>. This directive may be specified
266 multiple times to build a list of recipients to send notifications to.
267 <p class="Pp">The <var class="Ar">recipient</var> must be an email
268 addresses that accepts mail. The <var class="Ar">sender</var> will
269 be used as the From address. If not specified, the sender defaults
270 to an email address composed of the user account running
271 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> and the local
273 <p class="Pp">If a <var class="Ar">responder</var> is specified via the
274 <code class="Ic">reply to</code> directive, the
275 <var class="Ar">responder</var> will be used as the Reply-to
276 address. Setting the Reply-to header can be useful if replies should
277 go to a mailing list instead of the <var class="Ar">sender</var>,
279 <p class="Pp">By default, mail will be sent to the SMTP server listening
280 on the loopback address 127.0.0.1 on port 25. The
281 <code class="Ic">relay</code> and <code class="Ic">port</code>
282 directives can be used to specify a different SMTP server address
285 <dt id="url"><a class="permalink" href="#url"><code class="Ic">url</code></a>
286 <var class="Ar">URL</var> [<code class="Ic">auth</code>
287 <var class="Ar">label</var> [<code class="Ic">insecure</code>]]
288 [<code class="Ic">hmac</code> <var class="Ar">label</var>]</dt>
289 <dd>Send notifications via HTTP. This directive may be specified multiple
290 times to build a list of HTTP servers to send notifications to.
291 <p class="Pp">The notification will be sent as a POST request to the
292 given <var class="Ar">URL</var>, which must be a valid HTTP URL and
293 begin with either “http://” or
294 “https://”. If HTTPS is used, sending of notifications
295 will only succeed if no TLS errors occur.</p>
296 <p class="Pp">The optional <code class="Ic">auth</code> directive
297 enables HTTP Basic authentication. Authentication credentials must
298 be specified in the separate
299 <a class="Xr" aria-label="gotd-secrets.conf, section
300 5">gotd-secrets.conf(5)</a> file, using the
301 <var class="Ar">label</var> as identifier. Unless the
302 <code class="Ic">insecure</code> option is specified the
303 notification target <var class="Ar">URL</var> must be a
304 “https://” URL to avoid leaking of authentication
306 <p class="Pp">If a <code class="Ic">hmac</code> secret is provided, the
307 request body will be signed using HMAC, allowing the receiver to
308 verify the notification message's authenticity and integrity. The
309 HMAC secret to use must be specified in the separate
310 <a class="Xr" aria-label="gotd-secrets.conf, section
311 5">gotd-secrets.conf(5)</a> file, using the
312 <var class="Ar">label</var> as identifier. The signature uses
313 HMAC-SHA256 and will be sent in the HTTP header
314 “X-Gotd-Signature”.</p>
315 <p class="Pp">The request body contains a JSON object with a
316 “notifications” property containing an array of
317 notification objects. The following notification object properties
318 are always present:</p>
320 <dt id="repo"><a class="permalink" href="#repo"><code class="Dv">repo</code></a></dt>
321 <dd>The repository name as a string.</dd>
322 <dt id="authenticated_user"><a class="permalink" href="#authenticated_user"><code class="Dv">authenticated_user</code></a></dt>
323 <dd>The committer's user account as authenticated by
324 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> as a
326 <dt id="type"><a class="permalink" href="#type"><code class="Dv">type</code></a></dt>
327 <dd>The notification object type as a string.</dd>
329 <p class="Pp">Each notification object carries additional type-specific
330 properties. The types and their type-specific properties are:</p>
332 <dt id="commit"><a class="permalink" href="#commit"><code class="Dv">commit</code></a></dt>
333 <dd>The commit notification object has the following fields. Except
334 where noted, all are optional.
336 <dt id="short"><a class="permalink" href="#short"><code class="Dv">short</code></a></dt>
337 <dd>Boolean, indicates whether the object has all the fields set.
338 When several commits are batched in a single send operation,
339 not all of the fields are available for each commit
341 <dt id="id"><a class="permalink" href="#id"><code class="Dv">id</code></a></dt>
342 <dd>The commit ID as string, may be abbreviated.</dd>
343 <dt id="committer"><a class="permalink" href="#committer"><code class="Dv">committer</code></a></dt>
344 <dd>An object with the committer information with the following
347 <dl class="Bl-tag Bl-compact">
348 <dt id="full"><a class="permalink" href="#full"><code class="Dv">full</code></a></dt>
349 <dd>Committer's full name.</dd>
350 <dt id="name"><a class="permalink" href="#name"><code class="Dv">name</code></a></dt>
351 <dd>Committer's name.</dd>
352 <dt id="mail"><a class="permalink" href="#mail"><code class="Dv">mail</code></a></dt>
353 <dd>Committer's mail address.</dd>
354 <dt id="user~2"><a class="permalink" href="#user~2"><code class="Dv">user</code></a></dt>
355 <dd>Committer's username. This is the only field guaranteed to
359 <dt id="author"><a class="permalink" href="#author"><code class="Dv">author</code></a></dt>
360 <dd>An object with the author information. Has the same fields as
361 the ‘committer’ but may be unset.</dd>
362 <dt id="date"><a class="permalink" href="#date"><code class="Dv">date</code></a></dt>
363 <dd>Number, representing the number of seconds since the Epoch in
365 <dt id="short_message"><a class="permalink" href="#short_message"><code class="Dv">short_message</code></a></dt>
366 <dd>The first line of the commit message. This field is always
368 <dt id="message"><a class="permalink" href="#message"><code class="Dv">message</code></a></dt>
369 <dd>The complete commit message, may be unset.</dd>
370 <dt id="diffstat"><a class="permalink" href="#diffstat"><code class="Dv">diffstat</code></a></dt>
371 <dd>An object with the summarized changes, may be unset. Contains
372 a ‘files’ field with an array of objects
373 describing the changes per-file and a ‘total’
374 field with the cumulative changes. The changes per-file
375 contains the following fields:
377 <dl class="Bl-tag Bl-compact">
378 <dt id="action"><a class="permalink" href="#action"><code class="Dv">action</code></a></dt>
379 <dd>A string describing the action, can be
380 “added”, “deleted”,
381 “modified”, “mode changed”, or
382 “unknown”.</dd>
383 <dt id="file"><a class="permalink" href="#file"><code class="Dv">file</code></a></dt>
384 <dd>The file path.</dd>
385 <dt id="added"><a class="permalink" href="#added"><code class="Dv">added</code></a></dt>
386 <dd>The number of lines added.</dd>
387 <dt id="removed"><a class="permalink" href="#removed"><code class="Dv">removed</code></a></dt>
388 <dd>The number of lines removed.</dd>
390 <p class="Pp">The ‘total’ object contains two
391 fields: ‘added’ and ‘removed’
392 which are the number of added and removed lines
397 <dt id="branch-deleted"><a class="permalink" href="#branch-deleted"><code class="Dv">branch-deleted</code></a></dt>
398 <dd>The branch deleted notifications has the following fields, all
399 guaranteed to be set:
401 <dt id="ref"><a class="permalink" href="#ref"><code class="Dv">ref</code></a></dt>
402 <dd>The removed branch reference.</dd>
403 <dt id="id~2"><a class="permalink" href="#id~2"><code class="Dv">id</code></a></dt>
404 <dd>The hash of the commit pointed by the deleted branch.</dd>
407 <dt id="tag~2"><a class="permalink" href="#tag~2"><code class="Dv">tag</code></a></dt>
408 <dd>The tag notification has the following fields, all guaranteed to
412 <dd>The tag reference.</dd>
414 <dd>The user information, with the same format of the
415 ‘committer’ field for the ‘commit’
416 notification but with all the field guaranteed to be set.</dd>
417 <dt id="date~2"><a class="permalink" href="#date~2"><code class="Dv">date</code></a></dt>
418 <dd>Number, representing the number of seconds since the Epoch in
420 <dt id="object"><a class="permalink" href="#object"><code class="Dv">object</code></a></dt>
421 <dd>The object being tagged. It contains the fields
422 ‘type’ with the object type and
423 ‘id’ with the object id being tagged.</dd>
424 <dt id="message~2"><a class="permalink" href="#message~2"><code class="Dv">message</code></a></dt>
425 <dd>The tag message.</dd>
435 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
436 <dl class="Bl-tag Bl-compact">
437 <dt><span class="Pa">/etc/gotd.conf</span></dt>
438 <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
442 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
443 <div class="Bd Bd-indent Li">
444 <pre># Run as the default user:
447 # Listen on the default socket:
448 listen on "/var/run/gotd.sock"
450 # This repository can be accessed via ssh://user@example.com/src
451 repository "src" {
452 path "/var/git/src.git"
453 permit rw flan_hacker
454 permit rw :developers
457 protect branch "main"
458 protect tag namespace "refs/tags/"
461 # This repository can be accessed via
462 # ssh://user@example.com/openbsd/ports
463 repository "openbsd/ports" {
464 path "/var/git/ports.git"
470 branch "main"
471 tag namespace "refs/tags/"
475 branch "main"
476 reference namespace "refs/tags/"
477 email to openbsd-ports-changes@example.com
481 # Use a larger request timeout value:
482 connection request timeout 2h
484 # Some users are granted a higher concurrent connection limit:
486 limit user flan_hacker 16
487 limit user anonymous 32
492 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
494 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
495 <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
496 <a class="Xr" aria-label="gotd-secrets.conf, section
497 5">gotd-secrets.conf(5)</a>, <a class="Xr" aria-label="gotd, section
501 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
502 line"><span class="foot-left"></span><span class="foot-date">December 28,
503 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
