1 % UNICORN(1) Unicorn User Manual
2 % The Unicorn Community <mongrel-unicorn@rubyforge.org>
7 unicorn - a rackup-like command to launch the Unicorn HTTP server
11 unicorn [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
15 A rackup(1)-like command to launch Rack applications using Unicorn.
16 It is expected to be started in your application root (APP_ROOT), but
17 "Dir.chdir" may also be executed in the CONFIG_FILE or RACKUP_FILE.
19 While Unicorn takes a myriad of command-line options for
20 compatibility with ruby(1) and rackup(1), it is recommended to stick
21 to the few command-line options specified in the SYNOPSIS and use
22 the CONFIG_FILE as much as possible.
26 This defaults to \"config.ru\" in APP_ROOT. It should be the same
27 file used by rackup(1) and other Rack launchers, it uses the
30 Embedded command-line options are mostly parsed for compatibility
31 with rackup(1) but strongly discouraged.
34 -c, \--config-file CONFIG_FILE
35 : Path to the Unicorn-specific config file. The config file is
36 implemented as a Ruby DSL, so Ruby code may executed (e.g.
37 "Dir.chdir", "Process::UID.change_privilege"). See the RDoc/ri
38 for the *Unicorn::Configurator* class for the full list of
39 directives available from the DSL.
42 : Run daemonized in the background. The process is detached from
43 the controlling terminal and stdin is redirected to "/dev/null".
44 Unlike many common UNIX daemons, we do not chdir to \"/\"
45 upon daemonization to allow more control over the startup/upgrade
47 Unless specified in the CONFIG_FILE, stderr and stdout will
48 also be redirected to "/dev/null".
51 : Run under the given RACK_ENV. See the RACK ENVIRONMENT section
55 : Listens on a given ADDRESS. ADDRESS may be in the form of
56 HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
57 and PATH is meant to be a path to a UNIX domain socket.
58 Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080)
59 For production deployments, specifying the "listen" directive in
60 CONFIG_FILE is recommended as it allows fine-tuning of socket
63 # RACKUP COMPATIBILITY OPTIONS
65 : Listen on a TCP socket belonging to HOST, default is
66 "0.0.0.0" (all addresses).
67 If specified multiple times on the command-line, only the
68 last-specified value takes effect.
69 This option only exists for compatibility with the rackup(1) command,
70 use of "-l"/"\--listen" switch is recommended instead.
73 : Listen on the specified TCP PORT, default is 8080.
74 If specified multiple times on the command-line, only the last-specified
76 This option only exists for compatibility with the rackup(1) command,
77 use of "-l"/"\--listen" switch is recommended instead.
80 : No-op, this exists only for compatibility with rackup(1).
84 : Evaluate a LINE of Ruby code. This evaluation happens
85 immediately as the command-line is being parsed.
88 : Turn on debug mode, the $DEBUG variable is set to true.
91 : Turn on verbose warnings, the $VERBOSE variable is set to true.
94 : specify $LOAD_PATH. PATH will be prepended to $LOAD_PATH.
95 The \':\' character may be used to delimit multiple directories.
96 This directive may be used more than once. Modifications to
97 $LOAD_PATH take place immediately and in the order they were
98 specified on the command-line.
100 -r, \--require LIBRARY
101 : require a specified LIBRARY before executing the application. The
102 \"require\" statement will be executed immediately and in the order
103 they were specified on the command-line.
107 The following UNIX signals may be sent to the master process:
109 * HUP - reload config file, app, and gracefully restart all workers
110 * INT/TERM - quick shutdown, kills all workers immediately
111 * QUIT - graceful shutdown, waits for workers to finish their
112 current request before finishing.
113 * USR1 - reopen all logs owned by the master and all workers
114 See Unicorn::Util.reopen_logs for what is considered a log.
115 * USR2 - reexecute the running binary. A separate QUIT
116 should be sent to the original process once the child is verified to
118 * WINCH - gracefully stops workers but keep the master running.
119 This will only work for daemonized processes.
120 * TTIN - increment the number of worker processes by one
121 * TTOU - decrement the number of worker processes by one
123 See the [SIGNALS][4] document for full description of all signals
128 Accepted values of RACK_ENV and the middleware they automatically load
129 (outside of RACKUP_FILE) are exactly as those in rackup(1):
131 * development - loads Rack::CommonLogger, Rack::ShowExceptions, and
132 Rack::Lint middleware
133 * deployment - loads Rack::CommonLogger middleware
134 * none - loads no middleware at all, relying
135 entirely on RACKUP_FILE
137 All unrecognized values for RACK_ENV are assumed to be
138 "none". Production deployments are strongly encouraged to use
139 "deployment" or "none" for maximum performance.
141 As of Unicorn 0.94.0, RACK_ENV is exported as a process-wide environment
142 variable as well. While not current a part of the Rack specification as
143 of Rack 1.0.1, this has become a de facto standard in the Rack world.
145 Note that the Rack::ContentLength and Rack::Chunked middlewares
146 are never loaded by default. If needed, they should be
147 individually specified in the RACKUP_FILE, some frameworks do
150 # ENVIRONMENT VARIABLES
152 The RACK_ENV variable is set by the aforementioned \-E switch.
153 All application or library-specific environment variables (e.g. TMPDIR)
154 may always be set in the Unicorn CONFIG_FILE in addition to the spawning
155 shell. When transparently upgrading Unicorn, all environment variables
156 set in the old master process are inherited by the new master process.
157 Unicorn only uses (and will overwrite) the UNICORN_FD environment
158 variable internally when doing transparent upgrades.
163 * *Rack::Builder* ri/RDoc
164 * *Unicorn::Configurator* ri/RDoc
169 [1]: http://unicorn.bogomips.org/
170 [2]: http://rack.rubyforge.org/doc/
171 [3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
172 [4]: http://unicorn.bogomips.org/SIGNALS.html