NAME

     gotd.conf — gotd configuration file

DESCRIPTION

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

     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:

     connection option
             Set the specified options and limits for connections to the gotd(8) unix socket.

             The connection directive may be specified multiple times, and multiple option
             arguments may be specified within curly braces:

             connection {...}

             Each option should only be specified once.  If a given option is listed multiple
             times, the last line which sets this option wins.

             Valid connection options are:

             request timeout 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.

                     The timeout value may also have a suffix indicating its unit of measure.
                     Supported suffixes are:

                     s or S      seconds
                     m or M      minutes
                     h or H      hours

                     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.

             limit user identity number
                     Limit the maximum amount of concurrent connections by the user with the
                     username identity to number.  Numeric user IDs are also accepted.

                     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.

     listen on path
             Set the path to the unix socket which gotd(8) should listen on.  If not specified,
             the path /var/run/gotd.sock will be used.

     user user
             Set the user which will run gotd(8).  Initially, gotd(8) requires root privileges in
             order to create its unix socket.  Afterwards, gotd(8) drops privileges to the
             specified user.  If not specified, the user _gotd will be used.

REPOSITORY CONFIGURATION

     At least one repository context must exist for gotd(8) to function.  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.

     A repository context is declared with a unique name, followed by repository-specific
     configuration directives inside curly braces:

     repository name {...}

     got(1) and git(1) clients can connect to a repository by including the repository's unique
     name in the request URL.  Clients appending the string “.git” to the name will also be
     accepted.

     If desired, the name may contain path-separators, “/”, to expose repositories as part of a
     virtual client-visible directory hierarchy.

     The available repository configuration directives are as follows:

     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.

     path path
             Set the path to the Git repository.  Must be specified.

     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.  Numeric IDs are also
             accepted.

     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 gotd.conf.  These namespaces are always protected and even attempts to
             create new references in these namespaces will always be denied.

FILES

     /etc/gotd.conf
             Location of the gotd.conf configuration file.

EXAMPLES

           # 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

                   protect branch "main"
                   protect tag namespace "refs/tags/"
           }

           # 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

                   protect {
                           branch "main"
                           tag namespace "refs/tags/"
                   }
           }

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

SEE ALSO

     got(1), gotsh(1), gotd(8)