1 a596b957 2022-07-14 tracey .\"
  2 a596b957 2022-07-14 tracey .\" Copyright (c) 2020 Tracey Emery <tracey@traceyemery.net>
  3 a596b957 2022-07-14 tracey .\"
  4 a596b957 2022-07-14 tracey .\" Permission to use, copy, modify, and distribute this software for any
  5 a596b957 2022-07-14 tracey .\" purpose with or without fee is hereby granted, provided that the above
  6 a596b957 2022-07-14 tracey .\" copyright notice and this permission notice appear in all copies.
  7 a596b957 2022-07-14 tracey .\"
  8 a596b957 2022-07-14 tracey .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9 a596b957 2022-07-14 tracey .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10 a596b957 2022-07-14 tracey .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11 a596b957 2022-07-14 tracey .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12 a596b957 2022-07-14 tracey .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13 a596b957 2022-07-14 tracey .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14 a596b957 2022-07-14 tracey .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15 a596b957 2022-07-14 tracey .\"
 16 a596b957 2022-07-14 tracey .Dd $Mdocdate$
 17 59975c69 2022-08-29 stsp .Dt GOTWEBD.CONF 5
 18 a596b957 2022-07-14 tracey .Os
 19 a596b957 2022-07-14 tracey .Sh NAME
 20 59975c69 2022-08-29 stsp .Nm gotwebd.conf
 21 59975c69 2022-08-29 stsp .Nd gotwebd configuration file
 22 a596b957 2022-07-14 tracey .Sh DESCRIPTION
 23 a596b957 2022-07-14 tracey .Nm
 24 a596b957 2022-07-14 tracey is the run-time configuration file for
 25 59975c69 2022-08-29 stsp .Xr gotwebd 8 .
 26 a596b957 2022-07-14 tracey .Pp
 27 a596b957 2022-07-14 tracey The file format is line-based, with one configuration directive per line.
 28 a596b957 2022-07-14 tracey Any lines beginning with a
 29 a596b957 2022-07-14 tracey .Sq #
 30 a596b957 2022-07-14 tracey are treated as comments and ignored.
 31 a596b957 2022-07-14 tracey .Pp
 32 47b307cd 2022-10-02 op Macros can be defined that are later expanded in context.
 33 47b307cd 2022-10-02 op Macro names must start with a letter, digit, or underscore, and may
 34 47b307cd 2022-10-02 op contain any of those characters, but may not be reserved words.
 35 47b307cd 2022-10-02 op Macros are not expanded inside quotes.
 36 47b307cd 2022-10-02 op For example:
 37 47b307cd 2022-10-02 op .Bd -literal -offset indent
 38 47b307cd 2022-10-02 op lan_addr = "192.168.0.1"
 39 f497614d 2023-12-29 op listen on $lan_addr port 9090
 40 47b307cd 2022-10-02 op .Ed
 41 47b307cd 2022-10-02 op .Pp
 42 a596b957 2022-07-14 tracey Paths mentioned in
 43 a596b957 2022-07-14 tracey .Nm
 44 a596b957 2022-07-14 tracey must be relative to
 45 a596b957 2022-07-14 tracey .Pa /var/www ,
 46 a596b957 2022-07-14 tracey the
 47 a596b957 2022-07-14 tracey .Xr chroot 2
 48 a596b957 2022-07-14 tracey environment of
 49 a596b957 2022-07-14 tracey .Xr httpd 8 .
 50 a596b957 2022-07-14 tracey .Sh GLOBAL CONFIGURATION
 51 0dd80998 2022-08-29 stsp The available global configuration directives are as follows:
 52 a596b957 2022-07-14 tracey .Bl -tag -width Ds
 53 59975c69 2022-08-29 stsp .It Ic chroot Ar path
 54 59975c69 2022-08-29 stsp Set the path to the
 55 59975c69 2022-08-29 stsp .Xr chroot 2
 56 59975c69 2022-08-29 stsp environment of
 57 59975c69 2022-08-29 stsp .Xr httpd 8 .
 58 59975c69 2022-08-29 stsp If not specified then
 59 59975c69 2022-08-29 stsp .Pa /var/www
 60 59975c69 2022-08-29 stsp will be used.
 61 0dd80998 2022-08-29 stsp .It Ic prefork Ar number
 62 0dd80998 2022-08-29 stsp Run the specified number of server processes.
 63 f497614d 2023-12-29 op .Xr gotwebd 8
 64 f497614d 2023-12-29 op runs 3 server processes by default.
 65 0dd80998 2022-08-29 stsp .It Ic unix_socket_name Ar path
 66 0dd80998 2022-08-29 stsp Set the path to the default unix socket.
 67 f497614d 2023-12-29 op Defaults to
 68 f497614d 2023-12-29 op .Pa /var/www/run/gotweb.sock .
 69 0dd80998 2022-08-29 stsp .El
 70 0dd80998 2022-08-29 stsp .Sh SERVER CONFIGURATION
 71 0dd80998 2022-08-29 stsp At least one server context must exist for
 72 0dd80998 2022-08-29 stsp .Xr gotwebd 8
 73 0dd80998 2022-08-29 stsp to function.
 74 0dd80998 2022-08-29 stsp In case no server context is defined in the configuration file, a default
 75 0dd80998 2022-08-29 stsp server context will be used, which listens on a unix socket at
 76 0dd80998 2022-08-29 stsp .Pa /var/www/run/gotweb.sock
 77 0dd80998 2022-08-29 stsp and uses default parameters for all applicable settings.
 78 0dd80998 2022-08-29 stsp .Pp
 79 0dd80998 2022-08-29 stsp A server context is declared with a unique
 80 7e047b0e 2022-08-30 stsp .Ar name ,
 81 0dd80998 2022-08-29 stsp followed by server-specific configuration directives inside curly braces:
 82 0dd80998 2022-08-29 stsp .Pp
 83 0dd80998 2022-08-29 stsp .Ic server Ar name Brq ...
 84 0dd80998 2022-08-29 stsp .Pp
 85 c8af7691 2023-06-22 op The first server defined is used if the requested hostname is not
 86 c8af7691 2023-06-22 op matched by any server block.
 87 f21aef01 2022-08-30 stsp .Pp
 88 0dd80998 2022-08-29 stsp The available server configuration directives are as follows:
 89 0dd80998 2022-08-29 stsp .Bl -tag -width Ds
 90 59975c69 2022-08-29 stsp .It Ic custom_css Ar path
 91 59975c69 2022-08-29 stsp Set the path to a custom Cascading Style Sheet (CSS) to be used.
 92 f497614d 2023-12-29 op If this option is not specified then the default style sheet
 93 f497614d 2023-12-29 op .Sq gotweb.css
 94 f497614d 2023-12-29 op will be used.
 95 59975c69 2022-08-29 stsp .It Ic listen on Ar address Ic port Ar number
 96 f497614d 2023-12-29 op Configure an address and port for incoming FastCGI connections.
 97 0dd80998 2022-08-29 stsp Valid
 98 0dd80998 2022-08-29 stsp .Ar address
 99 f497614d 2023-12-29 op arguments are hostnames, IPv4 and IPv6 addresses.
