Blame


1 63657f42 2022-09-07 stsp <!DOCTYPE html>
2 63657f42 2022-09-07 stsp <html>
3 63657f42 2022-09-07 stsp <head>
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>
8 63657f42 2022-09-07 stsp </head>
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>
11 63657f42 2022-09-07 stsp
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.
15 63657f42 2022-09-07 stsp
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.
23 63657f42 2022-09-07 stsp -->
24 63657f42 2022-09-07 stsp <body>
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> &#x2014;
33 63657f42 2022-09-07 stsp <span class="Nd" role="doc-subtitle">gotwebd configuration file</span></p>
34 63657f42 2022-09-07 stsp </section>
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 &#x2018;#&#x2019; 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 = &quot;192.168.0.1&quot;
48 742bb3a1 2022-10-24 stsp listen on $lan_addr</pre>
49 742bb3a1 2022-10-24 stsp </div>
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>
54 63657f42 2022-09-07 stsp </section>
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>
75 63657f42 2022-09-07 stsp </dl>
76 63657f42 2022-09-07 stsp </section>
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>
90 63657f42 2022-09-07 stsp {...}</p>
91 63657f42 2022-09-07 stsp <p class="Pp"><a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> is
92 63657f42 2022-09-07 stsp compatible with TLS Server Name Indication (SNI), provided the
93 63657f42 2022-09-07 stsp <var class="Ar">name</var> of a server defined in
94 63657f42 2022-09-07 stsp <code class="Nm">gotwebd.conf</code> corresponds to the name of a server
95 63657f42 2022-09-07 stsp defined in <a class="Xr" aria-label="httpd.conf, section
96 63657f42 2022-09-07 stsp 5">httpd.conf(5)</a>.</p>
97 63657f42 2022-09-07 stsp <p class="Pp">The available server configuration directives are as follows:</p>
98 63657f42 2022-09-07 stsp <dl class="Bl-tag">
99 63657f42 2022-09-07 stsp <dt id="custom_css"><a class="permalink" href="#custom_css"><code class="Ic">custom_css</code></a>
100 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
101 63657f42 2022-09-07 stsp <dd>Set the path to a custom Cascading Style Sheet (CSS) to be used. If this
102 63657f42 2022-09-07 stsp option is not specified then a default style sheet will be used.</dd>
103 63657f42 2022-09-07 stsp <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
104 63657f42 2022-09-07 stsp on</code></a> <var class="Ar">address</var> <code class="Ic">port</code>
105 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
106 63657f42 2022-09-07 stsp <dd>Configure an address and port for incoming FCGI TCP connections. Valid
107 63657f42 2022-09-07 stsp <var class="Ar">address</var> arguments are hostnames, IP4 addresses, IPv6
108 63657f42 2022-09-07 stsp addresses, and network interface names. The <var class="Ar">port</var>
109 63657f42 2022-09-07 stsp argument may be number or a service name defined in
110 63657f42 2022-09-07 stsp <a class="Xr" aria-label="services, section 5">services(5)</a>.
111 63657f42 2022-09-07 stsp <p class="Pp">May be specified multiple times to build up a list of
112 63657f42 2022-09-07 stsp listening sockets. However, a given combination of address and port may
113 63657f42 2022-09-07 stsp only be used by one server.</p>
114 3cde8558 2022-09-23 stsp <p class="Pp">If a network interface name is given as
115 3cde8558 2022-09-23 stsp <var class="Ar">address</var> argument then
116 3cde8558 2022-09-23 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> will obtain
117 3cde8558 2022-09-23 stsp the list of addresses on this interface only on startup. Any future
118 3cde8558 2022-09-23 stsp changes to the address configuration of the interface will be
119 3cde8558 2022-09-23 stsp ignored.</p>
120 63657f42 2022-09-07 stsp </dd>
121 47f19dd5 2023-01-17 stsp <dt id="listen~2"><a class="permalink" href="#listen~2"><code class="Ic">listen
122 47f19dd5 2023-01-17 stsp on socket off</code></a></dt>
123 47f19dd5 2023-01-17 stsp <dd>Disable use of unix socket.</dd>
124 47f19dd5 2023-01-17 stsp <dt id="listen~3"><a class="permalink" href="#listen~3"><code class="Ic">listen
125 47f19dd5 2023-01-17 stsp on socket</code></a> <var class="Ar">path</var></dt>
126 47f19dd5 2023-01-17 stsp <dd>Set the path to the unix socket used by the server.</dd>
127 63657f42 2022-09-07 stsp <dt id="logo"><a class="permalink" href="#logo"><code class="Ic">logo</code></a>
128 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
129 63657f42 2022-09-07 stsp <dd>Set the path to an image file containing a logo to be displayed.</dd>
130 63657f42 2022-09-07 stsp <dt id="logo_url"><a class="permalink" href="#logo_url"><code class="Ic">logo_url</code></a>
131 63657f42 2022-09-07 stsp <var class="Ar">url</var></dt>
132 63657f42 2022-09-07 stsp <dd>Set a hyperlink for the logo.</dd>
133 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>
134 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
135 63657f42 2022-09-07 stsp <dd>Set the maximum amount of commits displayed per page.</dd>
136 63657f42 2022-09-07 stsp <dt id="max_repos"><a class="permalink" href="#max_repos"><code class="Ic">max_repos</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 <a class="Xr" aria-label="gotwebd,
139 63657f42 2022-09-07 stsp section 8">gotwebd(8)</a> will work with.</dd>
140 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>
141 63657f42 2022-09-07 stsp <var class="Ar">number</var></dt>
142 63657f42 2022-09-07 stsp <dd>Set the maximum amount of repositories displayed on the index screen.</dd>
143 63657f42 2022-09-07 stsp <dt id="repos_path"><a class="permalink" href="#repos_path"><code class="Ic">repos_path</code></a>
144 63657f42 2022-09-07 stsp <var class="Ar">path</var></dt>
145 63657f42 2022-09-07 stsp <dd>Set the path to the directory which contains Git repositories that the
146 63657f42 2022-09-07 stsp server should publish.</dd>
147 fd9580e1 2022-11-03 stsp <dt id="respect_exportok"><a class="permalink" href="#respect_exportok"><code class="Ic">respect_exportok</code></a>
148 fd9580e1 2022-11-03 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
149 fd9580e1 2022-11-03 stsp <dd>Set whether to display the repository only if it contains the magic
150 fd9580e1 2022-11-03 stsp <span class="Pa">git-daemon-export-ok</span> file.</dd>
151 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>
152 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
153 63657f42 2022-09-07 stsp <dd>Toggle display of last repository modification date.</dd>
154 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>
155 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
156 63657f42 2022-09-07 stsp <dd>Toggle display of clone URLs for a repository. This requires the creation
157 63657f42 2022-09-07 stsp of a <span class="Pa">cloneurl</span> file inside the repository which
158 63657f42 2022-09-07 stsp contains one URL per line.</dd>
159 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>
160 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
161 63657f42 2022-09-07 stsp <dd>Toggle display of the repository description. The
162 63657f42 2022-09-07 stsp <span class="Pa">description</span> file in the repository should be
163 63657f42 2022-09-07 stsp updated with an appropriate description.</dd>
164 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>
165 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
166 63657f42 2022-09-07 stsp <dd>Set whether to display the repository owner. Displaying the owner requires
167 63657f42 2022-09-07 stsp owner information to be added to the <span class="Pa">config</span> file
168 63657f42 2022-09-07 stsp in the repository. <a class="Xr" aria-label="gotwebd, section
169 63657f42 2022-09-07 stsp 8">gotwebd(8)</a> will parse owner information from either a [gotweb] or a
170 63657f42 2022-09-07 stsp [gitweb] section. For example:
171 63657f42 2022-09-07 stsp <div class="Bd Pp Bd-indent Li">
172 63657f42 2022-09-07 stsp <pre>[gotweb]
173 63657f42 2022-09-07 stsp owner = &quot;Your Name&quot;</pre>
174 63657f42 2022-09-07 stsp </div>
175 63657f42 2022-09-07 stsp </dd>
176 63657f42 2022-09-07 stsp <dt id="site_link"><a class="permalink" href="#site_link"><code class="Ic">site_link</code></a>
177 63657f42 2022-09-07 stsp <var class="Ar">string</var></dt>
178 63657f42 2022-09-07 stsp <dd>Set the displayed site link name for the index page.</dd>
179 63657f42 2022-09-07 stsp <dt id="site_name"><a class="permalink" href="#site_name"><code class="Ic">site_name</code></a>
180 63657f42 2022-09-07 stsp <var class="Ar">string</var></dt>
181 63657f42 2022-09-07 stsp <dd>Set the displayed site name title.</dd>
182 63657f42 2022-09-07 stsp <dt id="site_owner"><a class="permalink" href="#site_owner"><code class="Ic">site_owner</code></a>
183 63657f42 2022-09-07 stsp <var class="Ar">string</var></dt>
184 63657f42 2022-09-07 stsp <dd>Set the displayed site owner.</dd>
185 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>
186 63657f42 2022-09-07 stsp <var class="Ar">on</var> | <var class="Ar">off</var></dt>
187 63657f42 2022-09-07 stsp <dd>Toggle display of the site owner.</dd>
188 63657f42 2022-09-07 stsp </dl>
189 63657f42 2022-09-07 stsp </section>
190 63657f42 2022-09-07 stsp <section class="Sh">
191 47f19dd5 2023-01-17 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
192 47f19dd5 2023-01-17 stsp <dl class="Bl-tag Bl-compact">
193 47f19dd5 2023-01-17 stsp <dt><span class="Pa">/etc/gotwebd.conf</span></dt>
194 47f19dd5 2023-01-17 stsp <dd>Default location of the <code class="Nm">gotwebd.conf</code> configuration
195 47f19dd5 2023-01-17 stsp file.</dd>
196 47f19dd5 2023-01-17 stsp </dl>
197 47f19dd5 2023-01-17 stsp </section>
198 47f19dd5 2023-01-17 stsp <section class="Sh">
199 63657f42 2022-09-07 stsp <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
200 63657f42 2022-09-07 stsp <p class="Pp">These are the currently configurable items for
201 63657f42 2022-09-07 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> with their
202 63657f42 2022-09-07 stsp default values.</p>
203 63657f42 2022-09-07 stsp <div class="Bd Pp Bd-indent Li">
204 63657f42 2022-09-07 stsp <pre>#
205 63657f42 2022-09-07 stsp # gotwebd options
206 63657f42 2022-09-07 stsp # all paths relative to /var/www (httpd chroot jail)
207 63657f42 2022-09-07 stsp #
208 63657f42 2022-09-07 stsp
209 f6a6fa94 2023-02-22 stsp prefork 3
210 63657f42 2022-09-07 stsp
211 63657f42 2022-09-07 stsp server &quot;localhost-unix&quot; {
212 63657f42 2022-09-07 stsp repos_path &quot;/got/public&quot;
213 47f19dd5 2023-01-17 stsp listen on socket &quot;/run/gotweb.sock&quot;
214 63657f42 2022-09-07 stsp
215 47f19dd5 2023-01-17 stsp site_name &quot;my public repos&quot;
216 47f19dd5 2023-01-17 stsp site_owner &quot;Got Owner&quot;
217 47f19dd5 2023-01-17 stsp site_link &quot;repos&quot;
218 63657f42 2022-09-07 stsp
219 63657f42 2022-09-07 stsp logo &quot;got.png&quot;
220 63657f42 2022-09-07 stsp logo_url &quot;https://gameoftrees.org&quot;
221 63657f42 2022-09-07 stsp
222 63657f42 2022-09-07 stsp # on by default
223 f6a6fa94 2023-02-22 stsp #show_site_owner on
224 f6a6fa94 2023-02-22 stsp #show_repo_owner on
225 f6a6fa94 2023-02-22 stsp #show_repo_age on
226 63657f42 2022-09-07 stsp #show_repo_description no
227 f6a6fa94 2023-02-22 stsp #show_repo_cloneurl on
228 f6a6fa94 2023-02-22 stsp #respect_exportok off
229 63657f42 2022-09-07 stsp
230 f6a6fa94 2023-02-22 stsp #max_repos 0
231 63657f42 2022-09-07 stsp #max_repos_display 25
232 f6a6fa94 2023-02-22 stsp #max_commits_display 25
233 63657f42 2022-09-07 stsp }
234 63657f42 2022-09-07 stsp
235 63657f42 2022-09-07 stsp # Example server context for FCGI over TCP connections:
236 63657f42 2022-09-07 stsp #server &quot;localhost-tcp&quot; {
237 63657f42 2022-09-07 stsp # repos_path &quot;/got/public&quot;
238 47f19dd5 2023-01-17 stsp # listen on socket off
239 63657f42 2022-09-07 stsp # listen on 127.0.0.1 port 9000
240 63657f42 2022-09-07 stsp # listen on ::1 port 9000
241 63657f42 2022-09-07 stsp #}</pre>
242 63657f42 2022-09-07 stsp </div>
243 63657f42 2022-09-07 stsp </section>
244 63657f42 2022-09-07 stsp <section class="Sh">
245 63657f42 2022-09-07 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
246 63657f42 2022-09-07 stsp ALSO</a></h2>
247 63657f42 2022-09-07 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
248 63657f42 2022-09-07 stsp <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
249 63657f42 2022-09-07 stsp <a class="Xr" aria-label="services, section 5">services(5)</a>,
250 63657f42 2022-09-07 stsp <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>,
251 63657f42 2022-09-07 stsp <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
252 63657f42 2022-09-07 stsp </section>
253 63657f42 2022-09-07 stsp </main>
254 63657f42 2022-09-07 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
255 f6a6fa94 2023-02-22 stsp line"><span class="foot-left"></span><span class="foot-date">February 22,
256 47f19dd5 2023-01-17 stsp 2023</span> <span class="foot-os">OpenBSD 7.2</span></div>
257 63657f42 2022-09-07 stsp </body>
258 63657f42 2022-09-07 stsp </html>