.\" .\" Copyright (c) 2020 Tracey Emery .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate$ .Dt GOTWEBD.CONF 5 .Os .Sh NAME .Nm gotwebd.conf .Nd gotwebd configuration file .Sh DESCRIPTION .Nm is the run-time configuration file for .Xr gotwebd 8 . .Pp The file format is line-based, with one configuration directive per line. Any lines beginning with a .Sq # are treated as comments and ignored. .Pp 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: .Bd -literal -offset indent lan_addr = "192.168.0.1" listen on $lan_addr .Ed .Pp Paths mentioned in .Nm must be relative to .Pa /var/www , the .Xr chroot 2 environment of .Xr httpd 8 . .Sh GLOBAL CONFIGURATION The available global configuration directives are as follows: .Bl -tag -width Ds .It Ic chroot Ar path Set the path to the .Xr chroot 2 environment of .Xr httpd 8 . If not specified then .Pa /var/www will be used. .It Ic prefork Ar number Run the specified number of server processes. .It Ic unix_socket Ar on | off Controls whether the servers will listen on unix sockets by default. .It Ic unix_socket_name Ar path Set the path to the default unix socket. .El .Sh SERVER CONFIGURATION At least one server context must exist for .Xr gotwebd 8 to function. In case no server context is defined in the configuration file, a default server context will be used, which listens on a unix socket at .Pa /var/www/run/gotweb.sock and uses default parameters for all applicable settings. .Pp A server context is declared with a unique .Ar name , followed by server-specific configuration directives inside curly braces: .Pp .Ic server Ar name Brq ... .Pp .Xr gotwebd 8 is compatible with TLS Server Name Indication (SNI), provided the .Ar name of a server defined in .Nm corresponds to the name of a server defined in .Xr httpd.conf 5 . .Pp The available server configuration directives are as follows: .Bl -tag -width Ds .It Ic custom_css Ar path Set the path to a custom Cascading Style Sheet (CSS) to be used. If this option is not specified then a default style sheet will be used. .It Ic listen on Ar address Ic port Ar number Configure an address and port for incoming FCGI TCP connections. Valid .Ar address arguments are hostnames, IP4 addresses, IPv6 addresses, and network interface names. The .Ar port argument may be number or a service name defined in .Xr services 5 . .Pp May be specified multiple times to build up a list of listening sockets. However, a given combination of address and port may only be used by one server. .Pp If a network interface name is given as .Ar address argument then .Xr gotwebd 8 will obtain the list of addresses on this interface only on startup. Any future changes to the address configuration of the interface will be ignored. .It Ic listen on socket off Disable use of unix socket. .It Ic listen on socket Ar path Set the path to the unix socket used by the server. .It Ic logo Ar path Set the path to an image file containing a logo to be displayed. .It Ic logo_url Ar url Set a hyperlink for the logo. .It Ic max_commits_display Ar number Set the maximum amount of commits displayed per page. .It Ic max_repos Ar number Set the maximum amount of repositories .Xr gotwebd 8 will work with. .It Ic max_repos_display Ar number Set the maximum amount of repositories displayed on the index screen. .It Ic repos_path Ar path Set the path to the directory which contains Git repositories that the server should publish. .It Ic respect_exportok Ar on | off Set whether to display the repository only if it contains the magic .Pa git-daemon-export-ok file. .It Ic show_repo_age Ar on | off Toggle display of last repository modification date. .It Ic show_repo_cloneurl Ar on | off Toggle display of clone URLs for a repository. This requires the creation of a .Pa cloneurl file inside the repository which contains one URL per line. .It Ic show_repo_description Ar on | off Toggle display of the repository description. The .Pa description file in the repository should be updated with an appropriate description. .It Ic show_repo_owner Ar on | off Set whether to display the repository owner. Displaying the owner requires owner information to be added to the .Pa config file in the repository. .Xr gotwebd 8 will parse owner information from either a [gotweb] or a [gitweb] section. For example: .Bd -literal -offset indent [gotweb] owner = "Your Name" .Ed .It Ic site_link Ar string Set the displayed site link name for the index page. .It Ic site_name Ar string Set the displayed site name title. .It Ic site_owner Ar string Set the displayed site owner. .It Ic show_site_owner Ar on | off Toggle display of the site owner. .El .Sh FILES .Bl -tag -width Ds -compact .It Pa /etc/gotwebd.conf Default location of the .Nm configuration file. .El .Sh EXAMPLES These are the currently configurable items for .Xr gotwebd 8 with their default values. .Bd -literal -offset indent # # gotwebd options # all paths relative to /var/www (httpd chroot jail) # prefork 1 server "localhost-unix" { repos_path "/got/public" listen on socket "/run/gotweb.sock" site_name "my public repos" site_owner "Got Owner" site_link "repos" logo "got.png" logo_url "https://gameoftrees.org" # on by default #show_site_owner off #show_repo_owner off #show_repo_age false #show_repo_description no #show_repo_cloneurl off # off by default #respect_exportok on #max_repos 100 #max_repos_display 25 #max_commits_display 50 } # Example server context for FCGI over TCP connections: #server "localhost-tcp" { # repos_path "/got/public" # listen on socket off # listen on 127.0.0.1 port 9000 # listen on ::1 port 9000 #} .Ed .Sh SEE ALSO .Xr got 1 , .Xr httpd.conf 5 , .Xr services 5 , .Xr gotwebd 8 , .Xr httpd 8