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 # one gotwebd reachable at http://gotweb1.example.com/
136 server "gotweb1.example.com" {
138 root "/htdocs/gotwebd"
139 location "/" {
140 fastcgi socket "/run/gotweb.sock"
144 # hosting multiple gotwebd instances on the same HTTP server:
145 # http://gotweb2.example.com/gotwebd-unix/
146 # http://gotweb2.example.com/gotwebd-tcp/
147 server "gotweb2.example.com" {
149 location "/gotwebd-unix/" {
150 fastcgi socket "/run/gotweb.sock"
152 location "/gotwebd-unix/*" {
153 root "/htdocs/gotwebd"
156 location "/gotwebd-tcp/" {
157 fastcgi socket tcp 127.0.0.1 9000
159 location "/gotwebd-tcp/*" {
160 root "/htdocs/gotwebd"
167 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
169 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
170 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
171 <a class="Xr" aria-label="gotwebd.conf, section 5">gotwebd.conf(5)</a>,
172 <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
173 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
176 <h2 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h2>
177 <p class="Pp"><span class="An">Omar Polo</span>
178 <<a class="Mt" href="mailto:op@openbsd.org">op@openbsd.org</a>>
180 <span class="An">Stefan Sperling</span>
181 <<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>>
183 <span class="An">Tracey Emery</span>
184 <<a class="Mt" href="mailto:tracey@traceyemery.net">tracey@traceyemery.net</a>></p>
187 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
188 line"><span class="foot-left"></span><span class="foot-date">September 18,
189 2023</span> <span class="foot-os">OpenBSD 7.3</span></div>
