MERECAT(8)

📦
version 2.31+git20260330 · 3 versions
, in ubuntu stonking
ok bestie, drink some water, we're reading the merecat(8) man page together 💖

👑 NAME 👑

merecat — the Simple, small and fast HTTP server 🐱✨ (yes, the name is a whole pun, more on that in a sec)

🌸 SYNOPSIS 🌸

merecat [-ghnrsSvV] [-c CGI] [-d PATH] [-f FILE] [-I IDENT] [-l LEVEL]
        [-p PORT] [-P PIDFN] [-t FILE] [-u USER] [WEBDIR] [HOSTNAME]

that's it. that's the whole vibe check. 🫶

🦋 DESCRIPTION 🦋

okay so the tea ☕ — merecat literally started life as a pun on Mongoose, which is another totally great web server, but she's since grown up and become genuinely useful for actual web serving purposes, no cap. However, and I need you to hear this: she is not a real Meerkat. She is merely yet another copycat 🐈 — forked from the great thttpd created by Jef Poskanzer. iconic lineage honestly.

The limited feature set is exactly what makes Merecat so quick 🏃‍♀️💨 it's giving "small menu, fast kitchen":

  • Virtual hosts
  • URL-traffic-based throttling
  • CGI/1.1
  • HTTP/1.1 Keep-alive
  • Built-in gzip deflate using zlib
  • HTTPS support using OpenSSL/LibreSSL
  • Dual server support, both HTTP/HTTPS from one process
  • HTTP redirect support, per server. E.g., possible to redirect from HTTP to HTTPS. Limited set of Nginx style environment variables supported.
  • Reverse proxy support (proxy-pass), to front local application servers (Node.js, Python, Go, etc.) while letting Merecat handle TLS termination.
  • Native PHP support, using php-cgi, if enabled in merecat.conf(5)

and the resulting footprint — ~140 kiB 🍓 — makes Merecat suitable for small and embedded systems. she's tiny. she's mighty. periodt.

✨ OPTIONS ✨

This program follows the usual UNIX command line syntax, because of course she does, she's a well-behaved girl 💅. Some options are, however, not available when merecat is built with support for /etc/merecat.conf. The distributed archive comes with an example configuration file, which should be fairly straightforward to comprehend (iykyk). For details on the available configuration directives, see merecat.conf(5).

The options, in their entirety, are as follows — every single one, no skimming bestie:

  • -c CGI — Wildcard pattern for CGI programs. The config file setting for this flag is cgi-pattern = PATTERN. The default is "**.cgi|/cgi-bin/*".

For more details, see below 👀

  • -d PATH — Directory to chdir() to after chrooting. If you are not chrooting, use the WEBDIR to do a single chdir(). If you are chrooting, this lets you put the web files in a subdirectory of the chroot tree, instead of in the top level mixed in with the chroot files. The config file setting for this flag is data-directory = DIR.
  • -f FILE — The config file to read. By default merecat looks for /etc/merecat.conf, unless the software has been configured to use a different prefix.

If the default system configuration file is missing, or if merecat is started with -f none, merecat will run in stand-alone mode using only command line options like listening port and server root directory. solo mode activated 🧚

  • -g — Use global .htpasswd and .htaccess files. This means that every file in the entire document tree is protected by a single .htpasswd or .htaccess file at the top of the tree. Otherwise the semantics of the .htpasswd and .htaccess files are the same. If this option is set but there is no .htpasswd or .htaccess files in the top-level directory, then merecat proceeds as if the option was not set — first looking for local .htpasswd and .htaccess files, and if they do not exist either then serving the requested file without any password or access restriction.

