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. Comments can be put anywhere in the file using a hash mark
41 (‘#’), and extend to the end of the current line. Arguments
42 names not beginning with a letter, digit or underscore, as well as reserved
43 words (such as <code class="Ic">listen</code>,
44 <code class="Ic">server</code> <span class="No">or</span>
45 <code class="Ic">user</code>), must be quoted. Arguments containing
46 whitespace should be surrounded by double quotes (").</p>
47 <p class="Pp">Macros can be defined that are later expanded in context. Macro
48 names must start with a letter, digit, or underscore, and may contain any of
49 those characters, but may not be reserved words. Macros are not expanded
50 inside quotes. For example:</p>
51 <div class="Bd Pp Bd-indent Li">
52 <pre>lan_addr = "192.168.0.1"
53 listen on $lan_addr port 9090</pre>
55 <p class="Pp">Paths mentioned in <code class="Nm">gotwebd.conf</code> must be
56 relative to <span class="Pa">/var/www</span>, the
57 <a class="Xr" aria-label="chroot, section 2">chroot(2)</a> environment of
58 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a>.</p>
61 <h2 class="Sh" id="GLOBAL_CONFIGURATION"><a class="permalink" href="#GLOBAL_CONFIGURATION">GLOBAL
62 CONFIGURATION</a></h2>
63 <p class="Pp">The available global configuration directives are as follows:</p>
65 <dt id="chroot"><a class="permalink" href="#chroot"><code class="Ic">chroot</code></a>
66 <var class="Ar">path</var></dt>
67 <dd>Set the path to the <a class="Xr" aria-label="chroot, section
68 2">chroot(2)</a> environment of <a class="Xr" aria-label="httpd, section
69 8">httpd(8)</a>. If not specified, it defaults to
70 <span class="Pa">/var/www</span>, the home directory of the www user.</dd>
71 <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
72 on</code></a> <var class="Ar">address</var> <code class="Ic">port</code>
73 <var class="Ar">number</var></dt>
74 <dd>Configure an address and port for incoming FastCGI connections. Valid
75 <var class="Ar">address</var> arguments are hostnames, IPv4 and IPv6
76 addresses. The <var class="Ar">port</var> argument may be number or a
77 service name defined in <a class="Xr" aria-label="services, section
78 5">services(5)</a>. May be specified multiple times to build up a list of
79 listening sockets.</dd>
80 <dt id="listen~2"><a class="permalink" href="#listen~2"><code class="Ic">listen
81 on socket</code></a> <var class="Ar">path</var></dt>
82 <dd>Configure a <span class="Ux">UNIX</span>-domain socket for incoming
83 FastCGI connections. May be specified multiple times to build up a list of
84 listening sockets.</dd>
85 <dt id="prefork"><a class="permalink" href="#prefork"><code class="Ic">prefork</code></a>
86 <var class="Ar">number</var></dt>
87 <dd>Run the specified number of server processes.
88 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> runs 3 server
89 processes by default.</dd>
90 <dt id="user"><a class="permalink" href="#user"><code class="Ic">user</code></a>
91 <var class="Ar">user</var></dt>
92 <dd>Set the <var class="Ar">user</var> which will run
93 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>. If not
94 specified, the user www will be used.</dd>
96 <p class="Pp">If no <code class="Ic">listen</code> directive is used,
97 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> will listen on
98 the <span class="Ux">UNIX</span>-domain socket at
99 <span class="Pa">/var/www/run/gotweb.sock</span>.</p>
102 <h2 class="Sh" id="SERVER_CONFIGURATION"><a class="permalink" href="#SERVER_CONFIGURATION">SERVER
103 CONFIGURATION</a></h2>
104 <p class="Pp">At least one server context must exist for
105 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a> to function. In
106 case no server context is defined in the configuration file, a default
107 server context will be used which uses default parameters for all applicable
109 <p class="Pp">A server context is declared with a unique
110 <var class="Ar">name</var>, followed by server-specific configuration
111 directives inside curly braces:</p>
112 <p class="Pp"><code class="Ic">server</code> <var class="Ar">name</var>
114 <p class="Pp">The first server defined is used if the requested hostname is not
115 matched by any server block.</p>
116 <p class="Pp">The available server configuration directives are as follows:</p>
118 <dt id="custom_css"><a class="permalink" href="#custom_css"><code class="Ic">custom_css</code></a>
119 <var class="Ar">path</var></dt>
120 <dd>Set the path to a custom Cascading Style Sheet (CSS) to be used. If this
121 option is not specified then the default style sheet
122 ‘gotweb.css’ will be used.</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. Defaults
126 to ‘got.png’.</dd>
127 <dt id="logo_url"><a class="permalink" href="#logo_url"><code class="Ic">logo_url</code></a>
128 <var class="Ar">url</var></dt>
129 <dd>Set a hyperlink for the logo. Defaults to
130 <a class="Lk" href="https://gameoftrees.org">https://gameoftrees.org</a>.</dd>
131 <dt id="max_commits_display"><a class="permalink" href="#max_commits_display"><code class="Ic">max_commits_display</code></a>
132 <var class="Ar">number</var></dt>
133 <dd>Set the maximum amount of commits and tags displayed per page. Defaults to
135 <dt id="max_repos_display"><a class="permalink" href="#max_repos_display"><code class="Ic">max_repos_display</code></a>
136 <var class="Ar">number</var></dt>
137 <dd>Set the maximum amount of repositories displayed on the index screen.
138 Defaults to 25. Set to zero to show all the repositories without
140 <dt id="repos_path"><a class="permalink" href="#repos_path"><code class="Ic">repos_path</code></a>
141 <var class="Ar">path</var></dt>
142 <dd>Set the path to the directory which contains Git repositories that the
143 server should publish. Defaults to <span class="Pa">/got/public</span>
144 under the chroot.</dd>
145 <dt id="respect_exportok"><a class="permalink" href="#respect_exportok"><code class="Ic">respect_exportok</code></a>
146 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
147 <dd>Set whether to display the repository only if it contains the magic
148 <span class="Pa">git-daemon-export-ok</span> file. Disabled by
150 <dt id="show_repo_age"><a class="permalink" href="#show_repo_age"><code class="Ic">show_repo_age</code></a>
151 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
152 <dd>Toggle display of last repository modification date. Enabled by
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. Enabled by default.</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. Enabled by default. 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. Enabled by default. This
167 requires the creation of an <span class="Pa">owner</span> file in the
168 repository or adding an ‘owner’ field under the [gotweb] or
169 [gitweb] section in the <span class="Pa">config</span> file inside the
170 repository. For example:
171 <div class="Bd Pp Bd-indent Li">
173 owner = "Your Name"</pre>
175 <p class="Pp">The <span class="Pa">owner</span> file has priority over the
176 <span class="Pa">config</span> if present.</p>
178 <dt id="site_link"><a class="permalink" href="#site_link"><code class="Ic">site_link</code></a>
179 <var class="Ar">string</var></dt>
180 <dd>Set the displayed site link name for the index page. Defaults to
181 ‘Repos’.</dd>
182 <dt id="site_name"><a class="permalink" href="#site_name"><code class="Ic">site_name</code></a>
183 <var class="Ar">string</var></dt>
184 <dd>Set the displayed site name title. Defaults to
185 ‘Gotweb’.</dd>
186 <dt id="site_owner"><a class="permalink" href="#site_owner"><code class="Ic">site_owner</code></a>
187 <var class="Ar">string</var></dt>
188 <dd>Set the displayed site owner. Defaults to ‘Got Owner’.</dd>
189 <dt id="show_site_owner"><a class="permalink" href="#show_site_owner"><code class="Ic">show_site_owner</code></a>
190 <var class="Ar">on</var> | <var class="Ar">off</var></dt>
191 <dd>Toggle display of the site owner. Enabled by default.</dd>
192 <dt id="summary_commits_display"><a class="permalink" href="#summary_commits_display"><code class="Ic">summary_commits_display</code></a>
193 <var class="Ar">number</var></dt>
194 <dd>The maximum number of commits to show in the summary page. Defaults to
196 <dt id="summary_tags_display"><a class="permalink" href="#summary_tags_display"><code class="Ic">summary_tags_display</code></a>
197 <var class="Ar">number</var></dt>
198 <dd>The maximum number of tags to show in the summary page. Defaults to
203 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
204 <dl class="Bl-tag Bl-compact">
205 <dt><span class="Pa">/etc/gotwebd.conf</span></dt>
206 <dd>Default location of the <code class="Nm">gotwebd.conf</code> configuration
208 <dt><span class="Pa">/var/www/run/gotweb.sock</span></dt>
209 <dd>Default location for the <a class="Xr" aria-label="gotwebd, section
210 8">gotwebd(8)</a> listening socket.</dd>
214 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
215 <p class="Pp">A sample configuration:</p>
216 <div class="Bd Pp Bd-indent Li">
217 <pre>server "localhost" {
218 site_name "my public repos"
219 site_owner "Flan Hacker"
220 site_link "Flan' Projects"
223 <p class="Pp">Another example, this time listening on a local port instead of
224 the implicit <span class="Ux">UNIX</span> socket.</p>
225 <div class="Bd Pp Bd-indent Li">
226 <pre>listen on 127.0.0.1 port 9000
227 listen on ::1 port 9000
229 server "localhost" {
230 site_name "my public repos"
235 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
237 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
238 <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
239 <a class="Xr" aria-label="services, section 5">services(5)</a>,
240 <a class="Xr" aria-label="gotwebd, section 8">gotwebd(8)</a>,
241 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
244 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
245 line"><span class="foot-left"></span><span class="foot-date">November 21,
246 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
