2 13b2bc37 2022-10-23 stsp .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
4 13b2bc37 2022-10-23 stsp .\" Permission to use, copy, modify, and distribute this software for any
5 13b2bc37 2022-10-23 stsp .\" purpose with or without fee is hereby granted, provided that the above
6 13b2bc37 2022-10-23 stsp .\" copyright notice and this permission notice appear in all copies.
8 13b2bc37 2022-10-23 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 13b2bc37 2022-10-23 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 13b2bc37 2022-10-23 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 13b2bc37 2022-10-23 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 13b2bc37 2022-10-23 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 13b2bc37 2022-10-23 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 13b2bc37 2022-10-23 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 13b2bc37 2022-10-23 stsp .Dd $Mdocdate$
17 13b2bc37 2022-10-23 stsp .Dt GOTD.CONF 5
20 13b2bc37 2022-10-23 stsp .Nm gotd.conf
21 13b2bc37 2022-10-23 stsp .Nd gotd configuration file
22 13b2bc37 2022-10-23 stsp .Sh DESCRIPTION
24 13b2bc37 2022-10-23 stsp is the run-time configuration file for
25 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
27 13b2bc37 2022-10-23 stsp The file format is line-based, with one configuration directive per line.
28 13b2bc37 2022-10-23 stsp Any lines beginning with a
30 13b2bc37 2022-10-23 stsp are treated as comments and ignored.
31 13b2bc37 2022-10-23 stsp .Sh GLOBAL CONFIGURATION
32 13b2bc37 2022-10-23 stsp The available global configuration directives are as follows:
33 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
34 40b85cca 2023-01-03 stsp .It Ic connection Ar option
35 40b85cca 2023-01-03 stsp Set the specified options and limits for connections to the
37 40b85cca 2023-01-03 stsp unix socket.
40 40b85cca 2023-01-03 stsp .Ic connection
41 40b85cca 2023-01-03 stsp directive may be specified multiple times, and multiple
43 40b85cca 2023-01-03 stsp arguments may be specified within curly braces:
45 40b85cca 2023-01-03 stsp .Ic connection Brq Ar ...
47 40b85cca 2023-01-03 stsp Each option should only be specified once.
48 40b85cca 2023-01-03 stsp If a given option is listed multiple times, the last line which sets this
49 40b85cca 2023-01-03 stsp option wins.
51 40b85cca 2023-01-03 stsp Valid connection options are:
52 40b85cca 2023-01-03 stsp .Bl -tag -width Ds
53 40b85cca 2023-01-03 stsp .It Ic request timeout Ar seconds
54 40b85cca 2023-01-03 stsp Specify the inactivity timeout for operations between client and server.
55 40b85cca 2023-01-03 stsp If this timeout is exceeded while a Git protocol request is being processed,
56 40b85cca 2023-01-03 stsp the request will be aborted and the connection will be terminated.
58 2be11cde 2023-01-03 op The timeout value may also have a suffix indicating its unit of measure.
59 2be11cde 2023-01-03 op Supported suffixes are:
61 2be11cde 2023-01-03 op .Bl -tag -compact -width tenletters
62 2be11cde 2023-01-03 op .It Ar s No or Ar S
64 2be11cde 2023-01-03 op .It Ar m No or Ar M
66 2be11cde 2023-01-03 op .It Ar h No or Ar H
70 2be11cde 2023-01-03 op The default timeout is 1h (3600 seconds, one hour).
71 40b85cca 2023-01-03 stsp This should only be changed if legitimate requests are exceeding the default
72 40b85cca 2023-01-03 stsp timeout for some reason, such as the server spending an extraordinary
73 40b85cca 2023-01-03 stsp amount of time generating a pack file.
74 40b85cca 2023-01-03 stsp .It Ic limit Ic user Ar identity Ar number
75 40b85cca 2023-01-03 stsp Limit the maximum amount of concurrent connections by the user with
76 40b85cca 2023-01-03 stsp the username
77 40b85cca 2023-01-03 stsp .Ar identity
79 40b85cca 2023-01-03 stsp .Ar number .
80 40b85cca 2023-01-03 stsp Numeric user IDs are also accepted.
82 40b85cca 2023-01-03 stsp The default per-user limit is 4.
83 40b85cca 2023-01-03 stsp This should only be changed if concurrent connections from a given user are
84 40b85cca 2023-01-03 stsp expected to exceed the default limit, for example if an anonymous user
85 40b85cca 2023-01-03 stsp is granted read access and many concurrent connections will share this
86 40b85cca 2023-01-03 stsp anonymous user identity.
88 83577462 2023-01-05 stsp .It Ic listen on Ar path
89 13b2bc37 2022-10-23 stsp Set the path to the unix socket which
91 13b2bc37 2022-10-23 stsp should listen on.
92 13b2bc37 2022-10-23 stsp If not specified, the path
93 13b2bc37 2022-10-23 stsp .Pa /var/run/gotd.sock
94 13b2bc37 2022-10-23 stsp will be used.
95 13b2bc37 2022-10-23 stsp .It Ic user Ar user
98 13b2bc37 2022-10-23 stsp which will run
99 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
102 eec68231 2022-12-14 stsp requires root privileges in order to create its unix socket.
103 13b2bc37 2022-10-23 stsp Afterwards,
105 13b2bc37 2022-10-23 stsp drops privileges to the specified
107 13b2bc37 2022-10-23 stsp If not specified, the user _gotd will be used.
109 13b2bc37 2022-10-23 stsp .Sh REPOSITORY CONFIGURATION
110 13b2bc37 2022-10-23 stsp At least one repository context must exist for
112 13b2bc37 2022-10-23 stsp to function.
113 0ccf3acb 2022-11-16 stsp For each repository, access rules must be configured using the
117 0ccf3acb 2022-11-16 stsp configuration directives.
118 0ccf3acb 2022-11-16 stsp Multiple access rules can be specified, and the last matching rule
119 0ccf3acb 2022-11-16 stsp determines the action taken.
120 0ccf3acb 2022-11-16 stsp If no rule matches, access to the repository is denied.
122 13b2bc37 2022-10-23 stsp A repository context is declared with a unique
124 13b2bc37 2022-10-23 stsp followed by repository-specific configuration directives inside curly braces:
126 13b2bc37 2022-10-23 stsp .Ic repository Ar name Brq ...
131 13b2bc37 2022-10-23 stsp clients can connect to a repository by including the repository's unique
133 13b2bc37 2022-10-23 stsp in the request URL.
134 13b2bc37 2022-10-23 stsp Clients appending the string
138 13b2bc37 2022-10-23 stsp will also be accepted.
140 13b2bc37 2022-10-23 stsp If desired, the
142 13b2bc37 2022-10-23 stsp may contain path-separators,
144 13b2bc37 2022-10-23 stsp to expose repositories as part of a virtual client-visible directory hierarchy.
146 13b2bc37 2022-10-23 stsp The available repository configuration directives are as follows:
147 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
148 0ccf3acb 2022-11-16 stsp .It Ic deny Ar identity
149 0ccf3acb 2022-11-16 stsp Deny repository access to users with the username
150 0ccf3acb 2022-11-16 stsp .Ar identity .
151 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
154 0ccf3acb 2022-11-16 stsp .Ar identity .
155 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
156 13b2bc37 2022-10-23 stsp .It Ic path Ar path
157 13b2bc37 2022-10-23 stsp Set the path to the Git repository.
158 3b706203 2023-01-02 stsp Must be specified.
159 0ccf3acb 2022-11-16 stsp .It Ic permit Ar mode Ar identity
160 0ccf3acb 2022-11-16 stsp Permit repository access to users with the username
161 0ccf3acb 2022-11-16 stsp .Ar identity .
164 0ccf3acb 2022-11-16 stsp argument must be set to either
166 0ccf3acb 2022-11-16 stsp for read-only access,
169 0ccf3acb 2022-11-16 stsp for read-write access.
170 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
173 0ccf3acb 2022-11-16 stsp .Ar identity .
174 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
175 9afa3de2 2023-04-04 stsp .It Ic protect Brq Ar ...
177 9afa3de2 2023-04-04 stsp .Cm protect
178 9afa3de2 2023-04-04 stsp directive may be used to protect branches and tags in a repository
179 9afa3de2 2023-04-04 stsp from being overwritten by potentially destructive client-side commands,
180 9afa3de2 2023-04-04 stsp such as when
181 9afa3de2 2023-04-04 stsp .Cm got send -f
183 9afa3de2 2023-04-04 stsp .Cm git push -f
184 9afa3de2 2023-04-04 stsp are used to change the history of a branch.
186 9afa3de2 2023-04-04 stsp To build a set of protected branches and tags, multiple
187 9afa3de2 2023-04-04 stsp .Ic protect
188 9afa3de2 2023-04-04 stsp directives may be specified per repository and
190 9afa3de2 2023-04-04 stsp .Ic protect
191 9afa3de2 2023-04-04 stsp directive parameters may be specified within curly braces.
193 9afa3de2 2023-04-04 stsp The available
194 9afa3de2 2023-04-04 stsp .Cm protect
195 9afa3de2 2023-04-04 stsp parameters are as follows:
197 9afa3de2 2023-04-04 stsp .Bl -tag -width Ds
198 9afa3de2 2023-04-04 stsp .It Ic branch Ar name
199 9afa3de2 2023-04-04 stsp Protect the named branch.
200 9afa3de2 2023-04-04 stsp The branch may be created if it does not exist yet.
201 9afa3de2 2023-04-04 stsp Attempts to delete the branch or change its history will be denied.
205 9afa3de2 2023-04-04 stsp does not already begin with
206 9afa3de2 2023-04-04 stsp .Dq refs/heads/
207 9afa3de2 2023-04-04 stsp it will be looked up in the
208 9afa3de2 2023-04-04 stsp .Dq refs/heads/
209 9afa3de2 2023-04-04 stsp reference namespace.
210 9afa3de2 2023-04-04 stsp .It Ic branch Ic namespace Ar namespace
211 9afa3de2 2023-04-04 stsp Protect the given reference namespace, assuming that references in
212 9afa3de2 2023-04-04 stsp this namespace represent branches.
213 9afa3de2 2023-04-04 stsp New branches may be created in the namespace.
214 9afa3de2 2023-04-04 stsp Attempts to change the history of branches or delete them will be denied.
217 9afa3de2 2023-04-04 stsp .Ar namespace
218 9afa3de2 2023-04-04 stsp argument must be absolute, starting with
219 9afa3de2 2023-04-04 stsp .Dq refs/ .
220 9afa3de2 2023-04-04 stsp .It Ic tag Ic namespace Ar namespace
221 9afa3de2 2023-04-04 stsp Protect the given reference namespace, assuming that references in
222 9afa3de2 2023-04-04 stsp this namespace represent tags.
223 9afa3de2 2023-04-04 stsp New tags may be created in the namespace.
224 9afa3de2 2023-04-04 stsp Attempts to change or delete existing tags will be denied.
227 9afa3de2 2023-04-04 stsp .Ar namespace
228 9afa3de2 2023-04-04 stsp argument must be absolute, starting with
229 9afa3de2 2023-04-04 stsp .Dq refs/ .
232 9afa3de2 2023-04-04 stsp The special reference namespaces
233 9afa3de2 2023-04-04 stsp .Dq refs/got/
235 9afa3de2 2023-04-04 stsp .Dq refs/remotes/
236 9afa3de2 2023-04-04 stsp do not need to be listed in
238 9afa3de2 2023-04-04 stsp These namespaces are always protected and even attempts to create new
239 9afa3de2 2023-04-04 stsp references in these namespaces will always be denied.
240 ba97b2d7 2024-03-20 stsp .It Ic notify Brq Ar ...
243 ba97b2d7 2024-03-20 stsp directive enables notifications about new commits or tags
244 ba97b2d7 2024-03-20 stsp added to the repository.
246 ba97b2d7 2024-03-20 stsp Notifications via email require an SMTP daemon which accepts mail
247 ba97b2d7 2024-03-20 stsp for forwarding without requiring client authentication or encryption.
251 ba97b2d7 2024-03-20 stsp .Xr smtpd 8
252 ba97b2d7 2024-03-20 stsp daemon can be used for this purpose.
253 ba97b2d7 2024-03-20 stsp The default content of email notifications looks similar to the output of the
254 ba97b2d7 2024-03-20 stsp .Cm got log -d
257 5565365c 2024-03-27 op Notifications via HTTP require a HTTP or HTTPS server which is accepting
258 5565365c 2024-03-27 op POST requests with or without HTTP Basic authentication.
259 5565365c 2024-03-27 op Depending on the use case a custom server-side CGI script may be required
260 5565365c 2024-03-27 op for the processing of notifications.
261 5565365c 2024-03-27 op HTTP notifications can achieve functionality
262 5565365c 2024-03-27 op similar to Git's server-side post-receive hook script with
264 5565365c 2024-03-27 op by triggering arbitrary post-commit actions via the HTTP server.
268 ba97b2d7 2024-03-20 stsp directive expects parameters which must be enclosed in curly braces.
269 ba97b2d7 2024-03-20 stsp The available parameters are as follows:
271 ba97b2d7 2024-03-20 stsp .Bl -tag -width Ds
272 ba97b2d7 2024-03-20 stsp .It Ic branch Ar name
273 ba97b2d7 2024-03-20 stsp Send notifications about commits to the named branch.
276 ba97b2d7 2024-03-20 stsp will be looked up in the
277 ba97b2d7 2024-03-20 stsp .Dq refs/heads/
278 ba97b2d7 2024-03-20 stsp reference namespace.
279 ba97b2d7 2024-03-20 stsp This directive may be specified multiple times to build a list of
280 ba97b2d7 2024-03-20 stsp branches to send notifications for.
281 ba97b2d7 2024-03-20 stsp If neither a
284 ba97b2d7 2024-03-20 stsp .Ic reference namespace
285 ba97b2d7 2024-03-20 stsp are specified then changes to any reference will trigger notifications.
286 ba97b2d7 2024-03-20 stsp .It Ic reference Ic namespace Ar namespace
287 ba97b2d7 2024-03-20 stsp Send notifications about commits or tags within a reference namespace.
288 ba97b2d7 2024-03-20 stsp This directive may be specified multiple times to build a list of
289 ba97b2d7 2024-03-20 stsp namespaces to send notifications for.
290 ba97b2d7 2024-03-20 stsp If neither a
293 ba97b2d7 2024-03-20 stsp .Ic reference namespace
294 ba97b2d7 2024-03-20 stsp are specified then changes to any reference will trigger notifications.
295 ba97b2d7 2024-03-20 stsp .It Ic email Oo Ic from Ar sender Oc Ic to Ar recipient Oo Ic reply to Ar responder Oc Oo Ic relay Ar hostname Oo Ic port Ar port Oc Oc
296 ba97b2d7 2024-03-20 stsp Send notifications via email to the specified
297 ba97b2d7 2024-03-20 stsp .Ar recipient .
298 ba97b2d7 2024-03-20 stsp This directive may be specified multiple times to build a list of
299 ba97b2d7 2024-03-20 stsp recipients to send notifications to.
302 ba97b2d7 2024-03-20 stsp .Ar recipient
303 ba97b2d7 2024-03-20 stsp must be an email addresses that accepts mail.
306 ba97b2d7 2024-03-20 stsp will be used as the From address.
307 ba97b2d7 2024-03-20 stsp If not specified, the sender defaults to an email address composed of the user
308 ba97b2d7 2024-03-20 stsp account running
310 ba97b2d7 2024-03-20 stsp and the local hostname.
313 ba97b2d7 2024-03-20 stsp .Ar responder
314 ba97b2d7 2024-03-20 stsp is specified via the
315 ba97b2d7 2024-03-20 stsp .Ic reply to
316 ba97b2d7 2024-03-20 stsp directive, the
317 ba97b2d7 2024-03-20 stsp .Ar responder
318 ba97b2d7 2024-03-20 stsp will be used as the Reply-to address.
319 ba97b2d7 2024-03-20 stsp Setting the Reply-to header can be useful if replies should go to a
320 ba97b2d7 2024-03-20 stsp mailing list instead of the
321 ba97b2d7 2024-03-20 stsp .Ar sender ,
322 ba97b2d7 2024-03-20 stsp for example.
324 ba97b2d7 2024-03-20 stsp By default, mail will be sent to the SMTP server listening on the loopback
325 ba97b2d7 2024-03-20 stsp address 127.0.0.1 on port 25.
330 ba97b2d7 2024-03-20 stsp directives can be used to specify a different SMTP server address and port.
332 5565365c 2024-03-27 op .It Ic url Ar URL Oo Ic user Ar user Ic password Ar password Oc
333 5565365c 2024-03-27 op Send notifications via HTTP.
334 5565365c 2024-03-27 op This directive may be specified multiple times to build a list of
335 5565365c 2024-03-27 op HTTP servers to send notifications to.
337 5565365c 2024-03-27 op The notification will be sent as a POST request to the given
339 5565365c 2024-03-27 op which must be a valid HTTP URL and begin with either
342 5565365c 2024-03-27 op .Dq https:// .
343 5565365c 2024-03-27 op If HTTPS is used, sending of notifications will only succeed if
344 5565365c 2024-03-27 op no TLS errors occur.
350 5565365c 2024-03-27 op directives enable HTTP Basic authentication.
351 5565365c 2024-03-27 op If used, both a
355 5565365c 2024-03-27 op must be specified.
358 5565365c 2024-03-27 op must not be an empty string.
360 5565365c 2024-03-27 op The request body contains a JSON document with the following objects:
361 5565365c 2024-03-27 op .Bl -tag -width { "notifications" : array }
362 5565365c 2024-03-27 op .It { "notifications" : array }
363 5565365c 2024-03-27 op The top-level object contains an array of all notifications in this request.
367 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
368 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
369 13b2bc37 2022-10-23 stsp Location of the
371 13b2bc37 2022-10-23 stsp configuration file.
373 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
374 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
375 6f854dde 2023-01-04 stsp # Run as the default user:
378 83577462 2023-01-05 stsp # Listen on the default socket:
379 83577462 2023-01-05 stsp listen on "/var/run/gotd.sock"
381 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
382 13b2bc37 2022-10-23 stsp repository "src" {
383 13b2bc37 2022-10-23 stsp path "/var/git/src.git"
384 0ccf3acb 2022-11-16 stsp permit rw flan_hacker
385 0ccf3acb 2022-11-16 stsp permit rw :developers
386 0ccf3acb 2022-11-16 stsp permit ro anonymous
388 9afa3de2 2023-04-04 stsp protect branch "main"
389 9afa3de2 2023-04-04 stsp protect tag namespace "refs/tags/"
392 13b2bc37 2022-10-23 stsp # This repository can be accessed via
393 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
394 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
395 13b2bc37 2022-10-23 stsp path "/var/git/ports.git"
396 0ccf3acb 2022-11-16 stsp permit rw :porters
397 0ccf3acb 2022-11-16 stsp permit ro anonymous
398 0ccf3acb 2022-11-16 stsp deny flan_hacker
401 9afa3de2 2023-04-04 stsp branch "main"
402 9afa3de2 2023-04-04 stsp tag namespace "refs/tags/"
406 ba97b2d7 2024-03-20 stsp branch "main"
407 ba97b2d7 2024-03-20 stsp reference namespace "refs/tags/"
408 ba97b2d7 2024-03-20 stsp email to openbsd-ports-changes@example.com
409 ba97b2d7 2024-03-20 stsp .\" url https://example.com/notify/ user "flan_announcer" password "secret"
413 40b85cca 2023-01-03 stsp # Use a larger request timeout value:
414 2be11cde 2023-01-03 op connection request timeout 2h
416 40b85cca 2023-01-03 stsp # Some users are granted a higher concurrent connection limit:
417 40b85cca 2023-01-03 stsp connection {
418 40b85cca 2023-01-03 stsp limit user flan_hacker 16
419 40b85cca 2023-01-03 stsp limit user anonymous 32
422 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
423 13b2bc37 2022-10-23 stsp .Xr got 1 ,
424 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,
