1 63657f42 2022-09-07 stsp <!DOCTYPE html>
4 63657f42 2022-09-07 stsp <meta charset="utf-8"/>
5 63657f42 2022-09-07 stsp <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 63657f42 2022-09-07 stsp <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 63657f42 2022-09-07 stsp <title>GOTWEBD.CONF(5)</title>
9 63657f42 2022-09-07 stsp <!-- This is an automatically generated file. Do not edit.
10 63657f42 2022-09-07 stsp Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
12 63657f42 2022-09-07 stsp Permission to use, copy, modify, and distribute this software for any
13 63657f42 2022-09-07 stsp purpose with or without fee is hereby granted, provided that the above
14 63657f42 2022-09-07 stsp copyright notice and this permission notice appear in all copies.
16 63657f42 2022-09-07 stsp THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 63657f42 2022-09-07 stsp WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 63657f42 2022-09-07 stsp MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 63657f42 2022-09-07 stsp ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 63657f42 2022-09-07 stsp WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 63657f42 2022-09-07 stsp ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 63657f42 2022-09-07 stsp OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 63657f42 2022-09-07 stsp <div class="head" role="doc-pageheader" aria-label="Manual header
26 63657f42 2022-09-07 stsp line"><span class="head-ltitle">GOTWEBD.CONF(5)</span>
27 63657f42 2022-09-07 stsp <span class="head-vol">File Formats Manual</span>
28 63657f42 2022-09-07 stsp <span class="head-rtitle">GOTWEBD.CONF(5)</span></div>
29 63657f42 2022-09-07 stsp <main class="manual-text">
30 63657f42 2022-09-07 stsp <section class="Sh">
31 63657f42 2022-09-07 stsp <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 63657f42 2022-09-07 stsp <p class="Pp"><code class="Nm">gotwebd.conf</code> —
33 63657f42 2022-09-07 stsp <span class="Nd" role="doc-subtitle">gotwebd configuration file</span></p>
35 63657f42 2022-09-07 stsp <section class="Sh">
36 63657f42 2022-09-07 stsp <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
37 63657f42 2022-09-07 stsp <p class="Pp"><code class="Nm">gotwebd.conf</code> is the run-time configuration
38 63657f42 2022-09-07 stsp file for <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>.</p>
39 63657f42 2022-09-07 stsp <p class="Pp">The file format is line-based, with one configuration directive
40 63657f42 2022-09-07 stsp per line. Any lines beginning with a ‘#’ are treated as
41 63657f42 2022-09-07 stsp comments and ignored.</p>
42 742bb3a1 2022-10-24 stsp <p class="Pp">Macros can be defined that are later expanded in context. Macro
43 742bb3a1 2022-10-24 stsp names must start with a letter, digit, or underscore, and may contain any of
44 742bb3a1 2022-10-24 stsp those characters, but may not be reserved words. Macros are not expanded
45 742bb3a1 2022-10-24 stsp inside quotes. For example:</p>
46 742bb3a1 2022-10-24 stsp <div class="Bd Pp Bd-indent Li">
47 742bb3a1 2022-10-24 stsp <pre>lan_addr = "192.168.0.1"
48 742bb3a1 2022-10-24 stsp listen on $lan_addr</pre>
50 63657f42 2022-09-07 stsp <p class="Pp">Paths mentioned in <code class="Nm">gotwebd.conf</code> must be
51 63657f42 2022-09-07 stsp relative to <span class="Pa">/var/www</span>, the
52 63657f42 2022-09-07 stsp <a class="Xr" aria-label="chroot, section 2">chroot(2)</a> environment of
53 63657f42 2022-09-07 stsp <a class="Xr" aria-label="httpd, section 8">httpd(8)</a>.</p>
55 63657f42 2022-09-07 stsp <section class="Sh">
56 63657f42 2022-09-07 stsp <h2 class="Sh" id="GLOBAL_CONFIGURATION"><a class="permalink" href="#GLOBAL_CONFIGURATION">GLOBAL
57 63657f42 2022-09-07 stsp CONFIGURATION</a></h2>
58 63657f42 2022-09-07 stsp <p class="Pp">The available global configuration directives are as follows:</p>
59 63657f42 2022-09-07 stsp <dl class="Bl-tag">
60 63657f42 2022-09-07 stsp <dt id="chroot"><a class="permalink" href="#chroot"><code class="Ic">chroot</code></a>
61 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
62 3cde8558 2022-09-23 stsp <dd>Set the path to the <a class="Xr" aria-label="chroot, section
63 63657f42 2022-09-07 stsp 2">chroot(2)</a> environment of <a class="Xr" aria-label="httpd, section
64 63657f42 2022-09-07 stsp 8">httpd(8)</a>. If not specified then <span class="Pa">/var/www</span>
65 63657f42 2022-09-07 stsp will be used.</dd>
66 63657f42 2022-09-07 stsp <dt id="prefork"><a class="permalink" href="#prefork"><code class="Ic">prefork</code></a>
67 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
68 63657f42 2022-09-07 stsp <dd>Run the specified number of server processes.</dd>
69 63657f42 2022-09-07 stsp <dt id="unix_socket"><a class="permalink" href="#unix_socket"><code class="Ic">unix_socket</code></a>
70 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
71 63657f42 2022-09-07 stsp <dd>Controls whether the servers will listen on unix sockets by default.</dd>
72 63657f42 2022-09-07 stsp <dt id="unix_socket_name"><a class="permalink" href="#unix_socket_name"><code class="Ic">unix_socket_name</code></a>
73 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
74 63657f42 2022-09-07 stsp <dd>Set the path to the default unix socket.</dd>
77 63657f42 2022-09-07 stsp <section class="Sh">
78 63657f42 2022-09-07 stsp <h2 class="Sh" id="SERVER_CONFIGURATION"><a class="permalink" href="#SERVER_CONFIGURATION">SERVER
79 63657f42 2022-09-07 stsp CONFIGURATION</a></h2>
80 63657f42 2022-09-07 stsp <p class="Pp">At least one server context must exist for
81 63657f42 2022-09-07 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> to function. In
82 63657f42 2022-09-07 stsp case no server context is defined in the configuration file, a default
83 63657f42 2022-09-07 stsp server context will be used, which listens on a unix socket at
84 63657f42 2022-09-07 stsp <span class="Pa">/var/www/run/gotweb.sock</span> and uses default parameters
85 63657f42 2022-09-07 stsp for all applicable settings.</p>
86 63657f42 2022-09-07 stsp <p class="Pp">A server context is declared with a unique
87 63657f42 2022-09-07 stsp <var class="Ar">name</var>, followed by server-specific configuration
88 63657f42 2022-09-07 stsp directives inside curly braces:</p>
89 63657f42 2022-09-07 stsp <p class="Pp"><code class="Ic">server</code> <var class="Ar">name</var>
91 41ae98c9 2023-06-23 stsp <p class="Pp">The first server defined is used if the requested hostname is not
92 41ae98c9 2023-06-23 stsp matched by any server block.</p>
93 63657f42 2022-09-07 stsp <p class="Pp">The available server configuration directives are as follows:</p>
94 63657f42 2022-09-07 stsp <dl class="Bl-tag">
95 63657f42 2022-09-07 stsp <dt id="custom_css"><a class="permalink" href="#custom_css"><code class="Ic">custom_css</code></a>
96 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
97 63657f42 2022-09-07 stsp <dd>Set the path to a custom Cascading Style Sheet (CSS) to be used. If this
98 63657f42 2022-09-07 stsp option is not specified then a default style sheet will be used.</dd>
99 63657f42 2022-09-07 stsp <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
100 63657f42 2022-09-07 stsp on</code></a> <var class="Ar">address</var> <code class="Ic">port</code>
101 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
102 63657f42 2022-09-07 stsp <dd>Configure an address and port for incoming FCGI TCP connections. Valid
103 63657f42 2022-09-07 stsp <var class="Ar">address</var> arguments are hostnames, IP4 addresses, IPv6
104 63657f42 2022-09-07 stsp addresses, and network interface names. The <var class="Ar">port</var>
105 63657f42 2022-09-07 stsp argument may be number or a service name defined in
106 63657f42 2022-09-07 stsp <a class="Xr" aria-label="services, section 5">services(5)</a>.
107 63657f42 2022-09-07 stsp <p class="Pp">May be specified multiple times to build up a list of
108 63657f42 2022-09-07 stsp listening sockets. However, a given combination of address and port may
109 63657f42 2022-09-07 stsp only be used by one server.</p>
110 3cde8558 2022-09-23 stsp <p class="Pp">If a network interface name is given as
111 3cde8558 2022-09-23 stsp <var class="Ar">address</var> argument then
112 3cde8558 2022-09-23 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> will obtain
113 3cde8558 2022-09-23 stsp the list of addresses on this interface only on startup. Any future
114 3cde8558 2022-09-23 stsp changes to the address configuration of the interface will be
115 3cde8558 2022-09-23 stsp ignored.</p>
117 47f19dd5 2023-01-17 stsp <dt id="listen~2"><a class="permalink" href="#listen~2"><code class="Ic">listen
118 47f19dd5 2023-01-17 stsp on socket off</code></a></dt>
119 47f19dd5 2023-01-17 stsp <dd>Disable use of unix socket.</dd>
120 47f19dd5 2023-01-17 stsp <dt id="listen~3"><a class="permalink" href="#listen~3"><code class="Ic">listen
121 47f19dd5 2023-01-17 stsp on socket</code></a> <var class="Ar">path</var></dt>
122 47f19dd5 2023-01-17 stsp <dd>Set the path to the unix socket used by the server.</dd>
123 63657f42 2022-09-07 stsp <dt id="logo"><a class="permalink" href="#logo"><code class="Ic">logo</code></a>
124 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
125 63657f42 2022-09-07 stsp <dd>Set the path to an image file containing a logo to be displayed.</dd>
126 63657f42 2022-09-07 stsp <dt id="logo_url"><a class="permalink" href="#logo_url"><code class="Ic">logo_url</code></a>
127 63657f42 2022-09-07 stsp <var class="Ar">url</var></dt>
128 63657f42 2022-09-07 stsp <dd>Set a hyperlink for the logo.</dd>
129 63657f42 2022-09-07 stsp <dt id="max_commits_display"><a class="permalink" href="#max_commits_display"><code class="Ic">max_commits_display</code></a>
130 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
131 63657f42 2022-09-07 stsp <dd>Set the maximum amount of commits displayed per page.</dd>
132 63657f42 2022-09-07 stsp <dt id="max_repos"><a class="permalink" href="#max_repos"><code class="Ic">max_repos</code></a>
133 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
134 63657f42 2022-09-07 stsp <dd>Set the maximum amount of repositories <a class="Xr" aria-label="gotwebd,
135 63657f42 2022-09-07 stsp section 8">gotwebd(8)</a> will work with.</dd>
136 63657f42 2022-09-07 stsp <dt id="max_repos_display"><a class="permalink" href="#max_repos_display"><code class="Ic">max_repos_display</code></a>
137 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
138 63657f42 2022-09-07 stsp <dd>Set the maximum amount of repositories displayed on the index screen.</dd>
139 63657f42 2022-09-07 stsp <dt id="repos_path"><a class="permalink" href="#repos_path"><code class="Ic">repos_path</code></a>
140 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
141 63657f42 2022-09-07 stsp <dd>Set the path to the directory which contains Git repositories that the
142 63657f42 2022-09-07 stsp server should publish.</dd>
143 fd9580e1 2022-11-03 stsp <dt id="respect_exportok"><a class="permalink" href="#respect_exportok"><code class="Ic">respect_exportok</code></a>
144 fd9580e1 2022-11-03 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
145 fd9580e1 2022-11-03 stsp <dd>Set whether to display the repository only if it contains the magic
146 fd9580e1 2022-11-03 stsp <span class="Pa">git-daemon-export-ok</span> file.</dd>
147 63657f42 2022-09-07 stsp <dt id="show_repo_age"><a class="permalink" href="#show_repo_age"><code class="Ic">show_repo_age</code></a>
148 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
149 63657f42 2022-09-07 stsp <dd>Toggle display of last repository modification date.</dd>
150 63657f42 2022-09-07 stsp <dt id="show_repo_cloneurl"><a class="permalink" href="#show_repo_cloneurl"><code class="Ic">show_repo_cloneurl</code></a>
151 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
152 63657f42 2022-09-07 stsp <dd>Toggle display of clone URLs for a repository. This requires the creation
153 63657f42 2022-09-07 stsp of a <span class="Pa">cloneurl</span> file inside the repository which
154 63657f42 2022-09-07 stsp contains one URL per line.</dd>
155 63657f42 2022-09-07 stsp <dt id="show_repo_description"><a class="permalink" href="#show_repo_description"><code class="Ic">show_repo_description</code></a>
156 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
157 63657f42 2022-09-07 stsp <dd>Toggle display of the repository description. The
158 63657f42 2022-09-07 stsp <span class="Pa">description</span> file in the repository should be
159 63657f42 2022-09-07 stsp updated with an appropriate description.</dd>
160 63657f42 2022-09-07 stsp <dt id="show_repo_owner"><a class="permalink" href="#show_repo_owner"><code class="Ic">show_repo_owner</code></a>
161 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
162 63657f42 2022-09-07 stsp <dd>Set whether to display the repository owner. Displaying the owner requires
163 63657f42 2022-09-07 stsp owner information to be added to the <span class="Pa">config</span> file
164 63657f42 2022-09-07 stsp in the repository. <a class="Xr" aria-label="gotwebd, section
165 63657f42 2022-09-07 stsp 8">gotwebd(8)</a> will parse owner information from either a [gotweb] or a
166 63657f42 2022-09-07 stsp [gitweb] section. For example:
167 63657f42 2022-09-07 stsp <div class="Bd Pp Bd-indent Li">
168 63657f42 2022-09-07 stsp <pre>[gotweb]
169 63657f42 2022-09-07 stsp owner = "Your Name"</pre>
172 63657f42 2022-09-07 stsp <dt id="site_link"><a class="permalink" href="#site_link"><code class="Ic">site_link</code></a>
173 63657f42 2022-09-07 stsp <var class="Ar">string</var></dt>
174 63657f42 2022-09-07 stsp <dd>Set the displayed site link name for the index page.</dd>
175 63657f42 2022-09-07 stsp <dt id="site_name"><a class="permalink" href="#site_name"><code class="Ic">site_name</code></a>
176 63657f42 2022-09-07 stsp <var class="Ar">string</var></dt>
177 63657f42 2022-09-07 stsp <dd>Set the displayed site name title.</dd>
178 63657f42 2022-09-07 stsp <dt id="site_owner"><a class="permalink" href="#site_owner"><code class="Ic">site_owner</code></a>
179 63657f42 2022-09-07 stsp <var class="Ar">string</var></dt>
180 63657f42 2022-09-07 stsp <dd>Set the displayed site owner.</dd>
181 63657f42 2022-09-07 stsp <dt id="show_site_owner"><a class="permalink" href="#show_site_owner"><code class="Ic">show_site_owner</code></a>
182 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
183 63657f42 2022-09-07 stsp <dd>Toggle display of the site owner.</dd>
186 63657f42 2022-09-07 stsp <section class="Sh">
187 47f19dd5 2023-01-17 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
188 47f19dd5 2023-01-17 stsp <dl class="Bl-tag Bl-compact">
189 47f19dd5 2023-01-17 stsp <dt><span class="Pa">/etc/gotwebd.conf</span></dt>
190 47f19dd5 2023-01-17 stsp <dd>Default location of the <code class="Nm">gotwebd.conf</code> configuration
194 47f19dd5 2023-01-17 stsp <section class="Sh">
195 63657f42 2022-09-07 stsp <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
196 63657f42 2022-09-07 stsp <p class="Pp">These are the currently configurable items for
197 63657f42 2022-09-07 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> with their
198 63657f42 2022-09-07 stsp default values.</p>
199 63657f42 2022-09-07 stsp <div class="Bd Pp Bd-indent Li">
201 63657f42 2022-09-07 stsp # gotwebd options
202 63657f42 2022-09-07 stsp # all paths relative to /var/www (httpd chroot jail)
207 63657f42 2022-09-07 stsp server "localhost-unix" {
208 63657f42 2022-09-07 stsp repos_path "/got/public"
209 47f19dd5 2023-01-17 stsp listen on socket "/run/gotweb.sock"
211 47f19dd5 2023-01-17 stsp site_name "my public repos"
212 47f19dd5 2023-01-17 stsp site_owner "Got Owner"
213 47f19dd5 2023-01-17 stsp site_link "repos"
215 63657f42 2022-09-07 stsp logo "got.png"
216 63657f42 2022-09-07 stsp logo_url "https://gameoftrees.org"
218 63657f42 2022-09-07 stsp # on by default
219 f6a6fa94 2023-02-22 stsp #show_site_owner on
220 f6a6fa94 2023-02-22 stsp #show_repo_owner on
221 f6a6fa94 2023-02-22 stsp #show_repo_age on
222 41ae98c9 2023-06-23 stsp #show_repo_description on
223 f6a6fa94 2023-02-22 stsp #show_repo_cloneurl on
224 f6a6fa94 2023-02-22 stsp #respect_exportok off
226 f6a6fa94 2023-02-22 stsp #max_repos 0
227 63657f42 2022-09-07 stsp #max_repos_display 25
228 f6a6fa94 2023-02-22 stsp #max_commits_display 25
231 63657f42 2022-09-07 stsp # Example server context for FCGI over TCP connections:
232 63657f42 2022-09-07 stsp #server "localhost-tcp" {
233 63657f42 2022-09-07 stsp # repos_path "/got/public"
234 47f19dd5 2023-01-17 stsp # listen on socket off
235 63657f42 2022-09-07 stsp # listen on 127.0.0.1 port 9000
236 63657f42 2022-09-07 stsp # listen on ::1 port 9000
240 63657f42 2022-09-07 stsp <section class="Sh">
241 63657f42 2022-09-07 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
242 63657f42 2022-09-07 stsp ALSO</a></h2>
243 63657f42 2022-09-07 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
244 63657f42 2022-09-07 stsp <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
245 63657f42 2022-09-07 stsp <a class="Xr" aria-label="services, section 5">services(5)</a>,
246 63657f42 2022-09-07 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>,
247 63657f42 2022-09-07 stsp <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
250 63657f42 2022-09-07 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
251 14895951 2023-09-18 stsp line"><span class="foot-left"></span><span class="foot-date">September 18,
252 e68eaba8 2023-04-20 stsp 2023</span> <span class="foot-os">OpenBSD 7.3</span></div>
