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 Comments can be put anywhere in the file using a hash mark
30 and extend to the end of the current line.
31 Arguments names not beginning with a letter, digit or underscore,
32 as well as reserved words
33 .Pq such as Ic listen , Ic repository No or Ic user ,
35 Arguments containing whitespace should be surrounded by double quotes
38 Macros can be defined that are later expanded in context.
39 Macro names must start with a letter, digit, or underscore, and may
40 contain any of those characters, but may not be reserved words.
41 Macros are not expanded inside quotes.
43 .Bd -literal -offset indent
44 path = "/var/run/gotd.sock"
47 .Sh GLOBAL CONFIGURATION
48 The available global configuration directives are as follows:
50 .It Ic connection Ar option
51 Set the specified options and limits for connections to the
57 directive may be specified multiple times, and multiple
59 arguments may be specified within curly braces:
61 .Ic connection Brq Ar ...
63 Each option should only be specified once.
64 If a given option is listed multiple times, the last line which sets this
67 Valid connection options are:
69 .It Ic request timeout Ar seconds
70 Specify the inactivity timeout for operations between client and server.
71 If this timeout is exceeded while a Git protocol request is being processed,
72 the request will be aborted and the connection will be terminated.
74 The timeout value may also have a suffix indicating its unit of measure.
75 Supported suffixes are:
77 .Bl -tag -compact -width tenletters
86 The default timeout is 1h (3600 seconds, one hour).
87 This should only be changed if legitimate requests are exceeding the default
88 timeout for some reason, such as the server spending an extraordinary
89 amount of time generating a pack file.
90 .It Ic limit Ic user Ar identity Ar number
91 Limit the maximum amount of concurrent connections by the user with
96 Numeric user IDs are also accepted.
98 The default per-user limit is 4.
99 This should only be changed if concurrent connections from a given user are
100 expected to exceed the default limit, for example if an anonymous user
101 is granted read access and many concurrent connections will share this
102 anonymous user identity.
104 .It Ic listen on Ar path
105 Set the path to the unix socket which
108 If not specified, the path
109 .Pa /var/run/gotd.sock
118 requires root privileges in order to create its unix socket.
121 drops privileges to the specified
123 If not specified, the user _gotd will be used.
124 Numeric user IDs are also accepted.
126 .Sh REPOSITORY CONFIGURATION
127 At least one repository context must exist for
130 For each repository, access rules must be configured using the
134 configuration directives.
135 Multiple access rules can be specified, and the last matching rule
136 determines the action taken.
137 If no rule matches, access to the repository is denied.
139 A repository context is declared with a unique
141 followed by repository-specific configuration directives inside curly braces:
143 .Ic repository Ar name Brq ...
148 clients can connect to a repository by including the repository's unique
151 Clients appending the string
155 will also be accepted.
159 may contain path-separators,
161 to expose repositories as part of a virtual client-visible directory hierarchy.
163 The available repository configuration directives are as follows:
165 .It Ic deny Ar identity
166 Deny repository access to users with the username
168 Group names may be matched by prepending a colon
172 Numeric IDs are also accepted.
174 Set the path to the Git repository.
176 .It Ic permit Ar mode Ar identity
177 Permit repository access to users with the username
181 argument must be set to either
183 for read-only access,
186 for read-write access.
187 Group names may be matched by prepending a colon
191 Numeric IDs are also accepted.
192 .It Ic protect Brq Ar ...
195 directive may be used to protect branches and tags in a repository
196 from being overwritten by potentially destructive client-side commands,
201 are used to change the history of a branch.
203 To build a set of protected branches and tags, multiple
205 directives may be specified per repository and
208 directive parameters may be specified within curly braces.
212 parameters are as follows:
214 .It Ic branch Ar name
215 Protect the named branch.
216 The branch may be created if it does not exist yet.
217 Attempts to delete the branch or change its history will be denied.
221 does not already begin with
223 it will be looked up in the
226 .It Ic branch Ic namespace Ar namespace
227 Protect the given reference namespace, assuming that references in
228 this namespace represent branches.
229 New branches may be created in the namespace.
230 Attempts to change the history of branches or delete them will be denied.
234 argument must be absolute, starting with
236 .It Ic tag Ic namespace Ar namespace
237 Protect the given reference namespace, assuming that references in
238 this namespace represent tags.
239 New tags may be created in the namespace.
240 Attempts to change or delete existing tags will be denied.
244 argument must be absolute, starting with
248 The special reference namespaces
252 do not need to be listed in
254 These namespaces are always protected and even attempts to create new
255 references in these namespaces will always be denied.
256 .It Ic notify Brq Ar ...
259 directive enables notifications about new commits or tags
260 added to the repository.
262 Notifications via email require an SMTP daemon which accepts mail
263 for forwarding without requiring client authentication or encryption.
268 daemon can be used for this purpose.
269 The default content of email notifications looks similar to the output of the
273 Notifications via HTTP require a HTTP or HTTPS server which is accepting
274 POST requests with or without HTTP Basic authentication.
275 Depending on the use case a custom server-side CGI script may be required
276 for the processing of notifications.
277 HTTP notifications can achieve functionality
278 similar to Git's server-side post-receive hook script with
280 by triggering arbitrary post-commit actions via the HTTP server.
284 directive expects parameters which must be enclosed in curly braces.
285 The available parameters are as follows:
287 .It Ic branch Ar name
288 Send notifications about commits to the named branch.
291 will be looked up in the
294 This directive may be specified multiple times to build a list of
295 branches to send notifications for.
299 .Ic reference namespace
300 are specified then changes to any reference will trigger notifications.
301 .It Ic reference Ic namespace Ar namespace
302 Send notifications about commits or tags within a reference namespace.
303 This directive may be specified multiple times to build a list of
304 namespaces to send notifications for.
308 .Ic reference namespace
309 are specified then changes to any reference will trigger notifications.
310 .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
311 Send notifications via email to the specified
313 This directive may be specified multiple times to build a list of
314 recipients to send notifications to.
318 must be an email addresses that accepts mail.
321 will be used as the From address.
322 If not specified, the sender defaults to an email address composed of the user
325 and the local hostname.
333 will be used as the Reply-to address.
334 Setting the Reply-to header can be useful if replies should go to a
335 mailing list instead of the
339 By default, mail will be sent to the SMTP server listening on the loopback
340 address 127.0.0.1 on port 25.
345 directives can be used to specify a different SMTP server address and port.
346 .It Ic url Ar URL Oo Ic auth Ar label Oo Ic insecure Oc Oc Oo Ic hmac Ar label Oc
347 Send notifications via HTTP.
348 This directive may be specified multiple times to build a list of
349 HTTP servers to send notifications to.
351 The notification will be sent as a POST request to the given
353 which must be a valid HTTP URL and begin with either
357 If HTTPS is used, sending of notifications will only succeed if
362 directive enables HTTP Basic authentication.
363 Authentication credentials must be specified in the separate
364 .Xr gotd-secrets.conf 5
370 option is specified the notification target
374 URL to avoid leaking of authentication credentials.
378 secret is provided, the request body will be signed using HMAC, allowing the
379 receiver to verify the notification message's authenticity and integrity.
380 The HMAC secret to use must be specified in the separate
381 .Xr gotd-secrets.conf 5
385 The signature uses HMAC-SHA256 and will be sent in the HTTP header
386 .Dq X-Gotd-Signature .
388 The request body contains a JSON object with a
390 property containing an array of notification objects.
391 The following notification object properties are always present:
392 .Bl -tag -width authenticated_user
394 The repository name as a string.
395 .It Dv authenticated_user
396 The committer's user account as authenticated by
400 The notification object type as a string.
403 Each notification object carries additional type-specific properties.
404 The types and their type-specific properties are:
407 The commit notification object has the following fields.
408 Except where noted, all are optional.
411 Boolean, indicates whether the object has all the fields set.
412 When several commits are batched in a single send operation, not all of
413 the fields are available for each commit object.
415 The commit ID as string, may be abbreviated.
417 An object with the committer information with the following fields:
419 .Bl -tag -compact -width Ds
421 Committer's full name.
425 Committer's mail address.
427 Committer's username.
428 This is the only field guaranteed to be set.
431 An object with the author information.
432 Has the same fields as the
436 Number, representing the number of seconds since the Epoch in UTC.
438 The first line of the commit message.
439 This field is always set.
441 The complete commit message, may be unset.
443 An object with the summarized changes, may be unset.
446 field with an array of objects describing the changes per-file and a
448 field with the cumulative changes.
449 The changes per-file contains the following fields:
451 .Bl -tag -compact -width removed
453 A string describing the action, can be
463 The number of lines added.
465 The number of lines removed.
470 object contains two fields:
474 which are the number of added and removed lines respectively.
476 .It Dv branch-deleted
477 The branch deleted notifications has the following fields, all guaranteed
481 The removed branch reference.
483 The hash of the commit pointed by the deleted branch.
486 The tag notification has the following fields, all guaranteed to be set:
491 The user information, with the same format of the
495 notification but with all the field guaranteed to be set.
497 Number, representing the number of seconds since the Epoch in UTC.
499 The object being tagged.
500 It contains the fields
502 with the object type and
504 with the object id being tagged.
512 .Bl -tag -width Ds -compact
513 .It Pa /etc/gotd.conf
519 .Bd -literal -offset indent
520 # Run as the default user:
523 # Listen on the default socket:
524 listen on "/var/run/gotd.sock"
526 # This repository can be accessed via ssh://user@example.com/src
528 path "/var/git/src.git"
529 permit rw flan_hacker
530 permit rw :developers
533 protect branch "main"
534 protect tag namespace "refs/tags/"
537 # This repository can be accessed via
538 # ssh://user@example.com/openbsd/ports
539 repository "openbsd/ports" {
540 path "/var/git/ports.git"
547 tag namespace "refs/tags/"
552 reference namespace "refs/tags/"
553 email to openbsd-ports-changes@example.com
554 .\" url https://example.com/notify/ user "flan_announcer" password "secret"
558 # Use a larger request timeout value:
559 connection request timeout 2h
561 # Some users are granted a higher concurrent connection limit:
563 limit user flan_hacker 16
564 limit user anonymous 32
570 .Xr gotd-secrets.conf 5 ,
