GOTSYSD.CONF(5) File Formats Manual GOTSYSD.CONF(5)

gotsysd.conf — gotsysd configuration file

gotsysd.conf is the run-time configuration file for gotsysd(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 (").

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:

path = "/var/run/gotsysd.sock"
listen on $path

The available global configuration directives are as follows:

user user
The name of the gotd(8) user account. Defauls to “_gotd”. gotsysd(8) will switch to this user account as needed.
path
Set the path to the unix socket which gotsysd(8) should listen on. If not specified, the path /var/run/gotsysd.sock will be used.
identity
Permit gotsysd(8) unix socket access to users with the username identity. Group names may be matched by prepending a colon (‘:’) to identity. Numeric IDs are also accepted.

Multiple permit rules can be specified.

If no permit rule is specified, the users root and _gotd are granted access by default.

directory path
Set the path to the repository directory within which Git repositories will be created and managed by gotsysd(8). This repository directory must be owned by and be exclusively accessible to the gotd(8) user.

If not specified, the path /git will be used.

deny identity
Deny repository access to users with the username identity.

Access rules set in gotsysd.conf apply to all repositories and override conflicting per-repository access rules specified in gotsys.conf(5).

Group names may be matched by prepending a colon (‘:’) to identity.

The special user identity “*” (an asterisk) can be used to match all users, including the “anonymous” user.

Multiple access rules can be specified, and the last matching rule determines the action taken. If no rule matches, the per-repository rules specified in gotsys.conf(5) will take effect.

permit mode identity
Permit repository access to users with the username identity.

Access rules set in gotsysd.conf apply to all repositories and override conflicting per-repository access rules specified in gotsys.conf(5).

The mode argument must be set to either ro for read-only access, or rw for read-write access. Group names may be matched by prepending a colon (‘:’) to identity.

The special user identity “anonymous” can be used when public read-only access to repositories over SSH is desired. The anonymous user has an empty password, cannot use an SSH public key, and can only be granted read-only access.

See gotsh(1) for important hints about how to configure sshd(8) to prevent abuse of certain SSH features by anonymous users.

The special user identity “*” (an asterisk) can be used to match all users, except the “anonymous” user. Read-only anonymous access must be enabled explicitly.

Multiple access rules can be specified, and the last matching rule determines the action taken. If no rule matches, the per-repository rules specified in gotsys.conf(5) will take effect.

start end
Set the start and end (inclusive) of the range from which gotsysd(8) will allocate user and group IDs when creating user accounts specified in gotsys.conf(5). The start of this range must be greater than 1000 and must be smaller than the end.

The default range is 5000 to 5999.

User accounts created by gotsysd(8) will use the gotsh(1) shell.

user
Set the user which will run gotsysd(8). Initially, gotsysd(8) requires root privileges. Afterwards, gotsysd(8) partly drops privileges to its own user and to the gotd(8) user. If not specified, the user _gotsysd will be used. Numeric user IDs are also accepted.

gotsysd(8) can automatically manage gotwebd(8) by generating a gotwebd.conf(5) configuration file based on configuration directives in gotsysd.conf and in gotsys.conf(5), and then starting or restarting gotwebd(8) to apply configuration changes.

To activate management of gotwebd(8) by gotsysd(8), at least one gotwebd.conf(5) server must be declared by using the web server configuration directive in gotsysd.conf.

Additionally, global parameters for gotwebd(8) can be set using the gotweb configuration directive in gotsysd.conf.

While gotwebd.conf(5) will be automatically generated by gotsysd(8), the system administrator must manually configure httpd(8) or another web server and make sure that appropriate requests are forwarded to gotwebd(8) via FastCGI.

Global parameters for gotwebd(8), declared inside curly braces of the gotweb {...} configuration directive, are as follows:

path
Set the path to the Unix-domain socket for gotwebctl(8) commands. By default the path /var/run/gotwebd.sock will be used.
number
Spawn enough processes such that number requests can be handled in parallel. By default, gotwebd(8) will handle up to 3 requests in parallel. The maximum allowed is 32.
path
Set the path to the chroot(2) environment of httpd(8). If not specified, it defaults to /var/www, the home directory of the www user. Setting the path to / effectively disables chroot.
path
Set the path to the directory which contains static files linked from HTML generated by gotwebd(8), such as gotweb.css. The specified path will be looked up relative to the chroot directory of httpd(8). If not specified then htdocs/gotwebd will be used.

The global htdocs directive can be overridden by gotsysd.conf. web server directives.

Disable authentication, allowing any browser to view any repository not hidden via hide repositories and hide repository directives in either gotsysd.conf or gotsys.conf(5).

The global disable authentication directive can be overridden by web server directives in gotsysd.conf or gotsys.conf(5).

[insecure]
Enable authentication, requiring browsers to present a login token cookie before read-only repository access is granted. Unless the insecure keyword is used, the login token cookie will be marked as “Secure”, which causes browsers to only send the cookie when connected to the web server over a TLS connection.

The global enable authentication directive can be overridden by web server directives in gotsysd.conf or gotsys.conf(5). However, gotsys.conf(5) deliberately lacks the insecure keyword.

name
Sets the user name displayed in login hints which are shown on the error page if authentication has failed.

If not set then no login hint will be displayed and users will somehow need to learn about using the gotsh(1) weblogin command via other means.

number
Sets the SSH port number displayed in login hints which are shown on the error page if authentication has failed.
name
Set the user which runs gotwebd(8). Defaults to the user _gotwebd.
name
Set the user which runs httpd(8). Defaults to the user www.
path
Configure a Unix-domain socket for incoming FastCGI connections. May be specified multiple times to build up a list of listening sockets.

While the specified path must be absolute, it should usually point inside the web server's chroot directory such that the web server can access the socket.

If no listen directive is used, gotwebd(8) will listen on the Unix-domain socket at /var/www/run/gotweb.sock.

address port number
Configure an address and port for incoming FastCGI connections. May be specified multiple times to build up a list of listening sockets.

Valid address arguments are hostnames, IPv4 and IPv6 addresses. The port argument may be number or a service name defined in services(5).

If no listen directive is used, gotwebd(8) will listen on the Unix-domain socket at /var/www/run/gotweb.sock.

A gotwebd.conf(5) server is declared with:

web server hostname

The hostname should be the name which web browsers use to reach the host running the instance of httpd(8) which forwards requests to gotwebd(8).

Optional parameters for the web server may be given in curly braces:

web server hostname {...}

The parameters are as follows:

path
Sets the URL path under which httpd(8) is routing requests to this gotwebd(8) server. Defaults to “/”.

The specified path should match the path of the location block in httpd.conf(5) which forwards requests to gotwebd(8).

path
Set the path to the directory which contains static files linked from HTML generated by gotwebd(8), such as gotweb.css. The specified path will be looked up relative to the chroot directory of httpd(8).
on | off
Controls whether repositories are hidden by default. Hidden repositories cannot be browsed via gotwebd(8).

By default, hide repositories is set to off and all repositories found in the gotsysd.conf repository directory will be displayed.

Disable authentication, allowing any browser to view any repository not hidden via the hide repositories and hide repository directives in gotsys.conf(5).

The web server's disable authentication directive can be overridden by directives in gotsys.conf(5).

[insecure]
Enable authentication, requiring browsers to present a login token cookie before read-only repository access is granted. Unless the insecure keyword is used, the login token cookie will be marked as “Secure”, which causes browsers to only send the cookie when connected to the web server over a TLS connection.

The web server's enable authentication directive can be overridden by directives in gotsys.conf(5). However, gotsys.conf(5) deliberately lacks the insecure keyword.

on | off
Toggle display of last repository modification date. Enabled by default.

Additional parameters for web servers can be set in gotsys.conf(5). gotsysd(8) will ignore gotsys.conf(5) configuration directives which cannot be mapped to a known web server hostname declared in gotsysd.conf.

The following example shows default settings:

user _gotsysd
gotd user _gotd
listen on "/var/run/gotsysd.sock"
repository directory "/git"
uid range 5000 5999

Regardless of what gotsys.conf(5) says, allow the user account “backup-user” to read any repository:

repository permit ro backup-user

Regardless of what gotsys.conf(5) says, make all repositories read-only:

repository permit ro "*"

Regardless of what gotsys.conf(5) says, make all repositories inaccessible:

repository deny "*"

Display repositories in the default /git repository directory on the web with gotwebd(8), using default settings:

web server "gotweb.example.com"

Make gotwebd(8) hide repositories which are not explicitly unhidden in gotsys.conf(5), and enable authentication unless overridden in on per-server or per-repository basis in gotsys.conf(5):

web server "gotweb.example.com" {
	hide repositories on
	enable authentication
}

Configure gotwebd(8) to listen on a TCP socket:

gotweb {
	listen on 127.0.0.1 port 9000
}

got(1), gotsh(1), gotwebd.conf(5), gotd(8), gotsysd(8), gotwebd(8), httpd(8), sshd(8).

OpenBSD 7.9 April 13, 2026 GOTSYSD.CONF(5)