SIGNALS

   1 == Signal handling
   2
   3 In general, signals need only be sent to the master process.  However,
   4 the signals Unicorn uses internally to communicate with the worker
   5 processes are documented here as well.  With the exception of TTIN/TTOU,
   6 signal handling matches the behavior of {nginx}[http://nginx.net/] so it
   7 should be possible to easily share process management scripts between
   8 Unicorn and nginx.
   9
  10 One example init script is distributed with unicorn:
  11 http://unicorn.bogomips.org/examples/init.sh
  12
  13 === Master Process
  14
  15 * HUP - reloads config file and gracefully restart all workers.
  16   If the "preload_app" directive is false (the default), then workers
  17   will also pick up any application code changes when restarted.  If
  18   "preload_app" is true, then application code changes will have no
  19   effect; USR2 + QUIT (see below) must be used to load newer code in
  20   this case.  When reloading the application, +Gem.refresh+ will
  21   be called so updated code for your application can pick up newly
  22   installed RubyGems.  It is not recommended that you uninstall
  23   libraries your application depends on while Unicorn is running,
  24   as respawned workers may enter a spawn loop when they fail to
  25   load an uninstalled dependency.
  26
  27 * INT/TERM - quick shutdown, kills all workers immediately
  28
  29 * QUIT - graceful shutdown, waits for workers to finish their
  30   current request before finishing.
  31
  32 * USR1 - reopen all logs owned by the master and all workers
  33   See Unicorn::Util.reopen_logs for what is considered a log.
  34
  35 * USR2 - reexecute the running binary.  A separate QUIT
  36   should be sent to the original process once the child is verified to
  37   be up and running.
  38
  39 * WINCH - gracefully stops workers but keep the master running.
  40   This will only work for daemonized processes.
  41
  42 * TTIN - increment the number of worker processes by one
  43
  44 * TTOU - decrement the number of worker processes by one
  45
  46 === Worker Processes
  47
  48 Note: as of unicorn 4.8, the master uses a pipe to signal workers
  49 instead of kill(2) for most cases.  Using signals still (and works and
  50 remains supported for external tools/libraries), however.
  51
  52 Sending signals directly to the worker processes should not normally be
  53 needed.  If the master process is running, any exited worker will be
  54 automatically respawned.
  55
  56 * INT/TERM - Quick shutdown, immediately exit.
  57   Unless WINCH has been sent to the master (or the master is killed),
  58   the master process will respawn a worker to replace this one.
  59   Immediate shutdown is still triggered using kill(2) and not the
  60   internal pipe as of unicorn 4.8
  61
  62 * QUIT - Gracefully exit after finishing the current request.
  63   Unless WINCH has been sent to the master (or the master is killed),
  64   the master process will respawn a worker to replace this one.
  65
  66 * USR1 - Reopen all logs owned by the worker process.
  67   See Unicorn::Util.reopen_logs for what is considered a log.
  68   Log files are not reopened until it is done processing
  69   the current request, so multiple log lines for one request
  70   (as done by Rails) will not be split across multiple logs.
  71
  72   It is NOT recommended to send the USR1 signal directly to workers via
  73   "killall -USR1 unicorn" if you are using user/group-switching support
  74   in your workers.  You will encounter incorrect file permissions and
  75   workers will need to be respawned.  Sending USR1 to the master process
  76   first will ensure logs have the correct permissions before the master
  77   forwards the USR1 signal to workers.
  78
  79 === Procedure to replace a running unicorn executable
  80
  81 You may replace a running instance of unicorn with a new one without
  82 losing any incoming connections.  Doing so will reload all of your
  83 application code, Unicorn config, Ruby executable, and all libraries.
  84 The only things that will not change (due to OS limitations) are:
  85
  86 1. The path to the unicorn executable script.  If you want to change to
  87    a different installation of Ruby, you can modify the shebang
  88    line to point to your alternative interpreter.
  89
  90 The procedure is exactly like that of nginx:
  91
  92 1. Send USR2 to the master process
  93
  94 2. Check your process manager or pid files to see if a new master spawned
  95    successfully.  If you're using a pid file, the old process will have
  96    ".oldbin" appended to its path.  You should have two master instances
  97    of unicorn running now, both of which will have workers servicing
  98    requests.  Your process tree should look something like this:
  99
 100      unicorn master (old)
 101      \_ unicorn worker[0]
 102      \_ unicorn worker[1]
 103      \_ unicorn worker[2]
 104      \_ unicorn worker[3]
 105      \_ unicorn master
 106         \_ unicorn worker[0]
 107         \_ unicorn worker[1]
 108         \_ unicorn worker[2]
 109         \_ unicorn worker[3]
 110
 111 3. You can now send WINCH to the old master process so only the new workers
 112    serve requests.  If your unicorn process is bound to an interactive
 113    terminal (not daemonized), you can skip this step.  Step 5 will be more
 114    difficult but you can also skip it if your process is not daemonized.
 115
 116 4. You should now ensure that everything is running correctly with the
 117    new workers as the old workers die off.
 118
 119 5. If everything seems ok, then send QUIT to the old master.  You're done!
 120
 121    If something is broken, then send HUP to the old master to reload
 122    the config and restart its workers.  Then send QUIT to the new master
 123    process.