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>
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.
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">
31 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 <p class="Pp"><code class="Nm">gotwebd.conf</code> —
33 <span class="Nd" role="doc-subtitle">gotwebd configuration file</span></p>
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 ‘#’ 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 = "192.168.0.1"
48 listen on $lan_addr</pre>
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>
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>
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>
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>
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>
91 <p class="Pp">The first server defined is used if the requested hostname is not
92 matched by any server block.</p>
93 <p class="Pp">The available server configuration directives are as follows:</p>
95 <dt id="custom_css"><a class="permalink" href="#custom_css"><code class="Ic">custom_css</code></a>
96 <var class="Ar">path</var></dt>
97 <dd>Set the path to a custom Cascading Style Sheet (CSS) to be used. If this
98 option is not specified then a default style sheet will be used.</dd>
99 <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
100 on</code></a> <var class="Ar">address</var> <code class="Ic">port</code>
101 <var class="Ar">number</var></dt>
102 <dd>Configure an address and port for incoming FCGI TCP connections. Valid
103 <var class="Ar">address</var> arguments are hostnames, IP4 addresses, IPv6
104 addresses, and network interface names. The <var class="Ar">port</var>
105 argument may be number or a service name defined in
106 <a class="Xr" aria-label="services, section 5">services(5)</a>.
107 <p class="Pp">May be specified multiple times to build up a list of
108 listening sockets. However, a given combination of address and port may
109 only be used by one server.</p>
110 <p class="Pp">If a network interface name is given as
111 <var class="Ar">address</var> argument then
112 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> will obtain
113 the list of addresses on this interface only on startup. Any future
114 changes to the address configuration of the interface will be
117 <dt id="listen~2"><a class="permalink" href="#listen~2"><code class="Ic">listen
118 on socket off</code></a></dt>
119 <dd>Disable use of unix socket.</dd>
120 <dt id="listen~3"><a class="permalink" href="#listen~3"><code class="Ic">listen
121 on socket</code></a> <var class="Ar">path</var></dt>
122 <dd>Set the path to the unix socket used by the server.</dd>
123 <dt id="logo"><a class="permalink" href="#logo"><code class="Ic">logo</code></a>
124 <var class="Ar">path</var></dt>
125 <dd>Set the path to an image file containing a logo to be displayed.</dd>
126 <dt id="logo_url"><a class="permalink" href="#logo_url"><code class="Ic">logo_url</code></a>
127 <var class="Ar">url</var></dt>
128 <dd>Set a hyperlink for the logo.</dd>
129 <dt id="max_commits_display"><a class="permalink" href="#max_commits_display"><code class="Ic">max_commits_display</code></a>
130 <var class="Ar">number</var></dt>
131 <dd>Set the maximum amount of commits displayed per page.</dd>
132 <dt id="max_repos"><a class="permalink" href="#max_repos"><code class="Ic">max_repos</code></a>
133 <var class="Ar">number</var></dt>
134 <dd>Set the maximum amount of repositories <a class="Xr" aria-label="gotwebd,
135 section 8">gotwebd(8)</a> will work with.</dd>
136 <dt id="max_repos_display"><a class="permalink" href="#max_repos_display"><code class="Ic">max_repos_display</code></a>
137 <var class="Ar">number</var></dt>
138 <dd>Set the maximum amount of repositories displayed on the index screen.</dd>
139 <dt id="repos_path"><a class="permalink" href="#repos_path"><code class="Ic">repos_path</code></a>
140 <var class="Ar">path</var></dt>
141 <dd>Set the path to the directory which contains Git repositories that the
142 server should publish.</dd>
143 <dt id="respect_exportok"><a class="permalink" href="#respect_exportok"><code class="Ic">respect_exportok</code></a>
144 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
145 <dd>Set whether to display the repository only if it contains the magic
146 <span class="Pa">git-daemon-export-ok</span> file.</dd>
147 <dt id="show_repo_age"><a class="permalink" href="#show_repo_age"><code class="Ic">show_repo_age</code></a>
148 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
149 <dd>Toggle display of last repository modification date.</dd>
150 <dt id="show_repo_cloneurl"><a class="permalink" href="#show_repo_cloneurl"><code class="Ic">show_repo_cloneurl</code></a>
151 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
152 <dd>Toggle display of clone URLs for a repository. This requires the creation
153 of a <span class="Pa">cloneurl</span> file inside the repository which
154 contains one URL per line.</dd>
155 <dt id="show_repo_description"><a class="permalink" href="#show_repo_description"><code class="Ic">show_repo_description</code></a>
156 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
157 <dd>Toggle display of the repository description. The
158 <span class="Pa">description</span> file in the repository should be
159 updated with an appropriate description.</dd>
160 <dt id="show_repo_owner"><a class="permalink" href="#show_repo_owner"><code class="Ic">show_repo_owner</code></a>
161 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
162 <dd>Set whether to display the repository owner. Displaying the owner requires
163 owner information to be added to the <span class="Pa">config</span> file
164 in the repository. <a class="Xr" aria-label="gotwebd, section
165 8">gotwebd(8)</a> will parse owner information from either a [gotweb] or a
166 [gitweb] section. For example:
167 <div class="Bd Pp Bd-indent Li">
169 owner = "Your Name"</pre>
172 <dt id="site_link"><a class="permalink" href="#site_link"><code class="Ic">site_link</code></a>
173 <var class="Ar">string</var></dt>
174 <dd>Set the displayed site link name for the index page.</dd>
175 <dt id="site_name"><a class="permalink" href="#site_name"><code class="Ic">site_name</code></a>
176 <var class="Ar">string</var></dt>
177 <dd>Set the displayed site name title.</dd>
178 <dt id="site_owner"><a class="permalink" href="#site_owner"><code class="Ic">site_owner</code></a>
179 <var class="Ar">string</var></dt>
180 <dd>Set the displayed site owner.</dd>
181 <dt id="show_site_owner"><a class="permalink" href="#show_site_owner"><code class="Ic">show_site_owner</code></a>
182 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
183 <dd>Toggle display of the site owner.</dd>
187 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
188 <dl class="Bl-tag Bl-compact">
189 <dt><span class="Pa">/etc/gotwebd.conf</span></dt>
190 <dd>Default location of the <code class="Nm">gotwebd.conf</code> configuration
195 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
196 <p class="Pp">These are the currently configurable items for
197 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> with their
199 <div class="Bd Pp Bd-indent Li">
202 # all paths relative to /var/www (httpd chroot jail)
207 server "localhost-unix" {
208 repos_path "/got/public"
209 listen on socket "/run/gotweb.sock"
211 site_name "my public repos"
212 site_owner "Got Owner"
213 site_link "repos"
215 logo "got.png"
216 logo_url "https://gameoftrees.org"
222 #show_repo_description on
223 #show_repo_cloneurl on
224 #respect_exportok off
227 #max_repos_display 25
228 #max_commits_display 25
231 # Example server context for FCGI over TCP connections:
232 #server "localhost-tcp" {
233 # repos_path "/got/public"
234 # listen on socket off
235 # listen on 127.0.0.1 port 9000
236 # listen on ::1 port 9000
241 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
243 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
244 <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
245 <a class="Xr" aria-label="services, section 5">services(5)</a>,
246 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>,
247 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
250 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
251 line"><span class="foot-left"></span><span class="foot-date">August 29,
252 2023</span> <span class="foot-os">OpenBSD 7.3</span></div>
