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