Simple, small and fast HTTP server
started out as a pun at Mongoose, which is
another great web server, but is now useful for actual web serving purposes.
It is however not a real Meerkat, merely yet another copycat, forked from the
created by Jef Poskanzer.
The limited feature set makes Merecat very quick:
- Virtual hosts
- URL-traffic-based throttling
- 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
- Native PHP support, using php-cgi, if enabled in
The resulting footprint (~140 kiB) makes Merecat suitable for small and embedded
This program follows the usual UNIX command line syntax. 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. For details on the available configuration
The options, in their entirety, are as follows:
- Wildcard pattern for CGI programs. The config file setting
for this flag is cgi-pattern =
PATTERN. The default is
For more details, see below.
- 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
- 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 coonfiguration file is missing, or if
merecat is started with
merecat will run in stand-alone mode using
only command line options like listening port and server root
- Use global .htpasswd and
.htaccess files. This means that every file
in the entire document tree is protected by a single
.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
.htaccess files, and if they do not exist
either then serving the requested file without any password or access
The config file setting for this flag is
identity to use for all log messages. Useful when running multiple
servers. Defaults to use the program name, i.e.
- Set log level: none, err, info,
- Runs merecat in the foreground
like a regular program. Required when 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.
- Alternate TCP port number to listen on. The default is 80.
The config file setting for this flag is port
- 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.
- Do a chroot() at initialization time, restricting file
access to the program's current directory. The config file setting for
this flag is chroot =
- 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
- 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
- Enable throttling using this file with throttle settings.
See below for details.
- User to drop privileges to 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
- Do el-cheapo virtual hosting. The config file setting for
this flag is virtual-host =
- Shows the current version info.
- This optional argument is provided as a convenience
— by default merecat serves files from
the current directory. The config file setting for this is
- 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
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
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.
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, on the command line, 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,
To disable CGI as a security measure, either disable the default
, 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.
CGI_PATTERN, CGI_TIMELIMIT, CGI_NICE, CGI_PATH,
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
default. This file is formatted as the familiar colon-separated
username/encrypted-password pair, records delimited by newlines. The utility
included to help create and modify .htpasswd
can use a global
file if started with the
switch, or you can rely on a per directory
file which also protects subdirectories.
Access restriction is available as an option at compile time. If enabled, it
uses an access file in the directory to be protected, called
by default. This file consists of a
rule and a host address or a network range per line. Valid rules are:
- The following host address or network range is allowed to
access the requested directory and its files.
- The following host address or network range is not allowed
to access the requested directory and its files.
There are three ways to specify a valid host address or network range:
- e.g. 10.2.3.4
network with subnet mask,
- e.g. 10.0.0.0/255.255.0.0
network using CIDR notation,
- e.g. 10.0.0.0/16
can use a global
file if started with the
switch, or you can rely on a per directory
file which also protects subdirectories.
Note that rules are processed in the same order as they are listed in the access
file and that the first rule which matches the client's address is applied
(there is no order clause).
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.
The throttle file lets you set maximum byte rates on URLs or URL groups. You can
optionally set a minimum rate too. The format of the throttle file is 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 in the file are byte rates, specified in units of bytes per second.
For comparison, 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 want to set a minimum rate as well, use number-number.
# 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
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. 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 is not even started.
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 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
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 188.8.131.52
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 is a different way - use A records instead, each with a
different IP address, like so:
www.acme.com IN A 184.108.40.206
www.joe.acme.com IN A 220.127.116.11
www.jane.acme.com IN A 18.104.22.168
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. 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
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 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 22.214.171.124
ln -s www.joe.acme.com 126.96.36.199
ln -s www.jane.acme.com 188.8.131.52
This lets the older HTTP/1.0 browsers find the right subdirectory.
There is 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, this multiple-process method does not work with CNAME multihosting
— for that, you must use a single merecat process with the
merecat lets you define your own custom error pages for the various HTTP errors.
There is 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
, 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
. If no custom error file is
found for a given error number, then the usual built-in error page is
In a virtual hosts setup you can also have different custom error pages for each
host. In this case you put another errors/
directory in the top of that virtual host's web tree.
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
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:
- A wildcard pattern for the URLs that should require a local
referer. This is typically just image files, sound files, and so on. For
For most sites, that one setting is all you need to enable referer
urlpat = "**.jpg|**.gif|**.au|**.wav"
= <true |
- 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.
- 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.
is very picky about symbolic links. Before
delivering any file, it first checks each element in the path to see if it is
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 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.
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.
is also 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 —
checks explicitly for the world-readable
bit. This is so that 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.
The same logic applies to directories. As with the standard UNIX
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
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).
does all of its logging via
. All log
messages are prepended with the program name, unless the command line option
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: 184.108.40.206 - - "GET /file" 200 357
Aug 6 15:40:43 acme merecat: 220.127.116.11 - - "HEAD /file" 200 0
Aug 6 15:41:16 acme merecat: referer http://www.acme.com/ -> /dir
Aug 6 15:41:16 acme merecat: 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).
If started in the foreground, -n
, and with debug
log level, -l
, logs will also be printed on stderr,
unless the user also requested -s
. However, not
all systems support the LOG_PERROR
handles a couple of signals, which you can
send via the standard UNIX
- These signals tell merecat to
shut down immediately.
- 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.
- This signal tells merecat to
generate the statistics syslog messages immediately, instead of waiting
for the regular hourly update.
⟨email@example.com⟩ wrote the famous
is based on.
⟨firstname.lastname@example.org⟩ introduced all new shiny bugs.
is a fork of
, which in turn is a fork of
. So first and foremost, a huge thanks to
and making it open source under the
simplified 2-clause BSD license! Anthony G.
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