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