100 0dd80998 2022-08-29 stsp The
101 0dd80998 2022-08-29 stsp .Ar port
102 0dd80998 2022-08-29 stsp argument may be number or a service name defined in
103 0dd80998 2022-08-29 stsp .Xr services 5 .
104 0dd80998 2022-08-29 stsp .Pp
105 0dd80998 2022-08-29 stsp May be specified multiple times to build up a list of listening sockets.
106 0dd80998 2022-08-29 stsp However, a given combination of address and port may only be used by
107 0dd80998 2022-08-29 stsp one server.
108 3a1c1a1b 2023-01-04 op .It Ic listen on socket Ar path
109 3a1c1a1b 2023-01-04 op Set the path to the unix socket used by the server.
110 59975c69 2022-08-29 stsp .It Ic logo Ar path
111 a596b957 2022-07-14 tracey Set the path to an image file containing a logo to be displayed.
112 f497614d 2023-12-29 op Defaults to
113 f497614d 2023-12-29 op .Sq got.png .
114 59975c69 2022-08-29 stsp .It Ic logo_url Ar url
115 a596b957 2022-07-14 tracey Set a hyperlink for the logo.
116 f497614d 2023-12-29 op Defaults to
117 f497614d 2023-12-29 op .Lk https://gameoftrees.org .
118 59975c69 2022-08-29 stsp .It Ic max_commits_display Ar number
119 f497614d 2023-12-29 op Set the maximum amount of commits and tags displayed per page.
120 f497614d 2023-12-29 op Defaults to 25.
121 59975c69 2022-08-29 stsp .It Ic max_repos_display Ar number
122 a596b957 2022-07-14 tracey Set the maximum amount of repositories displayed on the index screen.
123 f497614d 2023-12-29 op Defaults to 25.
124 f497614d 2023-12-29 op Set to zero to show all the repositories without pagination.
125 59975c69 2022-08-29 stsp .It Ic repos_path Ar path
126 59975c69 2022-08-29 stsp Set the path to the directory which contains Git repositories that
127 0dd80998 2022-08-29 stsp the server should publish.
128 f497614d 2023-12-29 op Defaults to
129 f497614d 2023-12-29 op .Pa /run/gotwebd.sock
130 f497614d 2023-12-29 op under the chroot.
131 d5996b9e 2022-10-31 landry .It Ic respect_exportok Ar on | off
132 d5996b9e 2022-10-31 landry Set whether to display the repository only if it contains the magic
133 d5996b9e 2022-10-31 landry .Pa git-daemon-export-ok
134 d5996b9e 2022-10-31 landry file.
135 f497614d 2023-12-29 op Disabled by default.
136 59975c69 2022-08-29 stsp .It Ic show_repo_age Ar on | off
137 a596b957 2022-07-14 tracey Toggle display of last repository modification date.
138 f497614d 2023-12-29 op Enabled by default.
139 59975c69 2022-08-29 stsp .It Ic show_repo_cloneurl Ar on | off
140 a596b957 2022-07-14 tracey Toggle display of clone URLs for a repository.
141 a596b957 2022-07-14 tracey This requires the creation of a
142 a596b957 2022-07-14 tracey .Pa cloneurl
143 a596b957 2022-07-14 tracey file inside the repository which contains one URL per line.
144 f497614d 2023-12-29 op Enabled by default.
145 59975c69 2022-08-29 stsp .It Ic show_repo_description Ar on | off
146 a596b957 2022-07-14 tracey Toggle display of the repository description.
147 f497614d 2023-12-29 op Enabled by default.
148 a596b957 2022-07-14 tracey The
149 a596b957 2022-07-14 tracey .Pa description
150 a596b957 2022-07-14 tracey file in the repository should be updated with an appropriate description.
151 59975c69 2022-08-29 stsp .It Ic show_repo_owner Ar on | off
152 a596b957 2022-07-14 tracey Set whether to display the repository owner.
153 f497614d 2023-12-29 op Enabled by default.
154 a596b957 2022-07-14 tracey Displaying the owner requires owner information to be added to the
155 a596b957 2022-07-14 tracey .Pa config
156 a596b957 2022-07-14 tracey file in the repository.
157 59975c69 2022-08-29 stsp .Xr gotwebd 8
158 a596b957 2022-07-14 tracey will parse owner information from either a [gotweb] or a [gitweb] section.
159 a596b957 2022-07-14 tracey For example:
160 a596b957 2022-07-14 tracey .Bd -literal -offset indent
161 a596b957 2022-07-14 tracey [gotweb]
162 a596b957 2022-07-14 tracey owner = "Your Name"
163 a596b957 2022-07-14 tracey .Ed
164 59975c69 2022-08-29 stsp .It Ic site_link Ar string
165 a596b957 2022-07-14 tracey Set the displayed site link name for the index page.
166 f497614d 2023-12-29 op Defaults to
167 f497614d 2023-12-29 op .Sq Repos .
168 59975c69 2022-08-29 stsp .It Ic site_name Ar string
169 a596b957 2022-07-14 tracey Set the displayed site name title.
170 f497614d 2023-12-29 op Defaults to
171 f497614d 2023-12-29 op .Sq Gotweb .
172 59975c69 2022-08-29 stsp .It Ic site_owner Ar string
173 a596b957 2022-07-14 tracey Set the displayed site owner.
174 f497614d 2023-12-29 op Defaults to
175 f497614d 2023-12-29 op .Sq Got Owner .
176 59975c69 2022-08-29 stsp .It Ic show_site_owner Ar on | off
177 a596b957 2022-07-14 tracey Toggle display of the site owner.
178 f497614d 2023-12-29 op Enabled by default.
179 8762929a 2023-12-29 op .It Ic summary_commits_display Ar number
180 8762929a 2023-12-29 op The maximum number of commits to show in the summary page.
181 f497614d 2023-12-29 op Defaults to 10.
182 8762929a 2023-12-29 op .It Ic summary_tags_display Ar number
183 8762929a 2023-12-29 op The maximum number of tags to show in the summary page.
184 f497614d 2023-12-29 op Defaults to 3.
185 0dd80998 2022-08-29 stsp .El
186 d375d894 2022-11-14 op .Sh FILES
187 d375d894 2022-11-14 op .Bl -tag -width Ds -compact
188 d375d894 2022-11-14 op .It Pa /etc/gotwebd.conf
189 d375d894 2022-11-14 op Default location of the
190 d375d894 2022-11-14 op .Nm
191 d375d894 2022-11-14 op configuration file.
192 d375d894 2022-11-14 op .El
193 a596b957 2022-07-14 tracey .Sh EXAMPLES
194 f497614d 2023-12-29 op A sample configuration:
195 a596b957 2022-07-14 tracey .Bd -literal -offset indent
196 f497614d 2023-12-29 op server "localhost" {
197 f497614d 2023-12-29 op 	site_name	"my public repos"
198 f497614d 2023-12-29 op 	site_owner	"Flan Hacker"
199 f497614d 2023-12-29 op 	site_link	"Flan' Projects"
200 59975c69 2022-08-29 stsp }
201 a596b957 2022-07-14 tracey .Ed
202 f497614d 2023-12-29 op .Pp
203 f497614d 2023-12-29 op Another example, this time listening on a local port instead of the
204 f497614d 2023-12-29 op implicit
205 f497614d 2023-12-29 op .Ux
206 f497614d 2023-12-29 op socket.
207 f497614d 2023-12-29 op .Bd -literal -offset indent
208 f497614d 2023-12-29 op server "localhost" {
209 f497614d 2023-12-29 op 	listen on 127.0.0.1 port 9000
210 f497614d 2023-12-29 op 	listen on ::1 port 9000
211 f497614d 2023-12-29 op }
212 f497614d 2023-12-29 op .Ed
213 a596b957 2022-07-14 tracey .Sh SEE ALSO
214 a596b957 2022-07-14 tracey .Xr got 1 ,
215 e0e2a861 2022-08-30 stsp .Xr httpd.conf 5 ,
216 0dd80998 2022-08-29 stsp .Xr services 5 ,
217 e0e2a861 2022-08-30 stsp .Xr gotwebd 8 ,
218 e0e2a861 2022-08-30 stsp .Xr httpd 8