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(8)</title>
8 </head>
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.
23 -->
24 <body>
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">
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</code> &#x2014;
33 <span class="Nd" role="doc-subtitle">Game of Trees FastCGI server for web
34 browsers</span></p>
35 </section>
36 <section class="Sh">
37 <h2 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h2>
38 <table class="Nm">
39 <tr>
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>
44 </tr>
45 </table>
46 </section>
47 <section class="Sh">
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
54 options:</p>
55 <dl class="Bl-tag">
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
71 times.</dd>
72 </dl>
73 <p class="Pp">Enabling <code class="Nm">gotwebd</code> requires the following
74 steps:</p>
75 <ol class="Bl-enum">
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>
85 </div>
86 </li>
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>
103 </ol>
104 </section>
105 <section class="Sh">
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">/var/www/run/gotweb.sock</span></dt>
124 <dd>Default location for the <code class="Nm">gotwebd</code> listening
125 socket.</dd>
126 <dt><span class="Pa">/tmp/</span></dt>
127 <dd>Directory for temporary files created by
128 <code class="Nm">gotwebd</code>.</dd>
129 </dl>
130 </section>
131 <section class="Sh">
132 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
133 <p class="Pp">Example configuration for <a class="Xr" aria-label="httpd.conf,
134 section 5">httpd.conf(5)</a>:</p>
135 <div class="Bd Pp Bd-indent Li">
136 <pre>types { include &quot;/usr/share/misc/mime.types&quot; }
138 server &quot;example.com&quot; {
139 listen on * port 80
140 root &quot;/htdocs/gotwebd&quot;
141 location &quot;/&quot; {
142 fastcgi socket &quot;/run/gotweb.sock&quot;
144 }</pre>
145 </div>
146 <p class="Pp">Hosting multiple <code class="Nm">gotwebd</code> instances on the
147 same HTTP server under different path prefixes, with the first reached via
148 the default <span class="Ux">UNIX</span>-domain socket, the second
149 configured to listen on localhost port 9000:</p>
150 <div class="Bd Pp Bd-indent Li">
151 <pre>server &quot;example.com&quot; {
152 listen on * port 80
154 location &quot;/gotwebd-unix/&quot; {
155 fastcgi socket &quot;/run/gotweb.sock&quot;
157 location &quot;/gotwebd-unix/*&quot; {
158 root &quot;/htdocs/gotwebd&quot;
159 request strip 1
162 location &quot;/gotwebd-tcp/&quot; {
163 fastcgi socket tcp localhost 9000
165 location &quot;/gotwebd-tcp/*&quot; {
166 root &quot;/htdocs/gotwebd&quot;
167 request strip 1
169 }</pre>
170 </div>
171 </section>
172 <section class="Sh">
173 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
174 ALSO</a></h2>
175 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
176 <a class="Xr" aria-label="git-repository, section 5">git-repository(5)</a>,
177 <a class="Xr" aria-label="gotwebd.conf, section 5">gotwebd.conf(5)</a>,
178 <a class="Xr" aria-label="httpd.conf, section 5">httpd.conf(5)</a>,
179 <a class="Xr" aria-label="httpd, section 8">httpd(8)</a></p>
180 </section>
181 <section class="Sh">
182 <h2 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h2>
183 <p class="Pp"><span class="An">Omar Polo</span>
184 &lt;<a class="Mt" href="mailto:op@openbsd.org">op@openbsd.org</a>&gt;
185 <br/>
186 <span class="An">Stefan Sperling</span>
187 &lt;<a class="Mt" href="mailto:stsp@openbsd.org">stsp@openbsd.org</a>&gt;
188 <br/>
189 <span class="An">Tracey Emery</span>
190 &lt;<a class="Mt" href="mailto:tracey@traceyemery.net">tracey@traceyemery.net</a>&gt;</p>
191 </section>
192 </main>
193 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
194 line"><span class="foot-left"></span><span class="foot-date">November 21,
195 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
196 </body>
197 </html>