.\"
.\" Copyright (c) 2022 Omar Polo
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.Dd September 23, 2022
.Dt GALILEO.CONF 5
.Os
.Sh NAME
.Nm galileo.conf
.Nd galileo configuration file
.Sh DESCRIPTION
.Nm
is the run-time configuration file for
.Xr galileo 8 .
.Pp
The file format is line-based, with one configuration directive per line.
Any lines beginning with a
.Sq #
are treated as comments and ignored.
.Sh GLOBAL CONFIGURATION
The available global configuration directives are as follows:
.Bl -tag -width Ds
.It Ic chroot Ar path
Set the
.Xr chroot 2
directory.
If not specified, it defaults to
.Pa /var/www ,
the home directory of the www user.
.It Ic prefork Ar number
Run the specified number of proxy processes.
.Xr galileo 8
runs 3 proxy processes by default.
.El
.Sh PROXY CONFIGURATION
At least one proxy must be defined for
.Xr galileo 8
to work.
.Pp
A proxy context is declared with a unique
.Ar name ,
followed by proxy-specific configuration directive inside curly braces:
.Pp
.Ic proxy Ar name Brq ...
.Pp
The available proxy configuration directives are as follows:
.Bl -tag -width Ds
.It Ic hostname Ar name
Specify the
.Ar name
used for SNI and the Gemini request.
Defaults to the address given in the
.Ic source
option.
.It Ic source Ar address Op Ic port Ar port
Specify to which
.Ar address
and
.Ar port
connect to.
.Ar port
is 1965 by default.
It's the only mandatory option.
.It Ic stylesheet Ar path
Specify the path to the stylesheet linked in the generated HTML.
This must be a valid absolute URI.
Defaults to
.Pa galileo.css
with prepended the URL prefix on which
.Xr galileo 8
is served.
.It Ic no tls
Do not setup the TLS layer.
Useful for saving some CPU cycles when connecting to a Gemini server
listening on localhost that is able to speak Gemini without TLS.
TLS is enabled by default.
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/galileo.conf
Default location of the
.Nm
configuration file.
.El
.Sh EXAMPLES
The following example will proxy the Gemini capsule
.Sq gemini://gemini.example.com
as
.Sq www.example.com
over HTTP:
.Bd -literal -offset indent
proxy "www.example.com" {
	source "gemini.example.com"
}
.Ed
.Pp
Alternatively, assuming the Gemini server is running on localhost on a
non-standard port:
.Bd -literal -offset indent
proxy "www.example.com" {
	source 127.0.0.1 port 10965
	hostname "gemini.example.com"
}
.Ed
.Pp
The matching configuration for
.Xr httpd 8
is:
.Bd -literal -offset indent
server "www.example.com" {
	listen on * port 80
	listen on * tls port 443
	tls {
		certificate "/etc/ssl/example.com.fullchain.pem"
		key "/etc/ssl/private/example.com.key"
	}
	location "/.well-known/acme-challenge/*" {
		root "/acme"
		request strip 2
	}
	location "/galileo.css" {
		root "/htdocs"
	}
	location "/*" {
		fastcgi socket "/run/galileo.sock"
	}
}
.Ed
.Pp
.Xr galileo 8
can also be exposed under a URL path prefix.
The following example proxies the same Gemini capsule as
.Sq www.example.com/galileo/
over HTTP.
The only change is in the
.Xr httpd 8
configuration, as
.Xr galileo 8
handles this case transparently if the HTTP server properly defines
the
.Sq PATH_INFO
and
.Sq SCRIPT_NAME
FastCGI parameters.
.Bd -literal -offset indent
server "www.example.com" {
	listen on * port 80

	location "/galileo/galileo.css" {
		request strip 1
		root "/htdocs"
	}
	location "/galileo/*" {
		request strip 1
		fastcgi socket "/run/galileo.sock"
	}
}
.Ed
.Sh SEE ALSO
.Xr httpd.conf 5 ,
.Xr galileo 8 ,
.Xr httpd 8