The config file setting for this flag is global-passwd = <true | false>.

  • -h — Show summary of command line options and exit. your little helper fr 🫶
  • -I IDENT — The syslog(3) identity to use for all log messages. Useful when running multiple servers. Defaults to use the program name, i.e. "merecat".
  • -l LEVEL — Set log level: none, err, info, notice, debug
  • -n — Runs merecat in the foreground like a regular program. Required when running in a process monitor like Finit or systemd. This also enables logging of errors and warnings to stderr, which can be disabled with -s.
  • -p PORT — Alternate TCP port number to listen on. The default is 80. The config file setting for this flag is port = PORT.
  • -P PIDFN — Optional PID file name. By default the IDENT option, or its default value, is used to construct the PID file name. Usually this results in /var/run/merecat.pid. If the argument to this option is an absolute path it will be used as-is. Otherwise the argument will be used as the basename for the PID file.
  • -r — Do a chroot() at initialization time, restricting file access to the program's current directory. The config file setting for this flag is chroot = <true | false>.
  • -s — Use syslog, even though running in foreground, -n. merecat uses syslog by default, this option is only relevant when running in the foreground to prevent warning and error messages to be printed to stderr.
  • -S — Do explicit symbolic link checking. Normally, merecat does not expand any symbolic links in filenames. For increased security this option can be enabled to check that the resulting path stays within the original document tree. Note, that if you are using the chroot option, the symlink checking is unnecessary and is turned off, so the safe way to save those CPU cycles 🧠✨ is to use chroot. The config file setting for this is check-symlinks = <true | false>.
  • -t FILE — Enable throttling using this file with throttle settings. See below for details.
  • -u USERNAME — User to drop privileges to after initialization when started as root. The default is nobody, on some systems www-data is preferred. The config file setting for this flag is username = USER.
  • -v — Do el-cheapo virtual hosting 💀. The config file setting for this flag is virtual-host = <true | false>.
  • -V — Shows the current version info.
  • WEBDIR — This optional argument is provided as a convenience — by default merecat serves files from the current directory. The config file setting for this is directory = DIR.
  • HOSTNAME — A second optional command line argument can be given to specify the hostname to bind to, for multihoming. The default is to bind to all hostnames supported on the local machine. See below for details. The config file setting for this flag is hostname = HOSTNAME.

🔒 CHROOT 🔒

chroot() is a system call that restricts the program's view of the filesystem to the current directory and directories below it. It becomes impossible for remote users to access any file outside of the initial directory. The restriction is inherited by child processes, so CGI programs get it too 👶. This is a very strong security measure, and is recommended. major main character energy for a syscall, honestly.

The only downside is that only root can call chroot(), so this means the program must be started as root. However — and this is the slay part — the last thing it does during initialization is to give up root access by becoming another user, so this is safe. 🫶

The program can also be compile-time configured to always do a chroot(), without needing the -r flag.

Note that with some other web servers, such as NCSA httpd, setting up a directory tree for use with chroot() is complicated, involving creating a bunch of special directories and copying in various files. not us 💅 With merecat it's a lot easier: all you have to do is make sure any shells, utilities, and config files used by your CGI programs and scripts are available. If you have CGI disabled, or if you make a policy that all CGI programs must be written in a compiled language such as C and statically linked, then you probably don't have to do any setup at all. zero effort, maximum slay.

However, one thing you should do is tell syslogd about the chroot tree, so that merecat can still generate syslog messages. Check your system's syslogd man page for how to do this. In FreeBSD you would put something like this in /etc/rc.conf:

syslogd_flags="-l /usr/local/www/data/dev/log"

Substitute in your own chroot tree's pathname, of course. Don't worry about creating the log socket, syslogd wants to do that itself. (You may need to create the dev directory.) In Linux the flag is -a instead of -l, and there may be other differences. 🙈

🧚 CGI 🧚

Merecat httpd supports the CGI 1.1 spec., https://tools.ietf.org/html/rfc3875.

In order for a CGI program to be allowed to run, its name must match the pattern specified either at compile time, on the command line, or in the config file. This is a simple shell-style filename pattern. Like:

  • * to match any string not including a slash
  • ** to match any string including slashes
  • ? to match any single character

Multiple patterns separated by | can also be used. The patterns get checked against the filename part of the incoming URL. Remember to quote any wildcard characters so that the shell doesn't mess with them! ⚠️ (yes the shell will absolutely eat your *, she's like that)

Restricting CGI programs to a single directory lets the site admin review them for security holes, and is strongly recommended. If there are individual users that you trust, you can enable their directories too using the pipe syntax, e.g. "|/jef/**".

To disable CGI as a security measure, either disable the default CGI_PATTERN in merecat.h, or set the configuration file option to the empty string, like this: cgi-pattern = ""

Note: the current working directory when a CGI program gets run is the directory that the CGI program lives in. This isn't in the CGI 1.1 spec, but it's what most other HTTP servers do.

Relevant merecat.h defines: CGI_PATTERN, CGI_TIMELIMIT, CGI_NICE, CGI_PATH, CGI_LD_LIBRARY_PATH, CGIBINDIR.

🎀 BASIC AUTHENTICATION 🎀

