.\" -*- nroff -*- .\" The Merecat web server stems from both sthttpd and thttpd, both of .\" which are free software under the 2-clause simplified BSD license. .\" .\" Copyright (c) 1995-2015 Jef Poskanzer .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNERS OR CONTRIBUTORS BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .Dd Nov 28, 2021 .Dt MERECAT.CONF 5 .Os "merecat (2.32)" .Sh NAME .Nm merecat.conf .Nd merecat httpd configuration file .Sh INTRODUCTION When .Nm merecat starts up it looks for its configuration file, .Pa /etc/merecat.conf . This manual page documents the settings available, which allows for more advanced setups. For simpler use-cases, however, you may not need a .Nm since the server runs fine with only command line parameters. .Pp .Sh DESCRIPTION The syntax of the config file is UNIX style .Cm key = value , separated by whitespace. The .Dq #\& character marks the start of a comment to end of line. The \\ character can be used as an escape character. .Pp .Em Note: changes to the configuration file are require a restart of .Nm merecat , unlike many other UNIX daemons .Cm SIGHUP does not reload the .Pa .conf file. .Ss Configuration Directives .Bl -tag -width Ds .It Cm charset = Qq Ar STRING Character set to use with text MIME types, default .Qq UTF-8 . If the default unicode charset causes trouble, try .Qq iso-8859-1 . .It Cm check-referer = Ar Enable check for external sites referencing material on your web server. For more information on referrers, see .Xr merecat 8 . Disabled by default. .It Cm check-symlinks = Ar For increased security, set this to true. Unless running chrooted in which case this is not really necessary. Disabled by default. .It Cm chroot = Ar Change web server root to .Ar WEBDIR , or the current directory, if no .Ar WEBDIR is given as argument. Chrooting is a security measure and means that .Nm cannot access files outside it, unless files are bind mounted, or similar into the chroot. Disabled by default. .It Cm compression-level = Ar -1..9 Control the compression level of the built-in Apache-like mod_deflate. The default value is -1, which gives a reasonable compromize between speed and compression. To disable compression set this to .Ar 0 and to get maximum compression, .Ar 9 . .Pp The default setting, .Ar -1 , means all "text/*" MIME type files, larger than 256 bytes, are compressed before sending to the client. .It Cm directory = Ar DIR If no WEBDIR is given on the command line this option can be used to change the web server document root. Defaults to the current directory. When chrooting this is the root directory, see the .Cm data-directory directive for more help. .It Cm data-directory = Ar DIR This setting is only relevant when chrooting, it adjusts the web server document root relative to the .Cm directory directive. .It Cm global-passwd = Ar Set this to true to protect the entire directory tree with a single .Pa .htpasswd and/or .Pa .htaccess file. When unset, which is the default, .Nm looks for a local .Pa .htpasswd and .Pa .htaccess file, or serves the file without password. .It Cm hostname = Ar HOSTNAME The hostname to bind to when multihoming. For more details on this, see below discussion. .It Cm list-dotfiles = Ar If dotfiles should be skipped in directory listings. Disabled by default. .It Cm local-pattern = Qq Ar PATTERN Used with .Cm check-referer , see .Xr merecat 8 for more details. .It Cm max-age = Ar SEC Controls the global max-age setting, in seconds, set in the HTTP/1.1 .Qq Ar Cache-Control: max-age header, returned with all responses. The default setting is disabled since v2.32 and the user is recommended to use per-resource cache control. See the server location directive for details. .It Cm port = Ar PORT The web server Internet port to listen to, defaults to 80, or 443 when HTTPS is enabled. See the .Cm ssl section below for more on configuring an HTTPS server. .It Cm url-pattern = Qq Ar PATTERN Used with .Cm check-referer , see .Xr merecat 8 for more details. .It Cm username = Qq Ar NAME Set username to drop privileges to after startup. Defaults to "nobody" which usually is defined on all UNIX systems. .It Cm virtual-host = Ar Enable virtual hosting, disabled by default. For more information on this, see .Xr merecat 8 . .It Cm user-agent-deny = Qq Ar PATTERN Wildcard pattern to deny access to illicit hammering bots. When set a matching user-agent will receive a 403 for all its requests. Use for instance .Qq **SemrushBot** or .Qq **SemrushBot**|**MJ12Bot**|**DotBot** to match multiple user-agents. .Pp The default is disabled, i.e. all user-agents are allowed. .It Cm cgi Qo Ar PATTERN Qc Cm { Wildcard pattern for CGI programs, for instance .Qq **.cgi or .Qq **.cgi|/cgi-bin/* . See the dedicated CGI section in .Xr merecat 8 for more on this. .Pp .Bl -tag -offset "" -compact .It Cm enabled = Ar The CGI module is disabled by default. .It Cm limit = Ar NUM Maximum number of allowed simultaneous CGI programs. Default 1. .El .It Cm } .It Cm php Qo Ar PATTERN Qc Cm { Wildcard pattern for PHP scripts, for instance .Qq **.php* or .Qq **.php5*|**.php4*|**.php* . Notice the trailing .Cm * , it is very important otherwise any HTTP GET request with arguments will fail. .Pp .Bl -tag -offset "" -compact .It Cm enabled = Ar The PHP module is disabled by default. .It Cm cgi-path = Qq Pa /path/to/php-cgi Default is .Qq Pa /usr/bin/php-cgi .El .It Cm } .It Cm ssi Qo Ar PATTERN Qc Cm { Wildcard pattern for triggering SSI, for instance .Qq **.shtml or .Qq **.shtml|**.stm|**.shtm . .Pp .Bl -tag -offset "" -compact .It Cm enabled = Ar The SSI module is disabled by default. .It Cm cgi-path = Qq Pa /path/to/ssi Default is .Qq Pa cgi-bin/ssi . See .Xr ssi 8 for more information. .It Cm silent = Ar This setting can be used to silence “[an error occurred while processing the directive]”, shown when an error occurrs during SSI processing. Default disabled (false). .El .It Cm } .It Cm ssl Cm { .Bl -tag -offset "" -compact .It Cm protocol = Qq Ar PROTOCOL Minimum SSL/TLS protocol level to enable. Can be one of: .Ar SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 . The default minimum protocol is .Ar TLSv1.1 . Note, some (Linux) distributions have .Ar SSLv3 disabled by default in their OpenSSL packages. .It Cm ciphers = Qq Ar CIPHERS The preferred list of ciphers the server supports. For a list of available ciphers, see the .Xr ciphers 1 man page. The default covers both TLSv1.3 (new ciphersuite) and older cipher list: .Bd -unfilled -offset indent TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256: \\ HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4:!DHE-RSA-CAMELLIA256-SHA: \\ !DHE-RSA-CAMELLIA128-SHA:!ECDHE-RSA-CHACHA20-POLY1305: \\ !DHE-RSA-CHACHA20-POLY1305:!DHE-RSA-AES256-CCM8:!DHE-RSA-AES256-CCM: \\ !DHE-RSA-AES128-CCM8:!DHE-RSA-AES128-CCM .Ed .Pp .It Cm certfile = Ar /path/to/cert.pem Public part of HTTPS certificate, optionally with full certificate chain. E.g., .Cm fullchain.pem if you use Let's Encrypt. Only PEM format is supported. .It Cm keyfile = Ar /path/to/key.pem Private key of HTTPS certificate, e.g., .Cm privkey.pem if you use Let's Encrypt. Only PEM format is supported. .Pp .Sy Note: This file must be kept private and should not be in the WEBROOT directory. .It Cm dhfile = Ar /path/th/dhparam.pem Optional Diffie-Hellman parameters. Not secret, unlike the .Cm keyfile the .Cm dhfile can be published online, if necessary. Create one like this: .Bd -unfilled -offset indent openssl dhparam -out dhparam.pem 2048 .Ed .El .It Cm } .It Cm server Ar name Cm { .Bl -tag -offset "" -compact .It Cm port = Ar PORT Server port to listen to. .It Cm ssl Cm { Ar ... Cm } Same as the global settings, above, only for this server. .It Cm location Qo Ar PATTERN Qc { .Bl -tag -offset "" -compact .It Cm path = Ar path/to/rewrite If a server location directive is found it has precedence over any .Cm redirect or virtual host. It is primarily used to rewrite, or redirect, requests inside the current server context. .Pp E.g., for handling .Nm certbot HTTP-01 renewal, use this in the port 80 server context. Any other path will be redirected to HTTPS, using the below .Cm redirect directive: .Pp .Bd -unfilled -offset "" -compact location "/.well-known/acme-challenge/**" { path = "letsencrypt/.well-known/acme-challenge/" } .Ed .El .It Cm redirect Qo Ar PATTERN Qc { .Bl -tag -offset "" -compact .It Cm code = Ar CODE HTTP redirect code to use, default: 301. Supported codes are: 301, 302, 303, 307. .It Cm location = Qq Ar proto://$host:port$request_uri$args Location to return for redirect, e.g. to redirect all request for HTTP to HTTPS for the same (virtual) host: .Pp .Bd -unfilled -offset "" -compact redirect "/**" { code = 301 location = "https://$host$request_uri$args" } .Ed .El .It Cm } .El .It Cm } .El .Sh SEE ALSO .Xr merecat 8 .Sh AUTHORS .An -split .An Jef Poskanzer Aq jef@mail.acme.com wrote the famous .Nm thttpd which .Nm is based on. .An Joachim Wiberg Aq troglobit@gmail.com added the .conf file parser and this man page.