1 8a35f56c 2022-07-16 thomas .\"
  2 8a35f56c 2022-07-16 thomas .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
  3 8a35f56c 2022-07-16 thomas .\"
  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.
  7 8a35f56c 2022-07-16 thomas .\"
  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.
 15 8a35f56c 2022-07-16 thomas .\"
 16 8a35f56c 2022-07-16 thomas .Dd $Mdocdate$
 17 55331ef5 2022-08-30 thomas .Dt GOTWEBD.CONF 5
 18 8a35f56c 2022-07-16 thomas .Os
 19 8a35f56c 2022-07-16 thomas .Sh NAME
 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
 23 8a35f56c 2022-07-16 thomas .Nm
 24 8a35f56c 2022-07-16 thomas is the run-time configuration file for
 25 55331ef5 2022-08-30 thomas .Xr gotwebd 8 .
 26 8a35f56c 2022-07-16 thomas .Pp
 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
 29 8a35f56c 2022-07-16 thomas .Sq #
 30 8a35f56c 2022-07-16 thomas are treated as comments and ignored.
 31 8a35f56c 2022-07-16 thomas .Pp
 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 b2d220cf 2023-12-30 thomas listen on $lan_addr port 9090
 40 cfab1835 2022-10-04 thomas .Ed
 41 cfab1835 2022-10-04 thomas .Pp
 42 8a35f56c 2022-07-16 thomas Paths mentioned in
 43 8a35f56c 2022-07-16 thomas .Nm
 44 8a35f56c 2022-07-16 thomas must be relative to
 45 8a35f56c 2022-07-16 thomas .Pa /var/www ,
 46 8a35f56c 2022-07-16 thomas the
 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 b2d220cf 2023-12-30 thomas .Xr gotwebd 8
 64 b2d220cf 2023-12-30 thomas runs 3 server processes by default.
 65 cf5878ee 2022-08-30 thomas .It Ic unix_socket Ar on | off
 66 cf5878ee 2022-08-30 thomas Controls whether the servers will listen on unix sockets by default.
 67 b2d220cf 2023-12-30 thomas Listening on unix sockets is the default.
 68 cf5878ee 2022-08-30 thomas .It Ic unix_socket_name Ar path
 69 cf5878ee 2022-08-30 thomas Set the path to the default unix socket.
 70 b2d220cf 2023-12-30 thomas Defaults to
 71 b2d220cf 2023-12-30 thomas .Pa /var/www/run/gotweb.sock .
 72 cf5878ee 2022-08-30 thomas .El
 73 cf5878ee 2022-08-30 thomas .Sh SERVER CONFIGURATION
 74 cf5878ee 2022-08-30 thomas At least one server context must exist for
 75 cf5878ee 2022-08-30 thomas .Xr gotwebd 8
 76 cf5878ee 2022-08-30 thomas to function.
 77 cf5878ee 2022-08-30 thomas In case no server context is defined in the configuration file, a default
 78 cf5878ee 2022-08-30 thomas server context will be used, which listens on a unix socket at
 79 cf5878ee 2022-08-30 thomas .Pa /var/www/run/gotweb.sock
 80 cf5878ee 2022-08-30 thomas and uses default parameters for all applicable settings.
 81 cf5878ee 2022-08-30 thomas .Pp
 82 cf5878ee 2022-08-30 thomas A server context is declared with a unique
 83 a568bf72 2022-08-30 thomas .Ar name ,
 84 cf5878ee 2022-08-30 thomas followed by server-specific configuration directives inside curly braces:
 85 cf5878ee 2022-08-30 thomas .Pp
 86 cf5878ee 2022-08-30 thomas .Ic server Ar name Brq ...
 87 cf5878ee 2022-08-30 thomas .Pp
 88 b95d1cf6 2023-06-25 thomas The first server defined is used if the requested hostname is not
 89 b95d1cf6 2023-06-25 thomas matched by any server block.
 90 211ff89e 2022-08-30 thomas .Pp
 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 b2d220cf 2023-12-30 thomas If this option is not specified then the default style sheet
 96 b2d220cf 2023-12-30 thomas .Sq gotweb.css
 97 b2d220cf 2023-12-30 thomas will be used.
 98 55331ef5 2022-08-30 thomas .It Ic listen on Ar address Ic port Ar number
 99 b2d220cf 2023-12-30 thomas Configure an address and port for incoming FastCGI connections.
