mirror of https://github.com/omar-polo/gmid.git
misc improvements to the manual
This commit is contained in:
parent
efacb859a7
commit
2b520ad595
82
gmid.1
82
gmid.1
|
@ -63,9 +63,12 @@ Stays and logs on the foreground.
|
||||||
.It Fl n
|
.It Fl n
|
||||||
Check that the configuration is valid, but don't start the server.
|
Check that the configuration is valid, but don't start the server.
|
||||||
.It Fl P Pa pidfile
|
.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
|
.Nm
|
||||||
pid to the given path.
|
will refuse to start.
|
||||||
.El
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
If no configuration file is given,
|
If no configuration file is given,
|
||||||
|
@ -81,8 +84,9 @@ By default is
|
||||||
i.e.
|
i.e.
|
||||||
.Pa ~/.local/share/gmid .
|
.Pa ~/.local/share/gmid .
|
||||||
.It Fl H Ar hostname
|
.It Fl H Ar hostname
|
||||||
The hostname, by default
|
The hostname
|
||||||
.Ar localhost .
|
.Ar localhost
|
||||||
|
by default.
|
||||||
Certificates for the given
|
Certificates for the given
|
||||||
.Ar hostname
|
.Ar hostname
|
||||||
are searched inside the
|
are searched inside the
|
||||||
|
@ -151,6 +155,13 @@ string:
|
||||||
block return 40 "temporary" "-" "failure"
|
block return 40 "temporary" "-" "failure"
|
||||||
.Ed
|
.Ed
|
||||||
.Pp
|
.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
|
Strict ordering of the sections is not enforced, so that is possible
|
||||||
to mix macros, options and
|
to mix macros, options and
|
||||||
.Ic server
|
.Ic server
|
||||||
|
@ -194,23 +205,23 @@ Future version of
|
||||||
.Nm
|
.Nm
|
||||||
may enforce this.
|
may enforce this.
|
||||||
.It Ic ipv6 Ar bool
|
.It Ic ipv6 Ar bool
|
||||||
Enable or disable IPv6 support.
|
Enable or disable IPv6 support, off by default.
|
||||||
By default is off.
|
|
||||||
.It Ic map Ar mime-type Cm to-ext Ar file-extension
|
.It Ic map Ar mime-type Cm to-ext Ar file-extension
|
||||||
Add a mapping for
|
Map
|
||||||
.Ar file-extension
|
.Ar mime-type
|
||||||
to the given
|
to the given
|
||||||
.Ar mime-type .
|
.Ar file-extension .
|
||||||
Both argument are strings.
|
Both argument are strings.
|
||||||
.It Ic port Ar portno
|
.It Ic port Ar portno
|
||||||
The port to listen on.
|
The port to listen on.
|
||||||
By default is 1965.
|
1965 by default.
|
||||||
.It Ic prefork Ar number
|
.It Ic prefork Ar number
|
||||||
Run the specified number of server processes.
|
Run the specified number of server processes.
|
||||||
This increases the performance and prevents delays when connecting to
|
This increases the performance and prevents delays when connecting to
|
||||||
a server.
|
a server.
|
||||||
|
When not in config-less mode,
|
||||||
.Nm
|
.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.
|
The maximum number allowed is 16.
|
||||||
.It Ic protocols Ar string
|
.It Ic protocols Ar string
|
||||||
Specify the TLS protocols to enable.
|
Specify the TLS protocols to enable.
|
||||||
|
@ -231,7 +242,7 @@ block:
|
||||||
.Bl -tag -width Ds
|
.Bl -tag -width Ds
|
||||||
.It Ic server Ar hostname Brq ...
|
.It Ic server Ar hostname Brq ...
|
||||||
Match the server name using shell globbing rules.
|
Match the server name using shell globbing rules.
|
||||||
This can be an explicit name,
|
It can be an explicit name,
|
||||||
.Ar www.example.com ,
|
.Ar www.example.com ,
|
||||||
or a name including a wildcards,
|
or a name including a wildcards,
|
||||||
.Ar *.example.com .
|
.Ar *.example.com .
|
||||||
|
@ -245,24 +256,24 @@ Specify an additional alias
|
||||||
for this server.
|
for this server.
|
||||||
.It Ic auto Ic index Ar bool
|
.It Ic auto Ic index Ar bool
|
||||||
If no index file is found, automatically generate a directory listing.
|
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
|
.It Ic block Op Ic return Ar code Op Ar meta
|
||||||
Send a reply and close the connection;
|
Send a reply and close the connection;
|
||||||
|
by default
|
||||||
.Ar code
|
.Ar code
|
||||||
is 40
|
is 40
|
||||||
and
|
and
|
||||||
.Ar meta
|
.Ar meta
|
||||||
is
|
is
|
||||||
.Dq temporary failure
|
.Dq temporary failure .
|
||||||
by default.
|
|
||||||
If
|
If
|
||||||
.Ar code
|
.Ar code
|
||||||
is in the 3x range, then
|
is in the 3x range, then
|
||||||
.Ar meta
|
.Ar meta
|
||||||
must be provided.
|
is mandatory.
|
||||||
Inside
|
Inside
|
||||||
.Ar meta ,
|
.Ar meta ,
|
||||||
the following special sequences are replaced:
|
the following special sequences are supported:
|
||||||
.Bl -tag -width Ds -compact
|
.Bl -tag -width Ds -compact
|
||||||
.It \&%\&%
|
.It \&%\&%
|
||||||
is replaced with a single
|
is replaced with a single
|
||||||
|
@ -296,7 +307,8 @@ is set to
|
||||||
.It Ic entrypoint Pa path
|
.It Ic entrypoint Pa path
|
||||||
Handle all the requests for the current virtual host using the
|
Handle all the requests for the current virtual host using the
|
||||||
CGI script at
|
CGI script at
|
||||||
.Pa path .
|
.Pa path ,
|
||||||
|
relative to the current document root.
|
||||||
.It Ic env Ar name Cm = Ar value
|
.It Ic env Ar name Cm = Ar value
|
||||||
Set the environment variable
|
Set the environment variable
|
||||||
.Ar name
|
.Ar name
|
||||||
|
@ -310,7 +322,7 @@ Can be provided more than once.
|
||||||
Enable FastCGI instead of serving files.
|
Enable FastCGI instead of serving files.
|
||||||
The
|
The
|
||||||
.Pa socket
|
.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,
|
If the FastCGI application is listening on a UNIX domain socket,
|
||||||
.Pa socket
|
.Pa socket
|
||||||
is a local path name within the
|
is a local path name within the
|
||||||
|
@ -325,7 +337,7 @@ is interpreted as a hostname or an IP address.
|
||||||
.Ar port
|
.Ar port
|
||||||
can be either a port number or the name of a service enclosed in
|
can be either a port number or the name of a service enclosed in
|
||||||
double quotes.
|
double quotes.
|
||||||
If it's not specified defaults to 9000.
|
If not specified defaults to 9000.
|
||||||
.It Ic index Ar string
|
.It Ic index Ar string
|
||||||
Set the directory index file.
|
Set the directory index file.
|
||||||
If not specified, it defaults to
|
If not specified, it defaults to
|
||||||
|
@ -366,8 +378,9 @@ to
|
||||||
.Ar value
|
.Ar value
|
||||||
for FastCGI.
|
for FastCGI.
|
||||||
.It Ic root Pa directory
|
.It Ic root Pa directory
|
||||||
Specify the root directory for this server.
|
Specify the root directory for this server
|
||||||
It's relative to the chroot, if enabled.
|
.Pq alas the current Dq document root .
|
||||||
|
It's relative to the chroot if enabled.
|
||||||
.It Ic require Ic client Ic ca Pa path
|
.It Ic require Ic client Ic ca Pa path
|
||||||
Allow requests only from clients that provide a certificate signed by
|
Allow requests only from clients that provide a certificate signed by
|
||||||
the CA certificate in
|
the CA certificate in
|
||||||
|
@ -480,6 +493,7 @@ are sent, and carry the same semantics as with CGI.
|
||||||
More parameters can be added with the
|
More parameters can be added with the
|
||||||
.Ic param
|
.Ic param
|
||||||
option.
|
option.
|
||||||
|
.Pp
|
||||||
.Bl -bullet -compact
|
.Bl -bullet -compact
|
||||||
.It
|
.It
|
||||||
GATEWAY_INTERFACE
|
GATEWAY_INTERFACE
|
||||||
|
@ -569,8 +583,7 @@ $ gmid .
|
||||||
To serve the directory
|
To serve the directory
|
||||||
.Pa docs
|
.Pa docs
|
||||||
and enable CGI scripts inside
|
and enable CGI scripts inside
|
||||||
.Pa docs/cgi ,
|
.Pa docs/cgi
|
||||||
you can
|
|
||||||
.Bd -literal -offset indent
|
.Bd -literal -offset indent
|
||||||
$ mkdir docs/cgi
|
$ mkdir docs/cgi
|
||||||
$ cat <<EOF > docs/cgi/hello
|
$ cat <<EOF > docs/cgi/hello
|
||||||
|
@ -602,7 +615,11 @@ server "it.example.com" {
|
||||||
cert "/path/to/cert.pem"
|
cert "/path/to/cert.pem"
|
||||||
key "/path/to/key.pem"
|
key "/path/to/key.pem"
|
||||||
root "/var/gemini/it.example.com"
|
root "/var/gemini/it.example.com"
|
||||||
|
|
||||||
|
# enable cgi scripts inside "cgi-bin"
|
||||||
cgi "/cgi-bin/*"
|
cgi "/cgi-bin/*"
|
||||||
|
|
||||||
|
# set the language for text/gemini files
|
||||||
lang "it"
|
lang "it"
|
||||||
}
|
}
|
||||||
.Ed
|
.Ed
|
||||||
|
@ -617,11 +634,14 @@ chroot "/var/gemini"
|
||||||
user "_gmid"
|
user "_gmid"
|
||||||
|
|
||||||
server "example.com" {
|
server "example.com" {
|
||||||
cert "/path/to/cert.pem"
|
cert "/path/to/cert.pem" # absolute path
|
||||||
key "/path/to/key.pem"
|
key "/path/to/key.pem" # also absolute
|
||||||
root "/example.com" # in the /var/gemini chroot
|
root "/example.com" # relative to the chroot
|
||||||
|
|
||||||
location "/static/*" {
|
location "/static/*" {
|
||||||
|
# load the following rules only for
|
||||||
|
# requests that matches "/static/*"
|
||||||
|
|
||||||
auto index on
|
auto index on
|
||||||
index "index.gemini"
|
index "index.gemini"
|
||||||
}
|
}
|
||||||
|
@ -642,12 +662,12 @@ program was written by
|
||||||
.Sh CAVEATS
|
.Sh CAVEATS
|
||||||
.Bl -bullet
|
.Bl -bullet
|
||||||
.It
|
.It
|
||||||
The root directories of all virtual hosts are opened during the daemon
|
All the root directories are opened during the daemon startup; if a
|
||||||
startup; this means that if a root directory gets deleted and then
|
root directory is deleted and then re-created,
|
||||||
re-created,
|
|
||||||
.Nm
|
.Nm
|
||||||
won't be able to serve files inside that directory until a restart.
|
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
|
.It
|
||||||
a %2F sequence is indistinguishable from a literal slash: this is not
|
a %2F sequence is indistinguishable from a literal slash: this is not
|
||||||
RFC3986-compliant.
|
RFC3986-compliant.
|
||||||
|
|
Loading…
Reference in New Issue