.\"
.\" 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.
Any lines beginning with a
.Sq #
are treated as comments and ignored.
.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.
.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.
.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
}

# 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
}

# 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 8