2 a596b957 2022-07-14 tracey .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
4 a596b957 2022-07-14 tracey .\" Permission to use, copy, modify, and distribute this software for any
5 a596b957 2022-07-14 tracey .\" purpose with or without fee is hereby granted, provided that the above
6 a596b957 2022-07-14 tracey .\" copyright notice and this permission notice appear in all copies.
8 a596b957 2022-07-14 tracey .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 a596b957 2022-07-14 tracey .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 a596b957 2022-07-14 tracey .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 a596b957 2022-07-14 tracey .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 a596b957 2022-07-14 tracey .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 a596b957 2022-07-14 tracey .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 a596b957 2022-07-14 tracey .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 a596b957 2022-07-14 tracey .Dd $Mdocdate$
17 59975c69 2022-08-29 stsp .Dt GOTWEBD.CONF 5
20 59975c69 2022-08-29 stsp .Nm gotwebd.conf
21 59975c69 2022-08-29 stsp .Nd gotwebd configuration file
22 a596b957 2022-07-14 tracey .Sh DESCRIPTION
24 a596b957 2022-07-14 tracey is the run-time configuration file for
25 59975c69 2022-08-29 stsp .Xr gotwebd 8 .
27 a596b957 2022-07-14 tracey The file format is line-based, with one configuration directive per line.
28 a596b957 2022-07-14 tracey Any lines beginning with a
30 a596b957 2022-07-14 tracey are treated as comments and ignored.
32 47b307cd 2022-10-02 op Macros can be defined that are later expanded in context.
33 47b307cd 2022-10-02 op Macro names must start with a letter, digit, or underscore, and may
34 47b307cd 2022-10-02 op contain any of those characters, but may not be reserved words.
35 47b307cd 2022-10-02 op Macros are not expanded inside quotes.
37 47b307cd 2022-10-02 op .Bd -literal -offset indent
38 47b307cd 2022-10-02 op lan_addr = "192.168.0.1"
39 f497614d 2023-12-29 op listen on $lan_addr port 9090
42 a596b957 2022-07-14 tracey Paths mentioned in
44 a596b957 2022-07-14 tracey must be relative to
45 a596b957 2022-07-14 tracey .Pa /var/www ,
47 a596b957 2022-07-14 tracey .Xr chroot 2
48 a596b957 2022-07-14 tracey environment of
49 a596b957 2022-07-14 tracey .Xr httpd 8 .
50 a596b957 2022-07-14 tracey .Sh GLOBAL CONFIGURATION
51 0dd80998 2022-08-29 stsp The available global configuration directives are as follows:
52 a596b957 2022-07-14 tracey .Bl -tag -width Ds
53 59975c69 2022-08-29 stsp .It Ic chroot Ar path
54 59975c69 2022-08-29 stsp Set the path to the
55 59975c69 2022-08-29 stsp .Xr chroot 2
56 59975c69 2022-08-29 stsp environment of
57 59975c69 2022-08-29 stsp .Xr httpd 8 .
58 59975c69 2022-08-29 stsp If not specified then
59 59975c69 2022-08-29 stsp .Pa /var/www
60 59975c69 2022-08-29 stsp will be used.
61 d68a7b14 2024-05-20 op .It Ic listen on Ar address Ic port Ar number
62 d68a7b14 2024-05-20 op Configure an address and port for incoming FastCGI connections.
65 d68a7b14 2024-05-20 op arguments are hostnames, IPv4 and IPv6 addresses.
68 d68a7b14 2024-05-20 op argument may be number or a service name defined in
69 d68a7b14 2024-05-20 op .Xr services 5 .
70 d68a7b14 2024-05-20 op May be specified multiple times to build up a list of listening sockets.
71 d68a7b14 2024-05-20 op .It Ic listen on socket Ar path
73 d68a7b14 2024-05-20 op .Ux Ns -domain
74 d68a7b14 2024-05-20 op socket for incoming FastCGI connections.
75 d68a7b14 2024-05-20 op May be specified multiple times to build up a list of listening sockets.
76 0dd80998 2022-08-29 stsp .It Ic prefork Ar number
77 0dd80998 2022-08-29 stsp Run the specified number of server processes.
79 f497614d 2023-12-29 op runs 3 server processes by default.
84 d68a7b14 2024-05-20 op directive is used,
86 d68a7b14 2024-05-20 op will listen on the
87 d68a7b14 2024-05-20 op .Ux Ns -domain
89 d68a7b14 2024-05-20 op .Pa /var/www/run/gotweb.sock .
90 0dd80998 2022-08-29 stsp .Sh SERVER CONFIGURATION
91 0dd80998 2022-08-29 stsp At least one server context must exist for
92 0dd80998 2022-08-29 stsp .Xr gotwebd 8
93 0dd80998 2022-08-29 stsp to function.
94 0dd80998 2022-08-29 stsp In case no server context is defined in the configuration file, a default
95 d68a7b14 2024-05-20 op server context will be used which uses default parameters for all
96 d68a7b14 2024-05-20 op applicable settings.
98 0dd80998 2022-08-29 stsp A server context is declared with a unique
100 0dd80998 2022-08-29 stsp followed by server-specific configuration directives inside curly braces:
102 0dd80998 2022-08-29 stsp .Ic server Ar name Brq ...
104 c8af7691 2023-06-22 op The first server defined is used if the requested hostname is not
105 c8af7691 2023-06-22 op matched by any server block.
107 0dd80998 2022-08-29 stsp The available server configuration directives are as follows:
108 0dd80998 2022-08-29 stsp .Bl -tag -width Ds
109 59975c69 2022-08-29 stsp .It Ic custom_css Ar path
110 59975c69 2022-08-29 stsp Set the path to a custom Cascading Style Sheet (CSS) to be used.
111 f497614d 2023-12-29 op If this option is not specified then the default style sheet
112 f497614d 2023-12-29 op .Sq gotweb.css
113 f497614d 2023-12-29 op will be used.
114 59975c69 2022-08-29 stsp .It Ic logo Ar path
115 a596b957 2022-07-14 tracey Set the path to an image file containing a logo to be displayed.
117 f497614d 2023-12-29 op .Sq got.png .
118 59975c69 2022-08-29 stsp .It Ic logo_url Ar url
119 a596b957 2022-07-14 tracey Set a hyperlink for the logo.
121 f497614d 2023-12-29 op .Lk https://gameoftrees.org .
122 59975c69 2022-08-29 stsp .It Ic max_commits_display Ar number
123 f497614d 2023-12-29 op Set the maximum amount of commits and tags displayed per page.
124 f497614d 2023-12-29 op Defaults to 25.
125 59975c69 2022-08-29 stsp .It Ic max_repos_display Ar number
126 a596b957 2022-07-14 tracey Set the maximum amount of repositories displayed on the index screen.
127 f497614d 2023-12-29 op Defaults to 25.
128 f497614d 2023-12-29 op Set to zero to show all the repositories without pagination.
129 59975c69 2022-08-29 stsp .It Ic repos_path Ar path
130 59975c69 2022-08-29 stsp Set the path to the directory which contains Git repositories that
131 0dd80998 2022-08-29 stsp the server should publish.
133 f497614d 2023-12-29 op .Pa /run/gotwebd.sock
134 f497614d 2023-12-29 op under the chroot.
135 d5996b9e 2022-10-31 landry .It Ic respect_exportok Ar on | off
136 d5996b9e 2022-10-31 landry Set whether to display the repository only if it contains the magic
137 d5996b9e 2022-10-31 landry .Pa git-daemon-export-ok
139 f497614d 2023-12-29 op Disabled by default.
140 59975c69 2022-08-29 stsp .It Ic show_repo_age Ar on | off
141 a596b957 2022-07-14 tracey Toggle display of last repository modification date.
142 f497614d 2023-12-29 op Enabled by default.
143 59975c69 2022-08-29 stsp .It Ic show_repo_cloneurl Ar on | off
144 a596b957 2022-07-14 tracey Toggle display of clone URLs for a repository.
145 a596b957 2022-07-14 tracey This requires the creation of a
146 a596b957 2022-07-14 tracey .Pa cloneurl
147 a596b957 2022-07-14 tracey file inside the repository which contains one URL per line.
148 f497614d 2023-12-29 op Enabled by default.
149 59975c69 2022-08-29 stsp .It Ic show_repo_description Ar on | off
150 a596b957 2022-07-14 tracey Toggle display of the repository description.
151 f497614d 2023-12-29 op Enabled by default.
153 a596b957 2022-07-14 tracey .Pa description
154 a596b957 2022-07-14 tracey file in the repository should be updated with an appropriate description.
155 59975c69 2022-08-29 stsp .It Ic show_repo_owner Ar on | off
156 a596b957 2022-07-14 tracey Set whether to display the repository owner.
157 f497614d 2023-12-29 op Enabled by default.
158 a596b957 2022-07-14 tracey Displaying the owner requires owner information to be added to the
159 a596b957 2022-07-14 tracey .Pa config
160 a596b957 2022-07-14 tracey file in the repository.
161 59975c69 2022-08-29 stsp .Xr gotwebd 8
162 a596b957 2022-07-14 tracey will parse owner information from either a [gotweb] or a [gitweb] section.
163 a596b957 2022-07-14 tracey For example:
164 a596b957 2022-07-14 tracey .Bd -literal -offset indent
166 a596b957 2022-07-14 tracey owner = "Your Name"
168 59975c69 2022-08-29 stsp .It Ic site_link Ar string
169 a596b957 2022-07-14 tracey Set the displayed site link name for the index page.
172 59975c69 2022-08-29 stsp .It Ic site_name Ar string
173 a596b957 2022-07-14 tracey Set the displayed site name title.
176 59975c69 2022-08-29 stsp .It Ic site_owner Ar string
177 a596b957 2022-07-14 tracey Set the displayed site owner.
179 f497614d 2023-12-29 op .Sq Got Owner .
180 59975c69 2022-08-29 stsp .It Ic show_site_owner Ar on | off
181 a596b957 2022-07-14 tracey Toggle display of the site owner.
182 f497614d 2023-12-29 op Enabled by default.
183 8762929a 2023-12-29 op .It Ic summary_commits_display Ar number
184 8762929a 2023-12-29 op The maximum number of commits to show in the summary page.
185 f497614d 2023-12-29 op Defaults to 10.
186 8762929a 2023-12-29 op .It Ic summary_tags_display Ar number
187 8762929a 2023-12-29 op The maximum number of tags to show in the summary page.
188 f497614d 2023-12-29 op Defaults to 3.
191 d375d894 2022-11-14 op .Bl -tag -width Ds -compact
192 d375d894 2022-11-14 op .It Pa /etc/gotwebd.conf
193 d375d894 2022-11-14 op Default location of the
195 d375d894 2022-11-14 op configuration file.
196 c6458e88 2024-05-20 op .It Pa /var/www/run/gotweb.sock
197 c6458e88 2024-05-20 op Default location for the
198 c6458e88 2024-05-20 op .Xr gotwebd 8
199 c6458e88 2024-05-20 op listening socket.
201 a596b957 2022-07-14 tracey .Sh EXAMPLES
202 f497614d 2023-12-29 op A sample configuration:
203 a596b957 2022-07-14 tracey .Bd -literal -offset indent
204 f497614d 2023-12-29 op server "localhost" {
205 f497614d 2023-12-29 op site_name "my public repos"
206 f497614d 2023-12-29 op site_owner "Flan Hacker"
207 f497614d 2023-12-29 op site_link "Flan' Projects"
211 f497614d 2023-12-29 op Another example, this time listening on a local port instead of the
215 f497614d 2023-12-29 op .Bd -literal -offset indent
216 d68a7b14 2024-05-20 op listen on 127.0.0.1 port 9000
217 d68a7b14 2024-05-20 op listen on ::1 port 9000
219 f497614d 2023-12-29 op server "localhost" {
220 d68a7b14 2024-05-20 op site_name "my public repos"
223 a596b957 2022-07-14 tracey .Sh SEE ALSO
224 a596b957 2022-07-14 tracey .Xr got 1 ,
225 e0e2a861 2022-08-30 stsp .Xr httpd.conf 5 ,
226 0dd80998 2022-08-29 stsp .Xr services 5 ,
227 e0e2a861 2022-08-30 stsp .Xr gotwebd 8 ,
228 e0e2a861 2022-08-30 stsp .Xr httpd 8
