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 a596b957 2022-07-14 tracey Paths mentioned in
34 a596b957 2022-07-14 tracey must be relative to
35 a596b957 2022-07-14 tracey .Pa /var/www ,
37 a596b957 2022-07-14 tracey .Xr chroot 2
38 a596b957 2022-07-14 tracey environment of
39 a596b957 2022-07-14 tracey .Xr httpd 8 .
40 a596b957 2022-07-14 tracey .Sh GLOBAL CONFIGURATION
41 0dd80998 2022-08-29 stsp The available global configuration directives are as follows:
42 a596b957 2022-07-14 tracey .Bl -tag -width Ds
43 59975c69 2022-08-29 stsp .It Ic chroot Ar path
44 59975c69 2022-08-29 stsp Set the path to the
46 59975c69 2022-08-29 stsp .Xr chroot 2
47 59975c69 2022-08-29 stsp environment of
48 59975c69 2022-08-29 stsp .Xr httpd 8 .
49 59975c69 2022-08-29 stsp If not specified then
50 59975c69 2022-08-29 stsp .Pa /var/www
51 59975c69 2022-08-29 stsp will be used.
52 0dd80998 2022-08-29 stsp .It Ic prefork Ar number
53 0dd80998 2022-08-29 stsp Run the specified number of server processes.
54 0dd80998 2022-08-29 stsp .It Ic fgci_socket Ar on | off
55 0dd80998 2022-08-29 stsp Controls whether the server will listen on FCGI TCP sockets by default.
56 0dd80998 2022-08-29 stsp .It Ic unix_socket Ar on | off
57 0dd80998 2022-08-29 stsp Controls whether the servers will listen on unix sockets by default.
58 0dd80998 2022-08-29 stsp .It Ic unix_socket_name Ar path
59 0dd80998 2022-08-29 stsp Set the path to the default unix socket.
61 0dd80998 2022-08-29 stsp .Sh SERVER CONFIGURATION
62 0dd80998 2022-08-29 stsp At least one server context must exist for
63 0dd80998 2022-08-29 stsp .Xr gotwebd 8
64 0dd80998 2022-08-29 stsp to function.
65 0dd80998 2022-08-29 stsp In case no server context is defined in the configuration file, a default
66 0dd80998 2022-08-29 stsp server context will be used, which listens on a unix socket at
67 0dd80998 2022-08-29 stsp .Pa /var/www/run/gotweb.sock
68 0dd80998 2022-08-29 stsp and uses default parameters for all applicable settings.
70 0dd80998 2022-08-29 stsp A server context is declared with a unique
72 0dd80998 2022-08-29 stsp followed by server-specific configuration directives inside curly braces:
74 0dd80998 2022-08-29 stsp .Ic server Ar name Brq ...
76 0dd80998 2022-08-29 stsp The available server configuration directives are as follows:
77 0dd80998 2022-08-29 stsp .Bl -tag -width Ds
78 59975c69 2022-08-29 stsp .It Ic custom_css Ar path
79 59975c69 2022-08-29 stsp Set the path to a custom Cascading Style Sheet (CSS) to be used.
80 0dd80998 2022-08-29 stsp If this option is not specified then a default style sheet will be used.
81 59975c69 2022-08-29 stsp .It Ic fgci_socket Ar on | off
82 0dd80998 2022-08-29 stsp Enable or disable listening on FCGI TCP sockets.
83 59975c69 2022-08-29 stsp .It Ic listen on Ar address Ic port Ar number
84 0dd80998 2022-08-29 stsp Configure an address and port for incoming FCGI TCP connections.
87 0dd80998 2022-08-29 stsp arguments are hostnames, IP4 addresses, IPv6 addresses, and network
88 0dd80998 2022-08-29 stsp interface names.
91 0dd80998 2022-08-29 stsp argument may be number or a service name defined in
92 0dd80998 2022-08-29 stsp .Xr services 5 .
94 0dd80998 2022-08-29 stsp May be specified multiple times to build up a list of listening sockets.
95 0dd80998 2022-08-29 stsp However, a given combination of address and port may only be used by
97 59975c69 2022-08-29 stsp .It Ic logo Ar path
98 a596b957 2022-07-14 tracey Set the path to an image file containing a logo to be displayed.
99 59975c69 2022-08-29 stsp .It Ic logo_url Ar url
100 a596b957 2022-07-14 tracey Set a hyperlink for the logo.
101 59975c69 2022-08-29 stsp .It Ic max_commits_display Ar number
102 59975c69 2022-08-29 stsp Set the maximum amount of commits displayed per page.
103 59975c69 2022-08-29 stsp .It Ic max_repos Ar number
104 a596b957 2022-07-14 tracey Set the maximum amount of repositories
105 59975c69 2022-08-29 stsp .Xr gotwebd 8
106 a596b957 2022-07-14 tracey will work with.
107 59975c69 2022-08-29 stsp .It Ic max_repos_display Ar number
108 a596b957 2022-07-14 tracey Set the maximum amount of repositories displayed on the index screen.
109 59975c69 2022-08-29 stsp .It Ic repos_path Ar path
110 59975c69 2022-08-29 stsp Set the path to the directory which contains Git repositories that
111 0dd80998 2022-08-29 stsp the server should publish.
112 59975c69 2022-08-29 stsp .It Ic show_repo_age Ar on | off
113 a596b957 2022-07-14 tracey Toggle display of last repository modification date.
114 59975c69 2022-08-29 stsp .It Ic show_repo_cloneurl Ar on | off
115 a596b957 2022-07-14 tracey Toggle display of clone URLs for a repository.
116 a596b957 2022-07-14 tracey This requires the creation of a
117 a596b957 2022-07-14 tracey .Pa cloneurl
118 a596b957 2022-07-14 tracey file inside the repository which contains one URL per line.
119 59975c69 2022-08-29 stsp .It Ic show_repo_description Ar on | off
120 a596b957 2022-07-14 tracey Toggle display of the repository description.
122 a596b957 2022-07-14 tracey .Pa description
123 a596b957 2022-07-14 tracey file in the repository should be updated with an appropriate description.
124 59975c69 2022-08-29 stsp .It Ic show_repo_owner Ar on | off
125 a596b957 2022-07-14 tracey Set whether to display the repository owner.
126 a596b957 2022-07-14 tracey Displaying the owner requires owner information to be added to the
127 a596b957 2022-07-14 tracey .Pa config
128 a596b957 2022-07-14 tracey file in the repository.
129 59975c69 2022-08-29 stsp .Xr gotwebd 8
130 a596b957 2022-07-14 tracey will parse owner information from either a [gotweb] or a [gitweb] section.
131 a596b957 2022-07-14 tracey For example:
132 a596b957 2022-07-14 tracey .Bd -literal -offset indent
134 a596b957 2022-07-14 tracey owner = "Your Name"
136 59975c69 2022-08-29 stsp .It Ic site_link Ar string
137 a596b957 2022-07-14 tracey Set the displayed site link name for the index page.
138 59975c69 2022-08-29 stsp .It Ic site_name Ar string
139 a596b957 2022-07-14 tracey Set the displayed site name title.
140 59975c69 2022-08-29 stsp .It Ic site_owner Ar string
141 a596b957 2022-07-14 tracey Set the displayed site owner.
142 59975c69 2022-08-29 stsp .It Ic show_site_owner Ar on | off
143 a596b957 2022-07-14 tracey Toggle display of the site owner.
144 59975c69 2022-08-29 stsp .It Ic unix_socket Ar on | off
145 0dd80998 2022-08-29 stsp Enable or disable use of unix sockets.
146 59975c69 2022-08-29 stsp .It Ic unix_socket_name Ar path
147 0dd80998 2022-08-29 stsp Set the path to the unix socket used by the server.
149 a596b957 2022-07-14 tracey .Sh EXAMPLES
150 a596b957 2022-07-14 tracey These are the currently configurable items for
151 59975c69 2022-08-29 stsp .Xr gotwebd 8
152 a596b957 2022-07-14 tracey with their default values.
153 a596b957 2022-07-14 tracey .Bd -literal -offset indent
155 59975c69 2022-08-29 stsp # gotwebd options
156 a596b957 2022-07-14 tracey # all paths relative to /var/www (httpd chroot jail)
161 59975c69 2022-08-29 stsp server "localhost-unix" {
162 59975c69 2022-08-29 stsp repos_path "/got/public"
163 59975c69 2022-08-29 stsp unix_socket_name "/run/gotweb.sock"
165 0dd80998 2022-08-29 stsp got_site_name "my public repos"
166 0dd80998 2022-08-29 stsp got_site_owner "Got Owner"
167 0dd80998 2022-08-29 stsp got_site_link "repos"
169 0dd80998 2022-08-29 stsp logo "got.png"
170 0dd80998 2022-08-29 stsp logo_url "https://gameoftrees.org"
172 0dd80998 2022-08-29 stsp # on by default
173 0dd80998 2022-08-29 stsp #show_site_owner off
174 0dd80998 2022-08-29 stsp #show_repo_owner off
175 0dd80998 2022-08-29 stsp #show_repo_age false
176 0dd80998 2022-08-29 stsp #show_repo_description no
177 0dd80998 2022-08-29 stsp #show_repo_cloneurl off
179 0dd80998 2022-08-29 stsp #max_repos 100
180 0dd80998 2022-08-29 stsp #max_repos_display 25
181 0dd80998 2022-08-29 stsp #max_commits_display 50
184 59975c69 2022-08-29 stsp # Example server context for FCGI over TCP connections:
185 59975c69 2022-08-29 stsp #server "localhost-tcp" {
186 59975c69 2022-08-29 stsp # repos_path "/got/public"
187 59975c69 2022-08-29 stsp # unix_socket off
188 59975c69 2022-08-29 stsp # fcgi_socket on
189 59975c69 2022-08-29 stsp # listen on 127.0.0.1 port 9000
190 59975c69 2022-08-29 stsp # listen on ::1 port 9000
193 a596b957 2022-07-14 tracey .Sh FILES
194 a596b957 2022-07-14 tracey .Bl -tag -width Ds -compact
195 a596b957 2022-07-14 tracey .It Pa /var/www/etc/gotweb.conf
196 a596b957 2022-07-14 tracey Location of the
198 a596b957 2022-07-14 tracey configuration file.
200 a596b957 2022-07-14 tracey .Sh SEE ALSO
201 a596b957 2022-07-14 tracey .Xr got 1 ,
202 0dd80998 2022-08-29 stsp .Xr services 5 ,
203 d69013de 2022-08-29 stsp .Xr gotwebd 8
