From 37a12997628fcab722512f8a6370b92d44e33529 Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Fri, 2 Oct 2009 20:44:03 -0700
Subject: initial revision

No tests yet, but the old "gossamer" and "rainbows" branches
seem to be basically working.
---
 SIGNALS | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 SIGNALS

(limited to 'SIGNALS')

diff --git a/SIGNALS b/SIGNALS
new file mode 100644
index 0000000..fe68fa9
--- /dev/null
+++ b/SIGNALS
@@ -0,0 +1,94 @@
+== Signal handling
+
+In general, signals need only be sent to the master process.  However, the
+signals Rainbows uses internally to communicate with the worker processes are
+documented here as well.
+
+=== Master Process
+
+* HUP - reload config file, app, and gracefully restart all workers
+
+* INT/TERM - quick shutdown, kills all workers immediately
+
+* QUIT - graceful shutdown, waits for workers to finish their
+  current request before finishing.
+
+* USR1 - reopen all logs owned by the master and all workers
+  See Unicorn::Util.reopen_logs for what is considered a log.
+
+* USR2 - reexecute the running binary.  A separate QUIT
+  should be sent to the original process once the child is verified to
+  be up and running.
+
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes.
+
+* TTIN - increment the number of worker processes by one
+
+* TTOU - decrement the number of worker processes by one
+
+=== Worker Processes
+
+Sending signals directly to the worker processes should not normally be
+needed.  If the master process is running, any exited worker will be
+automatically respawned.
+
+* INT/TERM - Quick shutdown, immediately exit.
+  Unless WINCH has been sent to the master (or the master is killed),
+  the master process will respawn a worker to replace this one.
+
+* QUIT - Gracefully exit after finishing the current request.
+  Unless WINCH has been sent to the master (or the master is killed),
+  the master process will respawn a worker to replace this one.
+
+* USR1 - Reopen all logs owned by the worker process.
+  See Unicorn::Util.reopen_logs for what is considered a log.
+  Log files are not reopened until it is done processing
+  the current request, so multiple log lines for one request
+  (as done by Rails) will not be split across multiple logs.
+
+=== Procedure to replace a running rainbows executable
+
+You may replace a running instance of unicorn with a new one without
+losing any incoming connections.  Doing so will reload all of your
+application code, Unicorn config, Ruby executable, and all libraries.
+The only things that will not change (due to OS limitations) are:
+
+1. The path to the rainbows executable script.  If you want to change to
+   a different installation of Ruby, you can modify the shebang
+   line to point to your alternative interpreter.
+
+The procedure is exactly like that of nginx:
+
+1. Send USR2 to the master process
+
+2. Check your process manager or pid files to see if a new master spawned
+   successfully.  If you're using a pid file, the old process will have
+   ".oldbin" appended to its path.  You should have two master instances
+   of rainbows running now, both of which will have workers servicing
+   requests.  Your process tree should look something like this:
+
+     rainbows master (old)
+     \_ rainbows worker[0]
+     \_ rainbows worker[1]
+     \_ rainbows worker[2]
+     \_ rainbows worker[3]
+     \_ rainbows master
+        \_ rainbows worker[0]
+        \_ rainbows worker[1]
+        \_ rainbows worker[2]
+        \_ rainbows worker[3]
+
+3. You can now send WINCH to the old master process so only the new workers
+   serve requests.  If your rainbows process is bound to an
+   interactive terminal, you can skip this step.  Step 5 will be more
+   difficult but you can also skip it if your process is not daemonized.
+
+4. You should now ensure that everything is running correctly with the
+   new workers as the old workers die off.
+
+5. If everything seems ok, then send QUIT to the old master.  You're done!
+
+   If something is broken, then send HUP to the old master to reload
+   the config and restart its workers.  Then send QUIT to the new master
+   process.
-- 
cgit v1.2.3-24-ge0c7