MERECAT.CONF(5)

File Formats Manual

MERECAT.CONF(5)

NAME

merecat.conf —

merecat httpd configuration file

INTRODUCTION

When merecat starts up it looks for its configuration file, /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 merecat.conf since the server runs fine with only command line parameters.

DESCRIPTION

The syntax of the config file is UNIX style

key =
  value

, separated by whitespace. The “#” character marks the start of a comment to end of line. The \ character can be used as an escape character.

Note: changes to the configuration file are require a restart of merecat, unlike many other UNIX daemons SIGHUP does not reload the .conf file.

Configuration Directives

charset = “STRING”

Character set to use with text MIME types, default “UTF-8”. If the default unicode charset causes trouble, try “iso-8859-1”.

check-referer = <true | false>

Enable check for external sites referencing material on your web server. For more information on referrers, see merecat(8). Disabled by default.

check-symlinks = <true | false>

For increased security, set this to true. Unless running chrooted in which case this is not really necessary. Disabled by default.

chroot = <true | false>

Change web server root to WEBDIR, or the current directory, if no WEBDIR is given as argument. Chrooting is a security measure and means that merecat.conf cannot access files outside it, unless files are bind mounted, or similar into the chroot. Disabled by default.

max-connections = NUM

Maximum number of simultaneous client connections, default 1024. Each connection costs one file descriptor, two while it is proxied to a backend, and at startup merecat.conf raises its own RLIMIT_NOFILE to match rather than claiming every descriptor the hard limit allows. Sizing the connection table this way keeps the resident memory of an idle server at a few MiB.

When the hard limit cannot cover the request, the number of connections is reduced to fit and a warning is logged at startup. Running under systemd the ceiling comes from LimitNOFILE in the unit file.

compression-level = -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 0 and to get maximum compression, 9.

The default setting, -1, means all "text/*" MIME type files, larger than 256 bytes, are compressed before sending to the client.

directory = 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 data-directory directive for more help.

data-directory = DIR

This setting is only relevant when chrooting, it adjusts the web server document root relative to the directory directive.

global-passwd = <true | false>

Set this to true to protect the entire directory tree with a single .htpasswd and/or .htaccess file. When unset, which is the default, merecat.conf looks for a local .htpasswd and .htaccess file, or serves the file without password.

hostname = HOSTNAME

The hostname to bind to when multihoming. For more details on this, see below discussion.

list-dotfiles = <true | false>

If dotfiles should be skipped in directory listings. Disabled by default.

local-pattern = “PATTERN”

Used with check-referer, see merecat(8) for more details.

max-age = SEC

Controls the global max-age setting, in seconds, set in the HTTP/1.1 “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.

port = PORT

The web server Internet port to listen to, defaults to 80, or 443 when HTTPS is enabled. See the ssl section below for more on configuring an HTTPS server.

url-pattern = “PATTERN”

Used with check-referer, see merecat(8) for more details.

username = “NAME”

Set username to drop privileges to after startup. Defaults to "nobody" which usually is defined on all UNIX systems.

virtual-host = <true | false>

Enable virtual hosting, disabled by default. For more information on this, see merecat(8).

user-agent-deny = “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 “**SemrushBot**” or “**SemrushBot**|**MJ12Bot**|**DotBot**” to match multiple user-agents.

The default is disabled, i.e. all user-agents are allowed.

