UNICORN(1) General Commands Manual UNICORN(1)
NAME
unicorn - a rackup-like command to launch the Unicorn HTTP server
SYNOPSIS
unicorn [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
DESCRIPTION
A rackup(1)-like command to launch Rack applications using Unicorn. It is expected to be started in your application root (APP_ROOT), but
the "working_directory" directive may be used in the CONFIG_FILE.
While unicorn takes a myriad of command-line options for compatibility with ruby(1) and rackup(1), it is recommended to stick to the few
command-line options specified in the SYNOPSIS and use the CONFIG_FILE as much as possible.
RACKUP FILE
This defaults to "config.ru" in APP_ROOT. It should be the same file used by rackup(1) and other Rack launchers, it uses the Rack::Builder
DSL.
Embedded command-line options are mostly parsed for compatibility with rackup(1) but strongly discouraged.
UNICORN OPTIONS
-c, --config-file CONFIG_FILE
Path to the Unicorn-specific config file. The config file is implemented as a Ruby DSL, so Ruby code may executed. See the RDoc/ri
for the Unicorn::Configurator class for the full list of directives available from the DSL. Using an absolute path for for CON-
FIG_FILE is recommended as it makes multiple instances of Unicorn easily distinguishable when viewing ps(1) output.
-D, --daemonize
Run daemonized in the background. The process is detached from the controlling terminal and stdin is redirected to "/dev/null".
Unlike many common UNIX daemons, we do not chdir to "/" upon daemonization to allow more control over the startup/upgrade process.
Unless specified in the CONFIG_FILE, stderr and stdout will also be redirected to "/dev/null".
-E, --env RACK_ENV
Run under the given RACK_ENV. See the RACK ENVIRONMENT section for more details.
-l, --listen ADDRESS
Listens on a given ADDRESS. ADDRESS may be in the form of HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket and PATH is
meant to be a path to a UNIX domain socket. Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080) For production deployments,
specifying the "listen" directive in CONFIG_FILE is recommended as it allows fine-tuning of socket options.
RACKUP COMPATIBILITY OPTIONS
-o, --host HOST
Listen on a TCP socket belonging to HOST, default is "0.0.0.0" (all addresses). If specified multiple times on the command-line,
only the last-specified value takes effect. This option only exists for compatibility with the rackup(1) command, use of
"-l"/"--listen" switch is recommended instead.
-p, --port PORT
Listen on the specified TCP PORT, default is 8080. If specified multiple times on the command-line, only the last-specified value
takes effect. This option only exists for compatibility with the rackup(1) command, use of "-l"/"--listen" switch is recommended
instead.
-s, --server SERVER
No-op, this exists only for compatibility with rackup(1).
RUBY OPTIONS
-e, --eval LINE
Evaluate a LINE of Ruby code. This evaluation happens immediately as the command-line is being parsed.
-d, --debug
Turn on debug mode, the $DEBUG variable is set to true.
-w, --warn
Turn on verbose warnings, the $VERBOSE variable is set to true.
-I, --include PATH
specify $LOAD_PATH. PATH will be prepended to $LOAD_PATH. The ':' character may be used to delimit multiple directories. This
directive may be used more than once. Modifications to $LOAD_PATH take place immediately and in the order they were specified on
the command-line.
-r, --require LIBRARY
require a specified LIBRARY before executing the application. The "require" statement will be executed immediately and in the order
they were specified on the command-line.
SIGNALS
The following UNIX signals may be sent to the master process:
o HUP - reload config file, app, and gracefully restart all workers
o INT/TERM - quick shutdown, kills all workers immediately
o QUIT - graceful shutdown, waits for workers to finish their current request before finishing.
o USR1 - reopen all logs owned by the master and all workers See Unicorn::Util.reopen_logs for what is considered a log.
o USR2 - reexecute the running binary. A separate QUIT should be sent to the original process once the child is verified to be up and run-
ning.
o WINCH - gracefully stops workers but keep the master running. This will only work for daemonized processes.
o TTIN - increment the number of worker processes by one
o TTOU - decrement the number of worker processes by one
See the SIGNALS (http://unicorn.bogomips.org/SIGNALS.html) document for full description of all signals used by Unicorn.
RACK ENVIRONMENT
Accepted values of RACK_ENV and the middleware they automatically load (outside of RACKUP_FILE) are exactly as those in rackup(1):
o development - loads Rack::CommonLogger, Rack::ShowExceptions, and Rack::Lint middleware
o deployment - loads Rack::CommonLogger middleware
o none - loads no middleware at all, relying entirely on RACKUP_FILE
All unrecognized values for RACK_ENV are assumed to be "none". Production deployments are strongly encouraged to use "deployment" or
"none" for maximum performance.
As of Unicorn 0.94.0, RACK_ENV is exported as a process-wide environment variable as well. While not current a part of the Rack specifica-
tion as of Rack 1.0.1, this has become a de facto standard in the Rack world.
Note that the Rack::ContentLength and Rack::Chunked middlewares are never loaded by default. If needed, they should be individually speci-
fied in the RACKUP_FILE, some frameworks do not require them.
ENVIRONMENT VARIABLES
The RACK_ENV variable is set by the aforementioned -E switch. All application or library-specific environment variables (e.g. TMPDIR) may
always be set in the Unicorn CONFIG_FILE in addition to the spawning shell. When transparently upgrading Unicorn, all environment vari-
ables set in the old master process are inherited by the new master process. Unicorn only uses (and will overwrite) the UNICORN_FD envi-
ronment variable internally when doing transparent upgrades.
SEE ALSO
o unicorn_rails(1)
o Rack::Builder ri/RDoc
o Unicorn::Configurator ri/RDoc
o Unicorn RDoc (http://unicorn.bogomips.org/)
o Rack RDoc (http://rack.rubyforge.org/doc/)
o Rackup HowTo (http://wiki.github.com/rack/rack/tutorial-rackup-howto)
AUTHORS
The Unicorn Community <mongrel-unicorn@rubyforge.org>.
Unicorn User Manual September 15, 2009 UNICORN(1)