2 .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .Nd gotwebd configuration file
24 is the run-time configuration file for
27 The file format is line-based, with one configuration directive per line.
28 Any lines beginning with a
30 are treated as comments and ignored.
40 .Sh GLOBAL CONFIGURATION
41 The available global configuration directives are as follows:
52 .It Ic prefork Ar number
53 Run the specified number of server processes.
54 .It Ic fgci_socket Ar on | off
55 Controls whether the server will listen on FCGI TCP sockets by default.
56 .It Ic unix_socket Ar on | off
57 Controls whether the servers will listen on unix sockets by default.
58 .It Ic unix_socket_name Ar path
59 Set the path to the default unix socket.
61 .Sh SERVER CONFIGURATION
62 At least one server context must exist for
65 In case no server context is defined in the configuration file, a default
66 server context will be used, which listens on a unix socket at
67 .Pa /var/www/run/gotweb.sock
68 and uses default parameters for all applicable settings.
70 A server context is declared with a unique
72 followed by server-specific configuration directives inside curly braces:
74 .Ic server Ar name Brq ...
77 is compatible with TLS Server Name Indication (SNI), provided the
79 of a server defined in
81 corresponds to the name of a server defined in
84 The available server configuration directives are as follows:
86 .It Ic custom_css Ar path
87 Set the path to a custom Cascading Style Sheet (CSS) to be used.
88 If this option is not specified then a default style sheet will be used.
89 .It Ic fgci_socket Ar on | off
90 Enable or disable listening on FCGI TCP sockets.
91 .It Ic listen on Ar address Ic port Ar number
92 Configure an address and port for incoming FCGI TCP connections.
95 arguments are hostnames, IP4 addresses, IPv6 addresses, and network
99 argument may be number or a service name defined in
102 May be specified multiple times to build up a list of listening sockets.
103 However, a given combination of address and port may only be used by
106 Set the path to an image file containing a logo to be displayed.
107 .It Ic logo_url Ar url
108 Set a hyperlink for the logo.
109 .It Ic max_commits_display Ar number
110 Set the maximum amount of commits displayed per page.
111 .It Ic max_repos Ar number
112 Set the maximum amount of repositories
115 .It Ic max_repos_display Ar number
116 Set the maximum amount of repositories displayed on the index screen.
117 .It Ic repos_path Ar path
118 Set the path to the directory which contains Git repositories that
119 the server should publish.
120 .It Ic show_repo_age Ar on | off
121 Toggle display of last repository modification date.
122 .It Ic show_repo_cloneurl Ar on | off
123 Toggle display of clone URLs for a repository.
124 This requires the creation of a
126 file inside the repository which contains one URL per line.
127 .It Ic show_repo_description Ar on | off
128 Toggle display of the repository description.
131 file in the repository should be updated with an appropriate description.
132 .It Ic show_repo_owner Ar on | off
133 Set whether to display the repository owner.
134 Displaying the owner requires owner information to be added to the
136 file in the repository.
138 will parse owner information from either a [gotweb] or a [gitweb] section.
140 .Bd -literal -offset indent
144 .It Ic site_link Ar string
145 Set the displayed site link name for the index page.
146 .It Ic site_name Ar string
147 Set the displayed site name title.
148 .It Ic site_owner Ar string
149 Set the displayed site owner.
150 .It Ic show_site_owner Ar on | off
151 Toggle display of the site owner.
152 .It Ic unix_socket Ar on | off
153 Enable or disable use of unix sockets.
154 .It Ic unix_socket_name Ar path
155 Set the path to the unix socket used by the server.
158 These are the currently configurable items for
160 with their default values.
161 .Bd -literal -offset indent
164 # all paths relative to /var/www (httpd chroot jail)
169 server "localhost-unix" {
170 repos_path "/got/public"
171 unix_socket_name "/run/gotweb.sock"
173 got_site_name "my public repos"
174 got_site_owner "Got Owner"
175 got_site_link "repos"
178 logo_url "https://gameoftrees.org"
184 #show_repo_description no
185 #show_repo_cloneurl off
188 #max_repos_display 25
189 #max_commits_display 50
192 # Example server context for FCGI over TCP connections:
193 #server "localhost-tcp" {
194 # repos_path "/got/public"
197 # listen on 127.0.0.1 port 9000
198 # listen on ::1 port 9000
202 .Bl -tag -width Ds -compact
203 .It Pa /var/www/etc/gotweb.conf
