MERECAT(8)

📦 version 2.31, in nixos 26.05, nixpkgs unstable

MERECAT(8) 🦋✨💅

System Manager's Manual — okay bestie, welcome to the iconic manual page for merecat, and yes we are in section 8, the system manager's zone. This is part 1 of the glow-up, so buckle up. 🎀

🌸 NAME 🌸

merecat — Simple, small and fast HTTP server. That's literally the whole title, no cap. 💖

✨ SYNOPSIS ✨

merecat [-ghnrsvV] [-c CGI] [-d PATH] [-f FILE] [-l LEVEL] [-p PORT]
        [-t FILE] [-u USER] [WEBDIR] [HOSTNAME]

🦋 DESCRIPTION 🦋

Okay so merecat started out as a pun at Mongoose, which is another great web server, but now it's genuinely useful for actual web serving purposes. It is however not a real Meerekat — merely yet another copycat, forked from the thttpd created by Jef Poskanzer. 🙈

The limited feature set makes it very quick. Virtual hosts and the URL-traffic-based throttling are just about its only features. This small footprint makes Merecat very suitable for small and embedded systems, even those smaller than a Raspberry Pi. 🍓

💅 OPTIONS 💅

This program follows the usual UNIX command line syntax. The options are as follows: 👑

  • -c CGI — Specifies a wildcard pattern for CGI programs, for instance "**.cgi" or "/cgi-bin/*". The config file option is cgi-pattern = "". See below for details. 🐚
  • -d PATH — Specifies a directory to chdir() to after chrooting. If you're 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 option name for this flag is "data-directory". 📁
  • -f FILE — Specifies a config file to read. 📄
  • -g — Use a global passwd file. This means that every file in the entire document tree is protected by the single .htpasswd file at the top of the tree. Otherwise the semantics of the .htpasswd file are the same. If this option is set but there is no .htpasswd file in the top-level directory, then merecat proceeds as if the option was not set — first looking for a local .htpasswd file, and if that doesn't exist either then serving the file without any password. The config file option for this flag is global-passwd = <true | false>. 🔐
  • -l LEVEL — Set log level: none, err, info, notice, debug. 📝
  • -n — Runs merecat in the foreground like a regular program. This is necessary when running in a process monitor like Finit or systemd. 🌀
  • -p — Specifies an alternate port number to listen on. The default is 80. The config file option name for this flag is "port". 🔌
  • -r — Do a chroot() at initialization time, restricting file access to the program's current directory. The config file option name for this flag is "chroot = <true | false>". 🏰
  • -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 option for this is "check-symlinks = <true | false>". 🔗
  • -t FILE — Specifies a file of throttle settings. See below for details. 🚦
  • -u USERNAME — Specifies what user to switch to after initialization when started as root. The default is "nobody", on some systems "www-data" is preferred. The config file option name for this flag is "username". 👤
  • -v — Do el-cheapo virtual hosting. The config-file option name for this flag is "virtual-host". 🏠
  • -V — Shows the current version info. ℹ️
  • WEBDIR — The default document root of the web server is defined in WEBDIR. But this can also be given as a command line argument. It specifies the directory to chdir() to at startup. This is merely a convenience — you could just as easily do a cd in the shell script that invokes the program. The config file option 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 option name for this flag is "hostname = HOSTNAME". 🌐

🎀 CONFIG FILE 🎀

Many options are not available from the command line but can be set in the "/etc/merecat.conf" configuration file. This file can be changed at runtime and merecat will pick up the changes with a restart. ♻️

The syntax of the config file is simple UNIX "option=value" separated by whitespace. The option names are listed below: 📝

  • cgi-limit = NUM — Maximum number of allowed simultaneous CGI programs. Default 1. 🧮
  • cgi-pattern = "**.cgi|/cgi-bin/*" — Specifies a wildcard pattern for CGI programs, for instance "**.cgi" or "/cgi-bin/*", the default is to have CGI disabled. See below CGI section for more on this. 🐣
  • charset = "UTF-8" — Specifies the character set to use with text MIME types. 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 below. Disabled by default. 🕵️♀️
  • check-symlinks = <true | false> — For increased security, set this option 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 cannot access files outside it, unless files are bind mounted, or similar into the chroot. Disabled by default. 🏯
  • 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. 📁
  • data-directory = DIR — When chrooting this can be used to adjust the web server document root. 🗂️
  • global-passwd = <true | false> — Set this to true to protect the entire directory tree with a single .htpasswd file. When unset, which is the default, merecat looks for a local .htpasswd file, or serves the file without password. 🔑
  • hostname = HOSTNAME — The hostname to bind to when multihoming. For more details on this, see below discussion. 🌍
  • local-pattern = "PATTERN" — Used with check-referer, see below for more details. 🧩
  • max-age = SEC — Specifies the number of seconds to be used in a "Cache-Control: max-age" header to be returned with all responses. An equivalent "Expires" header is also generated. The default is no Cache-Control or Expires headers, which is just fine for most sites. ⏳
  • port = PORT — The web server Internet port to listen to, default 80. 🔢
  • url-pattern = "PATTERN" — Used with check-referer, see below 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 below. 🏘️

🏰 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. 🔒

The only downside is that only root can call chroot(), so this means the program must be started as root. However, 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. 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. 🧚

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. 📜

In order for a CGI program to be allowed to run, its name must match the pattern specified either at compile time or in the config file. This is a simple shell-style filename pattern. Use * to match any string not including a slash, or ** to match any string including slashes, or ? 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. 🧨

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, use the config file and set the 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 options: CGI_PATTERN, CGI_TIMELIMIT, CGI_NICE, CGI_PATH, CGI_LD_LIBRARY_PATH, CGIBINDIR. ⚙️

