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 47b307cd 2022-10-02 op listen on $lan_addr
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 0dd80998 2022-08-29 stsp .It Ic prefork Ar number
62 0dd80998 2022-08-29 stsp Run the specified number of server processes.
63 0dd80998 2022-08-29 stsp .It Ic unix_socket Ar on | off
64 0dd80998 2022-08-29 stsp Controls whether the servers will listen on unix sockets by default.
65 0dd80998 2022-08-29 stsp .It Ic unix_socket_name Ar path
66 0dd80998 2022-08-29 stsp Set the path to the default unix socket.
68 0dd80998 2022-08-29 stsp .Sh SERVER CONFIGURATION
69 0dd80998 2022-08-29 stsp At least one server context must exist for
70 0dd80998 2022-08-29 stsp .Xr gotwebd 8
71 0dd80998 2022-08-29 stsp to function.
72 0dd80998 2022-08-29 stsp In case no server context is defined in the configuration file, a default
73 0dd80998 2022-08-29 stsp server context will be used, which listens on a unix socket at
74 0dd80998 2022-08-29 stsp .Pa /var/www/run/gotweb.sock
75 0dd80998 2022-08-29 stsp and uses default parameters for all applicable settings.
77 0dd80998 2022-08-29 stsp A server context is declared with a unique
79 0dd80998 2022-08-29 stsp followed by server-specific configuration directives inside curly braces:
81 0dd80998 2022-08-29 stsp .Ic server Ar name Brq ...
83 f21aef01 2022-08-30 stsp .Xr gotwebd 8
84 f21aef01 2022-08-30 stsp is compatible with TLS Server Name Indication (SNI), provided the
86 f21aef01 2022-08-30 stsp of a server defined in
88 f21aef01 2022-08-30 stsp corresponds to the name of a server defined in
89 f21aef01 2022-08-30 stsp .Xr httpd.conf 5 .
91 0dd80998 2022-08-29 stsp The available server configuration directives are as follows:
92 0dd80998 2022-08-29 stsp .Bl -tag -width Ds
93 59975c69 2022-08-29 stsp .It Ic custom_css Ar path
94 59975c69 2022-08-29 stsp Set the path to a custom Cascading Style Sheet (CSS) to be used.
95 0dd80998 2022-08-29 stsp If this option is not specified then a default style sheet will be used.
96 59975c69 2022-08-29 stsp .It Ic listen on Ar address Ic port Ar number
97 0dd80998 2022-08-29 stsp Configure an address and port for incoming FCGI TCP connections.
100 0dd80998 2022-08-29 stsp arguments are hostnames, IP4 addresses, IPv6 addresses, and network
101 0dd80998 2022-08-29 stsp interface names.
104 0dd80998 2022-08-29 stsp argument may be number or a service name defined in
105 0dd80998 2022-08-29 stsp .Xr services 5 .
107 0dd80998 2022-08-29 stsp May be specified multiple times to build up a list of listening sockets.
108 0dd80998 2022-08-29 stsp However, a given combination of address and port may only be used by
109 0dd80998 2022-08-29 stsp one server.
111 bde6e1ec 2022-09-23 stsp If a network interface name is given as
112 bde6e1ec 2022-09-23 stsp .Ar address
113 bde6e1ec 2022-09-23 stsp argument then
114 bde6e1ec 2022-09-23 stsp .Xr gotwebd 8
115 bde6e1ec 2022-09-23 stsp will obtain the list of addresses on this interface only on startup.
116 bde6e1ec 2022-09-23 stsp Any future changes to the address configuration of the interface will
117 bde6e1ec 2022-09-23 stsp be ignored.
118 3a1c1a1b 2023-01-04 op .It Ic listen on socket off
119 3a1c1a1b 2023-01-04 op Disable use of unix socket.
120 3a1c1a1b 2023-01-04 op .It Ic listen on socket Ar path
121 3a1c1a1b 2023-01-04 op Set the path to the unix socket used by the server.
122 59975c69 2022-08-29 stsp .It Ic logo Ar path
123 a596b957 2022-07-14 tracey Set the path to an image file containing a logo to be displayed.
124 59975c69 2022-08-29 stsp .It Ic logo_url Ar url
125 a596b957 2022-07-14 tracey Set a hyperlink for the logo.
126 59975c69 2022-08-29 stsp .It Ic max_commits_display Ar number
127 59975c69 2022-08-29 stsp Set the maximum amount of commits displayed per page.
128 59975c69 2022-08-29 stsp .It Ic max_repos Ar number
129 a596b957 2022-07-14 tracey Set the maximum amount of repositories
130 59975c69 2022-08-29 stsp .Xr gotwebd 8
131 a596b957 2022-07-14 tracey will work with.
132 59975c69 2022-08-29 stsp .It Ic max_repos_display Ar number
133 a596b957 2022-07-14 tracey Set the maximum amount of repositories displayed on the index screen.
134 59975c69 2022-08-29 stsp .It Ic repos_path Ar path
135 59975c69 2022-08-29 stsp Set the path to the directory which contains Git repositories that
136 0dd80998 2022-08-29 stsp the server should publish.
137 d5996b9e 2022-10-31 landry .It Ic respect_exportok Ar on | off
138 d5996b9e 2022-10-31 landry Set whether to display the repository only if it contains the magic
139 d5996b9e 2022-10-31 landry .Pa git-daemon-export-ok
141 59975c69 2022-08-29 stsp .It Ic show_repo_age Ar on | off
142 a596b957 2022-07-14 tracey Toggle display of last repository modification date.
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 59975c69 2022-08-29 stsp .It Ic show_repo_description Ar on | off
149 a596b957 2022-07-14 tracey Toggle display of the repository description.
151 a596b957 2022-07-14 tracey .Pa description
152 a596b957 2022-07-14 tracey file in the repository should be updated with an appropriate description.
153 59975c69 2022-08-29 stsp .It Ic show_repo_owner Ar on | off
154 a596b957 2022-07-14 tracey Set whether to display the repository owner.
155 a596b957 2022-07-14 tracey Displaying the owner requires owner information to be added to the
156 a596b957 2022-07-14 tracey .Pa config
157 a596b957 2022-07-14 tracey file in the repository.
158 59975c69 2022-08-29 stsp .Xr gotwebd 8
159 a596b957 2022-07-14 tracey will parse owner information from either a [gotweb] or a [gitweb] section.
160 a596b957 2022-07-14 tracey For example:
161 a596b957 2022-07-14 tracey .Bd -literal -offset indent
163 a596b957 2022-07-14 tracey owner = "Your Name"
165 59975c69 2022-08-29 stsp .It Ic site_link Ar string
166 a596b957 2022-07-14 tracey Set the displayed site link name for the index page.
167 59975c69 2022-08-29 stsp .It Ic site_name Ar string
168 a596b957 2022-07-14 tracey Set the displayed site name title.
169 59975c69 2022-08-29 stsp .It Ic site_owner Ar string
170 a596b957 2022-07-14 tracey Set the displayed site owner.
171 59975c69 2022-08-29 stsp .It Ic show_site_owner Ar on | off
172 a596b957 2022-07-14 tracey Toggle display of the site owner.
175 d375d894 2022-11-14 op .Bl -tag -width Ds -compact
176 d375d894 2022-11-14 op .It Pa /etc/gotwebd.conf
177 d375d894 2022-11-14 op Default location of the
179 d375d894 2022-11-14 op configuration file.
181 a596b957 2022-07-14 tracey .Sh EXAMPLES
182 a596b957 2022-07-14 tracey These are the currently configurable items for
183 59975c69 2022-08-29 stsp .Xr gotwebd 8
184 a596b957 2022-07-14 tracey with their default values.
185 a596b957 2022-07-14 tracey .Bd -literal -offset indent
187 59975c69 2022-08-29 stsp # gotwebd options
188 a596b957 2022-07-14 tracey # all paths relative to /var/www (httpd chroot jail)
193 59975c69 2022-08-29 stsp server "localhost-unix" {
194 59975c69 2022-08-29 stsp repos_path "/got/public"
195 3a1c1a1b 2023-01-04 op listen on socket "/run/gotweb.sock"
197 05791aa0 2023-01-02 op site_name "my public repos"
198 05791aa0 2023-01-02 op site_owner "Got Owner"
199 05791aa0 2023-01-02 op site_link "repos"
201 0dd80998 2022-08-29 stsp logo "got.png"
202 0dd80998 2022-08-29 stsp logo_url "https://gameoftrees.org"
204 0dd80998 2022-08-29 stsp # on by default
205 92e48697 2023-02-21 op #show_site_owner on
206 92e48697 2023-02-21 op #show_repo_owner on
207 92e48697 2023-02-21 op #show_repo_age on
208 0dd80998 2022-08-29 stsp #show_repo_description no
209 92e48697 2023-02-21 op #show_repo_cloneurl on
210 92e48697 2023-02-21 op #respect_exportok off
213 0dd80998 2022-08-29 stsp #max_repos_display 25
214 92e48697 2023-02-21 op #max_commits_display 25
217 59975c69 2022-08-29 stsp # Example server context for FCGI over TCP connections:
218 59975c69 2022-08-29 stsp #server "localhost-tcp" {
219 59975c69 2022-08-29 stsp # repos_path "/got/public"
220 3a1c1a1b 2023-01-04 op # listen on socket off
221 59975c69 2022-08-29 stsp # listen on 127.0.0.1 port 9000
222 59975c69 2022-08-29 stsp # listen on ::1 port 9000
225 a596b957 2022-07-14 tracey .Sh SEE ALSO
226 a596b957 2022-07-14 tracey .Xr got 1 ,
227 e0e2a861 2022-08-30 stsp .Xr httpd.conf 5 ,
228 0dd80998 2022-08-29 stsp .Xr services 5 ,
229 e0e2a861 2022-08-30 stsp .Xr gotwebd 8 ,
230 e0e2a861 2022-08-30 stsp .Xr httpd 8
