GOTSYSD.CONF(5)

NAME
gotsysd.conf - gotsysd configuration file

DESCRIPTION
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

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.

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

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

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 accounts created by gotsysd(8) will use the gotsh(1) shell.

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.

WEB SERVER CONFIGURATION
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:

control socket path
    Set the path to the UNIX-domain socket for gotwebctl(8) commands. By default the path /var/run/gotwebd.sock will be used.

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

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

htdocs 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
    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).

enable authentication [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.

login hint user 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.

login hint port number
    Sets the SSH port number displayed in login hints which are shown on the error page if authentication has failed.

redirect_method method
    Set the method used by gotwebd(8) when redirecting clients to another page, such as from the login page to the summary page.

    The available methods are:

    page_refresh
        Send HTTP response status code 200 (success) and serve a meta tag in the HTML response body with the http-equiv attribute set to “refresh” and a new URL in the url attribute.

        This method is the default and provides good browser compatibility overall. This method can get in the way of scripts trying to navigate through a gotsh(1) weblogin link, which is usually desirable, but not always.

    status_code
        Send HTTP response status code 307 (redirect) with a target URL in HTTP headers and with an empty response body.

        This method generally works as expected. In some situations browsers fail to follow the redirect and display the redirecting page instead. For example, gotsh(1) weblogin links have been known to fail loading the summary page if the redirecting link is opened by an external application asking Mozilla Firefox to open the login link, even though the redirect is followed as expected when the login link is visited via the browser's address bar.

user name
    Set the user which runs gotwebd(8). Defaults to the user _gotwebd.

www user name
    Set the user which runs httpd(8). Defaults to the user www.

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

listen on 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:

gotweb_url_root 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).

htdocs 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).

hide repositories 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
    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).

enable authentication [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.

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

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

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
    }

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