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