GOTSYS.CONF(5)

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 repositories hosted by gotd(8) 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.

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 key type must be followed by the base64-encoded public key.

        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.

Reference and branch names specified in gotsys.conf are non-empty UTF-8 strings with the following disallowed characters: ‘ ’ (space, tab, formfeed, newline, carriage return), ~ (tilde), ^ (caret), : (colon), ? (question mark), * (asterisk), [ (opening square bracket), \ (backslash), " (double quote), ' (single quote), { (opening curly brace), } (closing curly brace), = (equal sign), # (hash), $ (dollar sign). The name may not be the string “@”, may not begin with a / (slash), and may not begin or end with a . (period). Additionally, the name may not contain the two-character sequences //, .. , and @{.

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.

protect {...}
    The 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 got send -f and git push -f are used to change the history of a branch.

    To build a set of protected branches and tags, multiple protect directives may be specified per repository and multiple protect directive parameters may be specified within curly braces.

    The available protect parameters are as follows:

    branch 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.

        If the name does not already begin with “refs/heads/” it will be looked up in the “refs/heads/” reference namespace.

    branch namespace 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.

        The namespace argument must be absolute, starting with “refs/”.

    tag namespace 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.

        The namespace argument must be absolute, starting with “refs/”.

    The special reference namespaces “refs/got/” and “refs/remotes/” do not need to be listed in gotsys.conf. These namespaces are always protected and even attempts to create new references in these namespaces will always be denied.

notify {...}
    The notify directive enables notifications about new commits or tags added to the repository.

    The default content of email notifications looks similar to the output of the got log -d command.

    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 by triggering arbitrary post-commit actions via the HTTP server.

    The notify directive expects parameters which must be enclosed in curly braces. The available parameters are as follows:

    branch name
        Send notifications about commits to the named branch. The name will be looked up in the “refs/heads/” reference namespace. This directive may be specified multiple times to build a list of branches to send notifications for. If neither a branch nor a reference namespace are specified then changes to any reference will trigger notifications.

    reference namespace 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 branch nor a reference namespace are specified then changes to any reference will trigger notifications.

    email to recipient [reply to responder]
        Send notifications via email to the specified recipient. This directive may be specified multiple times to build a list of recipients to send notifications to.

        The recipient must be an email address that accepts mail.

        If a responder is specified via the reply to directive, the 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, for example.

    url URL [user user password password [insecure]] [hmac secret]
        Send notifications via HTTP. This directive may be specified multiple times to build a list of HTTP servers to send notifications to.

        The notification will be sent as a POST request to the given URL, which must be a valid HTTP URL and begin with either “http://” or “https://”. If HTTPS is used, sending of notifications will only succeed if no TLS errors occur.

        The optional user and password directives enable HTTP Basic authentication. If used, both a user and a password must be specified. The password must not be an empty string. Unless the insecure option is specified the notification target URL must be a “https://” URL to avoid leaking of authentication credentials.

        If a 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 signature uses HMAC-SHA256 and will be sent in the HTTP header “X-Gotd-Signature”. Suitable secrets can be generated with openssl(1) as follows:

            $ openssl rand -base64 32

        The request body contains a JSON object with a “notifications” property containing an array of notification objects. The following notification object properties are always present:

        repo
            The repository name as a string.

        authenticated_user
            The committer's user account as authenticated by gotd(8) as a string.

        type
            The notification object type as a string.

        Each notification object carries additional type-specific properties. The types and their type-specific properties are:

        commit
            The commit notification object has the following fields. Except where noted, all are optional.

            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.

            id  The commit ID as string, may be abbreviated.

            committer
                An object with the committer information with the following fields:

                full
                    Committer's full name.
                name
                    Committer's name.
                mail
                    Committer's mail address.
                user
                    Committer's username. This is the only field guaranteed to be set.

            author
                An object with the author information. Has the same fields as the ‘committer’ but may be unset.

            date
                Number, representing the number of seconds since the Epoch in UTC.

            short_message
                The first line of the commit message. This field is always set.

            message
                The complete commit message, may be unset.

            diffstat
                An object with the summarized changes, may be unset. Contains a ‘files’ field with an array of objects describing the changes per-file and a ‘total’ field with the cumulative changes. The changes per-file contains the following fields:

                action
                    A string describing the action, can be “added”, “deleted”, “modified”, “mode changed”, or “unknown”.
                file
                    The file path.
                added
                    The number of lines added.
                removed
                    The number of lines removed.

                The ‘total’ object contains two fields: ‘added’ and ‘removed’ which are the number of added and removed lines respectively.

        branch-deleted
            The branch deleted notifications has the following fields, all guaranteed to be set:

            ref The removed branch reference.

            id  The hash of the commit pointed by the deleted branch.

        tag The tag notification has the following fields, all guaranteed to be set:

            tag The tag reference.

            tagger
                The user information, with the same format of the ‘committer’ field for the ‘commit’ notification but with all the field guaranteed to be set.

            date
                Number, representing the number of seconds since the Epoch in UTC.

            object
                The object being tagged. It contains the fields ‘type’ with the object type and ‘id’ with the object id being tagged.

            message
                The tag message.

WEB SERVER CONFIGURATION
gotsys.conf can set configuration parameters for gotwebd(8) to display Git repositories on the web,

One or more web servers can be declared with the directive:

web server hostname {...}

The given hostname should be the name which web browsers use to reach the host running the web server.

All web servers share the same underlying repository directory managed by gotsysd(8). However, each web server can be configured to display an arbitrary subset of repositories and/or web sites, providing a unique view on the shared data.

If the given hostname does not exist in gotsysd.conf(5) on the server then gotsysd(8) will silently ignore web server parameters. The server administrator can use gotsysd.conf(5) to set global defaults for web server parameters documented here. When in doubt, the correct host name to use and the server-side defaults should be obtained from the server administrator.

Parameters for the web server must be given in curly braces and are as follows:

disable authentication
    Disable authentication, allowing any browser to view any web sites and any repository not hidden via the hide repositories or hide repository directives.

    Authentication can also be configured per repository and per web site.

enable authentication
    Enable authentication, requiring browsers to present a login token cookie before read-only repository or web site access is granted.

    Browsers presenting a valid login token cookie will be mapped to the user account which obtained the login token over SSH from the weblogin command of gotsh(1).

    Authentication can also be configured per repository and per web site.

deny identity
    Deny repository access to users with the username identity. Group names may be matched by prepending a colon (‘’): to identity. Numeric IDs are also accepted.

permit identity
    Permit repository access to users with the username identity. Group names may be matched by prepending a colon (‘’): to identity. Numeric IDs are also accepted.

hide repositories on | off
    Controls whether repositories are hidden by default. Hidden repositories cannot be browsed via gotwebd(8). However, web sites can be served out of a repository even if the repository is hidden.

site owner name
    Set the displayed site owner. If not set then no site owner will be displayed by gotwebd(8).

repositories url path url-path
    Sets the URL path under which Git repositories will be displayed by gotwebd(8). This allows for displaying a web site at the root URL path, while still displaying the default gotwebd(8) repository browser view at another URL path.

repository name {...}
    Set repository-specific parameters for gotwebd(8). The given name must match a Git repository declared in the REPOSITORY CONFIGURATION section of gotsys.conf.

    The available parameters are as follows:

    hide repository on | off
        Controls whether the repository is hidden. Hidden repositories cannot be browsed via gotwebd(8). If not set, the web server context's hide repositories parameter determines whether gotwebd(8) will display the repository.

        Web sites can be served out of a repository even if the repository is hidden.

    disable authentication
        Disable authentication, allowing any browser to view this repository unless it is hidden via the hide repositories or hide repository directives.

    enable authentication
        Enable authentication, requiring browsers to present a login token cookie before read-only access to this repository is granted.

        Browsers presenting a valid login token cookie will be mapped to the user account which obtained the login token over SSH from the weblogin command of gotsh(1).

    deny identity
        Deny repository access to users with the username identity. Group names may be matched by prepending a colon (‘’): to identity. Numeric IDs are also accepted.

    permit identity
        Permit repository access to users with the username identity. Group names may be matched by prepending a colon (‘’): to identity. Numeric IDs are also accepted.

website url-path {...}
    Declare a web site to be served by gotwebd(8) when the browser visits the given url-path.

    The available web site configuration parameters are as follows:

    repository name
        Serve web site content from the specified Git repository. The given name must match a Git repository declared in the REPOSITORY CONFIGURATION section of gotsys.conf.

    path path
        Look up files to serve as web site content at the specified path in the repository. Defaults to the root directory, “/”.

    branch name
        Look up files to serve as web site content on the specified branch in the repository. By default, the branch resolved via the repository's HEAD reference is used.

        If the name does not begin with “refs/heads” then the name is searched in the “refs/heads” reference namespace.

    disable authentication
        Disable authentication, allowing any browser to view this web site.

    enable authentication
        Enable authentication, requiring browsers to present a login token cookie before web site access is granted.

        Browsers presenting a valid login token cookie will be mapped to the user account which obtained the login token over SSH from the weblogin command of gotsh(1).

    deny identity
        Deny web site access to users with the username identity. Group names may be matched by prepending a colon (‘’): to identity. Numeric IDs are also accepted.

    permit identity
        Permit web site access to users with the username identity. Group names may be matched by prepending a colon (‘’): to identity. Numeric IDs are also accepted.

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
    	authorized key ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBBVqRHzWh20u49JoZPc34pBFo7w+0KGRCnkuNbeR7ufJUbXceDwzgssQHDVILD1QK0Mmku2jLo1MG/BtwTVpsWc= flan_squee@localhost
    }
    repository "src" {
    	permit rw :developers
    	permit ro anonymous
    	protect branch "main"
    	protect tag namespace "refs/tags/"
    }
    repository "openbsd-ports" {
    	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
    	}
    }
    repository "secret" {
    	permit rw flan_hacker
    	head "refs/heads/private"
    	protect branch "private"
    	protect tag namespace "refs/tags/"
    }

SEE ALSO
got(1), gotsys(1), gotd(8), gotsysd(8), gotwebd(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.