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

gotsys.conf — gotsys configuration file

gotsys.conf provides system configuration information to gotsysd(8).

gotsys.conf allows remote administrators to configure aspects of Git repository services without having shell access to the Git server's operating system. Remote administrators merely need to be granted write access to a special-purpose hosted by gotd(8) in order to configure Git repository services.

The file format is line-based, with one configuration directive per line. Any lines beginning with a ‘#’ are treated as comments and ignored.


The available global configuration directives are as follows:

name
Declare a group with the given name. Users can then be granted membership of this group in order to manage repository access rules on a per-group basis.

Group names may only contain alphabetic ASCII characters (a-z, A-Z), non-leading digits (0-9), non-leading hyphens (-), non-leading underscores (_), and non-leading periods (.).

The name “anonymous” is reserved for use with the permit directive and cannot be used with the group directive.

User and group names which are used for special purposes by the OpenBSD system cannot be used in gotsys.conf. The current list of reserved names is “build”, “root”, “wheel”, “daemon”, “kmem”, “sys”, “tty”, “operator”, “bin”, “wsrc”, “users”, “auth”, “games”, “staff”, “wobj”, “sshd”, “guest”, “utmp”, “crontab”, “www”, “network”, “authpf”, “dialer”, “nogroup”, and “nobody”.

name
Declare a user which can then be granted access to specific repositories.

A user must be declared with a unique name, followed by user-specific configuration directives inside curly braces:

user name {...}

User names may only contain alphabetic ASCII characters (a-z, A-Z), non-leading digits (0-9), non-leading hyphens (-), non-leading underscores (_), and non-leading periods (.).

The name “anonymous” is reserved for use with the permit directive and cannot be used with the user directive.

User and group names used for special purposes by the OpenBSD system cannot be used in gotsys.conf. The list of reserved user names is the same as documented above for the group directive.

When a user's declaration is removed from gotsys.conf the server account password will be locked, and any previously installed authorized keys will be removed, rendering the account inaccessible. The account can be made accessible again by restoring the user's gotsys.conf entry.

The available user parameters are as follows:

group
Make the user a member of the given group. This directive may be specified multiple times to add the user to multiple groups. All groups listed here must already have been declared with the group directive.
string
Set a password for the user. The string argument must be an encrypted password string, as generated by OpenBSD's encrypt(1) command. If not specified, password-based authentication will be disabled for this user.
key type key [comment]
Allow the user to authenticate with an SSH public key.

The list of arguments consist of the following space-separated fields: the key type, the base64-encoded key, and an optional comment. These arguments will usually correspond to the contents of an id_ecdsa.pub, id_ecdsa_sk.pub, id_ed25519.pub, id_ed25519_sk.pub, or id_rsa.pub file provided by the user.

The supported key types are:

  • sk-ecdsa-sha2-nistp256@openssh.com
  • ecdsa-sha2-nistp256
  • ecdsa-sha2-nistp384
  • ecdsa-sha2-nistp521
  • sk-ssh-ed25519@openssh.com
  • ssh-ed25519
  • ssh-rsa

The optional comment is not used for anything, but may be convenient for the user to identify the key.

The authorized key directive may be specified multiple times to allow the user to authenticate with any of the specified keys.

Two-factor authentication with FIDO keys can be enforced by only adding keys of type or .

Repositories declared in gotsys.conf will be created on the server if they do not already exist. Each repository must be given a unique name, followed by repository-specific configuration directives inside curly braces:

repository name {...}

Repository names may only contain alphabetic ASCII characters (a-z, A-Z), non-leading digits (0-9), non-leading hyphens (-), non-leading underscores (_), and non-leading periods (.).

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.

The available repository configuration directives are as follows:

Point the repository's symbolic HEAD reference at the specified branch. If not specified, HEAD will point at the branch “main”, regardless of whether this branch actually exists in the repository.

If HEAD points at a non-existent branch then clients may fail to clone the repository because they rely on HEAD to determine which branch to fetch by default.

identity
Deny repository access to users with the username identity. Group names may be matched by prepending a colon (‘:’) to identity.
mode identity
Permit repository access to users with the username identity. 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.

group developers
group porters

user flan_hacker {
	password "$2b$08$CFWp/ZC.DQi34.iHBgRzBerTzEGB9WY9tDN1CLCbPUpGC.fmNi4Ea"
	group developers
}

user flan_squee {
	group porters
	authorized key ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAQ2ZWscmMeCYLwm07gDSf0jApFJ58bMNxiErDqUrFz4
}

repository "src" {
	permit rw :developers
	permit ro anonymous
}

repository "openbsd/ports" {
	permit rw :porters
	permit ro anonymous
	deny flan_hacker

}

repository "secret" {
	permit rw flan_hacker
	head "refs/heads/private"
}

got(1), gotsys(1), gotd(8), gotsysd(8)

There is no way to rename or delete repositories via gotsys.conf. Existing repositories that are no longer mentioned in gotsys.conf will be inaccessible, as if they had been declared without any access rules.

April 22, 2025 OpenBSD 7.7