gotwebd/gotwebd.8

   1 .\"
   2 .\" Copyright (c) 2020 Stefan Sperling
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GOTWEBD 8
  18 .Os
  19 .Sh NAME
  20 .Nm gotwebd
  21 .Nd Game of Trees FastCGI server for web browsers
  22 .Sh SYNOPSIS
  23 .Nm
  24 .Op Fl dnv
  25 .Op Fl D Ar macro Ns = Ns Ar value
  26 .Op Fl f Ar file
  27 .Sh DESCRIPTION
  28 .Nm
  29 is a FastCGI server program which can display the contents of Git
  30 repositories via a web browser.
  31 The program has been designed to work out of the box with
  32 the
  33 .Xr httpd 8
  34 web server.
  35 .Pp
  36 .Nm
  37 provides the following options:
  38 .Bl -tag -width tenletters
  39 .It Fl D Ar macro Ns = Ns Ar value
  40 Define
  41 .Ar macro
  42 to be set to
  43 .Ar value .
  44 Overrides the definition of
  45 .Ar macro
  46 in the configuration file.
  47 .It Fl d
  48 Do not daemonize.
  49 Send log output to stderr.
  50 .It Fl f Ar file
  51 Set the path to the configuration file.
  52 If not specified, the file
  53 .Pa /etc/gotwebd.conf
  54 will be used.
  55 .It Fl n
  56 Parse the configuration file, report errors if any, and exit.
  57 .It Fl v
  58 Verbose mode.
  59 Verbosity increases if this option is used multiple times.
  60 .El
  61 .Pp
  62 Enabling
  63 .Nm
  64 requires the following steps:
  65 .Bl -enum
  66 .It
  67 The
  68 .Xr httpd.conf 5
  69 configuration file must be adjusted to run
  70 .Nm
  71 as a FastCGI helper program.
  72 The
  73 .Sx EXAMPLES
  74 section below contains an appropriate configuration file sample.
  75 .It
  76 httpd(8) must be enabled and started:
  77 .Bd -literal -offset indent
  78   # rcctl enable httpd
  79   # rcctl start httpd
  80 .Ed
  81 .It
  82 Optionally, the run-time behaviour of
  83 .Nm
  84 can be configured via the
  85 .Xr gotwebd.conf 5
  86 configuration file.
  87 .It
  88 Git repositories must be created at a suitable location inside the
  89 web server's
  90 .Xr chroot 2
  91 environment.
  92 These repositories should
  93 .Em not
  94 be writable by the user ID shared between
  95 .Nm
  96 and
  97 .Xr httpd 8 .
  98 The default location for repositories published by
  99 .Nm
 100 is
 101 .Pa /var/www/got/public .
 102 .It
 103 Git repositories served by
 104 .Nm
 105 should be kept up-to-date with a mechanism such as
 106 .Cm got fetch ,
 107 .Xr git-fetch 1 ,
 108 or
 109 .Xr rsync 1 ,
 110 scheduled by
 111 .Xr cron 8 .
 112 .El
 113 .Sh FILES
 114 .Bl -tag -width /var/www/got/public/ -compact
 115 .It Pa /etc/gotwebd.conf
 116 Default location of the
 117 .Xr gotwebd.conf 5
 118 configuration file.
 119 .It Pa /var/www/got/public/
 120 Default location for Git repositories served by
 121 .Nm .
 122 This location can be adjusted in the
 123 .Xr gotwebd.conf 5
 124 configuration file.
 125 .It Pa /var/www/bin/gotwebd/
 126 Directory containing statically linked
 127 .Xr got 1
 128 helper programs which are run by
 129 .Nm
 130 to read Git repositories.
 131 .It Pa /var/www/htdocs/gotwebd/
 132 Directory containing HTML, CSS, and image files used by
 133 .Nm .
 134 .It Pa /var/www/run/gotweb.sock
 135 Default location for the
 136 .Nm
 137 listening socket.
 138 .It Pa /tmp/
 139 Directory for temporary files created by
 140 .Nm .
 141 .El
 142 .Sh EXAMPLES
 143 Example configuration for
 144 .Xr httpd.conf 5 :
 145 .Bd -literal -offset indent
 146 types { include "/usr/share/misc/mime.types" }
 147
 148 server "example.com" {
 149         listen on * port 80
 150         root "/htdocs/gotwebd"
 151         location "/" {
 152                 fastcgi socket "/run/gotweb.sock"
 153         }
 154 }
 155 .Ed
 156 .Pp
 157 Hosting multiple
 158 .Nm gotwebd
 159 instances on the same HTTP server under different path prefixes, with
 160 the first reached via the default
 161 .Ux Ns -domain socket, the second configured to listen on localhost
 162 port 9000:
 163 .Bd -literal -offset indent
 164 server "example.com" {
 165         listen on * port 80
 166
 167         location "/gotwebd-unix/" {
 168                 fastcgi socket "/run/gotweb.sock"
 169         }
 170         location "/gotwebd-unix/*" {
 171                 root "/htdocs/gotwebd"
 172                 request strip 1
 173         }
 174
 175         location "/gotwebd-tcp/" {
 176                 fastcgi socket tcp localhost 9000
 177         }
 178         location "/gotwebd-tcp/*" {
 179                 root "/htdocs/gotwebd"
 180                 request strip 1
 181         }
 182 }
 183 .Ed
 184 .Sh SEE ALSO
 185 .Xr got 1 ,
 186 .Xr git-repository 5 ,
 187 .Xr gotwebd.conf 5 ,
 188 .Xr httpd.conf 5 ,
 189 .Xr httpd 8
 190 .Sh AUTHORS
 191 .An Omar Polo Aq Mt op@openbsd.org
 192 .An Stefan Sperling Aq Mt stsp@openbsd.org
 193 .An Tracey Emery Aq Mt tracey@traceyemery.net