100 cf5878ee 2022-08-30 thomas Valid
101 cf5878ee 2022-08-30 thomas .Ar address
102 b2d220cf 2023-12-30 thomas arguments are hostnames, IPv4 and IPv6 addresses.
103 cf5878ee 2022-08-30 thomas The
104 cf5878ee 2022-08-30 thomas .Ar port
105 cf5878ee 2022-08-30 thomas argument may be number or a service name defined in
106 cf5878ee 2022-08-30 thomas .Xr services 5 .
107 cf5878ee 2022-08-30 thomas .Pp
108 cf5878ee 2022-08-30 thomas May be specified multiple times to build up a list of listening sockets.
109 cf5878ee 2022-08-30 thomas However, a given combination of address and port may only be used by
110 cf5878ee 2022-08-30 thomas one server.
111 bea82c4f 2023-01-06 thomas .It Ic listen on socket off
112 bea82c4f 2023-01-06 thomas Disable use of unix socket.
113 bea82c4f 2023-01-06 thomas .It Ic listen on socket Ar path
114 bea82c4f 2023-01-06 thomas Set the path to the unix socket used by the server.
115 55331ef5 2022-08-30 thomas .It Ic logo Ar path
116 8a35f56c 2022-07-16 thomas Set the path to an image file containing a logo to be displayed.
117 b2d220cf 2023-12-30 thomas Defaults to
118 b2d220cf 2023-12-30 thomas .Sq got.png .
119 55331ef5 2022-08-30 thomas .It Ic logo_url Ar url
120 8a35f56c 2022-07-16 thomas Set a hyperlink for the logo.
121 b2d220cf 2023-12-30 thomas Defaults to
122 b2d220cf 2023-12-30 thomas .Lk https://gameoftrees.org .
123 55331ef5 2022-08-30 thomas .It Ic max_commits_display Ar number
124 b2d220cf 2023-12-30 thomas Set the maximum amount of commits and tags displayed per page.
125 b2d220cf 2023-12-30 thomas Defaults to 25.
126 55331ef5 2022-08-30 thomas .It Ic max_repos_display Ar number
127 8a35f56c 2022-07-16 thomas Set the maximum amount of repositories displayed on the index screen.
128 b2d220cf 2023-12-30 thomas Defaults to 25.
129 b2d220cf 2023-12-30 thomas Set to zero to show all the repositories without pagination.
130 55331ef5 2022-08-30 thomas .It Ic repos_path Ar path
131 55331ef5 2022-08-30 thomas Set the path to the directory which contains Git repositories that
132 cf5878ee 2022-08-30 thomas the server should publish.
133 b2d220cf 2023-12-30 thomas Defaults to
134 b2d220cf 2023-12-30 thomas .Pa /run/gotwebd.sock
135 b2d220cf 2023-12-30 thomas under the chroot.
136 3991b2a5 2022-10-31 thomas .It Ic respect_exportok Ar on | off
137 3991b2a5 2022-10-31 thomas Set whether to display the repository only if it contains the magic
138 3991b2a5 2022-10-31 thomas .Pa git-daemon-export-ok
139 3991b2a5 2022-10-31 thomas file.
140 b2d220cf 2023-12-30 thomas Disabled by default.
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 b2d220cf 2023-12-30 thomas Enabled by default.
144 55331ef5 2022-08-30 thomas .It Ic show_repo_cloneurl Ar on | off
145 8a35f56c 2022-07-16 thomas Toggle display of clone URLs for a repository.
146 8a35f56c 2022-07-16 thomas This requires the creation of a
147 8a35f56c 2022-07-16 thomas .Pa cloneurl
148 8a35f56c 2022-07-16 thomas file inside the repository which contains one URL per line.
149 b2d220cf 2023-12-30 thomas Enabled by default.
150 55331ef5 2022-08-30 thomas .It Ic show_repo_description Ar on | off
151 8a35f56c 2022-07-16 thomas Toggle display of the repository description.
152 b2d220cf 2023-12-30 thomas Enabled by default.
153 8a35f56c 2022-07-16 thomas The
154 8a35f56c 2022-07-16 thomas .Pa description
155 8a35f56c 2022-07-16 thomas file in the repository should be updated with an appropriate description.
156 55331ef5 2022-08-30 thomas .It Ic show_repo_owner Ar on | off
157 8a35f56c 2022-07-16 thomas Set whether to display the repository owner.
158 b2d220cf 2023-12-30 thomas Enabled by default.
159 8a35f56c 2022-07-16 thomas Displaying the owner requires owner information to be added to the
160 8a35f56c 2022-07-16 thomas .Pa config
161 8a35f56c 2022-07-16 thomas file in the repository.
162 55331ef5 2022-08-30 thomas .Xr gotwebd 8
163 8a35f56c 2022-07-16 thomas will parse owner information from either a [gotweb] or a [gitweb] section.
164 8a35f56c 2022-07-16 thomas For example:
165 8a35f56c 2022-07-16 thomas .Bd -literal -offset indent
166 8a35f56c 2022-07-16 thomas [gotweb]
167 8a35f56c 2022-07-16 thomas owner = "Your Name"
168 8a35f56c 2022-07-16 thomas .Ed
169 55331ef5 2022-08-30 thomas .It Ic site_link Ar string
170 8a35f56c 2022-07-16 thomas Set the displayed site link name for the index page.
171 b2d220cf 2023-12-30 thomas Defaults to
172 b2d220cf 2023-12-30 thomas .Sq Repos .
173 55331ef5 2022-08-30 thomas .It Ic site_name Ar string
174 8a35f56c 2022-07-16 thomas Set the displayed site name title.
175 b2d220cf 2023-12-30 thomas Defaults to
176 b2d220cf 2023-12-30 thomas .Sq Gotweb .
177 55331ef5 2022-08-30 thomas .It Ic site_owner Ar string
178 8a35f56c 2022-07-16 thomas Set the displayed site owner.
179 b2d220cf 2023-12-30 thomas Defaults to
180 b2d220cf 2023-12-30 thomas .Sq Got Owner .
181 55331ef5 2022-08-30 thomas .It Ic show_site_owner Ar on | off
182 8a35f56c 2022-07-16 thomas Toggle display of the site owner.
183 b2d220cf 2023-12-30 thomas Enabled by default.
184 e85a14fa 2023-12-30 thomas .It Ic summary_commits_display Ar number
185 e85a14fa 2023-12-30 thomas The maximum number of commits to show in the summary page.
186 b2d220cf 2023-12-30 thomas Defaults to 10.
187 e85a14fa 2023-12-30 thomas .It Ic summary_tags_display Ar number
188 e85a14fa 2023-12-30 thomas The maximum number of tags to show in the summary page.
189 b2d220cf 2023-12-30 thomas Defaults to 3.
190 cf5878ee 2022-08-30 thomas .El
191 634fd2c7 2022-11-17 thomas .Sh FILES
192 634fd2c7 2022-11-17 thomas .Bl -tag -width Ds -compact
193 634fd2c7 2022-11-17 thomas .It Pa /etc/gotwebd.conf
194 634fd2c7 2022-11-17 thomas Default location of the
195 634fd2c7 2022-11-17 thomas .Nm
196 634fd2c7 2022-11-17 thomas configuration file.
197 634fd2c7 2022-11-17 thomas .El
198 8a35f56c 2022-07-16 thomas .Sh EXAMPLES
199 b2d220cf 2023-12-30 thomas A sample configuration:
200 8a35f56c 2022-07-16 thomas .Bd -literal -offset indent
201 b2d220cf 2023-12-30 thomas server "localhost" {
202 b2d220cf 2023-12-30 thomas 	site_name	"my public repos"
203 b2d220cf 2023-12-30 thomas 	site_owner	"Flan Hacker"
204 b2d220cf 2023-12-30 thomas 	site_link	"Flan' Projects"
205 55331ef5 2022-08-30 thomas }
206 8a35f56c 2022-07-16 thomas .Ed
207 b2d220cf 2023-12-30 thomas .Pp
208 b2d220cf 2023-12-30 thomas Another example, this time listening on a local port instead of the
209 b2d220cf 2023-12-30 thomas implicit
210 b2d220cf 2023-12-30 thomas .Ux
211 b2d220cf 2023-12-30 thomas socket.
212 b2d220cf 2023-12-30 thomas .Bd -literal -offset indent
213 b2d220cf 2023-12-30 thomas server "localhost" {
214 b2d220cf 2023-12-30 thomas 	listen on socket off
215 b2d220cf 2023-12-30 thomas 	listen on 127.0.0.1 port 9000
216 b2d220cf 2023-12-30 thomas 	listen on ::1 port 9000
217 b2d220cf 2023-12-30 thomas }
218 b2d220cf 2023-12-30 thomas .Ed
219 8a35f56c 2022-07-16 thomas .Sh SEE ALSO
220 8a35f56c 2022-07-16 thomas .Xr got 1 ,
221 0176d7a5 2022-08-30 thomas .Xr httpd.conf 5 ,
222 cf5878ee 2022-08-30 thomas .Xr services 5 ,
223 0176d7a5 2022-08-30 thomas .Xr gotwebd 8 ,
224 0176d7a5 2022-08-30 thomas .Xr httpd 8