Blame


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