GOTWEBD.CONF(5)

📦

version 0.126 · 2 versions

0.126 · alpine 3.24, nixos 26.05 (latest)
0.129 · nixpkgs unstable

💖 NAME 💖

gotwebd.conf — the configuration file for gotwebd(8). Yep, it’s a File Formats Manual page, section 5, iykyk. ✨

🦋 DESCRIPTION 🦋

Okay so gotwebd.conf is the run-time configuration file for gotwebd(8). It’s where you tell your Got web server how to act, and it’s giving main character energy but make it settings. 💅

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 they extend to the end of the current line. 🎀

Argument names that don’t begin with a letter, digit, or underscore — plus reserved words like listen, server, or user — must be quoted. Arguments containing whitespace should be surrounded by double quotes (").

Macros can be defined and later expanded in context. Macro names must start with a letter, digit, or underscore, and may contain any of those characters, but they 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, bestie:

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

Heads up, bestie: if no listen directive is used, gotwebd(8) will listen on the Unix-domain socket at /var/www/run/gotweb.sock. No cap. 💀

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

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.

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 be configured on a per-repository basis.

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

enable authentication [insecure] — turns authentication ON, bestie, so browsers have to present a login token cookie before they get read-only repository access 💅. You can also configure authentication on a per-repository basis. If this isn’t specified, the global configuration context decides whether authentication is enabled. Periodt.
hide repositories on | off — controls whether repositories are hidden by default. Hidden repositories literally 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. No cap.
login hint user name — sets the user name to use in login hints displayed when authentication fails. If it’s not set, then the login hint setting in the global configuration context will be used ✨.
logo_url url — sets a hyperlink for the logo. Defaults to https://gameoftrees.org 🎀.
max_commits_display number — sets the maximum amount of commits and tags displayed per page. Defaults to 25 💖.
max_repos_display number — sets the maximum amount of repositories displayed on the index screen. Defaults to 25. Set it to zero to show all the repositories without pagination 🦋.
repos_path path — sets 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 — sets the server’s SSH ECDSA host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol. If it’s not set, then SSH fingerprints found in the global configuration context will be used 🧚.
ssh_hostkey_ed25519 string — sets the server’s SSH ED25519 host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol. If it’s not set, then SSH fingerprints found in the global configuration context will be used 🌸.
ssh_hostkey_rsa string — sets the server’s SSH RSA host key fingerprint to be displayed beneath login hints and beneath clone URLs which use the SSH protocol. If it’s not set, then SSH fingerprints found in the global configuration context will be used ⭐.

💜 `repository name {...}` 💜

Sets 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. That’s the tea ☕.

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 — sets 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 it’s not set, then SSH fingerprints found in the server or global configuration context will be used.
ssh_hostkey_ed25519 string — sets 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 it’s not set, then SSH fingerprints found in the server or global configuration context will be used.
ssh_hostkey_rsa string — sets 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 it’s 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 — denies 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 — permits 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 — disables authentication, allowing any browser to view the repository. Any access rules configured with permit or deny directives for this repository will be ignored. If it’s not specified, the server context or global context determines whether authentication is disabled 💀.
enable authentication [insecure] — enables authentication, requiring browsers to present a login token cookie before read-only repository access is granted. If it’s 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 it’s not set, the server context’s hide repositories parameter determines whether gotwebd(8) will display the repository 🌈.

🦋 `website url-path {...}` 🦋

Shows 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 — denies 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 — permits 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 — disables 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 it’s not specified, the server context or global context determines whether authentication is disabled.
enable authentication [insecure] — enables authentication, requiring browsers to present a login token cookie before access to the web site is granted. If it’s not specified, the server context or global context determines whether authentication is enabled.
repository name — serves 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 — looks 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 — looks up files to serve as web site content at the specified path in the repository. Defaults to the root directory, / 🎀.
respect_exportok on | off — flips on the whole "is this repo even allowed to be seen" vibe check: the repo only shows up if it's got that magic git-daemon-export-ok file inside it — and like, that's regardless of whether authentication is enabled and whether the auth actually failed or succeeded. Off by default, so nobody's hiding unless you say so 💅
show_repo_age on | off — toggles whether we show off when the repo was last touched. On by default ✨
show_repo_cloneurl on | off — toggles showing the clone URLs for a repo. Ngl this one needs a lil help from you: either the repo's option has to be set, or you gotta create a cloneurl file inside the repo with one URL per line. On by default 🫶
show_repo_description on | off — toggles showing the repo description. On by default. Bestie, you should update the description file inside the repo with an actual description. Or (iconic alternative), you can set it via the per-repository description option right in gotwebd.conf 🎀
show_repo_owner on | off — sets whether the repo owner gets shown. On by default. For this to work you need an owner file inside the repository, or an owner field under the [gotweb] or [gitweb] section in the config file inside the repository. Like so:

      [gotweb]
      owner = "Your Name"

And heads up — if both exist, the owner file wins over the config 👑

site_link string — the site link name that shows up on the index page. Defaults to Repositories.
site_name string — the displayed site name title. Defaults to Gotweb.
site_owner string — the displayed site owner. Defaults to Got Owner.
show_site_owner on | off — toggles showing the site owner. On by default 🌸
summary_commits_display number — the max number of commits to show on the summary page. Defaults to 10.
summary_tags_display number — the max number of tags to show on the summary page. Defaults to 3.

✨ TYPES ✨

Lowkey the most underrated section imo. This is where you configure media types 🎨

So when it's serving plain files — think style-sheets, images, or any 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. And if you don't specify anything? No stress, gotwebd(8) comes with 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 has to include one or more lines of this syntax, all wrapped up in curly braces:

type/subtype name [name ...]

type/subtype name [name ...] — sets the media type and subtype to the specified extension name. You can list one or more names per line, and each line may end with an optional semicolon. Later lines overwrite earlier lines (so like, last one in wins, periodt) 💅
include file — pulls in types definitions from an external file — for example /usr/share/misc/mime.types 📂

🌈 FILES 🌈

/etc/gotwebd.conf — the default location of the gotwebd.conf configuration file.
/var/www/run/gotweb.sock — the default location for the gotwebd(8) Unix-domain socket.

🔥 EXAMPLES 🔥

Okay this part ate, let's get into it. A sample config that 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 one — this time listening on a local port instead of the implicit Unix-domain socket, and serving repos that live 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"
      }

And this one shows off 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 next one is the main character example — it shows how gotwebd(8) can serve static web sites straight out of Git repositories. Big energy:

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

And finally, the authentication example — the one where all the access-control drama happens 🔐

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

That's the whole page bestie, you made it 💖 go forth and serve some repos. This one's the Debian build, dated $Mdocdate$ , and it's the GOTWEBD.CONF(5) page — ily, bye 🎀✨

📦 where this page comes from

alpine 3.24: got-doc 0.126-r0 · ISC
nixos 26.05: got 0.125
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms