Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
UNICORN(1)							    UNICORN(1)

       unicorn - a rackup-like command to launch the Unicorn HTTP server

       unicorn [-c CONFIG_FILE]	[-E RACK_ENV] [-D] [RACKUP_FILE]

       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  com-
       mand-line  options specified in the SYNOPSIS and	use the	CONFIG_FILE as
       much as possible.

       This defaults to	"" in APP_ROOT.  It should be the  same  file
       used  by	 rackup(1) and other Rack launchers, it	uses the Rack::Builder

       Embedded	command-line options are mostly	parsed for compatibility  with
       rackup(1) but strongly discouraged.

       -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 CONFIG_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
	      ""  (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.

       -N, --no-default-middleware
	      Disables	loading	middleware implied by RACK_ENV.	 This bypasses
	      the configuration	documented in the  RACK	 ENVIRONMENT  section,
	      but  still  allows  RACK_ENV  to	be used	for application/frame-
	      work-specific purposes.

       -o, --host HOST
	      Listen on	a TCP socket belonging to HOST,	default	 is  ""
	      (all  addresses).	  If  specified	 multiple  times  on  the com-
	      mand-line, only the last-specified value takes effect.  This op-
	      tion  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 val-
	      ue takes effect.	This option only exists	for compatibility with
	      the  rackup(1)  command, use of "-l"/"--listen" switch is	recom-
	      mended instead.

       -s, --server SERVER
	      No-op, this exists only for compatibility	with rackup(1).

       -e, --eval LINE
	      Evaluate a LINE of Ruby code.  This evaluation  happens  immedi-
	      ately 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.

       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  Uni-
	 corn::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-

       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	(	 document  for
       full description	of all signals used by Unicorn.

       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".  Produc-
       tion  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  environ-
       ment 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

       Note  the  Rack::ContentLength  and  Rack::Chunked middlewares are also
       loaded by "deployment"  and  "development",  but	 no  other  values  of
       RACK_ENV.   If needed, they must	be individually	specified in the RACK-
       UP_FILE,	some frameworks	do not require them.

       The RACK_ENV variable is	set by the aforementioned -E switch.  All  ap-
       plication  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 variables
       set in the old master process are inherited by the new master  process.
       Unicorn only uses (and will overwrite) the UNICORN_FD environment vari-
       able internally when doing transparent upgrades.

       UNICORN_FD is a comma-delimited list of one or  more  file  descriptors
       used  to	implement USR2 upgrades.  Init systems may bind	listen sockets
       itself and spawn	unicorn	with UNICORN_FD	set  to	 the  file  descriptor
       numbers of the listen socket(s).

       As  of unicorn 5.0, LISTEN_PID and LISTEN_FDS are used for socket acti-
       vation as documented in the sd_listen_fds(3) manpage.  Users relying on
       this feature do not need	to specify a listen socket in the unicorn con-
       fig file.

       o Rack::Builder ri/RDoc

       o Unicorn::Configurator					       ri/RDoc

       o unicorn RDoc <>

       o Rack RDoc <>

       o Rackup	  HowTo	 <

       The Unicorn Community <>.

Unicorn	User Manual	      September	15, 2009		    UNICORN(1)


Want to link to this manual page? Use this URL:

home | help