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 Any lines beginning with a
  29 .Sq #
  30 are treated as comments and ignored.
  31 .Pp
  32 Macros can be defined that are later expanded in context.
  33 Macro names must start with a letter, digit, or underscore, and may
  34 contain any of those characters, but may not be reserved words.
  35 Macros are not expanded inside quotes.
  36 For example:
  37 .Bd -literal -offset indent
  38 lan_addr = "192.168.0.1"
  39 listen on $lan_addr
  40 .Ed
  41 .Pp
  42 Paths mentioned in
  43 .Nm
  44 must be relative to
  45 .Pa /var/www ,
  46 the
  47 .Xr chroot 2
  48 environment of
  49 .Xr httpd 8 .
  50 .Sh GLOBAL CONFIGURATION
  51 The available global configuration directives are as follows:
  52 .Bl -tag -width Ds
  53 .It Ic chroot Ar path
  54 Set the path to the
  55 .Xr chroot 2
  56 environment of
  57 .Xr httpd 8 .
  58 If not specified then
  59 .Pa /var/www
  60 will be used.
  61 .It Ic prefork Ar number
  62 Run the specified number of server processes.
  63 .It Ic unix_socket Ar on | off
  64 Controls whether the servers will listen on unix sockets by default.
  65 .It Ic unix_socket_name Ar path
  66 Set the path to the default unix socket.
  67 .El
  68 .Sh SERVER CONFIGURATION
  69 At least one server context must exist for
  70 .Xr gotwebd 8
  71 to function.
  72 In case no server context is defined in the configuration file, a default
  73 server context will be used, which listens on a unix socket at
  74 .Pa /var/www/run/gotweb.sock
  75 and uses default parameters for all applicable settings.
  76 .Pp
  77 A server context is declared with a unique
  78 .Ar name ,
  79 followed by server-specific configuration directives inside curly braces:
  80 .Pp
  81 .Ic server Ar name Brq ...
  82 .Pp
  83 .Xr gotwebd 8
  84 is compatible with TLS Server Name Indication (SNI), provided the
  85 .Ar name
  86 of a server defined in
  87 .Nm
  88 corresponds to the name of a server defined in
  89 .Xr httpd.conf 5 .
  90 .Pp
  91 The available server configuration directives are as follows:
  92 .Bl -tag -width Ds
  93 .It Ic custom_css Ar path
  94 Set the path to a custom Cascading Style Sheet (CSS) to be used.
  95 If this option is not specified then a default style sheet will be used.
  96 .It Ic listen on Ar address Ic port Ar number
  97 Configure an address and port for incoming FCGI TCP connections.
  98 Valid
  99 .Ar address
 100 arguments are hostnames, IP4 addresses, IPv6 addresses, and network
 101 interface names.
 102 The
 103 .Ar port
 104 argument may be number or a service name defined in
 105 .Xr services 5 .
 106 .Pp
 107 May be specified multiple times to build up a list of listening sockets.
 108 However, a given combination of address and port may only be used by
 109 one server.
 110 .Pp
 111 If a network interface name is given as
 112 .Ar address
 113 argument then
 114 .Xr gotwebd 8
 115 will obtain the list of addresses on this interface only on startup.
 116 Any future changes to the address configuration of the interface will
 117 be ignored.
 118 .It Ic listen on socket off
 119 Disable use of unix socket.
 120 .It Ic listen on socket Ar path
 121 Set the path to the unix socket used by the server.
 122 .It Ic logo Ar path
 123 Set the path to an image file containing a logo to be displayed.
 124 .It Ic logo_url Ar url
 125 Set a hyperlink for the logo.
 126 .It Ic max_commits_display Ar number
 127 Set the maximum amount of commits displayed per page.
 128 .It Ic max_repos Ar number
 129 Set the maximum amount of repositories
 130 .Xr gotwebd 8
 131 will work with.
 132 .It Ic max_repos_display Ar number
 133 Set the maximum amount of repositories displayed on the index screen.
 134 .It Ic repos_path Ar path
 135 Set the path to the directory which contains Git repositories that
 136 the server should publish.
 137 .It Ic respect_exportok Ar on | off
 138 Set whether to display the repository only if it contains the magic
 139 .Pa git-daemon-export-ok
 140 file.
 141 .It Ic show_repo_age Ar on | off
 142 Toggle display of last repository modification date.
 143 .It Ic show_repo_cloneurl Ar on | off
 144 Toggle display of clone URLs for a repository.
 145 This requires the creation of a
 146 .Pa cloneurl
 147 file inside the repository which contains one URL per line.
 148 .It Ic show_repo_description Ar on | off
 149 Toggle display of the repository description.
 150 The
 151 .Pa description
 152 file in the repository should be updated with an appropriate description.
 153 .It Ic show_repo_owner Ar on | off
 154 Set whether to display the repository owner.
 155 Displaying the owner requires owner information to be added to the
 156 .Pa config
 157 file in the repository.
 158 .Xr gotwebd 8
 159 will parse owner information from either a [gotweb] or a [gitweb] section.
 160 For example:
 161 .Bd -literal -offset indent
 162 [gotweb]
 163 owner = "Your Name"
 164 .Ed
 165 .It Ic site_link Ar string
 166 Set the displayed site link name for the index page.
 167 .It Ic site_name Ar string
 168 Set the displayed site name title.
 169 .It Ic site_owner Ar string
 170 Set the displayed site owner.
 171 .It Ic show_site_owner Ar on | off
 172 Toggle display of the site owner.
 173 .El
 174 .Sh FILES
 175 .Bl -tag -width Ds -compact
 176 .It Pa /etc/gotwebd.conf
 177 Default location of the
 178 .Nm
 179 configuration file.
 180 .El
 181 .Sh EXAMPLES
 182 These are the currently configurable items for
 183 .Xr gotwebd 8
 184 with their default values.
 185 .Bd -literal -offset indent
 186 #
 187 # gotwebd options
 188 # all paths relative to /var/www (httpd chroot jail)
 189 #
 190
 191 prefork 3
 192
 193 server "localhost-unix" {
 194         repos_path "/got/public"
 195         listen on socket "/run/gotweb.sock"
 196
 197         site_name       "my public repos"
 198         site_owner      "Got Owner"
 199         site_link       "repos"
 200
 201         logo   "got.png"
 202         logo_url   "https://gameoftrees.org"
 203
 204         # on by default
 205         #show_site_owner  on
 206         #show_repo_owner  on
 207         #show_repo_age  on
 208         #show_repo_description no
 209         #show_repo_cloneurl  on
 210         #respect_exportok off
 211
 212         #max_repos   0
 213         #max_repos_display  25
 214         #max_commits_display  25
 215 }
 216
 217 # Example server context for FCGI over TCP connections:
 218 #server "localhost-tcp" {
 219 #       repos_path "/got/public"
 220 #       listen on socket off
 221 #       listen on 127.0.0.1 port 9000
 222 #       listen on ::1 port 9000
 223 #}
 224 .Ed
 225 .Sh SEE ALSO
 226 .Xr got 1 ,
 227 .Xr httpd.conf 5 ,
 228 .Xr services 5 ,
 229 .Xr gotwebd 8 ,
 230 .Xr httpd 8