Basic authentication is available as an option at compile time. See the included configure script for details. When enabled, it uses a password file in the directory to be protected, called .htpasswd by default. This file is formatted as the familiar colon-separated username/encrypted-password pair, records delimited by newlines. The utility program htpasswd(1) is included to help create and modify .htpasswd files. 💖

merecat can use a global .htpasswd file if started with the -g switch, or you can rely on a per directory file which also protects subdirectories.

Relevant merecat.h define: AUTH_FILE

🔒 ACCESS RESTRICTION 🔒

Access restriction is a whole option thing — it's only there if you compiled it in, bestie. If it's enabled, it uses an access file sitting in the directory you wanna protect, and by default that file is called .htaccess. Inside, each line is one rule plus one host address or network range. The valid rules are:

  • allow from — the host address or network range that comes next is allowed to get at the requested directory and all its files.
  • deny from — the host address or network range that comes next is NOT allowed to get at the requested directory and all its files.

And there are three ways to write a valid host address or network range:

  • IPv4 host address, e.g. 10.2.3.4
  • IPv4 network with subnet mask, e.g. 10.0.0.0/255.255.0.0
  • IPv4 network using CIDR notation, e.g. 10.0.0.0/16

merecat can rock a global .htaccess file if you start it with the -g switch — or you can vibe with a per-directory file, which also protects all the subdirectories under it. ✨ two paths, both valid ✨

okay this part is IMPORTANT, do not skip 🫶

Rules get processed in the exact same order they're listed in the access file, and the first rule that matches the client's address wins. There's no order clause, so the order in the file is the order, periodt.

So if there is no allow from 0.0.0.0/0 at the end of the file, the default action is to deny access. Yeah. Locked out by default. That's the vibe check.

Relevant merecat.h define: ACCESS_FILE

🐢 THROTTLING 🐢

The throttle file lets you set maximum byte rates on URLs or groups of URLs. You can optionally set a minimum rate too. The format is stupid simple, which we love:

  • A # starts a comment, and the rest of that line is just ignored, gone, forgotten 💀
  • Blank lines? Ignored.
  • Everything else is: a pattern, whitespace, then a number.

The pattern is a simple shell-style filename pattern using ?, **, *, or you can chain multiple such patterns together separated by |.

The numbers are byte rates, in units of bytes per second. For scale, bestie: a v.90 modem gives about 5000 B/s depending on compression, a double-B-channel ISDN line about 12800 B/s, and a T1 line is about 150000 B/s. If you wanna set a minimum rate as well, write it as number-number.

Example:

# throttle file for www.acme.com

**              2000-100000  # limit total web usage to 2/3 of our T1,
                             # but never go below 2000 B/s
