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