--- name: "thy" section: "8" platform: "linux" package: "thy" version: "0.9.4-1" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/thy" --- # thy(8) The most beautiful http daemon ## NAME thy - The most beautiful http daemon ## SYNOPSIS **thy \[***options***\] \[***files***\]** ## DESCRIPTION **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. ## OPTIONS **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 - **--version (-V)** Print the version number and exit. - **--help (-?)** Print a verbose help screen and exit. - **--usage** Print a short summary of options. ## SUB-ARGUMENT SYNTAX 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. ## ADDRESS FORMAT 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 The following example tells Thy to listen on port *443* on *127.0.0.1* for *ssl* requests: - ``` thy -l https:127.0.0.1/443 ``` This one does the same, except that Thy will listen on port *443* on all available addresses. Again, for *ssl* requests. - ``` thy -l https:/443 ``` This one makes Thy listen for simple, plain-text http requests on all available addresses on port *8082*. - ``` thy -l /8082 ``` Force Thy to listen on the default port (*80*) for plain-text http requests only on the *127.0.0.1* address. - ``` thy -l 127.0.0.1 ``` Do the same, but on port *8082*. - ``` thy -l 127.0.0.1/8082 ``` Read all configuration from */etc/thy/thy.conf*: - ``` thy /etc/thy/thy.conf ``` ## FILES - */etc/thy/* This directory contains the default html files used to report HTTP errors. ## BUGS Probably many. ## AUTHOR Gergely Nagy \ ## SEE ALSO [*thy-auth*(7)](/thy-auth/7.md), [*regex*(7)](/regex/7.md),\ **The thy info pages**