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 port 9090
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 .Xr gotwebd 8
64 runs 3 server processes by default.
65 .It Ic unix_socket_name Ar path
66 Set the path to the default unix socket.
67 Defaults to
68 .Pa /var/www/run/gotweb.sock .
69 .El
70 .Sh SERVER CONFIGURATION
71 At least one server context must exist for
72 .Xr gotwebd 8
73 to function.
74 In case no server context is defined in the configuration file, a default
75 server context will be used, which listens on a unix socket at
76 .Pa /var/www/run/gotweb.sock
77 and uses default parameters for all applicable settings.
78 .Pp
79 A server context is declared with a unique
80 .Ar name ,
81 followed by server-specific configuration directives inside curly braces:
82 .Pp
83 .Ic server Ar name Brq ...
84 .Pp
85 The first server defined is used if the requested hostname is not
86 matched by any server block.
87 .Pp
88 The available server configuration directives are as follows:
89 .Bl -tag -width Ds
90 .It Ic custom_css Ar path
91 Set the path to a custom Cascading Style Sheet (CSS) to be used.
92 If this option is not specified then the default style sheet
93 .Sq gotweb.css
94 will be used.
95 .It Ic listen on Ar address Ic port Ar number
96 Configure an address and port for incoming FastCGI connections.
97 Valid
98 .Ar address
99 arguments are hostnames, IPv4 and IPv6 addresses.
100 The
101 .Ar port
102 argument may be number or a service name defined in
103 .Xr services 5 .
104 .Pp
105 May be specified multiple times to build up a list of listening sockets.
106 However, a given combination of address and port may only be used by
107 one server.
108 .It Ic listen on socket Ar path
109 Set the path to the unix socket used by the server.
110 .It Ic logo Ar path
111 Set the path to an image file containing a logo to be displayed.
112 Defaults to
113 .Sq got.png .
114 .It Ic logo_url Ar url
115 Set a hyperlink for the logo.
116 Defaults to
117 .Lk https://gameoftrees.org .
118 .It Ic max_commits_display Ar number
119 Set the maximum amount of commits and tags displayed per page.
120 Defaults to 25.
121 .It Ic max_repos_display Ar number
122 Set the maximum amount of repositories displayed on the index screen.
123 Defaults to 25.
124 Set to zero to show all the repositories without pagination.
125 .It Ic repos_path Ar path
126 Set the path to the directory which contains Git repositories that
127 the server should publish.
128 Defaults to
129 .Pa /run/gotwebd.sock
130 under the chroot.
131 .It Ic respect_exportok Ar on | off
132 Set whether to display the repository only if it contains the magic
133 .Pa git-daemon-export-ok
134 file.
135 Disabled by default.
136 .It Ic show_repo_age Ar on | off
137 Toggle display of last repository modification date.
138 Enabled by default.
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 Enabled by default.
145 .It Ic show_repo_description Ar on | off
146 Toggle display of the repository description.
147 Enabled by default.
148 The
149 .Pa description
150 file in the repository should be updated with an appropriate description.
151 .It Ic show_repo_owner Ar on | off
152 Set whether to display the repository owner.
153 Enabled by default.
154 Displaying the owner requires owner information to be added to the
155 .Pa config
156 file in the repository.
157 .Xr gotwebd 8
158 will parse owner information from either a [gotweb] or a [gitweb] section.
159 For example:
160 .Bd -literal -offset indent
161 [gotweb]
162 owner = "Your Name"
163 .Ed
164 .It Ic site_link Ar string
165 Set the displayed site link name for the index page.
166 Defaults to
167 .Sq Repos .
168 .It Ic site_name Ar string
169 Set the displayed site name title.
170 Defaults to
171 .Sq Gotweb .
172 .It Ic site_owner Ar string
173 Set the displayed site owner.
174 Defaults to
175 .Sq Got Owner .
176 .It Ic show_site_owner Ar on | off
177 Toggle display of the site owner.
178 Enabled by default.
179 .It Ic summary_commits_display Ar number
180 The maximum number of commits to show in the summary page.
181 Defaults to 10.
182 .It Ic summary_tags_display Ar number
183 The maximum number of tags to show in the summary page.
184 Defaults to 3.
185 .El
186 .Sh FILES
187 .Bl -tag -width Ds -compact
188 .It Pa /etc/gotwebd.conf
189 Default location of the
190 .Nm
191 configuration file.
192 .El
193 .Sh EXAMPLES
194 A sample configuration:
195 .Bd -literal -offset indent
196 server "localhost" {
197 	site_name	"my public repos"
198 	site_owner	"Flan Hacker"
199 	site_link	"Flan' Projects"
200 }
201 .Ed
202 .Pp
203 Another example, this time listening on a local port instead of the
204 implicit
205 .Ux
206 socket.
207 .Bd -literal -offset indent
208 server "localhost" {
209 	listen on 127.0.0.1 port 9000
210 	listen on ::1 port 9000
211 }
212 .Ed
213 .Sh SEE ALSO
214 .Xr got 1 ,
215 .Xr httpd.conf 5 ,
216 .Xr services 5 ,
217 .Xr gotwebd 8 ,
218 .Xr httpd 8