Blob


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