.\"
.\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
.\"
.\" 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 port 9090
.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.
.Xr gotwebd 8
runs 3 server processes by default.
.It Ic unix_socket Ar on | off
Controls whether the servers will listen on unix sockets by default.
Listening on unix sockets is the default.
.It Ic unix_socket_name Ar path
Set the path to the default unix socket.
Defaults to
.Pa /var/www/run/gotweb.sock .
.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
The first server defined is used if the requested hostname is not
matched by any server block.
.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 the default style sheet
.Sq gotweb.css
will be used.
.It Ic listen on Ar address Ic port Ar number
Configure an address and port for incoming FastCGI connections.
Valid
.Ar address
arguments are hostnames, IPv4 and IPv6 addresses.
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.
.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.
Defaults to
.Sq got.png .
.It Ic logo_url Ar url
Set a hyperlink for the logo.
Defaults to
.Lk https://gameoftrees.org .
.It Ic max_commits_display Ar number
Set the maximum amount of commits and tags displayed per page.
Defaults to 25.
.It Ic max_repos_display Ar 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.
.It Ic repos_path Ar path
Set the path to the directory which contains Git repositories that
the server should publish.
Defaults to
.Pa /run/gotwebd.sock
under the chroot.
.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.
Disabled by default.
.It Ic show_repo_age Ar on | off
Toggle display of last repository modification date.
Enabled by default.
.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.
Enabled by default.
.It Ic show_repo_description Ar on | off
Toggle display of the repository description.
Enabled by default.
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.
Enabled by default.
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.
Defaults to
.Sq Repos .
.It Ic site_name Ar string
Set the displayed site name title.
Defaults to
.Sq Gotweb .
.It Ic site_owner Ar string
Set the displayed site owner.
Defaults to
.Sq Got Owner .
.It Ic show_site_owner Ar on | off
Toggle display of the site owner.
Enabled by default.
.It Ic summary_commits_display Ar number
The maximum number of commits to show in the summary page.
Defaults to 10.
.It Ic summary_tags_display Ar number
The maximum number of tags to show in the summary page.
Defaults to 3.
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/gotwebd.conf
Default location of the
.Nm
configuration file.
.El
.Sh EXAMPLES
A sample configuration:
.Bd -literal -offset indent
server "localhost" {
	site_name	"my public repos"
	site_owner	"Flan Hacker"
	site_link	"Flan' Projects"
}
.Ed
.Pp
Another example, this time listening on a local port instead of the
implicit
.Ux
socket.
.Bd -literal -offset indent
server "localhost" {
	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