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