1 .\"
2 .\" Copyright (c) 2022 Omar Polo
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 .Dd September 23, 2022
16 .Dt GALILEO.CONF 5
17 .Os
18 .Sh NAME
19 .Nm galileo.conf
20 .Nd galileo configuration file
21 .Sh DESCRIPTION
22 .Nm
23 is the run-time configuration file for
24 .Xr galileo 8 .
25 .Pp
26 The file format is line-based, with one configuration directive per line.
27 Any lines beginning with a
28 .Sq #
29 are treated as comments and ignored.
30 .Sh GLOBAL CONFIGURATION
31 The available global configuration directives are as follows:
32 .Bl -tag -width Ds
33 .It Ic chroot Ar path
34 Set the
35 .Xr chroot 2
36 directory.
37 If not specified, it defaults to
38 .Pa /var/www ,
39 the home directory of the www user.
40 .It Ic prefork Ar number
41 Run the specified number of proxy processes.
42 .Xr galileo 8
43 runs 3 proxy processes by default.
44 .El
45 .Sh PROXY CONFIGURATION
46 At least one proxy must be defined for
47 .Xr galileo 8
48 to work.
49 .Pp
50 A proxy context is declared with a unique
51 .Ar name ,
52 followed by proxy-specific configuration directive inside curly braces:
53 .Pp
54 .Ic proxy Ar name Brq ...
55 .Pp
56 The available proxy configuration directives are as follows:
57 .Bl -tag -width Ds
58 .It Ic hostname Ar name
59 Specify the
60 .Ar name
61 used for SNI and the Gemini request.
62 Defaults to the address given in the
63 .Ic source
64 option.
65 .It Ic source Ar address Op Ic port Ar port
66 Specify to which
67 .Ar address
68 and
69 .Ar port
70 connect to.
71 .Ar port
72 is 1965 by default.
73 It's the only mandatory option.
74 .It Ic stylesheet Ar path
75 Specify the path to the stylesheet linked in the generated HTML.
76 This must be a valid absolute URI.
77 Defaults to
78 .Pa galileo.css
79 with prepended the URL prefix on which
80 .Xr galileo 8
81 is served.
82 .It Ic no footer
83 Do not add a footer with the original link at the bottom of the
84 generated page.
85 .It Ic no image preview
86 Do not generate a preview for links that seem to point to an image.
87 .Nm galileo
88 uses an heuristic to determine if a link points to an image that may
89 be inappropriate and not work in some circumstances.
90 .It Ic no navigation bar
91 Do no add a navigation bar at the top of the generated page.
92 .It Ic no tls
93 Do not setup the TLS layer.
94 Useful for saving some CPU cycles when connecting to a Gemini server
95 listening on localhost that is able to speak Gemini without TLS.
96 TLS is enabled by default.
97 .El
98 .Sh FILES
99 .Bl -tag -width Ds -compact
100 .It Pa /etc/galileo.conf
101 Default location of the
102 .Nm
103 configuration file.
104 .El
105 .Sh EXAMPLES
106 The following example will proxy the Gemini capsule
107 .Sq gemini://gemini.example.com
108 as
109 .Sq www.example.com
110 over HTTP:
111 .Bd -literal -offset indent
112 proxy "www.example.com" {
113 	source "gemini.example.com"
114 }
115 .Ed
116 .Pp
117 A more complex example where the Gemini server is running on a
118 non-standard port:
119 .Bd -literal -offset indent
120 proxy "www.example.com" {
121 	source 127.0.0.1 port 10965
122 	hostname "gemini.example.com"
123 }
124 .Ed
125 .Pp
126 The matching configuration for
127 .Xr httpd 8
128 is:
129 .Bd -literal -offset indent
130 server "www.example.com" {
131 	listen on * port 80
132 	listen on * tls port 443
133 	tls {
134 		certificate "/etc/ssl/example.com.fullchain.pem"
135 		key "/etc/ssl/private/example.com.key"
136 	}
137 	location "/.well-known/acme-challenge/*" {
138 		root "/acme"
139 		request strip 2
140 	}
141 	location "/galileo.css" {
142 		root "/htdocs"
143 	}
144 	location "/*" {
145 		fastcgi socket "/run/galileo.sock"
146 	}
147 }
148 .Ed
149 .Pp
150 .Xr galileo 8
151 can also be exposed under a URL path prefix.
152 The following example proxies the same Gemini capsule as
153 .Sq www.example.com/galileo/
154 over HTTP.
155 The only change is in the
156 .Xr httpd 8
157 configuration, as
158 .Xr galileo 8
159 handles this case transparently if the HTTP server properly defines
160 the
161 .Sq PATH_INFO
162 and
163 .Sq SCRIPT_NAME
164 FastCGI parameters.
165 .Bd -literal -offset indent
166 server "www.example.com" {
167 	listen on * port 80
168 
169 	location "/galileo/galileo.css" {
170 		request strip 1
171 		root "/htdocs"
172 	}
173 	location "/galileo/*" {
174 		request strip 1
175 		fastcgi socket "/run/galileo.sock"
176 	}
177 }
178 .Ed
179 .Sh SEE ALSO
180 .Xr httpd.conf 5 ,
181 .Xr galileo 8 ,
182 .Xr httpd 8