mongrel_rails(1) Ruby Web Server


mongrel_rails <command> [options]


Mongrel is a fast HTTP library and server for Ruby that is intended for hosting Ruby web applications of any kind using plain HTTP rather than FastCGI or SCGI. It is framework agnostic and already supports Ruby On Rails, Og+Nitro, Camping, and IOWA frameworks.

Mongrel turns out to be really nice for development since it serves files much faster than WEBrick. For example, to use it in development with Ruby on Rails is easy as this:

$ mongrel_rails start

Mongrel is a self-documenting program by giving you an extensive help listing for each command. If you think that this manual page is outdated, simply running

mongrel_rails start -h

will print out each possible option and what it does.

These options are also used in the -C config_file option to set them without using the command line. The name used in the config file is slightly different since it's a YAML file.
Mongrel has a -G (generate) feature that will take any command line options you give it, generate the YAML file to replicate those options, and then exit. For example, you could make a config file like this:

mongrel_rails start -G mongrel_8080.yml -e production -p 8080

And it'll write all the options possible to mongrel_8080.yml, but with your specific changes for environment (-e production) and port (-p 8080). When you run a configuration file with -C, don't pass other options. Rather than have complex rules about whether a configuration file or command line option wins, mongrel_rails just uses configuration file and defaults, or command line options and defaults. Basically don't mix, it won't work.


The following commands are supported by mongrel:

start                          Starts the server.

stop                                   Stops the server. Mongrel is very conservative when it shuts down, so it will wait up to 60 seconds for threads to exit before it finally exits gracefully.

stop --force [--wait n]        Stops the server. This sends mongrel a kill -9 and then you must delete the .pid file. If the wait parameter is specified, mongrel will wait n seconds before it sends the kill signal.

restart                                Restarts the server.


Mongrel is extensible configurable, and it has the following configuration options (the name to use in configuration file is in parenthesis after the option name):

-e, --environment ENV (:environment)   Configures your Rails environment to what you need.

-d, --daemonize (:daemon)                      If given (no options) then Mongrel will run in the background.

-p, --port PORT (:port)                                Port to bind to when listening for connections.

-a, --address ADDR (:host)                     Address to bind to when listening for connections.

-l, --log PATH (:log_file)                     Where to dump log messages in daemon mode - use an absolute path.

-P, --pid PATH (:pid_file)                     Where to write the PID file so start and stop commands know the Process ID - use absolute paths.

-n,--num-procs PROCS (:num_processors) Maximum number of concurrent processing threads before Mongrel starts denying connections and trying to kill old threads.

-t, --timeout SEC (:timeout)                   Time to pause between accepting clients. Used as a throttle mechanism.

-m, --mime PATH (:mime_map)                    A YAML file that lists additional MIME types.

-c, --chdir PATH (:cwd)                                Directory to change to prior to starting Mongrel.

-r, --root PATH (:docroot)                     Document root where Mongrel should serve files from. If you are putting Mongrel under a different base URI, and you want it to serve files out of a different directory then you need to set this.

-B, --debug (:debug)                           Turns on a debugging mode which traces objects, threads, files request parameters, and logs accesses writing them to log/mongrel_debug. This option makes Mongrel very slow.

-C, --config PATH (NONE)                               Specifies a configuration YAML file that sets options - use absolute paths.

-S, --script PATH (:config_script)             A special Ruby file that is run after Rails is configured to give you the ability to change the configuration with Ruby. This would be where you can load customer Mongrel handlers, extra libraries, or setup additional Ruby code. This option is fairly advanced so use with caution.

-G, --generate PATH (NONE)                     Takes whatever options set for Mongrel, and the current defaults, and then writes them to a YAML file suitable for use with the -C option.

--prefix URI                                           A URI to mount your Rails application at rather than the default /. This URI is stripped off all requests by Rails (not Mongrel) so it cannot end in /.

--user USER                                            Must have --group too. The user to change to right after creating the listening socket. Use this if you have to bind Mongrel to a low port like port 80, but don't want Mongrel to run as root.

--group GROUP                                          Must have --user too. The group to change to right after creating the listening socket.

-h, --help                                             Show help message

--version                                                      Show mongrel version

Installation of plugins packages for mongrel like mongrel-cluster allows one to use additional commands, such as cluster::configure.


Mongrel ( was written by Zed Shaw. This manual page was written for the Debian system by Filipe Lautert <[email protected]>. It might be used and redistributed under the same terms as the program itself.