Blame


1 742bb3a1 2022-10-24 stsp <!DOCTYPE html>
2 742bb3a1 2022-10-24 stsp <html>
3 742bb3a1 2022-10-24 stsp <head>
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>
8 742bb3a1 2022-10-24 stsp </head>
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>
11 742bb3a1 2022-10-24 stsp
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.
15 742bb3a1 2022-10-24 stsp
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.
23 742bb3a1 2022-10-24 stsp -->
24 742bb3a1 2022-10-24 stsp <body>
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> &#x2014;
33 742bb3a1 2022-10-24 stsp <span class="Nd" role="doc-subtitle">gotd configuration file</span></p>
34 742bb3a1 2022-10-24 stsp </section>
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 &#x2018;#&#x2019; are treated as
41 742bb3a1 2022-10-24 stsp comments and ignored.</p>
42 742bb3a1 2022-10-24 stsp </section>
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>
80 47f19dd5 2023-01-17 stsp </dl>
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>
85 47f19dd5 2023-01-17 stsp </dd>
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>
97 47f19dd5 2023-01-17 stsp </dd>
98 47f19dd5 2023-01-17 stsp </dl>
99 47f19dd5 2023-01-17 stsp </dd>
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>
114 742bb3a1 2022-10-24 stsp </dl>
115 742bb3a1 2022-10-24 stsp </section>
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>
130 742bb3a1 2022-10-24 stsp {...}</p>
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 &#x201C;.git&#x201D; 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, &#x201C;/&#x201D;, 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 (&#x2018;:&#x2019;) 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 (&#x2018;:&#x2019;) 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
177 e68eaba8 2023-04-20 stsp denied.
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 &#x201C;refs/heads/&#x201D; it will be looked up in the
180 e68eaba8 2023-04-20 stsp &#x201C;refs/heads/&#x201D; reference namespace.</p>
181 e68eaba8 2023-04-20 stsp </dd>
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 &#x201C;refs/&#x201D;.</p>
190 e68eaba8 2023-04-20 stsp </dd>
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 &#x201C;refs/&#x201D;.</p>
198 e68eaba8 2023-04-20 stsp </dd>
199 e68eaba8 2023-04-20 stsp </dl>
200 e68eaba8 2023-04-20 stsp <p class="Pp">The special reference namespaces &#x201C;refs/got/&#x201D; and
201 e68eaba8 2023-04-20 stsp &#x201C;refs/remotes/&#x201D; 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>
205 bd0bf387 2024-04-23 stsp </dd>
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 &#x201C;refs/heads/&#x201D; 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>
271 bd0bf387 2024-04-23 stsp </dd>
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 &#x201C;http://&#x201D; or
281 bd0bf387 2024-04-23 stsp &#x201C;https://&#x201D;. 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 &#x201C;https://&#x201D; 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 &#x201C;notifications&#x201D; property containing an array of
294 dfc34448 2024-05-06 stsp notification objects. The following notification object properties
295 dfc34448 2024-05-06 stsp are always present:</p>
296 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
297 dfc34448 2024-05-06 stsp <dt id="repo"><a class="permalink" href="#repo"><code class="Dv">repo</code></a></dt>
298 dfc34448 2024-05-06 stsp <dd>The repository name as a string.</dd>
299 dfc34448 2024-05-06 stsp <dt id="authenticated_user"><a class="permalink" href="#authenticated_user"><code class="Dv">authenticated_user</code></a></dt>
300 dfc34448 2024-05-06 stsp <dd>The committer's user account as authenticated by
301 dfc34448 2024-05-06 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> as a
302 dfc34448 2024-05-06 stsp string.</dd>
303 dfc34448 2024-05-06 stsp <dt id="type"><a class="permalink" href="#type"><code class="Dv">type</code></a></dt>
304 dfc34448 2024-05-06 stsp <dd>The notification object type as a string.</dd>
305 dfc34448 2024-05-06 stsp </dl>
306 dfc34448 2024-05-06 stsp <p class="Pp">Each notification object carries additional type-specific
307 dfc34448 2024-05-06 stsp properties. The types and their type-specific properties are:</p>
308 dfc34448 2024-05-06 stsp <dl class="Bl-tag">
309 bd0bf387 2024-04-23 stsp <dt id="commit"><a class="permalink" href="#commit"><code class="Dv">commit</code></a></dt>
310 bd0bf387 2024-04-23 stsp <dd>The commit notification object has the following fields. Except
311 bd0bf387 2024-04-23 stsp where noted, all are optional.
312 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
313 bd0bf387 2024-04-23 stsp <dt id="short"><a class="permalink" href="#short"><code class="Dv">short</code></a></dt>
314 bd0bf387 2024-04-23 stsp <dd>Boolean, indicates whether the object has all the fields set.
315 bd0bf387 2024-04-23 stsp When several commits are batched in a single send operation,
316 bd0bf387 2024-04-23 stsp not all of the fields are available for each commit
317 bd0bf387 2024-04-23 stsp object.</dd>
318 bd0bf387 2024-04-23 stsp <dt id="id"><a class="permalink" href="#id"><code class="Dv">id</code></a></dt>
319 bd0bf387 2024-04-23 stsp <dd>The commit ID as string, may be abbreviated.</dd>
320 bd0bf387 2024-04-23 stsp <dt id="committer"><a class="permalink" href="#committer"><code class="Dv">committer</code></a></dt>
321 bd0bf387 2024-04-23 stsp <dd>An object with the committer information with the following
322 bd0bf387 2024-04-23 stsp fields:
323 bd0bf387 2024-04-23 stsp <p class="Pp"></p>
324 bd0bf387 2024-04-23 stsp <dl class="Bl-tag Bl-compact">
325 bd0bf387 2024-04-23 stsp <dt id="full"><a class="permalink" href="#full"><code class="Dv">full</code></a></dt>
326 bd0bf387 2024-04-23 stsp <dd>Committer's full name.</dd>
327 bd0bf387 2024-04-23 stsp <dt id="name"><a class="permalink" href="#name"><code class="Dv">name</code></a></dt>
328 bd0bf387 2024-04-23 stsp <dd>Committer's name.</dd>
329 bd0bf387 2024-04-23 stsp <dt id="mail"><a class="permalink" href="#mail"><code class="Dv">mail</code></a></dt>
330 bd0bf387 2024-04-23 stsp <dd>Committer's mail address.</dd>
331 bd0bf387 2024-04-23 stsp <dt id="user~2"><a class="permalink" href="#user~2"><code class="Dv">user</code></a></dt>
332 bd0bf387 2024-04-23 stsp <dd>Committer's username. This is the only field guaranteed to
333 bd0bf387 2024-04-23 stsp be set.</dd>
334 bd0bf387 2024-04-23 stsp </dl>
335 bd0bf387 2024-04-23 stsp </dd>
336 bd0bf387 2024-04-23 stsp <dt id="author"><a class="permalink" href="#author"><code class="Dv">author</code></a></dt>
337 bd0bf387 2024-04-23 stsp <dd>An object with the author information. Has the same fields as
338 dfc34448 2024-05-06 stsp the &#x2018;committer&#x2019; but may be unset.</dd>
339 bd0bf387 2024-04-23 stsp <dt id="date"><a class="permalink" href="#date"><code class="Dv">date</code></a></dt>
340 bd0bf387 2024-04-23 stsp <dd>Number, representing the number of seconds since the Epoch in
341 bd0bf387 2024-04-23 stsp UTC.</dd>
342 bd0bf387 2024-04-23 stsp <dt id="short_message"><a class="permalink" href="#short_message"><code class="Dv">short_message</code></a></dt>
343 bd0bf387 2024-04-23 stsp <dd>The first line of the commit message. This field is always
344 bd0bf387 2024-04-23 stsp set.</dd>
345 bd0bf387 2024-04-23 stsp <dt id="message"><a class="permalink" href="#message"><code class="Dv">message</code></a></dt>
346 bd0bf387 2024-04-23 stsp <dd>The complete commit message, may be unset.</dd>
347 bd0bf387 2024-04-23 stsp <dt id="diffstat"><a class="permalink" href="#diffstat"><code class="Dv">diffstat</code></a></dt>
348 bd0bf387 2024-04-23 stsp <dd>An object with the summarized changes, may be unset. Contains
349 dfc34448 2024-05-06 stsp a &#x2018;files&#x2019; field with an array of objects
350 dfc34448 2024-05-06 stsp describing the changes per-file and a &#x2018;total&#x2019;
351 dfc34448 2024-05-06 stsp field with the cumulative changes. The changes per-file
352 dfc34448 2024-05-06 stsp contains the following fields:
353 bd0bf387 2024-04-23 stsp <p class="Pp"></p>
354 bd0bf387 2024-04-23 stsp <dl class="Bl-tag Bl-compact">
355 bd0bf387 2024-04-23 stsp <dt id="action"><a class="permalink" href="#action"><code class="Dv">action</code></a></dt>
356 bd0bf387 2024-04-23 stsp <dd>A string describing the action, can be
357 bd0bf387 2024-04-23 stsp &#x201C;added&#x201D;, &#x201C;deleted&#x201D;,
358 bd0bf387 2024-04-23 stsp &#x201C;modified&#x201D;, &#x201C;mode changed&#x201D;, or
359 bd0bf387 2024-04-23 stsp &#x201C;unknown&#x201D;.</dd>
360 bd0bf387 2024-04-23 stsp <dt id="file"><a class="permalink" href="#file"><code class="Dv">file</code></a></dt>
361 bd0bf387 2024-04-23 stsp <dd>The file path.</dd>
362 bd0bf387 2024-04-23 stsp <dt id="added"><a class="permalink" href="#added"><code class="Dv">added</code></a></dt>
363 bd0bf387 2024-04-23 stsp <dd>The number of lines added.</dd>
364 bd0bf387 2024-04-23 stsp <dt id="removed"><a class="permalink" href="#removed"><code class="Dv">removed</code></a></dt>
365 bd0bf387 2024-04-23 stsp <dd>The number of lines removed.</dd>
366 bd0bf387 2024-04-23 stsp </dl>
367 dfc34448 2024-05-06 stsp <p class="Pp">The &#x2018;total&#x2019; object contains two
368 dfc34448 2024-05-06 stsp fields: &#x2018;added&#x2019; and &#x2018;removed&#x2019;
369 dfc34448 2024-05-06 stsp which are the number of added and removed lines
370 dfc34448 2024-05-06 stsp respectively.</p>
371 bd0bf387 2024-04-23 stsp </dd>
372 bd0bf387 2024-04-23 stsp </dl>
373 bd0bf387 2024-04-23 stsp </dd>
374 bd0bf387 2024-04-23 stsp <dt id="branch-deleted"><a class="permalink" href="#branch-deleted"><code class="Dv">branch-deleted</code></a></dt>
375 bd0bf387 2024-04-23 stsp <dd>The branch deleted notifications has the following fields, all
376 bd0bf387 2024-04-23 stsp guaranteed to be set:
377 dfc34448 2024-05-06 stsp <dl class="Bl-tag">
378 bd0bf387 2024-04-23 stsp <dt id="ref"><a class="permalink" href="#ref"><code class="Dv">ref</code></a></dt>
379 bd0bf387 2024-04-23 stsp <dd>The removed branch reference.</dd>
380 bd0bf387 2024-04-23 stsp <dt id="id~2"><a class="permalink" href="#id~2"><code class="Dv">id</code></a></dt>
381 bd0bf387 2024-04-23 stsp <dd>The hash of the commit pointed by the deleted branch.</dd>
382 bd0bf387 2024-04-23 stsp </dl>
383 bd0bf387 2024-04-23 stsp </dd>
384 bd0bf387 2024-04-23 stsp <dt id="tag~2"><a class="permalink" href="#tag~2"><code class="Dv">tag</code></a></dt>
385 bd0bf387 2024-04-23 stsp <dd>The tag notification has the following fields, all guaranteed to
386 bd0bf387 2024-04-23 stsp be set:
387 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
388 bd0bf387 2024-04-23 stsp <dt>tag</dt>
389 bd0bf387 2024-04-23 stsp <dd>The tag reference.</dd>
390 bd0bf387 2024-04-23 stsp <dt>tagger</dt>
391 bd0bf387 2024-04-23 stsp <dd>The user information, with the same format of the
392 dfc34448 2024-05-06 stsp &#x2018;committer&#x2019; field for the &#x2018;commit&#x2019;
393 dfc34448 2024-05-06 stsp notification but with all the field guaranteed to be set.</dd>
394 bd0bf387 2024-04-23 stsp <dt id="date~2"><a class="permalink" href="#date~2"><code class="Dv">date</code></a></dt>
395 bd0bf387 2024-04-23 stsp <dd>Number, representing the number of seconds since the Epoch in
396 bd0bf387 2024-04-23 stsp UTC.</dd>
397 bd0bf387 2024-04-23 stsp <dt id="object"><a class="permalink" href="#object"><code class="Dv">object</code></a></dt>
398 bd0bf387 2024-04-23 stsp <dd>The object being tagged. It contains the fields
399 dfc34448 2024-05-06 stsp &#x2018;type&#x2019; with the object type and
400 dfc34448 2024-05-06 stsp &#x2018;id&#x2019; with the object id being tagged.</dd>
401 bd0bf387 2024-04-23 stsp <dt id="message~2"><a class="permalink" href="#message~2"><code class="Dv">message</code></a></dt>
402 bd0bf387 2024-04-23 stsp <dd>The tag message.</dd>
403 bd0bf387 2024-04-23 stsp </dl>
404 bd0bf387 2024-04-23 stsp </dd>
405 bd0bf387 2024-04-23 stsp </dl>
406 bd0bf387 2024-04-23 stsp </dd>
407 bd0bf387 2024-04-23 stsp </dl>
408 e68eaba8 2023-04-20 stsp </dd>
409 742bb3a1 2022-10-24 stsp </dl>
410 742bb3a1 2022-10-24 stsp </section>
411 742bb3a1 2022-10-24 stsp <section class="Sh">
412 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
413 742bb3a1 2022-10-24 stsp <dl class="Bl-tag Bl-compact">
414 742bb3a1 2022-10-24 stsp <dt><span class="Pa">/etc/gotd.conf</span></dt>
415 742bb3a1 2022-10-24 stsp <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
416 742bb3a1 2022-10-24 stsp </dl>
417 742bb3a1 2022-10-24 stsp </section>
418 742bb3a1 2022-10-24 stsp <section class="Sh">
419 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
420 742bb3a1 2022-10-24 stsp <div class="Bd Bd-indent Li">
421 47f19dd5 2023-01-17 stsp <pre># Run as the default user:
422 742bb3a1 2022-10-24 stsp user _gotd
423 742bb3a1 2022-10-24 stsp
424 47f19dd5 2023-01-17 stsp # Listen on the default socket:
425 47f19dd5 2023-01-17 stsp listen on &quot;/var/run/gotd.sock&quot;
426 47f19dd5 2023-01-17 stsp
427 742bb3a1 2022-10-24 stsp # This repository can be accessed via ssh://user@example.com/src
428 742bb3a1 2022-10-24 stsp repository &quot;src&quot; {
429 742bb3a1 2022-10-24 stsp path &quot;/var/git/src.git&quot;
430 47f19dd5 2023-01-17 stsp permit rw flan_hacker
431 47f19dd5 2023-01-17 stsp permit rw :developers
432 47f19dd5 2023-01-17 stsp permit ro anonymous
433 e68eaba8 2023-04-20 stsp
434 e68eaba8 2023-04-20 stsp protect branch &quot;main&quot;
435 e68eaba8 2023-04-20 stsp protect tag namespace &quot;refs/tags/&quot;
436 742bb3a1 2022-10-24 stsp }
437 742bb3a1 2022-10-24 stsp
438 742bb3a1 2022-10-24 stsp # This repository can be accessed via
439 742bb3a1 2022-10-24 stsp # ssh://user@example.com/openbsd/ports
440 742bb3a1 2022-10-24 stsp repository &quot;openbsd/ports&quot; {
441 742bb3a1 2022-10-24 stsp path &quot;/var/git/ports.git&quot;
442 47f19dd5 2023-01-17 stsp permit rw :porters
443 47f19dd5 2023-01-17 stsp permit ro anonymous
444 47f19dd5 2023-01-17 stsp deny flan_hacker
445 e68eaba8 2023-04-20 stsp
446 e68eaba8 2023-04-20 stsp protect {
447 e68eaba8 2023-04-20 stsp branch &quot;main&quot;
448 e68eaba8 2023-04-20 stsp tag namespace &quot;refs/tags/&quot;
449 e68eaba8 2023-04-20 stsp }
450 bd0bf387 2024-04-23 stsp
451 bd0bf387 2024-04-23 stsp notify {
452 bd0bf387 2024-04-23 stsp branch &quot;main&quot;
453 bd0bf387 2024-04-23 stsp reference namespace &quot;refs/tags/&quot;
454 bd0bf387 2024-04-23 stsp email to openbsd-ports-changes@example.com
455 bd0bf387 2024-04-23 stsp }
456 47f19dd5 2023-01-17 stsp }
457 47f19dd5 2023-01-17 stsp
458 47f19dd5 2023-01-17 stsp # Use a larger request timeout value:
459 47f19dd5 2023-01-17 stsp connection request timeout 2h
460 47f19dd5 2023-01-17 stsp
461 47f19dd5 2023-01-17 stsp # Some users are granted a higher concurrent connection limit:
462 47f19dd5 2023-01-17 stsp connection {
463 47f19dd5 2023-01-17 stsp limit user flan_hacker 16
464 47f19dd5 2023-01-17 stsp limit user anonymous 32
465 742bb3a1 2022-10-24 stsp }</pre>
466 742bb3a1 2022-10-24 stsp </div>
467 742bb3a1 2022-10-24 stsp </section>
468 742bb3a1 2022-10-24 stsp <section class="Sh">
469 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
470 742bb3a1 2022-10-24 stsp ALSO</a></h2>
471 742bb3a1 2022-10-24 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
472 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
473 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a></p>
474 742bb3a1 2022-10-24 stsp </section>
475 742bb3a1 2022-10-24 stsp </main>
476 742bb3a1 2022-10-24 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
477 56f3f26e 2024-06-03 stsp line"><span class="foot-left"></span><span class="foot-date">June 3,
478 2b1d45b9 2024-03-11 stsp 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
479 742bb3a1 2022-10-24 stsp </body>
480 742bb3a1 2022-10-24 stsp </html>