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(8)</title>
9 <!-- This is an automatically generated file. Do not edit.
10 Copyright (c) 2020 Stefan Sperling
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(8)</span>
27 <span class="head-vol">System Manager's Manual</span>
28 <span class="head-rtitle">GOTWEBD(8)</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</code> —
33 <span class="Nd" role="doc-subtitle">Game of Trees Git FastCGI repository
34 server for web browsers</span></p>
37 <h2 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h2>
40 <td><code class="Nm">gotwebd</code></td>
41 <td>[<code class="Fl">-dnv</code>] [<code class="Fl">-D</code>
42 <var class="Ar">macro</var>=<var class="Ar">value</var>]
43 [<code class="Fl">-f</code> <var class="Ar">file</var>]</td>
48 <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
49 <p class="Pp"><code class="Nm">gotwebd</code> is a FastCGI server program which
50 can display the contents of Git repositories via a web browser. The program
51 has been designed to work out of the box with the
52 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a> web server.</p>
53 <p class="Pp"><code class="Nm">gotwebd</code> provides the following
56 <dt id="D"><a class="permalink" href="#D"><code class="Fl">-D</code></a>
57 <var class="Ar">macro</var>=<var class="Ar">value</var></dt>
58 <dd>Define <var class="Ar">macro</var> to be set to
59 <var class="Ar">value</var>. Overrides the definition of
60 <var class="Ar">macro</var> in the configuration file.</dd>
61 <dt id="d"><a class="permalink" href="#d"><code class="Fl">-d</code></a></dt>
62 <dd>Do not daemonize. Send log output to stderr.</dd>
63 <dt id="f"><a class="permalink" href="#f"><code class="Fl">-f</code></a>
64 <var class="Ar">file</var></dt>
65 <dd>Set the path to the configuration file. If not specified, the file
66 <span class="Pa">/etc/gotwebd.conf</span> will be used.</dd>
67 <dt id="n"><a class="permalink" href="#n"><code class="Fl">-n</code></a></dt>
68 <dd>Parse the configuration file, report errors if any, and exit.</dd>
69 <dt id="v"><a class="permalink" href="#v"><code class="Fl">-v</code></a></dt>
70 <dd>Verbose mode. Verbosity increases if this option is used multiple
73 <p class="Pp">Enabling <code class="Nm">gotwebd</code> requires the following
76 <li>The <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>
77 configuration file must be adjusted to run <code class="Nm">gotwebd</code>
78 as a FastCGI helper program. The
79 <a class="Sx" href="#EXAMPLES">EXAMPLES</a> section below contains an
80 appropriate configuration file sample.</li>
81 <li>httpd(8) must be enabled and started:
82 <div class="Bd Pp Bd-indent Li">
83 <pre> # rcctl enable httpd
84 # rcctl start httpd</pre>
87 <li>Optionally, the run-time behaviour of <code class="Nm">gotwebd</code> can
88 be configured via the <a class="Xr" aria-label="gotwebd.conf, section
89 5">gotwebd.conf(5)</a> configuration file.</li>
90 <li id="not">Git repositories must be created at a suitable location inside
91 the web server's <a class="Xr" aria-label="chroot, section
92 2">chroot(2)</a> environment. These repositories should
93 <a class="permalink" href="#not"><i class="Em">not</i></a> be writable by
94 the user ID shared between <code class="Nm">gotwebd</code> and
95 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a>. The default
96 location for repositories published by <code class="Nm">gotwebd</code> is
97 <span class="Pa">/var/www/got/public</span>.</li>
98 <li>Git repositories served by <code class="Nm">gotwebd</code> should be kept
99 up-to-date with a mechanism such as <code class="Cm">got fetch</code>,
100 <a class="Xr" aria-label="git-fetch, section 1">git-fetch(1)</a>, or
101 <a class="Xr" aria-label="rsync, section 1">rsync(1)</a>, scheduled by
102 <a class="Xr" aria-label="cron, section 8">cron(8)</a>.</li>
106 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
107 <dl class="Bl-tag Bl-compact">
108 <dt><span class="Pa">/etc/gotwebd.conf</span></dt>
109 <dd>Default location of the <a class="Xr" aria-label="gotwebd.conf, section
110 5">gotwebd.conf(5)</a> configuration file.</dd>
111 <dt><span class="Pa">/var/www/got/public/</span></dt>
112 <dd>Default location for Git repositories served by
113 <code class="Nm">gotwebd</code>. This location can be adjusted in the
114 <a class="Xr" aria-label="gotwebd.conf, section 5">gotwebd.conf(5)</a>
115 configuration file.</dd>
116 <dt><span class="Pa">/var/www/bin/gotwebd/</span></dt>
117 <dd>Directory containing statically linked <a class="Xr" aria-label="got,
118 section 1">got(1)</a> helper programs which are run by
119 <code class="Nm">gotwebd</code> to read Git repositories.</dd>
120 <dt><span class="Pa">/var/www/htdocs/gotwebd/</span></dt>
121 <dd>Directory containing HTML, CSS, and image files used by
122 <code class="Nm">gotwebd</code>.</dd>
123 <dt><span class="Pa">/tmp/</span></dt>
124 <dd>Directory for temporary files created by
125 <code class="Nm">gotwebd</code>.</dd>
129 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
130 <p class="Pp">Example configuration for <a class="Xr" aria-label="httpd.conf,
131 section 5">httpd.conf(5)</a>:</p>
132 <div class="Bd Pp Bd-indent Li">
133 <pre>types { include "/usr/share/misc/mime.types" }
135 server "example.com" {
137 root "/htdocs/gotwebd"
138 location "/" {
139 fastcgi socket "/run/gotweb.sock"
143 <p class="Pp">Hosting multiple <code class="Nm">gotwebd</code> instances on the
144 same HTTP server under different path prefixes, with the first reached via
145 the default <span class="Ux">UNIX</span>-domain socket, the second
146 configured to listen on localhost port 9000:</p>
147 <div class="Bd Pp Bd-indent Li">
148 <pre>server "example.com" {
151 location "/gotwebd-unix/" {
152 fastcgi socket "/run/gotweb.sock"
154 location "/gotwebd-unix/*" {
155 root "/htdocs/gotwebd"
159 location "/gotwebd-tcp/" {
160 fastcgi socket tcp localhost 9000
162 location "/gotwebd-tcp/*" {
163 root "/htdocs/gotwebd"
170 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
172 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
173 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
174 <a class="Xr" aria-label="gotwebd.conf, section 5">gotwebd.conf(5)</a>,
175 <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
176 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
179 <h2 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h2>
180 <p class="Pp"><span class="An">Omar Polo</span>
181 <<a class="Mt" href="mailto:op@openbsd.org">op@openbsd.org</a>>
183 <span class="An">Stefan Sperling</span>
184 <<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>>
186 <span class="An">Tracey Emery</span>
187 <<a class="Mt" href="mailto:tracey@traceyemery.net">tracey@traceyemery.net</a>></p>
190 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
191 line"><span class="foot-left"></span><span class="foot-date">March 11,
192 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
