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