GOTWEBD.CONF(5)

NAME
gotwebd.conf - gotwebd configuration file

DESCRIPTION
gotwebd.conf is the run-time configuration file for gotwebd(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, server 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:

    lan_addr = "192.168.0.1"
    listen on $lan_addr port 9090

GLOBAL CONFIGURATION
The available global configuration directives are as follows:

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.

    Whether these files will be served by gotwebd(8) or by httpd(8) depends on how request routing is configured in httpd(8).

    This setting can also be configured on a per-server basis.

gotweb_url_root path
    Sets the URL path under which httpd(8) is routing requests to gotwebd(8). Defaults to “/”.

    The specified path should match the path of the location block in httpd.conf(5) which forwards requests to gotwebd(8) via the FastCGI socket. If the URL path is not configured correctly then gotwebd(8) will not be able to serve static files from the htdocs directory. Browsers will not be able to load CSS and image files unless these files are served directly from httpd(8).

    This setting can also be configured on a per-server basis.

repos_url_path path
    Sets the URL path under which Git repositories will be displayed by gotwebd(8). The path specified here is relative to gotweb_url_root.

    Defaults to “/”. This default should only be changed if a website is configured as the landing page instead of the usual index page shown by gotwebd(8). Otherwise, changing repos_url_path will result in “not found” errors when browsers attempt to visit the gotweb root URL path.

    This setting can also be configured on a per-server basis.

disable authentication
    Disable authentication, allowing any browser to view any repository not hidden via the hide repositories, hide repository, or respect_exportok directives. Authentication is disabled by default.

enable authentication [insecure]
    Enable authentication, requiring browsers to present a login token cookie before read-only repository access is granted. Authentication can also be configured on a per-server or per-repository basis.

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

    Unauthenticated browsers will be mapped to the user account which runs httpd(8). This user account can be set with the www user directive. Attempts to read repositories as this user will be denied unless authentication is disabled for the repository.

    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.

listen on address port number
    Configure an address and port for incoming FastCGI connections. Valid address arguments are hostnames, IPv4 and IPv6 addresses. The port argument may be number or a service name defined in services(5). May be specified multiple times to build up a list of listening sockets.

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.

login hint port number
    Sets the SSH port number displayed in login hints which are shown on the error page if authentication has failed. This can be used to point SSH clients at the correct port number when sshd(8) is listening on a non-default port.

login hint user name
    Sets the user name displayed in login hints which are shown on the error page if authentication has failed. This can be used to advertise the name of an anonymous user account which has been given read access to one or more repositories via the permit directive.

    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.

    This setting can also be configured on a per-server basis.

login socket path
    Set the path to the UNIX-domain socket for gotsh(1) weblogin commands. By default the path /var/run/gotweb-login.sock will be used.

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.

user user
    Set the user which will run gotwebd(8). If not specified, the user _gotwebd will be used.

www user user
    Set the user which runs httpd(8). Needed to ensure that the web server can access UNIX-domain sockets created by gotwebd(8). If not specified, the user www will be used.

ssh_hostkey_ecdsa string
    Set the server's SSH ECDSA host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol.

ssh_hostkey_ed25519 string
    Set the server's SSH ED25519 host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol.

ssh_hostkey_rsa string
    Set the server's SSH RSA host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol.

If no listen directive is used, gotwebd(8) will listen on the UNIX-domain socket at /var/www/run/gotweb.sock.

SERVER CONFIGURATION
At least one server context must exist for gotwebd(8) to function. In case no server context is defined in the configuration file, a default server context will be used which uses default parameters for all applicable settings.

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

server name {...}

If more than one server is defined, each name should match the hostname which browsers use to reach the corresponding server. The first server defined is used if the requested hostname is not matched by any server block.

The available server configuration directives are as follows:

custom_css path
    Set the path to a custom Cascading Style Sheet (CSS) to be used. If this option is not specified then the default style sheet ‘gotweb.css’ will be used.

    This path must be valid in the web server's URL space since browsers will attempt to fetch it.

logo path
    Set the path to an image file containing a logo to be displayed. Defaults to ‘got.png’.

    This path must be valid in the web server's URL space since browsers will attempt to fetch it.

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 the global htdocs configuration setting applies.

    Whether these files will be served by gotwebd(8) or by httpd(8) depends on how request routing is configured in httpd(8).

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) via the FastCGI socket. If the URL path is not configured correctly then gotwebd(8) will not be able to serve static files from the htdocs directory. Browsers will not be able to load CSS and image files unless these files are served directly from httpd(8).

    If not set then the global gotweb_url_root setting will be used.