**.jpg|**.gif   50000   # limit images to 1/3 of our T1
**.mpg          20000   # and movies to even less
jef/**          20000   # jef's pages are too popular

How it actually works: every incoming URL filename gets checked against all the patterns in the throttle file. The server keeps stats on how much bandwidth each pattern has eaten up recently (via a rolling average). If a URL matches a pattern that's been blowing past its specified limit, then the data returned is actually slowed down, with pauses between each block. And if that's not possible (e.g. for CGI programs), or if the bandwidth has gotten way larger than the limit, then the server sends back a special code saying "try again later". iconic honestly

Minimum rates work similarly. If too many people are trying to fetch the same thing at once, throttling can slow every connection down so much that it's just not really useable. And on top of that, all those slow connections clog up the server, eating file handles and connection slots. Setting a minimum rate says: past a certain point, don't even bother — the server returns that "try again later" code and the connection is not even started. saves everyone the pain fr fr

There is no provision for setting a maximum connections/second throttle, because throttling a request uses as much CPU as handling it, so there would be no point. There's also no provision for throttling the number of simultaneous connections on a per-URL basis. However, you can control the overall number of connections for the whole server very simply: set the operating system's per-process file descriptor limit before starting merecat. And be sure to set the hard limit, not the soft limit. 😤

🏠 MULTIHOMING 🏠

Multihoming = using one machine to serve multiple hostnames. Say you're an internet provider and you want all your customers to have customized web addresses — you might have www.joe.acme.com, www.jane.acme.com, and your own www.acme.com, all running on the same physical hardware. This feature is also known as virtual hosts. There are three steps to setting this up.

One, make DNS entries for all of the hostnames. The current way to do this, allowed by HTTP/1.1, is to use CNAME aliases, like so:

www.acme.com IN A 192.100.66.1
www.joe.acme.com IN CNAME www.acme.com
www.jane.acme.com IN CNAME www.acme.com

However — this is incompatible with older HTTP/1.0 browsers. 🙈 If you wanna stay compatible, there's a different way: use A records instead, each with a different IP address, like so:

www.acme.com IN A 192.100.66.1
www.joe.acme.com IN A 192.100.66.200
www.jane.acme.com IN A 192.100.66.201

This is bad because it uses extra IP addresses, which are a somewhat scarce resource. But if you want people with older browsers to be able to visit your sites, you still have to do it this way. the struggle is real

Step two. If you're using the modern CNAME method of multihoming, you can skip this step entirely. Otherwise, with the older multiple-IP-address method, you must set up IP aliases or multiple interfaces for the extra addresses. You can use ifconfig(8)'s alias command to tell the machine to answer to all of the different IP addresses. Example:

ifconfig le0 www.acme.com
ifconfig le0 www.joe.acme.com alias
ifconfig le0 www.jane.acme.com alias

If your OS's version of ifconfig doesn't have an alias command, you're probably out of luck (but see http://www.acme.com/software/thttpd/notes.html for more info). 😭

Third and last, you must set up merecat to handle the multiple hosts. The easiest way is with the -v flag. This works with either CNAME multihosting or multiple-IP multihosting. What it does: it sends each incoming request to a subdirectory based on the hostname it's intended for. All you gotta do to set things up is create those subdirectories in the directory where merecat will run. With the example above, you'd do like so:

mkdir www.acme.com www.joe.acme.com www.jane.acme.com

If you're using old-style multiple-IP multihosting, you should also create symbolic links from the numeric addresses to the names, like so:

ln -s www.acme.com 192.100.66.1
ln -s www.joe.acme.com 192.100.66.200
ln -s www.jane.acme.com 192.100.66.201

This lets the older HTTP/1.0 browsers find the right subdirectory. 👑

There's an optional alternate step three if you're using multiple-IP multihosting: run a separate merecat process for each hostname. This gives you more flexibility, since you can run each of these processes in separate directories, with different throttle files, etc. Example:

merecat -r         /usr/www      www.acme.com
merecat -r -u joe  /usr/www/joe  www.joe.acme.com
merecat -r -u jane /usr/www/jane www.jane.acme.com
Remember, bestie: this multiple-process method does not work with CNAME multihosting — for that, you must use a single merecat process with the -v flag. ⚠️

🎀 CUSTOM ERRORS 🎀

merecat lets you define your own custom error pages for the various HTTP errors. There's a separate file for each error number, all stored in one special directory. The directory name is errors/, at the top of the web directory tree. The error files should be named errNNN.html, where NNN is the error number.

So for example, to make a custom error page for the authentication failure error, which is number 401, you'd put your HTML into the file errors/err401.html. And if no custom error file is found for a given error number, then the usual built-in error page gets generated instead. no drama, it's got a fallback

In a virtual hosts setup you can also have different custom error pages for each host. In that case you put another errors/ directory at the top of that virtual host's web tree. merecat will look first in the virtual host errors directory, then in the server-wide errors directory, and if neither of those has an appropriate error file, then it generates the built-in error. three-tier glow-up ✨

🚫 NON-LOCAL REFERERS 🚫

Sometimes another site on the net will embed your image files in their HTML files, which basically means they're stealing your bandwidth. 😤 You can prevent them from doing this by using non-local referer filtering. With this option, certain files can only be fetched via a local referer. The files have to be referenced by a local web page. If a web page on some other site references the files, that fetch will be blocked. There are three config file variables for this feature:

  • url-pattern = "**.jpg|**.gif|**.au|**.wav" — a wildcard pattern for the URLs that should require a local referer. This is typically just image files, sound files, and so on. For example:
urlpat = "**.jpg|**.gif|**.au|**.wav"

For most sites, that one setting is all you need to enable referer filtering. ✨

  • check-referer = <true | false> — by default, requests with no referer at all, or a null referer, or a referer with no apparent hostname, are allowed. With this variable set, such requests are disallowed.
  • local-pattern = "PATTERN" — a wildcard pattern that specifies the local host or hosts. This is used to determine if the host in the referer is local or not. If not specified it defaults to the actual local hostname.

merecat is very picky about symbolic links. Before delivering any file, it first checks each element in the path to see if it's a symbolic link, and expands them all out to get the final actual filename.

Along the way it checks for things like links with .. that go above the server's directory, and absolute symlinks (ones that start with a /). These are prohibited as security holes, so the server returns an error page for them. do not pass go 🚫

This means you cannot set up your web directory with a bunch of symlinks pointing to individual users' home web directories. Instead you do it the other way around — the user web directories are real subdirectories of the main web directory, and in each user's home directory there is a symlink pointing to their actual web directory. inverted, as the girls do 💅

The CGI pattern is also affected — it gets matched against the fully-expanded filename. So if you have a single CGI directory but then put a symbolic link in it pointing somewhere else, that will not work. The CGI program will be treated as a regular file and returned to the client, instead of getting run. This could be confusing. 🙈

💅 PERMISSIONS 💅

okay bestie, merecat is also super picky about file permissions. It wants data files (HTML, images) to be world readable. Readable by the group that the merecat process runs as is not enough — merecat checks explicitly for the world-readable bit. Why? So no one ever gets surprised by a file that's not set world-readable and yet somehow is readable by the HTTP server and therefore the whole world. periodt.

The same logic applies to directories. As with the standard UNIX ls program, merecat will only let you look at the contents of a directory if its read bit is on; but as with data files, this must be the world-read bit, not just the group-read bit.

merecat also wants the execute bit to be off for data files. A file that is marked executable but doesn't match the CGI pattern might be a script or program that got accidentally left in the wrong directory. Allowing people to fetch the contents of the file might be a security breach, so this is prohibited. Of course if an executable file does match the CGI pattern, then it just gets run as a CGI.

In summary, bestie:

  • data files should be mode 644 (rw-r--r--)
  • directories should be 755 (rwxr-xr-x) if you want to allow indexing
  • and 711 (rwx--x--x) to disallow it
  • CGI programs should be mode 755 (rwxr-xr-x) or 711 (rwx--x--x)

💖 LOGS 💖

merecat does all of its logging via syslog(3). All log messages are prepended with the program name, unless the command line option -I IDENT is used. The facility defaults to LOG_DAEMON. Aside from error messages, there are only a few log entry types of interest, all fairly similar to CERN Common Log Format:

Aug  6 15:40:34 acme merecat[583]: 165.113.207.103 - - "GET /file" 200 357
Aug  6 15:40:43 acme merecat[583]: 165.113.207.103 - - "HEAD /file" 200 0
Aug  6 15:41:16 acme merecat[583]: referer http://www.acme.com/ -> /dir
Aug  6 15:41:16 acme merecat[583]: user-agent Mozilla/1.1N

Note that merecat does not translate numeric IP addresses into domain names. This is both to save time and as a minor security measure (the numeric address is harder to spoof). iykyk.

If started in the foreground, -n, and with debug log level, -l debug, logs will also be printed on stderr, unless the user also requested -s. However, not all systems support the LOG_PERROR option to openlog().

Relevant merecat.h define: LOG_FACILITY.

⚡ SIGNALS ⚡

merecat handles a couple of signals, which you can send via the standard UNIX kill(1) command:

  • INT,TERM — these signals tell merecat to shut down immediately.
  • USR1 — this signal tells merecat to toggle log level, between current log level and LOG_DEBUG. If merecat was started with LOG_DEBUG the toggle will be to LOG_NOTICE, which is the default log level.
  • USR2 — this signal tells merecat to generate the statistics syslog messages immediately, instead of waiting for the regular hourly update.

🌈 SEE ALSO 🌈

👑 AUTHORS 👑

  • Jef Poskanzer <jef@mail.acme.com> wrote the famous thttpd which merecat is based on.
  • Joachim Wiberg <troglobit@gmail.com> introduced all new shiny bugs.

🫶 THANKS 🫶

merecat is a fork of sthttpd, which in turn is a fork of thttpd. So first and foremost, a huge thanks to Jef Poskanzer for creating thttpd and making it open source under the simplified 2-clause BSD license! Anthony G. Basile deserves another thank you, for merging Gentoo patches and refactoring the build system in sthttpd.

Also, many thanks to contributors, reviewers, testers: John LoVerso, Jordan Hayes, Chris Torek, Jim Thompson, Barton Schaffer, Geoff Adams, Dan Kegel, John Hascall, Bennett Todd, KIKUCHI Takahiro, Catalin Ionescu, Anders Bornäs, and Martin Olsson. Special thanks to Craig Leres for substantial debugging and development during the early days of thttpd.

and that's the whole vibe check, bestie! this iconic little manual page is merecat (3.00), dated Mar 15, 2026, and filed under MERECAT(8). 💅✨💖

📦 where this page comes from