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:
196 9afa3de2 2023-04-04 stsp .Bl -tag -width Ds
197 9afa3de2 2023-04-04 stsp .It Ic branch Ar name
198 9afa3de2 2023-04-04 stsp Protect the named branch.
199 9afa3de2 2023-04-04 stsp The branch may be created if it does not exist yet.
200 9afa3de2 2023-04-04 stsp Attempts to delete the branch or change its history will be denied.
204 9afa3de2 2023-04-04 stsp does not already begin with
205 9afa3de2 2023-04-04 stsp .Dq refs/heads/
206 9afa3de2 2023-04-04 stsp it will be looked up in the
207 9afa3de2 2023-04-04 stsp .Dq refs/heads/
208 9afa3de2 2023-04-04 stsp reference namespace.
209 9afa3de2 2023-04-04 stsp .It Ic branch Ic namespace Ar namespace
210 9afa3de2 2023-04-04 stsp Protect the given reference namespace, assuming that references in
211 9afa3de2 2023-04-04 stsp this namespace represent branches.
212 9afa3de2 2023-04-04 stsp New branches may be created in the namespace.
213 9afa3de2 2023-04-04 stsp Attempts to change the history of branches or delete them will be denied.
216 9afa3de2 2023-04-04 stsp .Ar namespace
217 9afa3de2 2023-04-04 stsp argument must be absolute, starting with
218 9afa3de2 2023-04-04 stsp .Dq refs/ .
219 9afa3de2 2023-04-04 stsp .It Ic tag Ic namespace Ar namespace
220 9afa3de2 2023-04-04 stsp Protect the given reference namespace, assuming that references in
221 9afa3de2 2023-04-04 stsp this namespace represent tags.
222 9afa3de2 2023-04-04 stsp New tags may be created in the namespace.
223 9afa3de2 2023-04-04 stsp Attempts to change or delete existing tags will be denied.
226 9afa3de2 2023-04-04 stsp .Ar namespace
227 9afa3de2 2023-04-04 stsp argument must be absolute, starting with
228 9afa3de2 2023-04-04 stsp .Dq refs/ .
231 9afa3de2 2023-04-04 stsp The special reference namespaces
232 9afa3de2 2023-04-04 stsp .Dq refs/got/
234 9afa3de2 2023-04-04 stsp .Dq refs/remotes/
235 9afa3de2 2023-04-04 stsp do not need to be listed in
237 9afa3de2 2023-04-04 stsp These namespaces are always protected and even attempts to create new
238 9afa3de2 2023-04-04 stsp references in these namespaces will always be denied.
239 ba97b2d7 2024-03-20 stsp .It Ic notify Brq Ar ...
242 ba97b2d7 2024-03-20 stsp directive enables notifications about new commits or tags
243 ba97b2d7 2024-03-20 stsp added to the repository.
245 ba97b2d7 2024-03-20 stsp Notifications via email require an SMTP daemon which accepts mail
246 ba97b2d7 2024-03-20 stsp for forwarding without requiring client authentication or encryption.
250 ba97b2d7 2024-03-20 stsp .Xr smtpd 8
251 ba97b2d7 2024-03-20 stsp daemon can be used for this purpose.
252 ba97b2d7 2024-03-20 stsp The default content of email notifications looks similar to the output of the
253 ba97b2d7 2024-03-20 stsp .Cm got log -d
256 5565365c 2024-03-27 op Notifications via HTTP require a HTTP or HTTPS server which is accepting
257 5565365c 2024-03-27 op POST requests with or without HTTP Basic authentication.
258 5565365c 2024-03-27 op Depending on the use case a custom server-side CGI script may be required
259 5565365c 2024-03-27 op for the processing of notifications.
260 5565365c 2024-03-27 op HTTP notifications can achieve functionality
261 5565365c 2024-03-27 op similar to Git's server-side post-receive hook script with
263 5565365c 2024-03-27 op by triggering arbitrary post-commit actions via the HTTP server.
267 ba97b2d7 2024-03-20 stsp directive expects parameters which must be enclosed in curly braces.
268 ba97b2d7 2024-03-20 stsp The available parameters are as follows:
269 ba97b2d7 2024-03-20 stsp .Bl -tag -width Ds
270 ba97b2d7 2024-03-20 stsp .It Ic branch Ar name
271 ba97b2d7 2024-03-20 stsp Send notifications about commits to the named branch.
274 ba97b2d7 2024-03-20 stsp will be looked up in the
275 ba97b2d7 2024-03-20 stsp .Dq refs/heads/
276 ba97b2d7 2024-03-20 stsp reference namespace.
277 ba97b2d7 2024-03-20 stsp This directive may be specified multiple times to build a list of
278 ba97b2d7 2024-03-20 stsp branches to send notifications for.
279 ba97b2d7 2024-03-20 stsp If neither a
282 ba97b2d7 2024-03-20 stsp .Ic reference namespace
283 ba97b2d7 2024-03-20 stsp are specified then changes to any reference will trigger notifications.
284 ba97b2d7 2024-03-20 stsp .It Ic reference Ic namespace Ar namespace
285 ba97b2d7 2024-03-20 stsp Send notifications about commits or tags within a reference namespace.
286 ba97b2d7 2024-03-20 stsp This directive may be specified multiple times to build a list of
287 ba97b2d7 2024-03-20 stsp namespaces to send notifications for.
288 ba97b2d7 2024-03-20 stsp If neither a
291 ba97b2d7 2024-03-20 stsp .Ic reference namespace
292 ba97b2d7 2024-03-20 stsp are specified then changes to any reference will trigger notifications.
293 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
294 ba97b2d7 2024-03-20 stsp Send notifications via email to the specified
295 ba97b2d7 2024-03-20 stsp .Ar recipient .
296 ba97b2d7 2024-03-20 stsp This directive may be specified multiple times to build a list of
297 ba97b2d7 2024-03-20 stsp recipients to send notifications to.
300 ba97b2d7 2024-03-20 stsp .Ar recipient
301 ba97b2d7 2024-03-20 stsp must be an email addresses that accepts mail.
304 ba97b2d7 2024-03-20 stsp will be used as the From address.
305 ba97b2d7 2024-03-20 stsp If not specified, the sender defaults to an email address composed of the user
306 ba97b2d7 2024-03-20 stsp account running
308 ba97b2d7 2024-03-20 stsp and the local hostname.
311 ba97b2d7 2024-03-20 stsp .Ar responder
312 ba97b2d7 2024-03-20 stsp is specified via the
313 ba97b2d7 2024-03-20 stsp .Ic reply to
314 ba97b2d7 2024-03-20 stsp directive, the
315 ba97b2d7 2024-03-20 stsp .Ar responder
316 ba97b2d7 2024-03-20 stsp will be used as the Reply-to address.
317 ba97b2d7 2024-03-20 stsp Setting the Reply-to header can be useful if replies should go to a
318 ba97b2d7 2024-03-20 stsp mailing list instead of the
319 ba97b2d7 2024-03-20 stsp .Ar sender ,
320 ba97b2d7 2024-03-20 stsp for example.
322 ba97b2d7 2024-03-20 stsp By default, mail will be sent to the SMTP server listening on the loopback
323 ba97b2d7 2024-03-20 stsp address 127.0.0.1 on port 25.
328 ba97b2d7 2024-03-20 stsp directives can be used to specify a different SMTP server address and port.
329 5565365c 2024-03-27 op .It Ic url Ar URL Oo Ic user Ar user Ic password Ar password Oc
330 5565365c 2024-03-27 op Send notifications via HTTP.
331 5565365c 2024-03-27 op This directive may be specified multiple times to build a list of
332 5565365c 2024-03-27 op HTTP servers to send notifications to.
334 5565365c 2024-03-27 op The notification will be sent as a POST request to the given
336 5565365c 2024-03-27 op which must be a valid HTTP URL and begin with either
339 5565365c 2024-03-27 op .Dq https:// .
340 5565365c 2024-03-27 op If HTTPS is used, sending of notifications will only succeed if
341 5565365c 2024-03-27 op no TLS errors occur.
347 5565365c 2024-03-27 op directives enable HTTP Basic authentication.
348 5565365c 2024-03-27 op If used, both a
352 5565365c 2024-03-27 op must be specified.
355 5565365c 2024-03-27 op must not be an empty string.
357 5565365c 2024-03-27 op The request body contains a JSON document with the following objects:
358 a397e3fb 2024-03-28 op .Bl -tag -width Ds
359 5565365c 2024-03-27 op .It { "notifications" : array }
360 5565365c 2024-03-27 op The top-level object contains an array of all notifications in this request.
365 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
366 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
367 13b2bc37 2022-10-23 stsp Location of the
369 13b2bc37 2022-10-23 stsp configuration file.
371 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
372 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
373 6f854dde 2023-01-04 stsp # Run as the default user:
376 83577462 2023-01-05 stsp # Listen on the default socket:
377 83577462 2023-01-05 stsp listen on "/var/run/gotd.sock"
379 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
380 13b2bc37 2022-10-23 stsp repository "src" {
381 13b2bc37 2022-10-23 stsp path "/var/git/src.git"
382 0ccf3acb 2022-11-16 stsp permit rw flan_hacker
383 0ccf3acb 2022-11-16 stsp permit rw :developers
384 0ccf3acb 2022-11-16 stsp permit ro anonymous
386 9afa3de2 2023-04-04 stsp protect branch "main"
387 9afa3de2 2023-04-04 stsp protect tag namespace "refs/tags/"
390 13b2bc37 2022-10-23 stsp # This repository can be accessed via
391 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
392 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
393 13b2bc37 2022-10-23 stsp path "/var/git/ports.git"
394 0ccf3acb 2022-11-16 stsp permit rw :porters
395 0ccf3acb 2022-11-16 stsp permit ro anonymous
396 0ccf3acb 2022-11-16 stsp deny flan_hacker
399 9afa3de2 2023-04-04 stsp branch "main"
400 9afa3de2 2023-04-04 stsp tag namespace "refs/tags/"
404 ba97b2d7 2024-03-20 stsp branch "main"
405 ba97b2d7 2024-03-20 stsp reference namespace "refs/tags/"
406 ba97b2d7 2024-03-20 stsp email to openbsd-ports-changes@example.com
407 ba97b2d7 2024-03-20 stsp .\" url https://example.com/notify/ user "flan_announcer" password "secret"
411 40b85cca 2023-01-03 stsp # Use a larger request timeout value:
412 2be11cde 2023-01-03 op connection request timeout 2h
414 40b85cca 2023-01-03 stsp # Some users are granted a higher concurrent connection limit:
415 40b85cca 2023-01-03 stsp connection {
416 40b85cca 2023-01-03 stsp limit user flan_hacker 16
417 40b85cca 2023-01-03 stsp limit user anonymous 32
420 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
421 13b2bc37 2022-10-23 stsp .Xr got 1 ,
422 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,
