playground/suckless-quark
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity
suckless-quark/quark.1

132 lines
2.9 KiB
Groff
Raw Normal View History

Mention default behaviour in the manual when the host is not given Signed-off-by: Laslo Hunhold <dev@frign.de>
2020-08-23 11:36:56 +00:00
.Dd 2020-08-23
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Dt QUARK 1
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Os suckless.org
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Sh NAME
.Nm quark
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Nd simple static web server
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Sh SYNOPSIS
.Nm
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Fl p Ar port
Make host parameters optional For me at least, the first valid configuration found by getaddrinfo works fine most of the time. Obviously if this isn't the configuration you want, you can specify the host explicitly.
2020-04-21 15:04:37 +00:00
.Op Fl h Ar host
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Op Fl u Ar user
.Op Fl g Ar group
.Op Fl n Ar num
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Op Fl d Ar dir
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Op Fl l
.Op Fl i Ar file
.Oo Fl v Ar vhost Oc ...
.Oo Fl m Ar map Oc ...
.Nm
.Fl U Ar file
.Op Fl p Ar port
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Op Fl u Ar user
.Op Fl g Ar group
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Op Fl n Ar num
.Op Fl d Ar dir
.Op Fl l
.Op Fl i Ar file
.Oo Fl v Ar vhost Oc ...
.Oo Fl m Ar map Oc ...
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Sh DESCRIPTION
.Nm
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
is a simple HTTP GET/HEAD-only web server for static content.
Update manpage to list capabilities and behaviour Signed-off-by: Laslo Hunhold <dev@frign.de>
2020-08-18 06:46:52 +00:00
It supports virtual hosts (see
.Fl v ) ,
explicit redirects (see
.Fl m ) ,
directory listings (see
.Fl l ) ,
conditional "If-Modified-Since"-requests (RFC 7232), range requests
(RFC 7233) and well-known URIs (RFC 8615), while refusing to serve
hidden files and directories.
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl d Ar dir
Serve
.Ar dir
after chrooting into it.
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
The default is ".".
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.It Fl g Ar group
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
Set group ID when dropping privileges, and in socket mode the group of the
socket file, to the ID of
.Ar group .
The default is "nogroup".
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.It Fl h Ar host
Use
.Ar host
as the server hostname.
Mention default behaviour in the manual when the host is not given Signed-off-by: Laslo Hunhold <dev@frign.de>
2020-08-23 11:36:56 +00:00
The default is the loopback interface (i.e. localhost).
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.It Fl i Ar file
Set
.Ar file
as the directory index.
The default is "index.html".
.It Fl l
Enable directory listing.
.It Fl m Ar map
Rename "target" to "URI" where appropriate Of course URIs point at "targets", but the URIs themselves should be called what they are, not only in the interest of clarity in terms of nomenclature. Signed-off-by: Laslo Hunhold <dev@frign.de>
2020-08-22 21:37:08 +00:00
Add the URI prefix mapping rule specified by
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Ar map ,
which has the form
Change target prefix mapping argument order Put the chost-specification at the end and make it optional. This makes more sense than having to give an arbitrary useless name in case you weren't using virtual hosts in the first place. While at it, clear up the wording in the manpage. Signed-off-by: Laslo Hunhold <dev@frign.de>
2019-02-23 23:40:46 +00:00
.Qq Pa from to [chost] ,
Improve tokenization for m- and v-flag parsing I wasn't happy with the tokenizer for the m- and v-flags, because it was handling space-separated input and there was no way to have spaces within the tokens themselves. This is a fine detail, but I didn't want to impose this restriction where it could be solved (path prefixes or folder names can very well contain spaces). Given it's a bit quirky to handle multiple arguments to a single flag in the command line, especially when parameters are optional, this alternative wasn't further considered and I instead implemented a tokenizer that allows escaping spaces with '\'. While at it, I clarified the manual regarding this point. Signed-off-by: Laslo Hunhold <dev@frign.de>
2019-02-24 20:50:39 +00:00
where each element is separated with spaces (0x20) that can be
escaped with '\\'.
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Pp
The prefix
.Pa from
Rename "target" to "URI" where appropriate Of course URIs point at "targets", but the URIs themselves should be called what they are, not only in the interest of clarity in terms of nomenclature. Signed-off-by: Laslo Hunhold <dev@frign.de>
2020-08-22 21:37:08 +00:00
of all matching URIs is replaced with
Change target prefix mapping argument order Put the chost-specification at the end and make it optional. This makes more sense than having to give an arbitrary useless name in case you weren't using virtual hosts in the first place. While at it, clear up the wording in the manpage. Signed-off-by: Laslo Hunhold <dev@frign.de>
2019-02-23 23:40:46 +00:00
.Pa to ,
optionally limited to the canonical virtual host
.Pa chost .
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
If no virtual hosts are given,
.Pa chost
is ignored.
.It Fl n Ar num
Set the maximum number of threads to
.Ar num .
The default is 512.
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.It Fl p Ar port
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
In host mode, listen on port
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.Ar port
for incoming connections.
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
In socket mode, use
.Ar port
for constructing proper virtual host
redirects on non-standard ports.
.It Fl U Ar file
Create the UNIX-domain socket
.Ar file ,
Refine manpage concerning the UNIX-domain socket file
2018-02-05 16:15:05 +00:00
listen on it for incoming connections and remove it on exit.
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.It Fl u Ar user
Set user ID when dropping privileges,
and in socket mode the user of the socket file,
to the ID of
.Ar user .
The default is "nobody".
.It Fl v Ar vhost
Add the virtual host specified by
.Ar vhost ,
which has the form
permit prefix to be empty in -v format string The previous parsing of the -v vhosts made sure there were 4 tokens. If there was no prefix specified, usage() is called. Now, it only checks for the firsts 3, with .prefix set to null if there are only 3 tokens.
2018-04-02 00:55:00 +00:00
.Qq Pa chost regex dir [prefix] ,
Improve tokenization for m- and v-flag parsing I wasn't happy with the tokenizer for the m- and v-flags, because it was handling space-separated input and there was no way to have spaces within the tokens themselves. This is a fine detail, but I didn't want to impose this restriction where it could be solved (path prefixes or folder names can very well contain spaces). Given it's a bit quirky to handle multiple arguments to a single flag in the command line, especially when parameters are optional, this alternative wasn't further considered and I instead implemented a tokenizer that allows escaping spaces with '\'. While at it, I clarified the manual regarding this point. Signed-off-by: Laslo Hunhold <dev@frign.de>
2019-02-24 20:50:39 +00:00
where each element is separated with spaces (0x20) that can be
escaped with '\\'.
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Pp
A request matching the virtual host regular expression
.Pa regex
(see
Add a space after the number in the Xr mandoc macro Detected with the mandoc(1)-linter. Signed-off-by: Laslo Hunhold <dev@frign.de>
2019-02-18 22:44:12 +00:00
.Xr regex 3 )
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
is redirected to the canonical host
.Pa chost ,
if they differ, using the directory
.Pa dir
Rename "target" to "URI" where appropriate Of course URIs point at "targets", but the URIs themselves should be called what they are, not only in the interest of clarity in terms of nomenclature. Signed-off-by: Laslo Hunhold <dev@frign.de>
2020-08-22 21:37:08 +00:00
as the root directory, optionally prefixing the URI with
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Pa prefix .
If any virtual hosts are specified, all requests on non-matching
hosts are discarded.
Initial commit of quark rewrite Roughly 700 LOC (half of the old quark on the Hiltjo branch) in size, this rewrite supports partial content and other good stuff that will make it fun again to use quark for simple static purposes. The error checking is rigorous and strict and it will report proper error codes back to the client whenever there was a problem or the request was invalid in some way. A cool feature is the support for listening on a UNIX-domain socket, which will in the long run allow us to solve problems with virtual hosts and other things in separate programs. But until then, this should be robust enough for most use-cases. This resets quark's version to 0, but this was no problem as there haven't been any quark releases yet. Feedback is appreciated.
2016-09-02 07:59:02 +00:00
.El
.Sh CUSTOMIZATION
.Nm
can be customized by creating a custom config.h from config.def.h and
(re)compiling the source code. This keeps it fast, secure and simple.
Update the documentation to reflect the new flag-centric usage
2018-03-05 08:51:29 +00:00
.Sh AUTHORS
.An Laslo Hunhold Aq Mt dev@frign.de
Reference in a new issue Copy permalink