Blob


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