🎀 BASIC AUTHENTICATION 🎀

Okay so Basic Authentication is available as an option at compile time. If it's enabled, it uses a password file that lives in the directory to be protected, called .htpasswd by default. The format is the familiar colon-separated username/encrypted-password pair situation, with records delimited by newlines. 💅

Big thing to know: the protection does not carry over to subdirectories. So no, it doesn't trickle down, it's not giving inherit-everything energy.

The utility program htpasswd(1) is included to help you create and modify .htpasswd files — she's your little helper, use her. 🫶

Relevant merecat.h option: AUTH_FILE

🌈 THROTTLING 🌈

The throttle file lets you set maximum byte rates on URLs or URL groups. You can optionally set a minimum rate too, because we love options. ✨

The format of the throttle file is genuinely very simple:

  • A # starts a comment, and the rest of the line is ignored.
  • Blank lines are ignored.
  • The rest of the lines should consist of a pattern, whitespace, and a number.

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

📊 the numbers bit 📊

The numbers in the file are byte rates, specified in units of bytes per second. For comparison, so you have a vibe check on scale:

  • a v.90 modem gives about 5000 B/s depending on compression
  • a double-B-channel ISDN line about 12800 B/s
  • a T1 line is about 150000 B/s

If you want to set a minimum rate as well, use 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 ⚙️

Throttling is implemented by checking each incoming URL filename against all of the patterns in the throttle file. The server accumulates statistics on how much bandwidth each pattern has accounted for recently (via a rolling average). If a URL matches a pattern that has been exceeding its specified limit, then the data returned is actually slowed down, with pauses between each block. 🐌

If that's not possible (e.g. for CGI programs) or if the bandwidth has gotten way larger than the limit, then the server returns a special code saying 'try again later'. 💀

The minimum rates are implemented similarly. Here's the reasoning: if too many people are trying to fetch something at the same time, throttling may slow down each connection so much that it's not really useable. Furthermore, all those slow connections clog up the server, using up file handles and connection slots. Setting a minimum rate says that past a certain point you should not even bother — the server returns the "try again later" code and the connection isn't even started. 🫶

🚫 what it does NOT do 🚫

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 is 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, by setting the operating system's per-process file descriptor limit before starting merecat. Be sure to set the hard limit, not the soft limit. 👑

🦋 MULTIHOMING 🦋

Multihoming means using one machine to serve multiple hostnames. For instance, if you're an internet provider and you want to let all of your customers 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. 💅

step one: DNS entries, bestie 🧚

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 want to 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, 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. 😭

step two: the IP situation 📡

Step two. If you're using the modern CNAME method of multihoming, then you can skip this step. Otherwise, using 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). 🙈

step three: tell merecat about it 👑

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 is send each incoming request to a subdirectory based on the hostname it's intended for.

All you have to do in order to set things up is to 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. 🌸

the alternate step three 💫

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
But remember, this multiple-process method does not work with CNAME multihosting — for that, you must use a single merecat process with the -v flag. No cap.

💖 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 would put your HTML into the file "errors/err401.html". 💅

If no custom error file is found for a given error number, then the usual built-in error page is generated. (She's got a fallback, she's fine.)

If you're using the virtual hosts option, you can also have different custom error pages for each different virtual host. In this case you put another "errors" directory in the top of that virtual host's web tree. merecat will look first in the virtual host errors directory, and then in the server-wide errors directory, and if neither of those has an appropriate error file then it will generate the built-in error. 🎀

🔥 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. Not slay. Not iconic. 😤

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. 🫶
Ngl, the example above literally spells the variable urlpat — that's what the page says, so copy it exactly and don't come for me. 💀

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. 🚨

This means you can't 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 subdirs of the main web directory, and in each user's home dir there's a symlink pointing to their actual web dir. 💫

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 won't 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 🎀

OK so merecat is also super picky about file permissions, bestie. It wants data files like HTML and images to be world readable. Readable by the group that the merecat process runs as? Not enough, ngl. merecat checks explicitly for the world-readable bit. This is literally so nobody ever gets surprised by a file that isn’t set world-readable and yet somehow is readable by the HTTP server and therefore by the whole world 😭.

Same energy for 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 just like 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, 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, and CGI programs should be mode 755 (rwxr-xr-x) or 711 (rwx--x--x).

📝 LOGS 📝

merecat does all of its logging via syslog(3). The facility it uses is configurable. 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 🔥.

The relevant merecat.h option is 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. Any requests in progress get aborted 💀.
  • USR1 — This signal tells merecat to shut down as soon as it’s done servicing all current requests. In addition, the network socket it uses to accept new connections gets closed immediately, which means a fresh merecat can be started up immediately.
  • USR2 — This signal tells merecat to generate the statistics syslog messages immediately, instead of waiting for the regular hourly update.

👀 SEE ALSO 👀

redirect(8), ssi(8), makeweb(1), htpasswd(1)

💖 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 writing 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 🫶.

Also, many thanks to contributors, reviewers, and testers: John LoVerso, Jordan Hayes, Chris Torek, Jim Thompson, Barton Schaffer, Geoff Adams, Dan Kegel, John Hascall, Bennett Todd, KIKUCHI Takahiro, Catalin Ionescu. Special thanks to Craig Leres for substantial debugging and development, and for not complaining about my coding style very much 🌸.

✍️ AUTHOR ✍️

Jef Poskanzer (mailto:jef@mail.acme.com) wrote the famous thttpd which merecat is based on. Joachim Nilsson (mailto:troglobit@gmail.com) introduced all the new bugs 😭💅.

And that’s the whole MERECAT(8) vibe, bestie: source/version is merecat (2.31), dated November 5, 2016 — periodt ✨👑.

📦 where this page comes from