1 .\"
2 .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
3 .\"
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.
7 .\"
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.
15 .\"
16 .Dd $Mdocdate$
17 .Dt GOTWEBD.CONF 5
18 .Os
19 .Sh NAME
20 .Nm gotwebd.conf
21 .Nd gotwebd configuration file
22 .Sh DESCRIPTION
23 .Nm
24 is the run-time configuration file for
25 .Xr gotwebd 8 .
26 .Pp
27 The file format is line-based, with one configuration directive per line.
28 Any lines beginning with a
29 .Sq #
30 are treated as comments and ignored.
31 .Pp
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.
36 For example:
37 .Bd -literal -offset indent
38 lan_addr = "192.168.0.1"
39 listen on $lan_addr
40 .Ed
41 .Pp
42 Paths mentioned in
43 .Nm
44 must be relative to
45 .Pa /var/www ,
46 the
47 .Xr chroot 2
48 environment of
49 .Xr httpd 8 .
50 .Sh GLOBAL CONFIGURATION
51 The available global configuration directives are as follows:
52 .Bl -tag -width Ds
53 .It Ic chroot Ar path
54 Set the path to the
55 .Xr chroot 2
56 environment of
57 .Xr httpd 8 .
58 If not specified then
59 .Pa /var/www
60 will be used.
61 .It Ic prefork Ar number
62 Run the specified number of server processes.
63 .It Ic unix_socket Ar on | off
64 Controls whether the servers will listen on unix sockets by default.
65 .It Ic unix_socket_name Ar path
66 Set the path to the default unix socket.
67 .El
68 .Sh SERVER CONFIGURATION
69 At least one server context must exist for
70 .Xr gotwebd 8
71 to function.
72 In case no server context is defined in the configuration file, a default
73 server context will be used, which listens on a unix socket at
74 .Pa /var/www/run/gotweb.sock
75 and uses default parameters for all applicable settings.
76 .Pp
77 A server context is declared with a unique
78 .Ar name ,
79 followed by server-specific configuration directives inside curly braces:
80 .Pp
81 .Ic server Ar name Brq ...
82 .Pp
83 .Xr gotwebd 8
84 is compatible with TLS Server Name Indication (SNI), provided the
85 .Ar name
86 of a server defined in
87 .Nm
88 corresponds to the name of a server defined in
89 .Xr httpd.conf 5 .
90 .Pp
91 The available server configuration directives are as follows:
92 .Bl -tag -width Ds
93 .It Ic custom_css Ar path
94 Set the path to a custom Cascading Style Sheet (CSS) to be used.
95 If this option is not specified then a default style sheet will be used.
96 .It Ic listen on Ar address Ic port Ar number
97 Configure an address and port for incoming FCGI TCP connections.
98 Valid
99 .Ar address
100 arguments are hostnames, IP4 addresses, IPv6 addresses, and network
101 interface names.
102 The
103 .Ar port
104 argument may be number or a service name defined in
105 .Xr services 5 .
106 .Pp
107 May be specified multiple times to build up a list of listening sockets.
108 However, a given combination of address and port may only be used by
109 one server.
110 .Pp
111 If a network interface name is given as
112 .Ar address
113 argument then
114 .Xr gotwebd 8
115 will obtain the list of addresses on this interface only on startup.
116 Any future changes to the address configuration of the interface will
117 be ignored.
118 .It Ic logo Ar path
119 Set the path to an image file containing a logo to be displayed.
120 .It Ic logo_url Ar url
121 Set a hyperlink for the logo.
122 .It Ic max_commits_display Ar number
123 Set the maximum amount of commits displayed per page.
124 .It Ic max_repos Ar number
125 Set the maximum amount of repositories
126 .Xr gotwebd 8
127 will work with.
128 .It Ic max_repos_display Ar number
129 Set the maximum amount of repositories displayed on the index screen.
130 .It Ic repos_path Ar path
131 Set the path to the directory which contains Git repositories that
132 the server should publish.
133 .It Ic respect_exportok Ar on | off
134 Set whether to display the repository only if it contains the magic
135 .Pa git-daemon-export-ok
136 file.
137 .It Ic show_repo_age Ar on | off
138 Toggle display of last repository modification date.
139 .It Ic show_repo_cloneurl Ar on | off
140 Toggle display of clone URLs for a repository.
141 This requires the creation of a
142 .Pa cloneurl
143 file inside the repository which contains one URL per line.
144 .It Ic show_repo_description Ar on | off
145 Toggle display of the repository description.
146 The
147 .Pa description
148 file in the repository should be updated with an appropriate description.
149 .It Ic show_repo_owner Ar on | off
150 Set whether to display the repository owner.
151 Displaying the owner requires owner information to be added to the
152 .Pa config
153 file in the repository.
154 .Xr gotwebd 8
155 will parse owner information from either a [gotweb] or a [gitweb] section.
156 For example:
157 .Bd -literal -offset indent
158 [gotweb]
159 owner = "Your Name"
160 .Ed
161 .It Ic site_link Ar string
162 Set the displayed site link name for the index page.
163 .It Ic site_name Ar string
164 Set the displayed site name title.
165 .It Ic site_owner Ar string
166 Set the displayed site owner.
167 .It Ic show_site_owner Ar on | off
168 Toggle display of the site owner.
169 .It Ic unix_socket Ar on | off
170 Enable or disable use of unix sockets.
171 .It Ic unix_socket_name Ar path
172 Set the path to the unix socket used by the server.
173 .El
174 .Sh EXAMPLES
175 These are the currently configurable items for
176 .Xr gotwebd 8
177 with their default values.
178 .Bd -literal -offset indent
179 #
180 # gotwebd options
181 # all paths relative to /var/www (httpd chroot jail)
182 #
183 
184 prefork 1
185 
186 server "localhost-unix" {
187 	repos_path "/got/public"
188 	unix_socket_name "/run/gotweb.sock"
189 
190 	got_site_name   "my public repos"
191 	got_site_owner   "Got Owner"
192 	got_site_link   "repos"
193 
194 	logo   "got.png"
195 	logo_url   "https://gameoftrees.org"
196 
197 	# on by default
198 	#show_site_owner  off
199 	#show_repo_owner  off
200 	#show_repo_age  false
201 	#show_repo_description no
202 	#show_repo_cloneurl  off
203 	# off by default
204 	#respect_exportok  on
205 
206 	#max_repos   100
207 	#max_repos_display  25
208 	#max_commits_display  50
209 }
210 
211 # Example server context for FCGI over TCP connections:
212 #server "localhost-tcp" {
213 #	repos_path "/got/public"
214 #	unix_socket		off
215 #	listen on 127.0.0.1 port 9000
216 #	listen on ::1 port 9000
217 #}
218 .Ed
219 .Sh FILES
220 .Bl -tag -width Ds -compact
221 .It Pa /etc/gotwebd.conf
222 Default location of the
223 .Nm
224 configuration file.
225 .El
226 .Sh SEE ALSO
227 .Xr got 1 ,
228 .Xr httpd.conf 5 ,
229 .Xr services 5 ,
230 .Xr gotwebd 8 ,
231 .Xr httpd 8