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