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