commit - efacb859a7ebc65cff1b51cff04cdc2aea3135e1
commit + 2b520ad595f4ac7d438ace3abf2a0e2dd2fb78b5
blob - 4057c03ba2030f3f37601e0573da0a46079456a5
blob + e894e9691ec77707774de469e5c1db6ff780b722
--- gmid.1
+++ gmid.1
.It Fl n
Check that the configuration is valid, but don't start the server.
.It Fl P Pa pidfile
-Write
+Write the daemon pid to the given location.
+.Ar pidfile
+will also act as lock: if another process is holding a lock on that
+file,
.Nm
-pid to the given path.
+will refuse to start.
.El
.Pp
If no configuration file is given,
i.e.
.Pa ~/.local/share/gmid .
.It Fl H Ar hostname
-The hostname, by default
-.Ar localhost .
+The hostname
+.Ar localhost
+by default.
Certificates for the given
.Ar hostname
are searched inside the
block return 40 "temporary" "-" "failure"
.Ed
.Pp
+Furthermore, quoting is necessary only when a string needs to contain
+spaces, something that looks like a number or a reserved keyword.
+The last example could have been written also as:
+.Bd -literal -offset indent
+block return 40 temporary "-" failure
+.Ed
+.Pp
Strict ordering of the sections is not enforced, so that is possible
to mix macros, options and
.Ic server
.Nm
may enforce this.
.It Ic ipv6 Ar bool
-Enable or disable IPv6 support.
-By default is off.
+Enable or disable IPv6 support, off by default.
.It Ic map Ar mime-type Cm to-ext Ar file-extension
-Add a mapping for
-.Ar file-extension
+Map
+.Ar mime-type
to the given
-.Ar mime-type .
+.Ar file-extension .
Both argument are strings.
.It Ic port Ar portno
The port to listen on.
-By default is 1965.
+1965 by default.
.It Ic prefork Ar number
Run the specified number of server processes.
This increases the performance and prevents delays when connecting to
a server.
+When not in config-less mode,
.Nm
-runs 3 server processes by default, when not in config-less mode.
+runs 3 server processes by default.
The maximum number allowed is 16.
.It Ic protocols Ar string
Specify the TLS protocols to enable.
.Bl -tag -width Ds
.It Ic server Ar hostname Brq ...
Match the server name using shell globbing rules.
-This can be an explicit name,
+It can be an explicit name,
.Ar www.example.com ,
or a name including a wildcards,
.Ar *.example.com .
for this server.
.It Ic auto Ic index Ar bool
If no index file is found, automatically generate a directory listing.
-It's disabled by default.
+Disabled by default.
.It Ic block Op Ic return Ar code Op Ar meta
Send a reply and close the connection;
+by default
.Ar code
is 40
and
.Ar meta
is
-.Dq temporary failure
-by default.
+.Dq temporary failure .
If
.Ar code
is in the 3x range, then
.Ar meta
-must be provided.
+is mandatory.
Inside
.Ar meta ,
-the following special sequences are replaced:
+the following special sequences are supported:
.Bl -tag -width Ds -compact
.It \&%\&%
is replaced with a single
.It Ic entrypoint Pa path
Handle all the requests for the current virtual host using the
CGI script at
-.Pa path .
+.Pa path ,
+relative to the current document root.
.It Ic env Ar name Cm = Ar value
Set the environment variable
.Ar name
Enable FastCGI instead of serving files.
The
.Pa socket
-can either be a UNIX domain socket or a TCP socket.
+can either be a UNIX-domain socket or a TCP socket.
If the FastCGI application is listening on a UNIX domain socket,
.Pa socket
is a local path name within the
.Ar port
can be either a port number or the name of a service enclosed in
double quotes.
-If it's not specified defaults to 9000.
+If not specified defaults to 9000.
.It Ic index Ar string
Set the directory index file.
If not specified, it defaults to
.Ar value
for FastCGI.
.It Ic root Pa directory
-Specify the root directory for this server.
-It's relative to the chroot, if enabled.
+Specify the root directory for this server
+.Pq alas the current Dq document root .
+It's relative to the chroot if enabled.
.It Ic require Ic client Ic ca Pa path
Allow requests only from clients that provide a certificate signed by
the CA certificate in
More parameters can be added with the
.Ic param
option.
+.Pp
.Bl -bullet -compact
.It
GATEWAY_INTERFACE
To serve the directory
.Pa docs
and enable CGI scripts inside
-.Pa docs/cgi ,
-you can
+.Pa docs/cgi
.Bd -literal -offset indent
$ mkdir docs/cgi
$ cat <<EOF > docs/cgi/hello
cert "/path/to/cert.pem"
key "/path/to/key.pem"
root "/var/gemini/it.example.com"
+
+ # enable cgi scripts inside "cgi-bin"
cgi "/cgi-bin/*"
+
+ # set the language for text/gemini files
lang "it"
}
.Ed
user "_gmid"
server "example.com" {
- cert "/path/to/cert.pem"
- key "/path/to/key.pem"
- root "/example.com" # in the /var/gemini chroot
+ cert "/path/to/cert.pem" # absolute path
+ key "/path/to/key.pem" # also absolute
+ root "/example.com" # relative to the chroot
location "/static/*" {
+ # load the following rules only for
+ # requests that matches "/static/*"
+
auto index on
index "index.gemini"
}
.Sh CAVEATS
.Bl -bullet
.It
-The root directories of all virtual hosts are opened during the daemon
-startup; this means that if a root directory gets deleted and then
-re-created,
+All the root directories are opened during the daemon startup; if a
+root directory is deleted and then re-created,
.Nm
won't be able to serve files inside that directory until a restart.
-This restriction applies only to the root directories and not their content.
+This restriction only applies to the root directories and not their
+content.
.It
a %2F sequence is indistinguishable from a literal slash: this is not
RFC3986-compliant.
