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 tls
83 Do not setup the TLS layer.
84 Useful for saving some CPU cycles when connecting to a Gemini server
85 listening on localhost that is able to speak Gemini without TLS.
86 TLS is enabled by default.
87 .El
88 .Sh FILES
89 .Bl -tag -width Ds -compact
90 .It Pa /etc/galileo.conf
91 Default location of the
92 .Nm
93 configuration file.
94 .El
95 .Sh EXAMPLES
96 The following example will proxy the Gemini capsule
97 .Sq gemini://gemini.example.com
98 as
99 .Sq www.example.com
100 over HTTP:
101 .Bd -literal -offset indent
102 proxy "www.example.com" {
103 	source "gemini.example.com"
104 }
105 .Ed
106 .Pp
107 Alternatively, assuming the Gemini server is running on localhost on a
108 non-standard port:
109 .Bd -literal -offset indent
110 proxy "www.example.com" {
111 	source 127.0.0.1 port 10965
112 	hostname "gemini.example.com"
113 }
114 .Ed
115 .Pp
116 The matching configuration for
117 .Xr httpd 8
118 is:
119 .Bd -literal -offset indent
120 server "www.example.com" {
121 	listen on * port 80
122 	listen on * tls port 443
123 	tls {
124 		certificate "/etc/ssl/example.com.fullchain.pem"
125 		key "/etc/ssl/private/example.com.key"
126 	}
127 	location "/.well-known/acme-challenge/*" {
128 		root "/acme"
129 		request strip 2
130 	}
131 	location "/galileo.css" {
132 		root "/htdocs"
133 	}
134 	location "/*" {
135 		fastcgi socket "/run/galileo.sock"
136 	}
137 }
138 .Ed
139 .Pp
140 .Xr galileo 8
141 can also be exposed under a URL path prefix.
142 The following example proxies the same Gemini capsule as
143 .Sq www.example.com/galileo/
144 over HTTP.
145 The only change is in the
146 .Xr httpd 8
147 configuration, as
148 .Xr galileo 8
149 handles this case transparently if the HTTP server properly defines
150 the
151 .Sq PATH_INFO
152 and
153 .Sq SCRIPT_NAME
154 FastCGI parameters.
155 .Bd -literal -offset indent
156 server "www.example.com" {
157 	listen on * port 80
158 
159 	location "/galileo/galileo.css" {
160 		request strip 1
161 		root "/htdocs"
162 	}
163 	location "/galileo/*" {
164 		request strip 1
165 		fastcgi socket "/run/galileo.sock"
166 	}
167 }
168 .Ed
169 .Sh SEE ALSO
170 .Xr httpd.conf 5 ,
171 .Xr galileo 8 ,
172 .Xr httpd 8