cgi “PATTERN” {

Wildcard pattern for CGI programs, for instance “**.cgi” or “**.cgi|/cgi-bin/*”. See the dedicated CGI section in merecat(8) for more on this.

enabled = <true | false>

The CGI module is disabled by default.

limit = NUM

Maximum number of allowed simultaneous CGI programs. Default 1.

setenv = { NAME=value, ... }

List of environment variables to pass to all CGI programs. Use this to inject custom variables that CGI scripts can read from their environment. Example:

setenv = { "MY_VAR=hello", "APP_ENV=production" }

Environment variables: Merecat scrubs the process environment before forking CGI children for security reasons. Environment variables set in the shell or via systemd EnvironmentFile are therefore not visible to CGI programs.

Use the setenv option to pass custom variables directly, or use a wrapper script for more complex needs:

#!/bin/sh 
export GIT_PROJECT_ROOT=/srv/repos 
export GIT_HTTP_EXPORT_ALL=1 
exec /usr/lib/git-core/git-http-backend

Install the wrapper as the CGI entry point instead of the program itself.

}

php “PATTERN” {

Wildcard pattern for PHP scripts, for instance “**.php*” or “**.php5*|**.php4*|**.php*”. Notice the trailing *, it is very important otherwise any HTTP GET request with arguments will fail.

enabled = <true | false>: The PHP module is disabled by default.
cgi-path = “/path/to/php-cgi”: Default is “/usr/bin/php-cgi”

}

ssi “PATTERN” {

Wildcard pattern for triggering SSI, for instance “**.shtml” or “**.shtml|**.stm|**.shtm”.

enabled = <true | false>: The SSI module is disabled by default.
cgi-path = “/path/to/ssi”: Default is “cgi-bin/ssi”. See ssi(8) for more information.
silent = <true | false>: 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).

}

ssl {

protocol = “PROTOCOL”

Minimum SSL/TLS protocol level to enable. Can be one of: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. The default minimum protocol is TLSv1.1. Note, some (Linux) distributions have SSLv3 disabled by default in their OpenSSL packages.

ciphers = “CIPHERS”

The preferred list of ciphers the server supports. For a list of available ciphers, see the ciphers(1) man page. The default covers both TLSv1.3 (new ciphersuite) and older cipher list:

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

certfile = /path/to/cert.pem

Public part of HTTPS certificate, optionally with full certificate chain. E.g., fullchain.pem if you use Let's Encrypt. Only PEM format is supported.

keyfile = /path/to/key.pem

Private key of HTTPS certificate, e.g., privkey.pem if you use Let's Encrypt. Only PEM format is supported.

Note: This file must be kept private and should not be in the WEBROOT directory.

dhfile = /path/th/dhparam.pem

Optional Diffie-Hellman parameters. Not secret, unlike the keyfile the dhfile can be published online, if necessary. Create one like this:

openssl dhparam -out dhparam.pem 2048

}

server name {

port = PORT

Server port to listen to.

ssl { ... }

Same as the global settings, above, only for this server.

location “PATTERN” {

path = path/to/rewrite

If a server location directive is found it has precedence over any redirect or virtual host. It is primarily used to rewrite, or redirect, requests inside the current server context.

E.g., for handling certbot HTTP-01 renewal, use this in the port 80 server context. Any other path will be redirected to HTTPS, using the below redirect directive:

location "/.well-known/acme-challenge/**" { 
    path = "letsencrypt/.well-known/acme-challenge/" 
}

redirect “PATTERN” {

code = CODE

HTTP redirect code to use, default: 301. Supported codes are: 301, 302, 303, 307.

location = “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:

redirect "/**" { 
    code = 301 
    location = "https://$host$request_uri$args" 
}

}

proxy-pass “PATTERN” {

host = “HOSTNAME”

Optional. Only forward requests whose Host: header matches this hostname. Use this with multihoming (virtual-host = true) to route different virtual hosts to different backends on the same port. For example, to proxy only requests for “git.example.com”:

proxy-pass "/**" { 
    host    = "git.example.com" 
    backend = "http://localhost:3000" 
}

When omitted, the rule applies regardless of the Host: header.

backend = “http://HOST:PORT[/PATH]”

Forward matching requests to the given HTTP backend server, acting as a reverse proxy. This is similar to the proxy_pass directive in nginx, and is the primary way to front local application servers (Node.js, Python, Go, etc.) with Merecat.

The backend hostname is resolved at startup to avoid blocking DNS lookups during request handling. Only HTTP backends are supported (not HTTPS). IPv6 backends use the bracketed literal syntax “http://[::1]:3000”; when a hostname has both IPv4 and IPv6 addresses the IPv4 address is preferred.

proxy-pass "/api/**" { 
    backend = "http://localhost:3000" 
}

The following headers are added to every forwarded request:

X-Forwarded-For: Client IP address (or the value already in X-Forwarded-For if the client is itself a proxy).
X-Real-IP: Client IP address.
X-Forwarded-Proto: “http” or “https”, depending on whether the client connected over a plain or TLS connection.

When the backend URL includes a path component, the matched URL prefix is stripped before forwarding and replaced with the backend path. For example, with:

proxy-pass "/api/**" { 
    backend = "http://localhost:3000/v2" 
}

a client request for “/api/users/42” is forwarded as “GET /v2/users/42” to the backend. If the backend URL has no path (or only “/”) the original request URI is forwarded unchanged.

Requests are forwarded as HTTP/1.0 with “Connection: close”, and both the request body and the backend response are buffered in full before being relayed. Request bodies and responses are limited to 8 MiB: a larger request body is rejected with “413 Request Entity Too Large”, a larger response with “502 Bad Gateway”. A backend that is down, resets the connection, or stalls for 60 seconds without making progress also results in a “502 Bad Gateway”. Proxied requests are access logged with the status code returned by the backend.

proxy-redirect = “FROM TO”

Optional. Rewrite Location: and Refresh: response headers returned by the backend. Both FROM and TO are literal URL prefixes separated by a space. Any response header value that starts with FROM is rewritten so that prefix becomes TO. This is useful when a backend returns absolute redirects using its own path prefix and the frontend exposes it under a different prefix.

For example, if the backend at “http://localhost:6419” redirects to “http://localhost:6419/grip/” but the frontend exposes the app under “/grip/”, add:

proxy-pass "/grip/**" { 
    backend        = "http://localhost:6419/" 
    proxy-redirect = "http://localhost:6419 http://localhost" 
}

Merecat then rewrites “Location: http://localhost:6419/grip/” to “Location: http://localhost/grip/”.

The keyword “default” derives the prefixes from the rule itself: FROM is the backend URL and TO is the URL pattern up to its first glob character, both normalized to end in a slash so the rewrite cannot match past a path boundary. Use it when the backend is unaware of the frontend prefix and redirects relative to its own root:

proxy-pass "/app/**" { 
    backend        = "http://localhost:4000/" 
    proxy-redirect = "default" 
}

Here a backend redirect to “http://localhost:4000/login” is rewritten to “/app/login”. When the backend URL has no path the request URI is preserved, so backend redirects already carry the frontend prefix; the derived TO is then just “/” and only the scheme, host, and port are dropped.

Up to 8 proxy-pass rules may be configured per server.

}

AUTHORS

Jef Poskanzer ⟨jef@mail.acme.com⟩ wrote the famous thttpd which merecat.conf is based on.
Joachim Wiberg ⟨troglobit@gmail.com⟩ added the .conf file parser and this man page.

March 15, 2026

merecat (3.00)

Maintained in troglobit/merecat as man/merecat.conf.5. Send corrections there, or read it on the mirror.

NAME

INTRODUCTION

DESCRIPTION

Configuration Directives

SEE ALSO

AUTHORS