repos_url_path path
    Sets the URL path under which Git repositories will be displayed by gotwebd(8). The path specified here is relative to gotweb_url_root.

    Defaults to “/”. This default should only be changed if a website is configured as the landing page instead of the usual index page shown by gotwebd(8). Otherwise, changing repos_url_path will result in “not found” errors when browsers attempt to visit the gotweb root URL path.

    If not set then the global repos_url_path setting will be used.

disable authentication
    Disable authentication for this server, allowing any browser to view any repository not hidden via the hide repositories, hide repository, or respect_exportok directives. Authentication can also configured on a per-repository basis.

    If not specified, the global configuration context determines whether authentication is disabled.

enable authentication [insecure]
    Enable authentication, requiring browsers to present a login token cookie before read-only repository access is granted. Authentication can also configured on a per-repository basis.

    If not specified, the global configuration context determines whether authentication is enabled.

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 repos_path will be displayed.

    If hide repositories is set to on then a repository will only be displayed if its repository-specific hide repository parameter is set to off. Repositories will be hidden regardless of whether authentication is enabled and has failed or succeeded.

login hint user name
    Sets the user name to use in login hints displayed when authentication fails. If not set then the login hint setting in the global configuration context will be used.

logo_url url
    Set a hyperlink for the logo. Defaults to https://gameoftrees.org.

max_commits_display number
    Set the maximum amount of commits and tags displayed per page. Defaults to 25.

max_repos_display number
    Set the maximum amount of repositories displayed on the index screen. Defaults to 25. Set to zero to show all the repositories without pagination.

repos_path path
    Set the path to the directory which contains Git repositories that the server should publish. This path is absolute. Repositories can be served even if they reside outside the web server's chroot directory.

    Defaults to /got/public inside the web server's chroot directory. The chroot directive must be used before the server declaration in order to take effect.

ssh_hostkey_ecdsa string
    Set the server's SSH ECDSA host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol. If not set then SSH fingerprints found in the global configuration context will be used.

ssh_hostkey_ed25519 string
    Set the server's SSH ED25519 host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol. If not set then SSH fingerprints found in the global configuration context will be used.

ssh_hostkey_rsa string
    Set the server's SSH RSA host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol. If not set then SSH fingerprints found in the global configuration context will be used.

repository name {...}
    Set options which apply to a particular repository served by this server.

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

    The repository will be looked up within the server's repos_path, where the directory name can exist with or without a “.git” suffix.

    For each repository, access rules can 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 access rules are set in a repository context, or if a repository exists in the server's repos_path without being mentioned in gotwebd.conf at all, then the access rules set in the server and global configuration contexts apply. If no rule matches then the repository will be inaccessible if authentication is enabled.

    The available repository configuration directives are as follows:

    clone_url string
        Sets the repository Git clone URL shown on the repository summary page. The string parameter should be wrapped in quotes and should be a valid URL for use with got clone or git clone.

        If no clone URL is set in gotwebd.conf then URLs stored in the repository's cloneurl file will be shown instead. This file may contain multiple URLs, one per line.

    ssh_hostkey_ecdsa string
        Set the server's SSH ECDSA host key fingerprint to be displayed beneath the clone URL. Should be set when the clone URL uses the SSH protocol. If not set then SSH fingerprints found in the server or global configuration context will be used.

    ssh_hostkey_ed25519 string
        Set the server's SSH ED25519 host key fingerprint to be displayed beneath the clone URL. Should be set when the clone URL uses the SSH protocol. If not set then SSH fingerprints found in the server or global configuration context will be used.

    ssh_hostkey_rsa string
        Set the server's SSH RSA host key fingerprint to be displayed beneath the clone URL. Should be set when the clone URL uses the SSH protocol. If not set then SSH fingerprints found in the server or global configuration context will be used.

    description string
        Sets the repository description shown on the repository listing page. The string parameter should be wrapped in quotes and can only contain one line of text.

        If no description is set in gotwebd.conf then the description stored in the repository's description file will be shown instead. This file may contain multiple lines of text.

    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.

    disable authentication
        Disable authentication, allowing any browser to view the repository. Any access rules configured with permit or deny directives for this repository will be ignored.

        If not specified, the server context or global context determines whether authentication is disabled.

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

        If not specified, the server context or global context determines whether authentication is enabled.

    hide repository on | off
        Controls whether the repository is hidden. Hidden repositories cannot be browsed via gotwebd(8).

        If not set, the server context's hide repositories parameter determines whether gotwebd(8) will display the repository.

