thy - The most beautiful http daemon

thy [options] [files]

Thy is a http daemon designed to be as fast and lightweight as possible. For speed, she uses sendfile(), and does not fork.

Among the features are name-based virtual hosts, userdir and directory index support; Range, If-Modified-Since, and keep-alive, on-the-fly compression, CGI, IPv6 and TLS.

Thy takes the following options (all of them can be localised - see --map later -, except where stated otherwise):

--add-env (-E) VARIABLE=VALUE

When one wants to pass a custom environment variable to all CGIs, handlers and the like, this option is the solution.

--add-handler (-H) EXTENSION=HANDLER

This option can be used to add an external handler (HANDLER) for every file with an extension of EXTENSION. If such a file is requested, it will be given as an argument to HANDLER, and treated as a CGI script.

--add-header (-D) FIELD=VALUE

One can use this option to add arbitrary headers to the HTTP response, like DAV: 1, if one wants to enable WebDAV support (requires external PROPFIND and other method handlers too).

--add-method (-M) METHOD=HANDLER

This option can be used to let Thy handle the METHOD request method with an external program: HANDLER. This can be used to add WebDAV support to Thy, for example.

--alias (-A) SOURCE=DEST

Add an alias from SOURCE to DEST, which means that if the former is encountered in an URL, it will be replaced by DEST, with the rest appended, to produce the filename to serve.

--auth (-a) OPTIONS

One can use this option to set various properties of the external authenticator, namely it's path, and the uid it should run as. One can add command-line arguments that will be passed to the Authoriser with the arg property. The file to read for access permissions is also configurable here with the file property.

By default, path is /usr/lib/thy/thy-auth, uid is 0, and file is .realm.

This is a global-only option.

--cache-control (-X) FIELD[=VALUE]

With this option, one can control how Thy will interact with webcache software. Possible fields are:

no-cache

For every request, add a Cache-Control: no-cache header field to the response.

no-store

For every request, add a Cache-Control: no-store header field to the response.

no-transform

For every request, add a Cache-Control: no-transform header field to the response.

must-revalidate

For every request, add a Cache-Control: must-revalidate header field to the response.

max-age=value

For every request, add a Cache-Control: max-age=value header field to the response.

If the response is served from a file on disc, add an Expires header too. The expiry date will be counted from value and the base specified using the expiry-base option.

expiry-base

Determines the base used for counting the value of the Expires response header. Recognised values are now or access (which mean the time of the request), and modification (which means the modification time of the served request).

All of these options can be localised, and they are turned off by default. Also note that all of these are mutually exclusive (not counting expiry-base).

--cgidirs (-C) DIRS

DIRS is a list of directories in which every single executable file will be treated as a CGI program.

--cgiexts (-c) EXTS

EXTS is a list of allowed extensions for CGI programs. Any executable with an extension in this list will be considered to be a CGI script. Specifying an empty value (-c ,) makes Thy bypass this check, and consider every executable to be a CGI.

Default value is .cgi.

--default-type (-d) TYPE

TYPE is the MIME type that should be returned if the file type could not be recognised by other means.

Default is application/octet-stream.

--errordoc (-e) CODE=PATH

Set the error-document for CODE to the file specified with PATH.

The recognised values for CODE are:

	301 (Moved Permanently)
	302 (Found)
	400 (Bad Request)
	401 (Unauthorized)
	403 (Forbidden)
	404 (Not Found)
	405 (Method Not Allowed)
	408 (Request Timeout)
	411 (Length Required)
	412 (Precondition Failed)
	413 (Request Entity Too Large)
	416 (Requested Range Not Satisfiable)
	500 (Internal Server Error)
	501 (Not Implemented)
	505 (HTTP Version Not Supported)

As a special value, all is recognised to mean that every error-document should be set to the given value.

--etag (-T) OPTION=VALUE

Controls the generation of ETag header fields. ETag can be controlled globally (for both files and directories) with the etag option, which is on by default. ETag generation for directories is controlled by the dirtag option, which is off by default.

--gzip (-g) OPTION=VALUE

This option controls the properties of compression support. Supported options are type and level. The latter specifies the compression level when using on-the-fly compression, and is a number between 0 and 9. Default is 6.

The former controls the compression type, and can be one of none, static and dynamic. Default is static.

--indexes (-i) FILES

FILES is a list of a filenames that can be used as pre-written HTML directory indexes.

Default is index.html.

--ipv4 (-4)

When no IP address is specified, bind only to IPv4 addresses. Default is to bind to all addresses, including IPv6 ones.

This is a global-only option.

--ipv6 (-6)

When no IP address is specified, bind only to IPv6 addresses. Default is to bind to all addresses, including IPv4 ones.

This is a global-only option.

--limits (-L) WHAT=LIMIT

This option can be used to limit some buffers in Thy, mainly used during parsing.

These buffers are header, which is the maximum size of the HTTP header that is accepted for parsing, and post_buffer, which is the maximum size of the buffer used to proxy the POST body between the client and the CGI.

The header limit is 2048 by default, post_buffer is 65536.

There is also cgis, which limits the number of concurrent CGI processes, it is 0 (disabled limitation) by default, and keepalive (defaulting to 100), which limits the maximum number of kept alive requests in a session.

The mmap property controls how many bytes can be mapped into memory at any given time. It is not used when Worker is not in use.

Specifying zero disables the limitation.

