Blame


1 a596b957 2022-07-14 tracey .\"
2 a596b957 2022-07-14 tracey .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
3 a596b957 2022-07-14 tracey .\"
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.
7 a596b957 2022-07-14 tracey .\"
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.
15 a596b957 2022-07-14 tracey .\"
16 a596b957 2022-07-14 tracey .Dd $Mdocdate$
17 59975c69 2022-08-29 stsp .Dt GOTWEBD.CONF 5
18 a596b957 2022-07-14 tracey .Os
19 a596b957 2022-07-14 tracey .Sh NAME
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
23 a596b957 2022-07-14 tracey .Nm
24 a596b957 2022-07-14 tracey is the run-time configuration file for
25 59975c69 2022-08-29 stsp .Xr gotwebd 8 .
26 a596b957 2022-07-14 tracey .Pp
27 a596b957 2022-07-14 tracey The file format is line-based, with one configuration directive per line.
28 10d38691 2024-08-06 op Comments can be put anywhere in the file using a hash mark
29 10d38691 2024-08-06 op .Pq Sq # ,
30 10d38691 2024-08-06 op and extend to the end of the current line.
31 10d38691 2024-08-06 op Arguments names not beginning with a letter, digit or underscore,
32 10d38691 2024-08-06 op as well as reserved words
33 10d38691 2024-08-06 op .Pq such as Ic listen , Ic server No or Ic user ,
34 10d38691 2024-08-06 op must be quoted.
35 10d38691 2024-08-06 op Arguments containing whitespace should be surrounded by double quotes
36 10d38691 2024-08-06 op .Pq \&" .
37 a596b957 2022-07-14 tracey .Pp
38 47b307cd 2022-10-02 op Macros can be defined that are later expanded in context.
39 47b307cd 2022-10-02 op Macro names must start with a letter, digit, or underscore, and may
40 47b307cd 2022-10-02 op contain any of those characters, but may not be reserved words.
41 47b307cd 2022-10-02 op Macros are not expanded inside quotes.
42 47b307cd 2022-10-02 op For example:
43 47b307cd 2022-10-02 op .Bd -literal -offset indent
44 47b307cd 2022-10-02 op lan_addr = "192.168.0.1"
45 f497614d 2023-12-29 op listen on $lan_addr port 9090
46 47b307cd 2022-10-02 op .Ed
47 47b307cd 2022-10-02 op .Pp
48 a596b957 2022-07-14 tracey Paths mentioned in
49 a596b957 2022-07-14 tracey .Nm
50 a596b957 2022-07-14 tracey must be relative to
51 a596b957 2022-07-14 tracey .Pa /var/www ,
52 a596b957 2022-07-14 tracey the
53 a596b957 2022-07-14 tracey .Xr chroot 2
54 a596b957 2022-07-14 tracey environment of
55 a596b957 2022-07-14 tracey .Xr httpd 8 .
56 a596b957 2022-07-14 tracey .Sh GLOBAL CONFIGURATION
57 0dd80998 2022-08-29 stsp The available global configuration directives are as follows:
58 a596b957 2022-07-14 tracey .Bl -tag -width Ds
59 59975c69 2022-08-29 stsp .It Ic chroot Ar path
60 59975c69 2022-08-29 stsp Set the path to the
61 59975c69 2022-08-29 stsp .Xr chroot 2
62 59975c69 2022-08-29 stsp environment of
63 59975c69 2022-08-29 stsp .Xr httpd 8 .
64 9bc2ee80 2024-05-21 op If not specified, it defaults to
65 9bc2ee80 2024-05-21 op .Pa /var/www ,
66 9bc2ee80 2024-05-21 op the home directory of the www user.
67 d68a7b14 2024-05-20 op .It Ic listen on Ar address Ic port Ar number
68 d68a7b14 2024-05-20 op Configure an address and port for incoming FastCGI connections.
69 d68a7b14 2024-05-20 op Valid
70 d68a7b14 2024-05-20 op .Ar address
71 d68a7b14 2024-05-20 op arguments are hostnames, IPv4 and IPv6 addresses.
72 d68a7b14 2024-05-20 op The
73 d68a7b14 2024-05-20 op .Ar port
74 d68a7b14 2024-05-20 op argument may be number or a service name defined in
75 d68a7b14 2024-05-20 op .Xr services 5 .
76 d68a7b14 2024-05-20 op May be specified multiple times to build up a list of listening sockets.
77 d68a7b14 2024-05-20 op .It Ic listen on socket Ar path
78 d68a7b14 2024-05-20 op Configure a
79 d68a7b14 2024-05-20 op .Ux Ns -domain
80 d68a7b14 2024-05-20 op socket for incoming FastCGI connections.
81 d68a7b14 2024-05-20 op May be specified multiple times to build up a list of listening sockets.
82 0dd80998 2022-08-29 stsp .It Ic prefork Ar number
83 0dd80998 2022-08-29 stsp Run the specified number of server processes.
84 f497614d 2023-12-29 op .Xr gotwebd 8
85 f497614d 2023-12-29 op runs 3 server processes by default.
86 9bc2ee80 2024-05-21 op .It Ic user Ar user
87 9bc2ee80 2024-05-21 op Set the
88 9bc2ee80 2024-05-21 op .Ar user
89 9bc2ee80 2024-05-21 op which will run
90 9bc2ee80 2024-05-21 op .Xr gotwebd 8 .
91 9bc2ee80 2024-05-21 op If not specified, the user www will be used.
92 0dd80998 2022-08-29 stsp .El
93 d68a7b14 2024-05-20 op .Pp
94 d68a7b14 2024-05-20 op If no
95 d68a7b14 2024-05-20 op .Ic listen
96 d68a7b14 2024-05-20 op directive is used,
97 d68a7b14 2024-05-20 op .Xr gotwebd 8
98 d68a7b14 2024-05-20 op will listen on the
99 d68a7b14 2024-05-20 op .Ux Ns -domain
100 d68a7b14 2024-05-20 op socket at
101 d68a7b14 2024-05-20 op .Pa /var/www/run/gotweb.sock .
102 0dd80998 2022-08-29 stsp .Sh SERVER CONFIGURATION
103 0dd80998 2022-08-29 stsp At least one server context must exist for
104 0dd80998 2022-08-29 stsp .Xr gotwebd 8
105 0dd80998 2022-08-29 stsp to function.
106 0dd80998 2022-08-29 stsp In case no server context is defined in the configuration file, a default
107 d68a7b14 2024-05-20 op server context will be used which uses default parameters for all
108 d68a7b14 2024-05-20 op applicable settings.
109 0dd80998 2022-08-29 stsp .Pp
110 0dd80998 2022-08-29 stsp A server context is declared with a unique
111 7e047b0e 2022-08-30 stsp .Ar name ,
112 0dd80998 2022-08-29 stsp followed by server-specific configuration directives inside curly braces:
113 0dd80998 2022-08-29 stsp .Pp
114 0dd80998 2022-08-29 stsp .Ic server Ar name Brq ...
115 0dd80998 2022-08-29 stsp .Pp
116 c8af7691 2023-06-22 op The first server defined is used if the requested hostname is not
117 c8af7691 2023-06-22 op matched by any server block.
118 f21aef01 2022-08-30 stsp .Pp
119 0dd80998 2022-08-29 stsp The available server configuration directives are as follows:
120 0dd80998 2022-08-29 stsp .Bl -tag -width Ds
121 59975c69 2022-08-29 stsp .It Ic custom_css Ar path
122 59975c69 2022-08-29 stsp Set the path to a custom Cascading Style Sheet (CSS) to be used.
123 f497614d 2023-12-29 op If this option is not specified then the default style sheet
124 f497614d 2023-12-29 op .Sq gotweb.css
125 f497614d 2023-12-29 op will be used.
126 59975c69 2022-08-29 stsp .It Ic logo Ar path
127 a596b957 2022-07-14 tracey Set the path to an image file containing a logo to be displayed.
128 f497614d 2023-12-29 op Defaults to
129 f497614d 2023-12-29 op .Sq got.png .
130 59975c69 2022-08-29 stsp .It Ic logo_url Ar url
131 a596b957 2022-07-14 tracey Set a hyperlink for the logo.
132 f497614d 2023-12-29 op Defaults to
133 f497614d 2023-12-29 op .Lk https://gameoftrees.org .
134 59975c69 2022-08-29 stsp .It Ic max_commits_display Ar number
135 f497614d 2023-12-29 op Set the maximum amount of commits and tags displayed per page.
136 f497614d 2023-12-29 op Defaults to 25.
137 59975c69 2022-08-29 stsp .It Ic max_repos_display Ar number
138 a596b957 2022-07-14 tracey Set the maximum amount of repositories displayed on the index screen.
139 f497614d 2023-12-29 op Defaults to 25.
140 f497614d 2023-12-29 op Set to zero to show all the repositories without pagination.
141 59975c69 2022-08-29 stsp .It Ic repos_path Ar path
142 59975c69 2022-08-29 stsp Set the path to the directory which contains Git repositories that
143 0dd80998 2022-08-29 stsp the server should publish.
144 f497614d 2023-12-29 op Defaults to
145 af206a19 2024-06-25 stsp .Pa /got/public
146 f497614d 2023-12-29 op under the chroot.
147 d5996b9e 2022-10-31 landry .It Ic respect_exportok Ar on | off
148 d5996b9e 2022-10-31 landry Set whether to display the repository only if it contains the magic
149 d5996b9e 2022-10-31 landry .Pa git-daemon-export-ok
150 d5996b9e 2022-10-31 landry file.
151 f497614d 2023-12-29 op Disabled by default.
152 59975c69 2022-08-29 stsp .It Ic show_repo_age Ar on | off
153 a596b957 2022-07-14 tracey Toggle display of last repository modification date.
154 f497614d 2023-12-29 op Enabled by default.
155 59975c69 2022-08-29 stsp .It Ic show_repo_cloneurl Ar on | off
156 a596b957 2022-07-14 tracey Toggle display of clone URLs for a repository.
157 a596b957 2022-07-14 tracey This requires the creation of a
158 a596b957 2022-07-14 tracey .Pa cloneurl
159 a596b957 2022-07-14 tracey file inside the repository which contains one URL per line.
160 f497614d 2023-12-29 op Enabled by default.
161 59975c69 2022-08-29 stsp .It Ic show_repo_description Ar on | off
162 a596b957 2022-07-14 tracey Toggle display of the repository description.
163 f497614d 2023-12-29 op Enabled by default.
164 a596b957 2022-07-14 tracey The
165 a596b957 2022-07-14 tracey .Pa description
166 a596b957 2022-07-14 tracey file in the repository should be updated with an appropriate description.
167 59975c69 2022-08-29 stsp .It Ic show_repo_owner Ar on | off
168 a596b957 2022-07-14 tracey Set whether to display the repository owner.
169 f497614d 2023-12-29 op Enabled by default.
170 9e111e2e 2024-07-29 op This requires the creation of an
171 9e111e2e 2024-07-29 op .Pa owner
172 9e111e2e 2024-07-29 op file in the repository or adding an
173 9e111e2e 2024-07-29 op .Sq owner
174 9e111e2e 2024-07-29 op field under the [gotweb] or [gitweb] section in the
175 a596b957 2022-07-14 tracey .Pa config
176 9e111e2e 2024-07-29 op file inside the repository.
177 a596b957 2022-07-14 tracey For example:
178 a596b957 2022-07-14 tracey .Bd -literal -offset indent
179 a596b957 2022-07-14 tracey [gotweb]
180 a596b957 2022-07-14 tracey owner = "Your Name"
181 a596b957 2022-07-14 tracey .Ed
182 9e111e2e 2024-07-29 op .Pp
183 9e111e2e 2024-07-29 op The
184 9e111e2e 2024-07-29 op .Pa owner
185 9e111e2e 2024-07-29 op file has priority over the
186 9e111e2e 2024-07-29 op .Pa config
187 9e111e2e 2024-07-29 op if present.
188 59975c69 2022-08-29 stsp .It Ic site_link Ar string
189 a596b957 2022-07-14 tracey Set the displayed site link name for the index page.
190 f497614d 2023-12-29 op Defaults to
191 f497614d 2023-12-29 op .Sq Repos .
192 59975c69 2022-08-29 stsp .It Ic site_name Ar string
193 a596b957 2022-07-14 tracey Set the displayed site name title.
194 f497614d 2023-12-29 op Defaults to
195 f497614d 2023-12-29 op .Sq Gotweb .
196 59975c69 2022-08-29 stsp .It Ic site_owner Ar string
197 a596b957 2022-07-14 tracey Set the displayed site owner.
198 f497614d 2023-12-29 op Defaults to
199 f497614d 2023-12-29 op .Sq Got Owner .
200 59975c69 2022-08-29 stsp .It Ic show_site_owner Ar on | off
201 a596b957 2022-07-14 tracey Toggle display of the site owner.
202 f497614d 2023-12-29 op Enabled by default.
203 8762929a 2023-12-29 op .It Ic summary_commits_display Ar number
204 8762929a 2023-12-29 op The maximum number of commits to show in the summary page.
205 f497614d 2023-12-29 op Defaults to 10.
206 8762929a 2023-12-29 op .It Ic summary_tags_display Ar number
207 8762929a 2023-12-29 op The maximum number of tags to show in the summary page.
208 f497614d 2023-12-29 op Defaults to 3.
209 0dd80998 2022-08-29 stsp .El
210 d375d894 2022-11-14 op .Sh FILES
211 d375d894 2022-11-14 op .Bl -tag -width Ds -compact
212 d375d894 2022-11-14 op .It Pa /etc/gotwebd.conf
213 d375d894 2022-11-14 op Default location of the
214 d375d894 2022-11-14 op .Nm
215 d375d894 2022-11-14 op configuration file.
216 c6458e88 2024-05-20 op .It Pa /var/www/run/gotweb.sock
217 c6458e88 2024-05-20 op Default location for the
218 c6458e88 2024-05-20 op .Xr gotwebd 8
219 c6458e88 2024-05-20 op listening socket.
220 d375d894 2022-11-14 op .El
221 a596b957 2022-07-14 tracey .Sh EXAMPLES
222 f497614d 2023-12-29 op A sample configuration:
223 a596b957 2022-07-14 tracey .Bd -literal -offset indent
224 f497614d 2023-12-29 op server "localhost" {
225 f497614d 2023-12-29 op site_name "my public repos"
226 f497614d 2023-12-29 op site_owner "Flan Hacker"
227 f497614d 2023-12-29 op site_link "Flan' Projects"
228 59975c69 2022-08-29 stsp }
229 a596b957 2022-07-14 tracey .Ed
230 f497614d 2023-12-29 op .Pp
231 f497614d 2023-12-29 op Another example, this time listening on a local port instead of the
232 f497614d 2023-12-29 op implicit
233 f497614d 2023-12-29 op .Ux
234 f497614d 2023-12-29 op socket.
235 f497614d 2023-12-29 op .Bd -literal -offset indent
236 d68a7b14 2024-05-20 op listen on 127.0.0.1 port 9000
237 d68a7b14 2024-05-20 op listen on ::1 port 9000
238 d68a7b14 2024-05-20 op
239 f497614d 2023-12-29 op server "localhost" {
240 d68a7b14 2024-05-20 op site_name "my public repos"
241 f497614d 2023-12-29 op }
242 f497614d 2023-12-29 op .Ed
243 a596b957 2022-07-14 tracey .Sh SEE ALSO
244 a596b957 2022-07-14 tracey .Xr got 1 ,
245 e0e2a861 2022-08-30 stsp .Xr httpd.conf 5 ,
246 0dd80998 2022-08-29 stsp .Xr services 5 ,
247 e0e2a861 2022-08-30 stsp .Xr gotwebd 8 ,
248 e0e2a861 2022-08-30 stsp .Xr httpd 8