GOTSYS(1)

SYNOPSIS

+ + + + + +

gotsys [-hV] command + [arg ...]

DESCRIPTION

gotsys performs tasks involving the + gotsys.conf(5) + configuration file consumed by gotsysd(8).

The options for gotsys are as follows:

-h: Display usage information and exit immediately.
-V, + --version: Display program version and exit immediately.

The commands for gotsys are as + follows:

apply + [-c commit] + [-f socket] + [-r repository-path] + [file]

Trigger system configuration tasks based on the + gotsys.conf(5) + configuration file found in the + gotsysd(8) system + repository. If no file argument is specified, the + file path gotsys.conf will be used. +

Usually, gotd(8) will trigger system configuration tasks whenever a new + version of gotsys.conf(5) is sent to the gotsysd(8) + system + repository. If system configuration fails or causes problems for + any reason, system administrators with shell access to the server can + use gotsys apply to reconfigure the system back + into a working state.

gotsys apply requires on-disk read + access to the gotsysd(8) system repository, as well as access to the + gotsysd(8) unix + socket. By default, only the root and _gotd users have the required + access permissions.

The options for gotsys apply are as + follows:

-c + commit

Obtain the gotsys.conf(5) configuration file from + the specified commit. +

The expected commit argument is a + commit ID, or a reference name or a keyword which will be resolved + to a commit ID. An abbreviated hash argument will be expanded to a + full commit ID automatically, provided the abbreviation is + unique.

If no commit is specified, a commit + corresponding to the repository's HEAD reference will be used.

-f + socket

Set the path to the unix socket which + gotsysd(8) is + listening on. If not specified, the path + /var/run/gotsysd.sock will be used.

-r + repository-path

Use the repository at the specified path. If not specified, the + repository path /git/gotsys.git will be + used.

check + [-q] [-f + file]

Read a gotsys.conf(5) configuration file and report + any errors. If no file is specified, the file + gotsys.conf in the current working directory will + be read. +

gotsys check is intended to be used by + administrators who manage a gotd(8) server remotely by committing changes to + gotsys.conf(5). + Files which do not pass gotsys check will be + rejected by the server. Running gotsys check + before committing changes to gotsys.conf(5) is therefore recommended.

The options for gotsys check are as + follows:

-f + file: The path to the configuration file to read. A + hyphen (-) can be used to read standard input: gotsys + check -f -
-q: Stay silent on standard output. Only report errors.

EXIT + STATUS

The gotsys utility exits 0 on + success, and >0 if an error occurs.

SEE + ALSO

gotsys.conf(5), gotd(8), gotsysd(8)

AUTHORS

Stefan Sperling + <stsp@openbsd.org>

Paths mentioned in gotwebd.conf must be - relative to /var/www, the - chroot(2) environment of - httpd(8).

NAME

gotsys.conf — + gotsys configuration file

DESCRIPTION

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 + system repository + 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.

GLOBAL + CONFIGURATION

+
+

The available global configuration directives are as follows:

group + 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”.

user + 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 + 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.

password + 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.

authorized + 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 + sk-ssh-ed25519@openssh.com + or + sk-ecdsa-sha2-nistp256@openssh.com.

REPOSITORY + CONFIGURATION

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:

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

EXAMPLES

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"
+}

SEE + ALSO

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

CAVEATS

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.

NAME

gotsysctl — + control the Game of Trees System + Daemon

SYNOPSIS

+ + + + + +

gotsysctl [-hV] [-f + path] command + [arg ...]

DESCRIPTION

gotsysctl controls the + gotsysd(8) daemon.

gotsysctl connects to the + gotsysd(8) unix socket, + sends a command, and displays the response from + gotsysd(8). Access to the + gotsysd(8) unix socket is + restricted to specific user accounts, see + gotsysd.conf(5).

The options for gotsysctl are as + follows:

-h: Display usage information and exit immediately.
-f + path: Set the path to the unix socket which + gotsysd(8) is listening + on. If not specified, the path + /var/run/gotsysd.sock will be used.
-V, + --version: Display program version and exit immediately.

The commands for gotsysctl are as + follows:

info: Display information about a running gotsysd(8) instance.

SEE + ALSO

gotsys.conf(5), gotsysd.conf(5), gotsysd(8)

AUTHORS

Stefan Sperling + <stsp@openbsd.org>

NAME

gotsysd — + Game of Trees System Daemon

SYNOPSIS

+ + + + + +

gotsysd [-dnv] [-f + config-file]

DESCRIPTION

gotsysd manages the system configuration + of a Git repository server running gotd(8).

gotsysd 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 + system repository + called gotsys.git in order to configure Git + repository services.

Tasks carried out by gotsysd include the + creation of Git repositores to be served by gotd(8), and the creation of user accounts which use the + gotsh(1) shell to access + gotd(8). The desired system + configuration is described by the file + gotsys.conf(5) in the + system repository.

The gotsysd configuration file format is + described in gotsysd.conf(5). gotsysd can be run without a + configuration file, using default settings.

gotsysd listens on a + unix(4) socket for + notifications issued by gotd(8), and for commands issued via + gotsysctl(8). + gotd(8) notifications are + sent when a remote administrator modifies the file + gotsys.conf(5) in the + system repository.

Only the users root and _gotd are granted access to the + gotsysd unix socket by default. Alternative access + rules can be configured in gotsysd.conf(5).

The options for gotsysd are as + follows:

-d: Do not daemonize. Send log output to stderr.
-f + config-file: Set the path to the configuration file. If not specified, the file + /etc/gotsysd.conf will be used. This file is not + required to exist.
-n: Configtest mode. Only check the configuration file for validity.
-v: Verbose mode. Verbosity increases if this option is used multiple + times.

FILES

/etc/gotsysd.conf: Default location of the configuration file.
/git: Default directory containing Git repositories managed by + gotsysd. This path can be configured in + gotsysd.conf(5).
/var/db/gotsysd: The directory where gotsysd stores persistent + state. Files in this directory are opened with exclusive locks, ensuring + that only one instance of gotsysd runs on a given + OpenBSD system.
/var/run/gotsysd.sock: Default location of the unix socket which gotsysd + is listening on. This path can be configured in + gotsysd.conf(5).

SEE + ALSO

got(1), + gotsh(1), + gotsys(1), + gotsys.conf(5), + gotsysd.conf(5), + gotd(8), + gotsysctl(8)

AUTHORS

Stefan Sperling + <stsp@openbsd.org>

NAME

gotsysd.conf — + gotsysd configuration file

DESCRIPTION

gotsysd.conf is the run-time configuration + file for gotsysd(8).

nhe 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

GLOBAL + CONFIGURATION

+
+

The available global configuration directives are as follows:

gotd + user user

The name of the gotd(8) + user account. Defauls to “_gotd”. + gotsysd(8) will switch + to this user account as needed.

listen + on 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.

permit + 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.

repository + 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.

uid + range 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 + 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.

EXAMPLES

The following example shows default settings:

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

SEE + ALSO

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