2 8a35f56c 2022-07-16 thomas .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
4 8a35f56c 2022-07-16 thomas .\" Permission to use, copy, modify, and distribute this software for any
5 8a35f56c 2022-07-16 thomas .\" purpose with or without fee is hereby granted, provided that the above
6 8a35f56c 2022-07-16 thomas .\" copyright notice and this permission notice appear in all copies.
8 8a35f56c 2022-07-16 thomas .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 8a35f56c 2022-07-16 thomas .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 8a35f56c 2022-07-16 thomas .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 8a35f56c 2022-07-16 thomas .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 8a35f56c 2022-07-16 thomas .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 8a35f56c 2022-07-16 thomas .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 8a35f56c 2022-07-16 thomas .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 8a35f56c 2022-07-16 thomas .Dd $Mdocdate$
17 55331ef5 2022-08-30 thomas .Dt GOTWEBD.CONF 5
20 55331ef5 2022-08-30 thomas .Nm gotwebd.conf
21 55331ef5 2022-08-30 thomas .Nd gotwebd configuration file
22 8a35f56c 2022-07-16 thomas .Sh DESCRIPTION
24 8a35f56c 2022-07-16 thomas is the run-time configuration file for
25 55331ef5 2022-08-30 thomas .Xr gotwebd 8 .
27 8a35f56c 2022-07-16 thomas The file format is line-based, with one configuration directive per line.
28 8a35f56c 2022-07-16 thomas Any lines beginning with a
30 8a35f56c 2022-07-16 thomas are treated as comments and ignored.
32 cfab1835 2022-10-04 thomas Macros can be defined that are later expanded in context.
33 cfab1835 2022-10-04 thomas Macro names must start with a letter, digit, or underscore, and may
34 cfab1835 2022-10-04 thomas contain any of those characters, but may not be reserved words.
35 cfab1835 2022-10-04 thomas Macros are not expanded inside quotes.
36 cfab1835 2022-10-04 thomas For example:
37 cfab1835 2022-10-04 thomas .Bd -literal -offset indent
38 cfab1835 2022-10-04 thomas lan_addr = "192.168.0.1"
39 cfab1835 2022-10-04 thomas listen on $lan_addr
42 8a35f56c 2022-07-16 thomas Paths mentioned in
44 8a35f56c 2022-07-16 thomas must be relative to
45 8a35f56c 2022-07-16 thomas .Pa /var/www ,
47 8a35f56c 2022-07-16 thomas .Xr chroot 2
48 8a35f56c 2022-07-16 thomas environment of
49 8a35f56c 2022-07-16 thomas .Xr httpd 8 .
50 8a35f56c 2022-07-16 thomas .Sh GLOBAL CONFIGURATION
51 cf5878ee 2022-08-30 thomas The available global configuration directives are as follows:
52 8a35f56c 2022-07-16 thomas .Bl -tag -width Ds
53 55331ef5 2022-08-30 thomas .It Ic chroot Ar path
54 55331ef5 2022-08-30 thomas Set the path to the
55 55331ef5 2022-08-30 thomas .Xr chroot 2
56 55331ef5 2022-08-30 thomas environment of
57 55331ef5 2022-08-30 thomas .Xr httpd 8 .
58 55331ef5 2022-08-30 thomas If not specified then
59 55331ef5 2022-08-30 thomas .Pa /var/www
60 55331ef5 2022-08-30 thomas will be used.
61 cf5878ee 2022-08-30 thomas .It Ic prefork Ar number
62 cf5878ee 2022-08-30 thomas Run the specified number of server processes.
63 cf5878ee 2022-08-30 thomas .It Ic unix_socket Ar on | off
64 cf5878ee 2022-08-30 thomas Controls whether the servers will listen on unix sockets by default.
65 cf5878ee 2022-08-30 thomas .It Ic unix_socket_name Ar path
66 cf5878ee 2022-08-30 thomas Set the path to the default unix socket.
68 cf5878ee 2022-08-30 thomas .Sh SERVER CONFIGURATION
69 cf5878ee 2022-08-30 thomas At least one server context must exist for
70 cf5878ee 2022-08-30 thomas .Xr gotwebd 8
71 cf5878ee 2022-08-30 thomas to function.
72 cf5878ee 2022-08-30 thomas In case no server context is defined in the configuration file, a default
73 cf5878ee 2022-08-30 thomas server context will be used, which listens on a unix socket at
74 cf5878ee 2022-08-30 thomas .Pa /var/www/run/gotweb.sock
75 cf5878ee 2022-08-30 thomas and uses default parameters for all applicable settings.
77 cf5878ee 2022-08-30 thomas A server context is declared with a unique
78 a568bf72 2022-08-30 thomas .Ar name ,
79 cf5878ee 2022-08-30 thomas followed by server-specific configuration directives inside curly braces:
81 cf5878ee 2022-08-30 thomas .Ic server Ar name Brq ...
83 211ff89e 2022-08-30 thomas .Xr gotwebd 8
84 211ff89e 2022-08-30 thomas is compatible with TLS Server Name Indication (SNI), provided the
86 211ff89e 2022-08-30 thomas of a server defined in
88 211ff89e 2022-08-30 thomas corresponds to the name of a server defined in
89 211ff89e 2022-08-30 thomas .Xr httpd.conf 5 .
91 cf5878ee 2022-08-30 thomas The available server configuration directives are as follows:
92 cf5878ee 2022-08-30 thomas .Bl -tag -width Ds
93 55331ef5 2022-08-30 thomas .It Ic custom_css Ar path
94 55331ef5 2022-08-30 thomas Set the path to a custom Cascading Style Sheet (CSS) to be used.
95 cf5878ee 2022-08-30 thomas If this option is not specified then a default style sheet will be used.
96 55331ef5 2022-08-30 thomas .It Ic listen on Ar address Ic port Ar number
97 cf5878ee 2022-08-30 thomas Configure an address and port for incoming FCGI TCP connections.
99 cf5878ee 2022-08-30 thomas .Ar address
100 cf5878ee 2022-08-30 thomas arguments are hostnames, IP4 addresses, IPv6 addresses, and network
101 cf5878ee 2022-08-30 thomas interface names.
104 cf5878ee 2022-08-30 thomas argument may be number or a service name defined in
105 cf5878ee 2022-08-30 thomas .Xr services 5 .
107 cf5878ee 2022-08-30 thomas May be specified multiple times to build up a list of listening sockets.
108 cf5878ee 2022-08-30 thomas However, a given combination of address and port may only be used by
109 cf5878ee 2022-08-30 thomas one server.
111 a8bfd781 2022-09-23 thomas If a network interface name is given as
112 a8bfd781 2022-09-23 thomas .Ar address
113 a8bfd781 2022-09-23 thomas argument then
114 a8bfd781 2022-09-23 thomas .Xr gotwebd 8
115 a8bfd781 2022-09-23 thomas will obtain the list of addresses on this interface only on startup.
116 a8bfd781 2022-09-23 thomas Any future changes to the address configuration of the interface will
117 a8bfd781 2022-09-23 thomas be ignored.
118 bea82c4f 2023-01-06 thomas .It Ic listen on socket off
119 bea82c4f 2023-01-06 thomas Disable use of unix socket.
120 bea82c4f 2023-01-06 thomas .It Ic listen on socket Ar path
121 bea82c4f 2023-01-06 thomas Set the path to the unix socket used by the server.
122 55331ef5 2022-08-30 thomas .It Ic logo Ar path
123 8a35f56c 2022-07-16 thomas Set the path to an image file containing a logo to be displayed.
124 55331ef5 2022-08-30 thomas .It Ic logo_url Ar url
125 8a35f56c 2022-07-16 thomas Set a hyperlink for the logo.
126 55331ef5 2022-08-30 thomas .It Ic max_commits_display Ar number
127 55331ef5 2022-08-30 thomas Set the maximum amount of commits displayed per page.
128 55331ef5 2022-08-30 thomas .It Ic max_repos Ar number
129 8a35f56c 2022-07-16 thomas Set the maximum amount of repositories
130 55331ef5 2022-08-30 thomas .Xr gotwebd 8
131 8a35f56c 2022-07-16 thomas will work with.
132 55331ef5 2022-08-30 thomas .It Ic max_repos_display Ar number
133 8a35f56c 2022-07-16 thomas Set the maximum amount of repositories displayed on the index screen.
134 55331ef5 2022-08-30 thomas .It Ic repos_path Ar path
135 55331ef5 2022-08-30 thomas Set the path to the directory which contains Git repositories that
136 cf5878ee 2022-08-30 thomas the server should publish.
137 3991b2a5 2022-10-31 thomas .It Ic respect_exportok Ar on | off
138 3991b2a5 2022-10-31 thomas Set whether to display the repository only if it contains the magic
139 3991b2a5 2022-10-31 thomas .Pa git-daemon-export-ok
141 55331ef5 2022-08-30 thomas .It Ic show_repo_age Ar on | off
142 8a35f56c 2022-07-16 thomas Toggle display of last repository modification date.
143 55331ef5 2022-08-30 thomas .It Ic show_repo_cloneurl Ar on | off
144 8a35f56c 2022-07-16 thomas Toggle display of clone URLs for a repository.
145 8a35f56c 2022-07-16 thomas This requires the creation of a
146 8a35f56c 2022-07-16 thomas .Pa cloneurl
147 8a35f56c 2022-07-16 thomas file inside the repository which contains one URL per line.
148 55331ef5 2022-08-30 thomas .It Ic show_repo_description Ar on | off
149 8a35f56c 2022-07-16 thomas Toggle display of the repository description.
151 8a35f56c 2022-07-16 thomas .Pa description
152 8a35f56c 2022-07-16 thomas file in the repository should be updated with an appropriate description.
153 55331ef5 2022-08-30 thomas .It Ic show_repo_owner Ar on | off
154 8a35f56c 2022-07-16 thomas Set whether to display the repository owner.
155 8a35f56c 2022-07-16 thomas Displaying the owner requires owner information to be added to the
156 8a35f56c 2022-07-16 thomas .Pa config
157 8a35f56c 2022-07-16 thomas file in the repository.
158 55331ef5 2022-08-30 thomas .Xr gotwebd 8
159 8a35f56c 2022-07-16 thomas will parse owner information from either a [gotweb] or a [gitweb] section.
160 8a35f56c 2022-07-16 thomas For example:
161 8a35f56c 2022-07-16 thomas .Bd -literal -offset indent
163 8a35f56c 2022-07-16 thomas owner = "Your Name"
165 55331ef5 2022-08-30 thomas .It Ic site_link Ar string
166 8a35f56c 2022-07-16 thomas Set the displayed site link name for the index page.
167 55331ef5 2022-08-30 thomas .It Ic site_name Ar string
168 8a35f56c 2022-07-16 thomas Set the displayed site name title.
169 55331ef5 2022-08-30 thomas .It Ic site_owner Ar string
170 8a35f56c 2022-07-16 thomas Set the displayed site owner.
171 55331ef5 2022-08-30 thomas .It Ic show_site_owner Ar on | off
172 8a35f56c 2022-07-16 thomas Toggle display of the site owner.
174 634fd2c7 2022-11-17 thomas .Sh FILES
175 634fd2c7 2022-11-17 thomas .Bl -tag -width Ds -compact
176 634fd2c7 2022-11-17 thomas .It Pa /etc/gotwebd.conf
177 634fd2c7 2022-11-17 thomas Default location of the
179 634fd2c7 2022-11-17 thomas configuration file.
181 8a35f56c 2022-07-16 thomas .Sh EXAMPLES
182 8a35f56c 2022-07-16 thomas These are the currently configurable items for
183 55331ef5 2022-08-30 thomas .Xr gotwebd 8
184 8a35f56c 2022-07-16 thomas with their default values.
185 8a35f56c 2022-07-16 thomas .Bd -literal -offset indent
187 55331ef5 2022-08-30 thomas # gotwebd options
188 8a35f56c 2022-07-16 thomas # all paths relative to /var/www (httpd chroot jail)
191 55331ef5 2022-08-30 thomas prefork 1
193 55331ef5 2022-08-30 thomas server "localhost-unix" {
194 55331ef5 2022-08-30 thomas repos_path "/got/public"
195 bea82c4f 2023-01-06 thomas listen on socket "/run/gotweb.sock"
197 ef504a85 2023-01-02 thomas site_name "my public repos"
198 ef504a85 2023-01-02 thomas site_owner "Got Owner"
199 ef504a85 2023-01-02 thomas site_link "repos"
201 cf5878ee 2022-08-30 thomas logo "got.png"
202 cf5878ee 2022-08-30 thomas logo_url "https://gameoftrees.org"
204 cf5878ee 2022-08-30 thomas # on by default
205 cf5878ee 2022-08-30 thomas #show_site_owner off
206 cf5878ee 2022-08-30 thomas #show_repo_owner off
207 cf5878ee 2022-08-30 thomas #show_repo_age false
208 cf5878ee 2022-08-30 thomas #show_repo_description no
209 cf5878ee 2022-08-30 thomas #show_repo_cloneurl off
210 3991b2a5 2022-10-31 thomas # off by default
211 3991b2a5 2022-10-31 thomas #respect_exportok on
213 cf5878ee 2022-08-30 thomas #max_repos 100
214 cf5878ee 2022-08-30 thomas #max_repos_display 25
215 cf5878ee 2022-08-30 thomas #max_commits_display 50
218 55331ef5 2022-08-30 thomas # Example server context for FCGI over TCP connections:
219 55331ef5 2022-08-30 thomas #server "localhost-tcp" {
220 55331ef5 2022-08-30 thomas # repos_path "/got/public"
221 bea82c4f 2023-01-06 thomas # listen on socket off
222 55331ef5 2022-08-30 thomas # listen on 127.0.0.1 port 9000
223 55331ef5 2022-08-30 thomas # listen on ::1 port 9000
226 8a35f56c 2022-07-16 thomas .Sh SEE ALSO
227 8a35f56c 2022-07-16 thomas .Xr got 1 ,
228 0176d7a5 2022-08-30 thomas .Xr httpd.conf 5 ,
229 cf5878ee 2022-08-30 thomas .Xr services 5 ,
230 0176d7a5 2022-08-30 thomas .Xr gotwebd 8 ,
231 0176d7a5 2022-08-30 thomas .Xr httpd 8
