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 port 9090</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.
69 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> runs 3 server
70 processes by default.</dd>
71 <dt id="unix_socket"><a class="permalink" href="#unix_socket"><code class="Ic">unix_socket</code></a>
72 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
73 <dd>Controls whether the servers will listen on unix sockets by default.
74 Listening on unix sockets is the default.</dd>
75 <dt id="unix_socket_name"><a class="permalink" href="#unix_socket_name"><code class="Ic">unix_socket_name</code></a>
76 <var class="Ar">path</var></dt>
77 <dd>Set the path to the default unix socket. Defaults to
78 <span class="Pa">/var/www/run/gotweb.sock</span>.</dd>
82 <h2 class="Sh" id="SERVER_CONFIGURATION"><a class="permalink" href="#SERVER_CONFIGURATION">SERVER
83 CONFIGURATION</a></h2>
84 <p class="Pp">At least one server context must exist for
85 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> to function. In
86 case no server context is defined in the configuration file, a default
87 server context will be used, which listens on a unix socket at
88 <span class="Pa">/var/www/run/gotweb.sock</span> and uses default parameters
89 for all applicable settings.</p>
90 <p class="Pp">A server context is declared with a unique
91 <var class="Ar">name</var>, followed by server-specific configuration
92 directives inside curly braces:</p>
93 <p class="Pp"><code class="Ic">server</code> <var class="Ar">name</var>
95 <p class="Pp">The first server defined is used if the requested hostname is not
96 matched by any server block.</p>
97 <p class="Pp">The available server configuration directives are as follows:</p>
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 the default style sheet
103 ‘gotweb.css’ will be used.</dd>
104 <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
105 on</code></a> <var class="Ar">address</var> <code class="Ic">port</code>
106 <var class="Ar">number</var></dt>
107 <dd>Configure an address and port for incoming FastCGI connections. Valid
108 <var class="Ar">address</var> arguments are hostnames, IPv4 and IPv6
109 addresses. The <var class="Ar">port</var> argument may be number or a
110 service name defined in <a class="Xr" aria-label="services, section
112 <p class="Pp">May be specified multiple times to build up a list of
113 listening sockets. However, a given combination of address and port may
114 only be used by one server.</p>
116 <dt id="listen~2"><a class="permalink" href="#listen~2"><code class="Ic">listen
117 on socket off</code></a></dt>
118 <dd>Disable use of unix socket.</dd>
119 <dt id="listen~3"><a class="permalink" href="#listen~3"><code class="Ic">listen
120 on socket</code></a> <var class="Ar">path</var></dt>
121 <dd>Set the path to the unix socket used by the server.</dd>
122 <dt id="logo"><a class="permalink" href="#logo"><code class="Ic">logo</code></a>
123 <var class="Ar">path</var></dt>
124 <dd>Set the path to an image file containing a logo to be displayed. Defaults
125 to ‘got.png’.</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. Defaults to
129 <a class="Lk" href="https://gameoftrees.org">https://gameoftrees.org</a>.</dd>
130 <dt id="max_commits_display"><a class="permalink" href="#max_commits_display"><code class="Ic">max_commits_display</code></a>
131 <var class="Ar">number</var></dt>
132 <dd>Set the maximum amount of commits and tags displayed per page. Defaults to
134 <dt id="max_repos_display"><a class="permalink" href="#max_repos_display"><code class="Ic">max_repos_display</code></a>
135 <var class="Ar">number</var></dt>
136 <dd>Set the maximum amount of repositories displayed on the index screen.
137 Defaults to 25. Set to zero to show all the repositories without
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. Defaults to
143 <span class="Pa">/run/gotwebd.sock</span> under the chroot.</dd>
144 <dt id="respect_exportok"><a class="permalink" href="#respect_exportok"><code class="Ic">respect_exportok</code></a>
145 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
146 <dd>Set whether to display the repository only if it contains the magic
147 <span class="Pa">git-daemon-export-ok</span> file. Disabled by
149 <dt id="show_repo_age"><a class="permalink" href="#show_repo_age"><code class="Ic">show_repo_age</code></a>
150 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
151 <dd>Toggle display of last repository modification date. Enabled by
153 <dt id="show_repo_cloneurl"><a class="permalink" href="#show_repo_cloneurl"><code class="Ic">show_repo_cloneurl</code></a>
154 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
155 <dd>Toggle display of clone URLs for a repository. This requires the creation
156 of a <span class="Pa">cloneurl</span> file inside the repository which
157 contains one URL per line. Enabled by default.</dd>
158 <dt id="show_repo_description"><a class="permalink" href="#show_repo_description"><code class="Ic">show_repo_description</code></a>
159 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
160 <dd>Toggle display of the repository description. Enabled by default. The
161 <span class="Pa">description</span> file in the repository should be
162 updated with an appropriate description.</dd>
163 <dt id="show_repo_owner"><a class="permalink" href="#show_repo_owner"><code class="Ic">show_repo_owner</code></a>
164 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
165 <dd>Set whether to display the repository owner. Enabled by default.
166 Displaying the owner requires owner information to be added to the
167 <span class="Pa">config</span> file in the repository.
168 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> will parse
169 owner information from either a [gotweb] or a [gitweb] section. For
171 <div class="Bd Pp Bd-indent Li">
173 owner = "Your Name"</pre>
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. Defaults to
179 ‘Repos’.</dd>
180 <dt id="site_name"><a class="permalink" href="#site_name"><code class="Ic">site_name</code></a>
181 <var class="Ar">string</var></dt>
182 <dd>Set the displayed site name title. Defaults to
183 ‘Gotweb’.</dd>
184 <dt id="site_owner"><a class="permalink" href="#site_owner"><code class="Ic">site_owner</code></a>
185 <var class="Ar">string</var></dt>
186 <dd>Set the displayed site owner. Defaults to ‘Got Owner’.</dd>
187 <dt id="show_site_owner"><a class="permalink" href="#show_site_owner"><code class="Ic">show_site_owner</code></a>
188 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
189 <dd>Toggle display of the site owner. Enabled by default.</dd>
190 <dt id="summary_commits_display"><a class="permalink" href="#summary_commits_display"><code class="Ic">summary_commits_display</code></a>
191 <var class="Ar">number</var></dt>
192 <dd>The maximum number of commits to show in the summary page. Defaults to
194 <dt id="summary_tags_display"><a class="permalink" href="#summary_tags_display"><code class="Ic">summary_tags_display</code></a>
195 <var class="Ar">number</var></dt>
196 <dd>The maximum number of tags to show in the summary page. Defaults to
201 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
202 <dl class="Bl-tag Bl-compact">
203 <dt><span class="Pa">/etc/gotwebd.conf</span></dt>
204 <dd>Default location of the <code class="Nm">gotwebd.conf</code> configuration
209 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
210 <p class="Pp">A sample configuration:</p>
211 <div class="Bd Pp Bd-indent Li">
212 <pre>server "localhost" {
213 site_name "my public repos"
214 site_owner "Flan Hacker"
215 site_link "Flan' Projects"
218 <p class="Pp">Another example, this time listening on a local port instead of
219 the implicit <span class="Ux">UNIX</span> socket.</p>
220 <div class="Bd Pp Bd-indent Li">
221 <pre>server "localhost" {
223 listen on 127.0.0.1 port 9000
224 listen on ::1 port 9000
229 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
231 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
232 <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
233 <a class="Xr" aria-label="services, section 5">services(5)</a>,
234 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>,
235 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
238 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
239 line"><span class="foot-left"></span><span class="foot-date">March 11,
240 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
