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.
32 Macros can be defined that are later expanded in context.
33 Macro names must start with a letter, digit, or underscore, and may
34 contain any of those characters, but may not be reserved words.
35 Macros are not expanded inside quotes.
37 .Bd -literal -offset indent
38 lan_addr = "192.168.0.1"
39 listen on $lan_addr port 9090
50 .Sh GLOBAL CONFIGURATION
51 The available global configuration directives are as follows:
58 If not specified, it defaults to
60 the home directory of the www user.
61 .It Ic listen on Ar address Ic port Ar number
62 Configure an address and port for incoming FastCGI connections.
65 arguments are hostnames, IPv4 and IPv6 addresses.
68 argument may be number or a service name defined in
70 May be specified multiple times to build up a list of listening sockets.
71 .It Ic listen on socket Ar path
74 socket for incoming FastCGI connections.
75 May be specified multiple times to build up a list of listening sockets.
76 .It Ic prefork Ar number
77 Run the specified number of server processes.
79 runs 3 server processes by default.
85 If not specified, the user www will be used.
95 .Pa /var/www/run/gotweb.sock .
96 .Sh SERVER CONFIGURATION
97 At least one server context must exist for
100 In case no server context is defined in the configuration file, a default
101 server context will be used which uses default parameters for all
104 A server context is declared with a unique
106 followed by server-specific configuration directives inside curly braces:
108 .Ic server Ar name Brq ...
110 The first server defined is used if the requested hostname is not
111 matched by any server block.
113 The available server configuration directives are as follows:
115 .It Ic custom_css Ar path
116 Set the path to a custom Cascading Style Sheet (CSS) to be used.
117 If this option is not specified then the default style sheet
121 Set the path to an image file containing a logo to be displayed.
124 .It Ic logo_url Ar url
125 Set a hyperlink for the logo.
127 .Lk https://gameoftrees.org .
128 .It Ic max_commits_display Ar number
129 Set the maximum amount of commits and tags displayed per page.
131 .It Ic max_repos_display Ar number
132 Set the maximum amount of repositories displayed on the index screen.
134 Set to zero to show all the repositories without pagination.
135 .It Ic repos_path Ar path
136 Set the path to the directory which contains Git repositories that
137 the server should publish.
139 .Pa /run/gotwebd.sock
141 .It Ic respect_exportok Ar on | off
142 Set whether to display the repository only if it contains the magic
143 .Pa git-daemon-export-ok
146 .It Ic show_repo_age Ar on | off
147 Toggle display of last repository modification date.
149 .It Ic show_repo_cloneurl Ar on | off
150 Toggle display of clone URLs for a repository.
151 This requires the creation of a
153 file inside the repository which contains one URL per line.
155 .It Ic show_repo_description Ar on | off
156 Toggle display of the repository description.
160 file in the repository should be updated with an appropriate description.
161 .It Ic show_repo_owner Ar on | off
162 Set whether to display the repository owner.
164 Displaying the owner requires owner information to be added to the
166 file in the repository.
168 will parse owner information from either a [gotweb] or a [gitweb] section.
170 .Bd -literal -offset indent
174 .It Ic site_link Ar string
175 Set the displayed site link name for the index page.
178 .It Ic site_name Ar string
179 Set the displayed site name title.
182 .It Ic site_owner Ar string
183 Set the displayed site owner.
186 .It Ic show_site_owner Ar on | off
187 Toggle display of the site owner.
189 .It Ic summary_commits_display Ar number
190 The maximum number of commits to show in the summary page.
192 .It Ic summary_tags_display Ar number
193 The maximum number of tags to show in the summary page.
197 .Bl -tag -width Ds -compact
198 .It Pa /etc/gotwebd.conf
199 Default location of the
202 .It Pa /var/www/run/gotweb.sock
203 Default location for the
208 A sample configuration:
209 .Bd -literal -offset indent
211 site_name "my public repos"
212 site_owner "Flan Hacker"
213 site_link "Flan' Projects"
217 Another example, this time listening on a local port instead of the
221 .Bd -literal -offset indent
222 listen on 127.0.0.1 port 9000
223 listen on ::1 port 9000
226 site_name "my public repos"
