GOTWEBD.CONF(5) File Formats Manual GOTWEBD.CONF(5)

gotwebd.conf — gotwebd configuration file

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

The available global configuration directives are as follows:

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

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

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.

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.
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
Set the user which will run gotwebd(8). If not specified, the user _gotwebd will be used.
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.

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

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:

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.

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.

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.

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

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.

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.
url
Set a hyperlink for the logo. Defaults to https://gameoftrees.org.
number
Set the maximum amount of commits and tags displayed per page. Defaults to 25.
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.
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.

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:

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

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

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.

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.
on | off
Toggle display of last repository modification date. Enabled by default.
on | off
Toggle display of clone URLs for a repository. This requires the creation of a cloneurl file inside the repository which contains one URL per line. Enabled by default.
on | off
Toggle display of the repository description. Enabled by default. The description file in the repository should be updated with an appropriate description.
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.

Set the displayed site link name for the index page. Defaults to ‘Repos’.
string
Set the displayed site name title. Defaults to ‘Gotweb’.
string
Set the displayed site owner. Defaults to ‘Got Owner’.
on | off
Toggle display of the site owner. Enabled by default.
number
The maximum number of commits to show in the summary page. Defaults to 10.
number
The maximum number of tags to show in the summary page. Defaults to 3.

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

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

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

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

OpenBSD 7.8 October 3, 2025 GOTWEBD.CONF(5)