.\"
.\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt GOTD.CONF 5
.Os
.Sh NAME
.Nm gotd.conf
.Nd gotd configuration file
.Sh DESCRIPTION
.Nm
is the run-time configuration file for
.Xr gotd 8 .
.Pp
The file format is line-based, with one configuration directive per line.
Comments can be put anywhere in the file using a hash mark
.Pq Sq # ,
and extend to the end of the current line.
Arguments names not beginning with a letter, digit or underscore,
as well as reserved words
.Pq such as Ic listen , Ic repository No or Ic user ,
must be quoted.
Arguments containing whitespace should be surrounded by double quotes
.Pq \&" .
.Pp
Macros can be defined that are later expanded in context.
Macro names must start with a letter, digit, or underscore, and may
contain any of those characters, but may not be reserved words.
Macros are not expanded inside quotes.
For example:
.Bd -literal -offset indent
path = "/var/run/gotd.sock"
listen on $path
.Ed
.Sh GLOBAL CONFIGURATION
The available global configuration directives are as follows:
.Bl -tag -width Ds
.It Ic connection Ar option
Set the specified options and limits for connections to the
.Xr gotd 8
unix socket.
.Pp
The
.Ic connection
directive may be specified multiple times, and multiple
.Ar option
arguments may be specified within curly braces:
.Pp
.Ic connection Brq Ar ...
.Pp
Each option should only be specified once.
If a given option is listed multiple times, the last line which sets this
option wins.
.Pp
Valid connection options are:
.Bl -tag -width Ds
.It Ic request timeout Ar 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.
.Pp
The timeout value may also have a suffix indicating its unit of measure.
Supported suffixes are:
.Pp
.Bl -tag -compact -width tenletters
.It Ar s No or Ar S
seconds
.It Ar m No or Ar M
minutes
.It Ar h No or Ar H
hours
.El
.Pp
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.
.It Ic limit Ic user Ar identity Ar number
Limit the maximum amount of concurrent connections by the user with
the username
.Ar identity
to
.Ar number .
Numeric user IDs are also accepted.
.Pp
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.
.El
.It Ic listen on Ar path
Set the path to the unix socket which
.Xr gotd 8
should listen on.
If not specified, the path
.Pa /var/run/gotd.sock
will be used.
.It Ic user Ar user
Set the
.Ar user
which will run
.Xr gotd 8 .
Initially,
.Xr gotd 8
requires root privileges in order to create its unix socket.
Afterwards,
.Xr gotd 8
drops privileges to the specified
.Ar user .
If not specified, the user _gotd will be used.
Numeric user IDs are also accepted.
.El
.Sh REPOSITORY CONFIGURATION
At least one repository context must exist for
.Xr gotd 8
to function.
For each repository, access rules must be configured using the
.Ic permit
and
.Ic 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.
.Pp
A repository context is declared with a unique
.Ar name ,
followed by repository-specific configuration directives inside curly braces:
.Pp
.Ic repository Ar name Brq ...
.Pp
.Xr got 1
and
.Xr git 1
clients can connect to a repository by including the repository's unique
.Ar name
in the request URL.
Clients appending the string
.Dq .git
to the
.Ar name
will also be accepted.
.Pp
If desired, the
.Ar name
may contain path-separators,
.Dq / ,
to expose repositories as part of a virtual client-visible directory hierarchy.
.Pp
The available repository configuration directives are as follows:
.Bl -tag -width Ds
.It Ic deny Ar identity
Deny repository access to users with the username
.Ar identity .
Group names may be matched by prepending a colon
.Pq Sq \&:
to
.Ar identity .
Numeric IDs are also accepted.
.It Ic path Ar path
Set the path to the Git repository.
Must be specified.
.It Ic permit Ar mode Ar identity
Permit repository access to users with the username
.Ar identity .
The
.Ar mode
argument must be set to either
.Ic ro
for read-only access,
or
.Ic rw
for read-write access.
Group names may be matched by prepending a colon
.Pq Sq \&:
to
.Ar identity .
Numeric IDs are also accepted.
.It Ic protect Brq Ar ...
The
.Cm protect
directive may be used to protect branches and tags in a repository
from being overwritten by potentially destructive client-side commands,
such as when
.Cm got send -f
and
.Cm git push -f
are used to change the history of a branch.
.Pp
To build a set of protected branches and tags, multiple
.Ic protect
directives may be specified per repository and
multiple
.Ic protect
directive parameters may be specified within curly braces.
.Pp
The available
.Cm protect
parameters are as follows:
.Bl -tag -width Ds
.It Ic branch Ar 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.
.Pp
If the
.Ar name
does not already begin with
.Dq refs/heads/
it will be looked up in the
.Dq refs/heads/
reference namespace.
.It Ic branch Ic namespace Ar 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.
.Pp
The
.Ar namespace
argument must be absolute, starting with
.Dq refs/ .
.It Ic tag Ic namespace Ar 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.
.Pp
The
.Ar namespace
argument must be absolute, starting with
.Dq refs/ .
.El
.Pp
The special reference namespaces
.Dq refs/got/
and
.Dq refs/remotes/
do not need to be listed in
.Nm .
These namespaces are always protected and even attempts to create new
references in these namespaces will always be denied.
.It Ic notify Brq Ar ...
The
.Ic notify
directive enables notifications about new commits or tags
added to the repository.
.Pp
Notifications via email require an SMTP daemon which accepts mail
for forwarding without requiring client authentication or encryption.
On
.Ox
the
.Xr smtpd 8
daemon can be used for this purpose.
The default content of email notifications looks similar to the output of the
.Cm got log -d
command.
.Pp
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
.Xr gotd 8
by triggering arbitrary post-commit actions via the HTTP server.
.Pp
The
.Ic notify
directive expects parameters which must be enclosed in curly braces.
The available parameters are as follows:
.Bl -tag -width Ds
.It Ic branch Ar name
Send notifications about commits to the named branch.
The
.Ar name
will be looked up in the
.Dq refs/heads/
reference namespace.
This directive may be specified multiple times to build a list of
branches to send notifications for.
If neither a
.Ic branch
nor a
.Ic reference namespace
are specified then changes to any reference will trigger notifications.
.It Ic reference Ic namespace Ar 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
.Ic branch
nor a
.Ic reference namespace
are specified then changes to any reference will trigger notifications.
.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
Send notifications via email to the specified
.Ar recipient .
This directive may be specified multiple times to build a list of
recipients to send notifications to.
.Pp
The
.Ar recipient
must be an email addresses that accepts mail.
The
.Ar sender
will be used as the From address.
If not specified, the sender defaults to an email address composed of the user
account running
.Xr gotd 8
and the local hostname.
.Pp
If a
.Ar responder
is specified via the
.Ic reply to
directive, the
.Ar 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
.Ar sender ,
for example.
.Pp
By default, mail will be sent to the SMTP server listening on the loopback
address 127.0.0.1 on port 25.
The
.Ic relay
and
.Ic port
directives can be used to specify a different SMTP server address and port.
.It Ic url Ar URL Oo Ic auth Ar label Oo Ic insecure Oc Oc Oo Ic hmac Ar label Oc
Send notifications via HTTP.
This directive may be specified multiple times to build a list of
HTTP servers to send notifications to.
.Pp
The notification will be sent as a POST request to the given
.Ar URL ,
which must be a valid HTTP URL and begin with either
.Dq http://
or
.Dq https:// .
If HTTPS is used, sending of notifications will only succeed if
no TLS errors occur.
.Pp
The optional
.Ic auth
directive enables HTTP Basic authentication.
Authentication credentials must be specified in the separate
.Xr gotd-secrets.conf 5
file, using the
.Ar label
as identifier.
Unless the
.Ic insecure
option is specified the notification target
.Ar URL
must be a
.Dq https://
URL to avoid leaking of authentication credentials.
.Pp
If a
.Ic 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
.Xr gotd-secrets.conf 5
file, using the
.Ar label
as identifier.
The signature uses HMAC-SHA256 and will be sent in the HTTP header
.Dq X-Gotd-Signature .
.Pp
The request body contains a JSON object with a
.Dq notifications
property containing an array of notification objects.
The following notification object properties are always present:
.Bl -tag -width authenticated_user
.It Dv repo
The repository name as a string.
.It Dv authenticated_user
The committer's user account as authenticated by
.Xr gotd 8
as a string.
.It Dv type
The notification object type as a string.
.El
.Pp
Each notification object carries additional type-specific properties.
The types and their type-specific properties are:
.Bl -tag -width Ds
.It Dv commit
The commit notification object has the following fields.
Except where noted, all are optional.
.Bl -tag -width Ds
.It Dv 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.
.It Dv id
The commit ID as string, may be abbreviated.
.It Dv committer
An object with the committer information with the following fields:
.Pp
.Bl -tag -compact -width Ds
.It Dv full
Committer's full name.
.It Dv name
Committer's name.
.It Dv mail
Committer's mail address.
.It Dv user
Committer's username.
This is the only field guaranteed to be set.
.El
.It Dv author
An object with the author information.
Has the same fields as the
.Sq committer
but may be unset.
.It Dv date
Number, representing the number of seconds since the Epoch in UTC.
.It Dv short_message
The first line of the commit message.
This field is always set.
.It Dv message
The complete commit message, may be unset.
.It Dv diffstat
An object with the summarized changes, may be unset.
Contains a
.Sq files
field with an array of objects describing the changes per-file and a
.Sq total
field with the cumulative changes.
The changes per-file contains the following fields:
.Pp
.Bl -tag -compact -width removed
.It Dv action
A string describing the action, can be
.Dq added ,
.Dq deleted ,
.Dq modified ,
.Dq mode changed ,
or
.Dq unknown .
.It Dv file
The file path.
.It Dv added
The number of lines added.
.It Dv removed
The number of lines removed.
.El
.Pp
The
.Sq total
object contains two fields:
.Sq added
and
.Sq removed
which are the number of added and removed lines respectively.
.El
.It Dv branch-deleted
The branch deleted notifications has the following fields, all guaranteed
to be set:
.Bl -tag -width Ds
.It Dv ref
The removed branch reference.
.It Dv id
The hash of the commit pointed by the deleted branch.
.El
.It Dv tag
The tag notification has the following fields, all guaranteed to be set:
.Bl -tag -width Ds
.It tag
The tag reference.
.It tagger
The user information, with the same format of the
.Sq committer
field for the
.Sq commit
notification but with all the field guaranteed to be set.
.It Dv date
Number, representing the number of seconds since the Epoch in UTC.
.It Dv object
The object being tagged.
It contains the fields
.Sq type
with the object type and
.Sq id
with the object id being tagged.
.It Dv message
The tag message.
.El
.El
.El
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/gotd.conf
Location of the
.Nm
configuration file.
.El
.Sh EXAMPLES
.Bd -literal -offset indent
# 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
.\"		url https://example.com/notify/ user "flan_announcer" password "secret"
	}
}

# 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
}
.Ed
.Sh SEE ALSO
.Xr got 1 ,
.Xr gotsh 1 ,
.Xr gotd-secrets.conf 5 ,
.Xr gotd 8