website url-path {...}
    Show a web site when the browser visits the given url-path.

    For each web site, access rules can 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 access rules are set in a web site context then the access rules set in the server and global configuration contexts apply. If no rule matches then the web site will be inaccessible if authentication is enabled.

    The hide repository or respect_exportok directives do not apply to web site content.

    Website content must conform to the Content-Security-Policy (CSP) generated by gotwebd(8), which is:

        default-src 'self'; script-src 'self'; object-src 'none';

    The available website configuration parameters are as follows:

    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.

    disable authentication
        Disable authentication, allowing any browser to view the web site. Any access rules configured with permit or deny directives for this web site will be ignored.

        If not specified, the server context or global context determines whether authentication is disabled.

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

        If not specified, the server context or global context determines whether authentication is enabled.

    repository name
        Serve web site content from the specified Git repository. The repository will be looked up within the server's repos_path, where the directory name can exist with or without a “.git” suffix.

        The repository parameter is mandatory.

    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.

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

respect_exportok on | off
    Set whether to display the repository only if it contains the magic git-daemon-export-ok file, regardless of whether authentication is enabled and has failed or succeeded. Disabled by default.

show_repo_age on | off
    Toggle display of last repository modification date. Enabled by default.

show_repo_cloneurl on | off
    Toggle display of clone URLs for a repository. This requires the repository's option to be set, or requires the creation of a cloneurl file inside the repository which contains one URL per line. Enabled by default.

show_repo_description on | off
    Toggle display of the repository description. Enabled by default. The description file in the repository should be updated with an appropriate description. Alternatively, the per-repository description option can be used to set a description in gotwebd.conf.

show_repo_owner on | off
    Set whether to display the repository owner. Enabled by default. This requires the creation of an owner file in the repository or adding an ‘owner’ field under the [gotweb] or [gitweb] section in the config file inside the repository. For example:

        [gotweb]
        owner = "Your Name"

    The owner file has priority over the config if present.

site_link string
    Set the displayed site link name for the index page. Defaults to ‘Repositories’.

site_name string
    Set the displayed site name title. Defaults to ‘Gotweb’.

site_owner string
    Set the displayed site owner. Defaults to ‘Got Owner’.

show_site_owner on | off
    Toggle display of the site owner. Enabled by default.

summary_commits_display number
    The maximum number of commits to show in the summary page. Defaults to 10.

summary_tags_display number
    The maximum number of tags to show in the summary page. Defaults to 3.

  TYPES
The types section configures media types. When serving plain files such as style-sheets, images, or other web site content, gotwebd(8) will set the Content-Type of the response header based on the file extension of the matching media type. If not specified, gotwebd(8) will use built-in media types for text/css, text/html, text/plain, text/xml, image/gif, image/png, image/jpeg, image/svg+xml, application/javascript, and application/manifest+json.

The types section must include one or more lines of the following syntax, enclosed in curly braces:

type/subtype name [name ...]
    Set the media type and subtype to the specified extension name. One or more names can be specified per line. Each line may end with an optional semicolon. Later lines overwrite earlier lines.

include file
    Include types definitions from an external file, for example /usr/share/misc/mime.types.

FILES
/etc/gotwebd.conf
    Default location of the gotwebd.conf configuration file.
/var/www/run/gotweb.sock
    Default location for the gotwebd(8) UNIX-domain socket.

EXAMPLES
A sample configuration which allows public browsing:

    www user "www"   # www username needs quotes since www is a keyword
    server "localhost" {
    	site_name	"my public repos"
    	site_owner	"Flan Hacker"
    	site_link	"Flan' Projects"
    }

Another example, this time listening on a local port instead of the implicit UNIX-domain socket, and serving repositories located outside the web server's chroot:

    listen on 127.0.0.1 port 9000
    listen on ::1 port 9000
    server "localhost" {
    	site_name	"my public repos"
    	repos_path	"/var/git"
    }

