Blame


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