2 .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .Nd gotd configuration file
24 is the run-time configuration file for
27 The file format is line-based, with one configuration directive per line.
28 Any lines beginning with a
30 are treated as comments and ignored.
31 .Sh GLOBAL CONFIGURATION
32 The available global configuration directives are as follows:
34 .It Ic connection Ar option
35 Set the specified options and limits for connections to the
41 directive may be specified multiple times, and multiple
43 arguments may be specified within curly braces:
45 .Ic connection Brq Ar ...
47 Each option should only be specified once.
48 If a given option is listed multiple times, the last line which sets this
51 Valid connection options are:
53 .It Ic request timeout Ar seconds
54 Specify the inactivity timeout for operations between client and server.
55 If this timeout is exceeded while a Git protocol request is being processed,
56 the request will be aborted and the connection will be terminated.
58 The timeout value may also have a suffix indicating its unit of measure.
59 Supported suffixes are:
61 .Bl -tag -compact -width tenletters
70 The default timeout is 1h (3600 seconds, one hour).
71 This should only be changed if legitimate requests are exceeding the default
72 timeout for some reason, such as the server spending an extraordinary
73 amount of time generating a pack file.
74 .It Ic limit Ic user Ar identity Ar number
75 Limit the maximum amount of concurrent connections by the user with
80 Numeric user IDs are also accepted.
82 The default per-user limit is 4.
83 This should only be changed if concurrent connections from a given user are
84 expected to exceed the default limit, for example if an anonymous user
85 is granted read access and many concurrent connections will share this
86 anonymous user identity.
88 .It Ic listen on Ar path
89 Set the path to the unix socket which
92 If not specified, the path
93 .Pa /var/run/gotd.sock
102 requires root privileges in order to create its unix socket.
105 drops privileges to the specified
107 If not specified, the user _gotd will be used.
109 .Sh REPOSITORY CONFIGURATION
110 At least one repository context must exist for
113 For each repository, access rules must be configured using the
117 configuration directives.
118 Multiple access rules can be specified, and the last matching rule
119 determines the action taken.
120 If no rule matches, access to the repository is denied.
122 A repository context is declared with a unique
124 followed by repository-specific configuration directives inside curly braces:
126 .Ic repository Ar name Brq ...
131 clients can connect to a repository by including the repository's unique
134 Clients appending the string
138 will also be accepted.
142 may contain path-separators,
144 to expose repositories as part of a virtual client-visible directory hierarchy.
146 The available repository configuration directives are as follows:
148 .It Ic deny Ar identity
149 Deny repository access to users with the username
151 Group names may be matched by prepending a colon
155 Numeric IDs are also accepted.
157 Set the path to the Git repository.
159 .It Ic permit Ar mode Ar identity
160 Permit repository access to users with the username
164 argument must be set to either
166 for read-only access,
169 for read-write access.
170 Group names may be matched by prepending a colon
174 Numeric IDs are also accepted.
175 .It Ic protect Brq Ar ...
178 directive may be used to protect branches and tags in a repository
179 from being overwritten by potentially destructive client-side commands,
184 are used to change the history of a branch.
186 To build a set of protected branches and tags, multiple
188 directives may be specified per repository and
191 directive parameters may be specified within curly braces.
195 parameters are as follows:
197 .It Ic branch Ar name
198 Protect the named branch.
199 The branch may be created if it does not exist yet.
200 Attempts to delete the branch or change its history will be denied.
204 does not already begin with
206 it will be looked up in the
209 .It Ic branch Ic namespace Ar namespace
210 Protect the given reference namespace, assuming that references in
211 this namespace represent branches.
212 New branches may be created in the namespace.
213 Attempts to change the history of branches or delete them will be denied.
217 argument must be absolute, starting with
219 .It Ic tag Ic namespace Ar namespace
220 Protect the given reference namespace, assuming that references in
221 this namespace represent tags.
222 New tags may be created in the namespace.
223 Attempts to change or delete existing tags will be denied.
227 argument must be absolute, starting with
231 The special reference namespaces
235 do not need to be listed in
237 These namespaces are always protected and even attempts to create new
238 references in these namespaces will always be denied.
239 .It Ic notify Brq Ar ...
242 directive enables notifications about new commits or tags
243 added to the repository.
245 Notifications via email require an SMTP daemon which accepts mail
246 for forwarding without requiring client authentication or encryption.
251 daemon can be used for this purpose.
252 The default content of email notifications looks similar to the output of the
256 Notifications via HTTP require a HTTP or HTTPS server which is accepting
257 POST requests with or without HTTP Basic authentication.
258 Depending on the use case a custom server-side CGI script may be required
259 for the processing of notifications.
260 HTTP notifications can achieve functionality
261 similar to Git's server-side post-receive hook script with
263 by triggering arbitrary post-commit actions via the HTTP server.
267 directive expects parameters which must be enclosed in curly braces.
268 The available parameters are as follows:
270 .It Ic branch Ar name
271 Send notifications about commits to the named branch.
274 will be looked up in the
277 This directive may be specified multiple times to build a list of
278 branches to send notifications for.
282 .Ic reference namespace
283 are specified then changes to any reference will trigger notifications.
284 .It Ic reference Ic namespace Ar namespace
285 Send notifications about commits or tags within a reference namespace.
286 This directive may be specified multiple times to build a list of
287 namespaces to send notifications for.
291 .Ic reference namespace
292 are specified then changes to any reference will trigger notifications.
293 .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 Send notifications via email to the specified
296 This directive may be specified multiple times to build a list of
297 recipients to send notifications to.
301 must be an email addresses that accepts mail.
304 will be used as the From address.
305 If not specified, the sender defaults to an email address composed of the user
308 and the local hostname.
316 will be used as the Reply-to address.
317 Setting the Reply-to header can be useful if replies should go to a
318 mailing list instead of the
322 By default, mail will be sent to the SMTP server listening on the loopback
323 address 127.0.0.1 on port 25.
328 directives can be used to specify a different SMTP server address and port.
329 .It Ic url Ar URL Oo Ic user Ar user Ic password Ar password Oo Ic insecure Oc Oc
330 Send notifications via HTTP.
331 This directive may be specified multiple times to build a list of
332 HTTP servers to send notifications to.
334 The notification will be sent as a POST request to the given
336 which must be a valid HTTP URL and begin with either
340 If HTTPS is used, sending of notifications will only succeed if
347 directives enable HTTP Basic authentication.
355 must not be an empty string.
358 option is specified the notification target
362 URL to avoid leaking of authentication credentials.
364 The request body contains a JSON object with a
366 property containing an array of notification objects.
367 Each notification object has a
370 Depending on the type, each notification object has different fields.
374 The commit notification object has the following fields.
375 Except where noted, all are optional.
378 Boolean, indicates whether the object has all the fields set.
379 When several commits are batched in a single send operation, not all of
380 the fields are available for each commit object.
382 The repository name as string.
384 The commit ID as string, may be abbreviated.
386 An object with the committer information with the following fields:
388 .Bl -tag -compact -width Ds
390 Committer's full name.
394 Committer's mail address.
396 Committer's username.
397 This is the only field guaranteed to be set.
400 An object with the author information.
401 Has the same fields as the
405 String representation of the date as
411 .Sq %a %b %e %X %Y UTC
414 The first line of the commit message.
415 This field is always set.
417 The complete commit message, may be unset.
419 An object with the summarized changes, may be unset.
422 field with an array of objects describing the changes per-file and a
424 field with the cumulative changes.
425 The changes per-file contains the following fields:
427 .Bl -tag -compact -width removed
429 A string describing the action, can be
439 The number of lines added.
441 The number of lines removed.
446 object contains two fields:
450 which are the number of added and removed lines respectively.
452 .It Dv branch-deleted
453 The branch deleted notifications has the following fields, all guaranteed
455 .Bl -tag -compact -width Ds
457 The repository name as string.
459 The removed branch reference.
461 The hash of the commit pointed by the deleted branch.
464 The tag notification has the following fields, all guaranteed to be set:
467 The repository name as string.
471 The user information, with the same format of the
475 notification but with all the field guaranteed to be set.
479 The object being tagged.
480 It contains the fields
482 with the object type and
484 with the object id being tagged.
492 .Bl -tag -width Ds -compact
493 .It Pa /etc/gotd.conf
499 .Bd -literal -offset indent
500 # Run as the default user:
503 # Listen on the default socket:
504 listen on "/var/run/gotd.sock"
506 # This repository can be accessed via ssh://user@example.com/src
508 path "/var/git/src.git"
509 permit rw flan_hacker
510 permit rw :developers
513 protect branch "main"
514 protect tag namespace "refs/tags/"
517 # This repository can be accessed via
518 # ssh://user@example.com/openbsd/ports
519 repository "openbsd/ports" {
520 path "/var/git/ports.git"
527 tag namespace "refs/tags/"
532 reference namespace "refs/tags/"
533 email to openbsd-ports-changes@example.com
534 .\" url https://example.com/notify/ user "flan_announcer" password "secret"
538 # Use a larger request timeout value:
539 connection request timeout 2h
541 # Some users are granted a higher concurrent connection limit:
543 limit user flan_hacker 16
544 limit user anonymous 32