As an exception to the zero-disables rule, the maxclients option controls the maximum number of clients. By default, it is around 1024, and one can't set it lower than around 50.

This is a global-only option.

--listen (-l) ADDRESS

Force thy to listen on IP instead of on all interfaces. Multiple addresses are allowed too. For the format of ADDRESS, see the appropriate section later.

This is a global-only option.

--map (-R) REGEX

Thy supports so-called regexp-specific options. That is, one specifiec a regex, and all subsequent options (those which can be localised - global options are not affected) will be set only for those requests that match the REGEX.

For more information about this feature, please see the info pages.

This is a global-only option.

--mime-type (-m) EXTENSION=TYPE

Add EXTENSION to the list of MIME types, mapping to TYPE. That is, if a file with the specified extension is found, the content-type returned will be TYPE.

--options (-o) OPTIONS...

Toggle some minor options, such as auth, buffer, cache, casemime, cgi, chroot, dirindex, expect, followall, hardlimit, lazycgi, pidfile, server, stats, usercgi, userdir, vary, vhost and worker. When specified with a no prefix, it will turn the corresponding option off.

Defaults are off for auth, cgi, chroot, followall, hardlimit, lazycgi, usercgi, vhost, and worker, but on for cache, casemime, dirindex, expect, vary and userdir.

Four options that take an argument are buffer, which defaults to 256, meaning that Thy will use a 256Kbyte buffer for sending data; pidfile, which defaults to /var/run/thy.pid, server, which defaults to Thy/0.9.4. With this, one can override how Thy identifies herself to clients. And stats, Which controls how often (in seconds) server statistics are logged. Setting it to 0 turns the feature off. Default is 3600.

The buffers, cache, chroot, expect, pidfile, stats and fIworker options are global-only.

--pidfile (-P) PIDFILE

Write the pid thy runs with to PIDFILE.

Default is /var/run/thy.pid.

This is a global-only option.

--ssl (-s) OPTION=VALUE

This option controls certain properties of the SSL support in Thy. These options are ca, the file containing the CA information (not used by default); cert, the file containing the server certificate (defaults to /etc/thy/cert.pem or /etc/thy/public.asc); key, the file containing the server key (defaults to /etc/thy/key.pem or /etc/thy/secret.asc); keyring, which contains the OpenPGP keyring (defaults to /etc/thy/ring.gpg); trustdb, which contains the OpenPGP trust database (defaults to /etc/thy/trustdb.gpg); type, which determines the used certification type (defaults to x509, the other possible value is openpgp); and verify, which determines the level of client certificate verification (defaults to 0). The higher the level, the stricter the verification is.

Thy also supports SRP authentication, therefore the srppasswd and srpconf options are available to set the password and the configuration file, respectively. Both are empty (which means SRP is not available) by default.

When in X509 mode, multiple ca, cert and key parameters are allowed.

This is a global-only option.

--timeout (-t) [keepalive=]SECONDS

Wait SECONDS seconds for a request to complete, before timing out.

Default is 180.

If keepalive= is specified too, set the timeout for kept-alive requests only. Default timeout for keep-alive requests is 15 seconds.

This is a global-only option.

--uid (-U) UID

UID is the user (either numerical id or user name) thy should run as.

Default is 65534.

This is a global-only option.

--userdir (-u) PATH

PATH is a directory under the users' home, from which HTML documents can be served upon a ~user request.

Default is public_html.

--webroot (-w) PATH

PATH specifies the root directory of the HTML documents.

Default is /var/www.

--worker (-W) OPTIONS...

One can use this option to set various properties of the external worker process, namely it's path, and the uid it should run as. One can add command-line arguments that will be passed to the Worker with the arg property.

By default, path is /usr/lib/thy/thy-worker, and uid is 65534.

This is a global-only option.

Miscellaneous options

Thy has a few options (for example, --options) that can take multiple sub-arguments. However, the sub-argument separator is not space, but comma. For example, if one wants to enable both the CGI and the vhost options, this is the command to write:

thy -o cgi,vhost

Another possible solution is to not use sub-arguments, but pass the same option with different sub-arguments more than once. That is, the above example can also be written as follows:

thy -o cgi -o vhost

A noteworthy feature is that in case the option is not a toggle, like the --options we used as a sample, but works on a list like --indexes, the list will only be appended to, never replaced. Thus, both of the above methods work for that option too: with the second method, later --indexes options will not overwrite the values of the former ones, but appended to the list.

Thy can listen on any number of addresses, all on different ports, http and https mixed. To provide a consistent way of specifying which address-port pairs are in TLS mode, and which are in plain, Thy recognises a three-component address format.

The first, optional component specifies the protocol, and if used, it must be followed by a colon. The recognised protocols are http, https, tls, and ssl. All but the first tell Thy that the address in question should receive TLS connetions. The default is http.

The second component is the IP address. Note that it must be a dotted-decimal address, not a hostname. Default is to listen on all addresses.

The last component is the port number to listen on. It must be preceded by a slash. Default is 80 for normal mode, and 443 for TLS mode.

Either one of the hostname or the port number can be omitted, in which case the default will be used.

EXAMPLES

/etc/thy/

This directory contains the default html files used to report HTTP errors.

Probably many.

Gergely Nagy <algernon@bonehunter.rulez.org>

thy-auth(7), regex(7),

The thy info pages