SIGNALS

   1 == Signal handling
   2
   3 In general, signals need only be sent to the master process.  However, the
   4 signals Rainbows uses internally to communicate with the worker processes are
   5 documented here as well.
   6
   7 === Master Process
   8
   9 * HUP - reload config file, app, and gracefully restart all workers
  10
  11 * INT/TERM - quick shutdown, kills all workers immediately
  12
  13 * QUIT - graceful shutdown, waits for workers to finish their
  14   current request before finishing.
  15
  16 * USR1 - reopen all logs owned by the master and all workers
  17   See Unicorn::Util.reopen_logs for what is considered a log.
  18
  19 * USR2 - reexecute the running binary.  A separate QUIT
  20   should be sent to the original process once the child is verified to
  21   be up and running.
  22
  23 * WINCH - gracefully stops workers but keep the master running.
  24   This will only work for daemonized processes.
  25
  26 * TTIN - increment the number of worker processes by one
  27
  28 * TTOU - decrement the number of worker processes by one
  29
  30 === Worker Processes
  31
  32 Sending signals directly to the worker processes should not normally be
  33 needed.  If the master process is running, any exited worker will be
  34 automatically respawned.
  35
  36 * INT/TERM - Quick shutdown, immediately exit.
  37   Unless WINCH has been sent to the master (or the master is killed),
  38   the master process will respawn a worker to replace this one.
  39
  40 * QUIT - Gracefully exit after finishing the current request.
  41   Unless WINCH has been sent to the master (or the master is killed),
  42   the master process will respawn a worker to replace this one.
  43
  44 * USR1 - Reopen all logs owned by the worker process.
  45   See Unicorn::Util.reopen_logs for what is considered a log.
  46   Log files are not reopened until it is done processing
  47   the current request, so multiple log lines for one request
  48   (as done by Rails) will not be split across multiple logs.
  49
  50 === Procedure to replace a running rainbows executable
  51
  52 You may replace a running instance of unicorn with a new one without
  53 losing any incoming connections.  Doing so will reload all of your
  54 application code, Unicorn config, Ruby executable, and all libraries.
  55 The only things that will not change (due to OS limitations) are:
  56
  57 1. The path to the rainbows executable script.  If you want to change to
  58    a different installation of Ruby, you can modify the shebang
  59    line to point to your alternative interpreter.
  60
  61 The procedure is exactly like that of nginx:
  62
  63 1. Send USR2 to the master process
  64
  65 2. Check your process manager or pid files to see if a new master spawned
  66    successfully.  If you're using a pid file, the old process will have
  67    ".oldbin" appended to its path.  You should have two master instances
  68    of rainbows running now, both of which will have workers servicing
  69    requests.  Your process tree should look something like this:
  70
  71      rainbows master (old)
  72      \_ rainbows worker[0]
  73      \_ rainbows worker[1]
  74      \_ rainbows worker[2]
  75      \_ rainbows worker[3]
  76      \_ rainbows master
  77         \_ rainbows worker[0]
  78         \_ rainbows worker[1]
  79         \_ rainbows worker[2]
  80         \_ rainbows worker[3]
  81
  82 3. You can now send WINCH to the old master process so only the new workers
  83    serve requests.  If your rainbows process is bound to an
  84    interactive terminal, you can skip this step.  Step 5 will be more
  85    difficult but you can also skip it if your process is not daemonized.
  86
  87 4. You should now ensure that everything is running correctly with the
  88    new workers as the old workers die off.
  89
  90 5. If everything seems ok, then send QUIT to the old master.  You're done!
  91
  92    If something is broken, then send HUP to the old master to reload
  93    the config and restart its workers.  Then send QUIT to the new master
  94    process.