summary refs log tree commit homepage
path: root/SIGNALS
blob: b1a3141a6037cd8aa298a6001942500641755b17 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
== Signal handling

In general, signals need only be sent to the master process.  However,
the signals unicorn uses internally to communicate with the worker
processes are documented here as well.

=== Master Process

 * HUP - reload config file and gracefully restart all workers
   If preload_app is false (the default), the application code
   will be reloaded when workers are restarted as well.

 * 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.

=== 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

 * QUIT - gracefully exit after finishing the current request

 * USR1 - reopen all logs owned by the worker process
   See Unicorn::Util.reopen_logs for what is considered a log.

=== Procedure to replace a running unicorn 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 listener backlog size of already-bound sockets

2. The path to the unicorn 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 unicorn running now, both of which will have workers servicing
   requests.  Your process tree should look something like this:

   unicorn master (old)
   \_ unicorn worker[0]
   \_ unicorn worker[1]
   \_ unicorn worker[2]
   \_ unicorn worker[3]
   \_ unicorn master
      \_ unicorn worker[0]
      \_ unicorn worker[1]
      \_ unicorn worker[2]
      \_ unicorn worker[3]

4. You can now send WINCH to the old master process so only the new workers
   serve requests.  If your unicorn 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.

5. You should now ensure that everything is running correctly with the
   new workers as the old workers die off.

6a. If everything seems ok, then send QUIT to the old master.  You're done!

6b. 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.