gotwebd/gotwebd.conf.5

   1 .\"
   2 .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
   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.CONF 5
  18 .Os
  19 .Sh NAME
  20 .Nm gotwebd.conf
  21 .Nd gotwebd configuration file
  22 .Sh DESCRIPTION
  23 .Nm
  24 is the run-time configuration file for
  25 .Xr gotwebd 8 .
  26 .Pp
  27 The file format is line-based, with one configuration directive per line.
  28 Comments can be put anywhere in the file using a hash mark
  29 .Pq Sq # ,
  30 and extend to the end of the current line.
  31 Arguments names not beginning with a letter, digit or underscore,
  32 as well as reserved words
  33 .Pq such as Ic listen , Ic server No or Ic user ,
  34 must be quoted.
  35 Arguments containing whitespace should be surrounded by double quotes
  36 .Pq \&" .
  37 .Pp
  38 Macros can be defined that are later expanded in context.
  39 Macro names must start with a letter, digit, or underscore, and may
  40 contain any of those characters, but may not be reserved words.
  41 Macros are not expanded inside quotes.
  42 For example:
  43 .Bd -literal -offset indent
  44 lan_addr = "192.168.0.1"
  45 listen on $lan_addr port 9090
  46 .Ed
  47 .Pp
  48 Paths mentioned in
  49 .Nm
  50 must be relative to
  51 .Pa /var/www ,
  52 the
  53 .Xr chroot 2
  54 environment of
  55 .Xr httpd 8 .
  56 .Sh GLOBAL CONFIGURATION
  57 The available global configuration directives are as follows:
  58 .Bl -tag -width Ds
  59 .It Ic chroot Ar path
  60 Set the path to the
  61 .Xr chroot 2
  62 environment of
  63 .Xr httpd 8 .
  64 If not specified, it defaults to
  65 .Pa /var/www ,
  66 the home directory of the www user.
  67 .It Ic listen on Ar address Ic port Ar number
  68 Configure an address and port for incoming FastCGI connections.
  69 Valid
  70 .Ar address
  71 arguments are hostnames, IPv4 and IPv6 addresses.
  72 The
  73 .Ar port
  74 argument may be number or a service name defined in
  75 .Xr services 5 .
  76 May be specified multiple times to build up a list of listening sockets.
  77 .It Ic listen on socket Ar path
  78 Configure a
  79 .Ux Ns -domain
  80 socket for incoming FastCGI connections.
  81 May be specified multiple times to build up a list of listening sockets.
  82 .It Ic prefork Ar number
  83 Run the specified number of server processes.
  84 .Xr gotwebd 8
  85 runs 3 server processes by default.
  86 .It Ic user Ar user
  87 Set the
  88 .Ar user
  89 which will run
  90 .Xr gotwebd 8 .
  91 If not specified, the user www will be used.
  92 .El
  93 .Pp
  94 If no
  95 .Ic listen
  96 directive is used,
  97 .Xr gotwebd 8
  98 will listen on the
  99 .Ux Ns -domain
 100 socket at
 101 .Pa /var/www/run/gotweb.sock .
 102 .Sh SERVER CONFIGURATION
 103 At least one server context must exist for
 104 .Xr gotwebd 8
 105 to function.
 106 In case no server context is defined in the configuration file, a default
 107 server context will be used which uses default parameters for all
 108 applicable settings.
 109 .Pp
 110 A server context is declared with a unique
 111 .Ar name ,
 112 followed by server-specific configuration directives inside curly braces:
 113 .Pp
 114 .Ic server Ar name Brq ...
 115 .Pp
 116 The first server defined is used if the requested hostname is not
 117 matched by any server block.
 118 .Pp
 119 The available server configuration directives are as follows:
 120 .Bl -tag -width Ds
 121 .It Ic custom_css Ar path
 122 Set the path to a custom Cascading Style Sheet (CSS) to be used.
 123 If this option is not specified then the default style sheet
 124 .Sq gotweb.css
 125 will be used.
 126 .It Ic logo Ar path
 127 Set the path to an image file containing a logo to be displayed.
 128 Defaults to
 129 .Sq got.png .
 130 .It Ic logo_url Ar url
 131 Set a hyperlink for the logo.
 132 Defaults to
 133 .Lk https://gameoftrees.org .
 134 .It Ic max_commits_display Ar number
 135 Set the maximum amount of commits and tags displayed per page.
 136 Defaults to 25.
 137 .It Ic max_repos_display Ar number
 138 Set the maximum amount of repositories displayed on the index screen.
 139 Defaults to 25.
 140 Set to zero to show all the repositories without pagination.
 141 .It Ic repos_path Ar path
 142 Set the path to the directory which contains Git repositories that
 143 the server should publish.
 144 Defaults to
 145 .Pa /got/public
 146 under the chroot.
 147 .It Ic respect_exportok Ar on | off
 148 Set whether to display the repository only if it contains the magic
 149 .Pa git-daemon-export-ok
 150 file.
 151 Disabled by default.
 152 .It Ic show_repo_age Ar on | off
 153 Toggle display of last repository modification date.
 154 Enabled by default.
 155 .It Ic show_repo_cloneurl Ar on | off
 156 Toggle display of clone URLs for a repository.
 157 This requires the creation of a
 158 .Pa cloneurl
 159 file inside the repository which contains one URL per line.
 160 Enabled by default.
 161 .It Ic show_repo_description Ar on | off
 162 Toggle display of the repository description.
 163 Enabled by default.
 164 The
 165 .Pa description
 166 file in the repository should be updated with an appropriate description.
 167 .It Ic show_repo_owner Ar on | off
 168 Set whether to display the repository owner.
 169 Enabled by default.
 170 This requires the creation of an
 171 .Pa owner
 172 file in the repository or adding an
 173 .Sq owner
 174 field under the [gotweb] or [gitweb] section in the
 175 .Pa config
 176 file inside the repository.
 177 For example:
 178 .Bd -literal -offset indent
 179 [gotweb]
 180 owner = "Your Name"
 181 .Ed
 182 .Pp
 183 The
 184 .Pa owner
 185 file has priority over the
 186 .Pa config
 187 if present.
 188 .It Ic site_link Ar string
 189 Set the displayed site link name for the index page.
 190 Defaults to
 191 .Sq Repos .
 192 .It Ic site_name Ar string
 193 Set the displayed site name title.
 194 Defaults to
 195 .Sq Gotweb .
 196 .It Ic site_owner Ar string
 197 Set the displayed site owner.
 198 Defaults to
 199 .Sq Got Owner .
 200 .It Ic show_site_owner Ar on | off
 201 Toggle display of the site owner.
 202 Enabled by default.
 203 .It Ic summary_commits_display Ar number
 204 The maximum number of commits to show in the summary page.
 205 Defaults to 10.
 206 .It Ic summary_tags_display Ar number
 207 The maximum number of tags to show in the summary page.
 208 Defaults to 3.
 209 .El
 210 .Sh FILES
 211 .Bl -tag -width Ds -compact
 212 .It Pa /etc/gotwebd.conf
 213 Default location of the
 214 .Nm
 215 configuration file.
 216 .It Pa /var/www/run/gotweb.sock
 217 Default location for the
 218 .Xr gotwebd 8
 219 listening socket.
 220 .El
 221 .Sh EXAMPLES
 222 A sample configuration:
 223 .Bd -literal -offset indent
 224 server "localhost" {
 225         site_name       "my public repos"
 226         site_owner      "Flan Hacker"
 227         site_link       "Flan' Projects"
 228 }
 229 .Ed
 230 .Pp
 231 Another example, this time listening on a local port instead of the
 232 implicit
 233 .Ux
 234 socket.
 235 .Bd -literal -offset indent
 236 listen on 127.0.0.1 port 9000
 237 listen on ::1 port 9000
 238
 239 server "localhost" {
 240         site_name "my public repos"
 241 }
 242 .Ed
 243 .Sh SEE ALSO
 244 .Xr got 1 ,
 245 .Xr httpd.conf 5 ,
 246 .Xr services 5 ,
 247 .Xr gotwebd 8 ,
 248 .Xr httpd 8