This example illustrates how to define custom media types:

    server "localhost" {
    	repos_path	"/var/git"
    }
    types {
    	text/css		css
    	text/html		html htm
    	text/plain		txt
    	image/gif		gif
    	image/jpeg		jpeg jpg
    	image/png		png
    	application/javascript	js
    	application/xml		xml
    }

This example illustrates how gotwebd(8) can serve static web sites out of Git repositories:

    # Load a set of mime types from an external file.
    types { include "/usr/share/misc/mime.types" }
    # This server displays just one web site, no Git repositories.
    server "www.example.com" {
    	# Do not display any Git repository data.
    	hide repositories on
    	# Serve the www.git repository as a web site when
    	# the browser visits "www.example.com".
    	website "/" {
    		repository "www"  # /var/www/got/public/www.git
    		# Any child URL paths the browser wants to
    		# visit will be looked up in www.git, on
    		# the branch which the symbolic HEAD
    		# reference points to.
    	}
    }
    # This server displays both web sites and Git repositories.
    server "project.example.com" {
    	repos_path	"/var/git"
    	# Display Git repositories when the URL path "/gotweb/" is
    	# is visited by the browser.
    	repos_url_path "/gotweb"
    	website "/" {
    		# Display the "www" repository as a web site when
    		# the browser visits "project.example.com".
    		repository "www"  # /var/git/www or /var/git/www.git
    		# Any child URL path the browser wants to visit will
    		# be looked up in www.git, except for "gotweb/" which
    		# maps to repos_path, and "docs/" which is used by
    		# other repositories defined below.
    	}
    	repository "www.git" {	# /var/git/www or /var/git/www.git
    		# Otherwise, hide data in this repository. It will
    		# not be shown under the "/gotweb" URL path.
    		hide repository on
    	}
    	# Display the src.git repository's "docs/html" directory
    	# as found on the main branch as a web site at the
    	# URL "project.example.com/docs/".
    	website "/docs" {
    		repository "src"
    		path "/docs/html"
    		branch "main"  # same as "refs/heads/main"
    		# Any child URL paths the browser wants to visit will
    		# be looked up in src.git, except for "gotweb/"
    		# which maps to repos_path, and "docs/api/" which is
    		# used by another web site defined below.
    	}
    	repository "src" {	# /var/git/src or /var/git/src.git
    		# Otherwise, hide data in this repository. It will
    		# not be shown under the "/gotweb" URL path.
    		hide repository on
    	}
    	# Display the "main" branch of api-docs.git repository
    	# as a web site at the URL
    	# "project.example.com/docs/api/latest/".
    	website "/docs/api/latest" {
    		repository "api-docs.git"
    		branch "main"
    	}
    	# Display the "1.x-stable" branch of the api-docs.git
    	# as a web site at the URL
    	# "project.example.com/docs/api/1.x/".
    	website "/docs/api/1.x" {
    		repository "api-docs.git"
    		branch "1.x-stable"
    	}
    	# The api-docs repository will also be shown under "/gotweb"
    	# because the hide repositories and hide repository
    	# settings default to "off".
    }

The following example illustrates the use of directives related to authentication:

    # 3 scopes: global, per-server, per-repository
    enable authentication  # override the default which is 'disable'
    # Allow user "admin" to read anything unless overridden with a
    # "deny" rule later.
    permit "admin"
    server "public.example.com" {
    	disable authentication	# override global setting
    	repos_path "/var/www/got/public"
    }
    server "secure.example.com" {
    	permit flan_squee	# grant access to flan_squee
    	permit :developers	# grant access to developers group
    	repos_path		"/var/git"
    	# Tell vistors who see a "login failed" error page that
    	# they can log in as the "anonymous" user via ssh.
    	login hint user "anonymous"
    	repository "got" {  # /var/git/got and /var/git/got.git
    		# Grant access to users who have authenticated as
    		# the anonymous user to gotsh(1), which anyone with
    		# an SSH client sbould be able to do.
    		# Dumb web crawlers will remain locked out.
    		permit "anonymous"
    	}
    	repository "public" {
    		# As an exception, allow any web browsers and
    		# web crawlers to view this repository.
    		disable authentication
    	}
    	repository "secret" {
    		deny admin # not even the admin can read this
    	}
    }

SEE ALSO
got(1), httpd.conf(5), services(5), gotwebctl(8), gotwebd(8), httpd(8)