NAME
gotd.conf
—
gotd configuration file
DESCRIPTION
gotd.conf
is the run-time configuration
file for gotd(8).
The file format is line-based, with one configuration directive
per line. Comments can be put anywhere in the file using a hash mark
(‘#’), and extend to the end of the current line. Arguments
names not beginning with a letter, digit or underscore, as well as reserved
words (such as listen
,
repository
or
user
), must be quoted. Arguments containing
whitespace should be surrounded by double quotes (").
GLOBAL CONFIGURATION
The available global configuration directives are as follows:
connection
option- Set the specified options and limits for connections to the
gotd(8) unix socket.
The
connection
directive may be specified multiple times, and multiple option arguments may be specified within curly braces:connection
{...}Each option should only be specified once. If a given option is listed multiple times, the last line which sets this option wins.
Valid connection options are:
request timeout
seconds- Specify the inactivity timeout for operations between client and
server. If this timeout is exceeded while a Git protocol request is
being processed, the request will be aborted and the connection will
be terminated.
The timeout value may also have a suffix indicating its unit of measure. Supported suffixes are:
- s or S
- seconds
- m or M
- minutes
- h or H
- hours
The default timeout is 1h (3600 seconds, one hour). This should only be changed if legitimate requests are exceeding the default timeout for some reason, such as the server spending an extraordinary amount of time generating a pack file.
limit
user
identity number- Limit the maximum amount of concurrent connections by the user with
the username identity to
number. Numeric user IDs are also accepted.
The default per-user limit is 4. This should only be changed if concurrent connections from a given user are expected to exceed the default limit, for example if an anonymous user is granted read access and many concurrent connections will share this anonymous user identity.
listen on
path- Set the path to the unix socket which gotd(8) should listen on. If not specified, the path /var/run/gotd.sock will be used.
user
user- Set the user which will run gotd(8). Initially, gotd(8) requires root privileges in order to create its unix socket. Afterwards, gotd(8) drops privileges to the specified user. If not specified, the user _gotd will be used. Numeric user IDs are also accepted.
REPOSITORY CONFIGURATION
At least one repository context must exist for
gotd(8) to function. For each
repository, access rules must be configured using the
permit
and deny
configuration directives. Multiple access rules can be specified, and the
last matching rule determines the action taken. If no rule matches, access
to the repository is denied.
A repository context is declared with a unique name, followed by repository-specific configuration directives inside curly braces:
repository
name
{...}
got(1) and git(1) clients can connect to a repository by including the repository's unique name in the request URL. Clients appending the string “.git” to the name will also be accepted.
If desired, the name may contain path-separators, “/”, to expose repositories as part of a virtual client-visible directory hierarchy.
The available repository configuration directives are as follows:
deny
identity- Deny repository access to users with the username identity. Group names may be matched by prepending a colon (‘:’) to identity. Numeric IDs are also accepted.
path
path- Set the path to the Git repository. Must be specified.
permit
mode identity- Permit repository access to users with the username
identity. The mode argument
must be set to either
ro
for read-only access, orrw
for read-write access. Group names may be matched by prepending a colon (‘:’) to identity. Numeric IDs are also accepted. protect
{...}- The
protect
directive may be used to protect branches and tags in a repository from being overwritten by potentially destructive client-side commands, such as whengot send -f
andgit push -f
are used to change the history of a branch.To build a set of protected branches and tags, multiple
protect
directives may be specified per repository and multipleprotect
directive parameters may be specified within curly braces.The available
protect
parameters are as follows:branch
name- Protect the named branch. The branch may be created if it does not
exist yet. Attempts to delete the branch or change its history will be
denied.
If the name does not already begin with “refs/heads/” it will be looked up in the “refs/heads/” reference namespace.
branch
namespace
namespace- Protect the given reference namespace, assuming that references in
this namespace represent branches. New branches may be created in the
namespace. Attempts to change the history of branches or delete them
will be denied.
The namespace argument must be absolute, starting with “refs/”.
tag
namespace
namespace- Protect the given reference namespace, assuming that references in
this namespace represent tags. New tags may be created in the
namespace. Attempts to change or delete existing tags will be denied.
The namespace argument must be absolute, starting with “refs/”.
The special reference namespaces “refs/got/” and “refs/remotes/” do not need to be listed in
gotd.conf
. These namespaces are always protected and even attempts to create new references in these namespaces will always be denied. notify
{...}- The
notify
directive enables notifications about new commits or tags added to the repository.Notifications via email require an SMTP daemon which accepts mail for forwarding without requiring client authentication or encryption. On OpenBSD the smtpd(8) daemon can be used for this purpose. The default content of email notifications looks similar to the output of the
got log -d
command.Notifications via HTTP require a HTTP or HTTPS server which is accepting POST requests with or without HTTP Basic authentication. Depending on the use case a custom server-side CGI script may be required for the processing of notifications. HTTP notifications can achieve functionality similar to Git's server-side post-receive hook script with gotd(8) by triggering arbitrary post-commit actions via the HTTP server.
The
notify
directive expects parameters which must be enclosed in curly braces. The available parameters are as follows:branch
name- Send notifications about commits to the named branch. The
name will be looked up in the
“refs/heads/” reference namespace. This directive may be
specified multiple times to build a list of branches to send
notifications for. If neither a
branch
nor areference namespace
are specified then changes to any reference will trigger notifications. reference
namespace
namespace- Send notifications about commits or tags within a reference namespace.
This directive may be specified multiple times to build a list of
namespaces to send notifications for. If neither a
branch
nor areference namespace
are specified then changes to any reference will trigger notifications. email
[from
sender]to
recipient [reply to
responder] [relay
hostname [port
port]]- Send notifications via email to the specified
recipient. This directive may be specified
multiple times to build a list of recipients to send notifications to.
The recipient must be an email addresses that accepts mail. The sender will be used as the From address. If not specified, the sender defaults to an email address composed of the user account running gotd(8) and the local hostname.
If a responder is specified via the
reply to
directive, the responder will be used as the Reply-to address. Setting the Reply-to header can be useful if replies should go to a mailing list instead of the sender, for example.By default, mail will be sent to the SMTP server listening on the loopback address 127.0.0.1 on port 25. The
relay
andport
directives can be used to specify a different SMTP server address and port. url
URL [auth
label [insecure
]] [hmac
label]- Send notifications via HTTP. This directive may be specified multiple
times to build a list of HTTP servers to send notifications to.
The notification will be sent as a POST request to the given URL, which must be a valid HTTP URL and begin with either “http://” or “https://”. If HTTPS is used, sending of notifications will only succeed if no TLS errors occur.
The optional
auth
directive enables HTTP Basic authentication. Authentication credentials must be specified in the separate gotd-secrets.conf(5) file, using the label as identifier. Unless theinsecure
option is specified the notification target URL must be a “https://” URL to avoid leaking of authentication credentials.If a
hmac
secret is provided, the request body will be signed using HMAC, allowing the receiver to verify the notification message's authenticity and integrity. The HMAC secret to use must be specified in the separate gotd-secrets.conf(5) file, using the label as identifier. The signature uses HMAC-SHA256 and will be sent in the HTTP header “X-Gotd-Signature”.The request body contains a JSON object with a “notifications” property containing an array of notification objects. The following notification object properties are always present:
repo
- The repository name as a string.
authenticated_user
- The committer's user account as authenticated by gotd(8) as a string.
type
- The notification object type as a string.
Each notification object carries additional type-specific properties. The types and their type-specific properties are:
commit
- The commit notification object has the following fields. Except
where noted, all are optional.
short
- Boolean, indicates whether the object has all the fields set. When several commits are batched in a single send operation, not all of the fields are available for each commit object.
id
- The commit ID as string, may be abbreviated.
committer
- An object with the committer information with the following
fields:
full
- Committer's full name.
name
- Committer's name.
mail
- Committer's mail address.
user
- Committer's username. This is the only field guaranteed to be set.
- An object with the author information. Has the same fields as the ‘committer’ but may be unset.
date
- Number, representing the number of seconds since the Epoch in UTC.
short_message
- The first line of the commit message. This field is always set.
message
- The complete commit message, may be unset.
diffstat
- An object with the summarized changes, may be unset. Contains
a ‘files’ field with an array of objects
describing the changes per-file and a ‘total’
field with the cumulative changes. The changes per-file
contains the following fields:
action
- A string describing the action, can be “added”, “deleted”, “modified”, “mode changed”, or “unknown”.
file
- The file path.
added
- The number of lines added.
removed
- The number of lines removed.
The ‘total’ object contains two fields: ‘added’ and ‘removed’ which are the number of added and removed lines respectively.
branch-deleted
- The branch deleted notifications has the following fields, all
guaranteed to be set:
ref
- The removed branch reference.
id
- The hash of the commit pointed by the deleted branch.
tag
- The tag notification has the following fields, all guaranteed to
be set:
- tag
- The tag reference.
- tagger
- The user information, with the same format of the ‘committer’ field for the ‘commit’ notification but with all the field guaranteed to be set.
date
- Number, representing the number of seconds since the Epoch in UTC.
object
- The object being tagged. It contains the fields ‘type’ with the object type and ‘id’ with the object id being tagged.
message
- The tag message.
FILES
- /etc/gotd.conf
- Location of the
gotd.conf
configuration file.
EXAMPLES
# Run as the default user: user _gotd # Listen on the default socket: listen on "/var/run/gotd.sock" # This repository can be accessed via ssh://user@example.com/src repository "src" { path "/var/git/src.git" permit rw flan_hacker permit rw :developers permit ro anonymous protect branch "main" protect tag namespace "refs/tags/" } # This repository can be accessed via # ssh://user@example.com/openbsd/ports repository "openbsd/ports" { path "/var/git/ports.git" permit rw :porters permit ro anonymous deny flan_hacker protect { branch "main" tag namespace "refs/tags/" } notify { branch "main" reference namespace "refs/tags/" email to openbsd-ports-changes@example.com } } # Use a larger request timeout value: connection request timeout 2h # Some users are granted a higher concurrent connection limit: connection { limit user flan_hacker 16 limit user anonymous 32 }