Class: Unicorn::Configurator
- Inherits:
-
Object
- Object
- Unicorn::Configurator
- Defined in:
- lib/unicorn/configurator.rb
Overview
Implements a simple DSL for configuring a Unicorn server.
See unicorn.bogomips.org/examples/unicorn.conf.rb and unicorn.bogomips.org/examples/unicorn.conf.minimal.rb example configuration files. An example config file for use with nginx is also available at unicorn.bogomips.org/examples/nginx.conf
Constant Summary collapse
- RACKUP =
:stopdoc: used to stash stuff for deferred processing of cli options in config.ru after “working_directory” is bound. Do not rely on this being around later on…
{ :daemonize => false, :host => Unicorn::Const::DEFAULT_HOST, :port => Unicorn::Const::DEFAULT_PORT, :set_listener => false, :options => { :listeners => [] } }
- DEFAULTS =
Default settings for Unicorn
{ :timeout => 60, :logger => Logger.new($stderr), :worker_processes => 1, :after_fork => lambda { |server, worker| server.logger.info("worker=#{worker.nr} spawned pid=#{$$}") }, :before_fork => lambda { |server, worker| server.logger.info("worker=#{worker.nr} spawning...") }, :before_exec => lambda { |server| server.logger.info("forked child re-executing...") }, :pid => nil, :preload_app => false, }
Instance Attribute Summary collapse
-
#after_reload ⇒ Object
Returns the value of attribute after_reload.
-
#config_file ⇒ Object
Returns the value of attribute config_file.
-
#set ⇒ Object
Returns the value of attribute set.
Instance Method Summary collapse
-
#[](key) ⇒ Object
:nodoc:.
-
#after_fork(*args, &block) ⇒ Object
sets after_fork hook to a given block.
-
#before_exec(*args, &block) ⇒ Object
sets the before_exec hook to a given Proc object.
-
#before_fork(*args, &block) ⇒ Object
sets before_fork got be a given Proc object.
-
#commit!(server, options = {}) ⇒ Object
:nodoc:.
-
#expand_addr(address) ⇒ Object
expands “unix:path/to/foo” to a socket relative to the current path expands pathnames of sockets if relative to “~” or “~username” expands “*:port and ”:port“ to ”0.0.0.0:port“.
-
#initialize(defaults = {}) ⇒ Configurator
constructor
:startdoc:.
-
#listen(address, opt = {}) ⇒ Object
adds an
address
to the existing listener set. -
#listeners(addresses) ⇒ Object
sets listeners to the given
addresses
, replacing or augmenting the current set. -
#logger(new) ⇒ Object
sets object to the
new
Logger-like object. -
#pid(path) ⇒ Object
sets the
path
for the PID file of the unicorn master process. -
#preload_app(bool) ⇒ Object
Enabling this preloads an application before forking worker processes.
-
#reload(merge_defaults = true) ⇒ Object
:nodoc:.
-
#stderr_path(path) ⇒ Object
Allow redirecting $stderr to a given path.
-
#stdout_path(path) ⇒ Object
Same as stderr_path, except for $stdout.
-
#timeout(seconds) ⇒ Object
sets the timeout of worker processes to
seconds
. -
#user(user, group = nil) ⇒ Object
Runs worker processes as the specified
user
andgroup
. -
#worker_processes(nr) ⇒ Object
sets the current number of worker_processes to
nr
. -
#working_directory(path) ⇒ Object
sets the working directory for Unicorn.
Constructor Details
#initialize(defaults = {}) ⇒ Configurator
:startdoc:
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
# File 'lib/unicorn/configurator.rb', line 45 def initialize(defaults = {}) #:nodoc: self.set = Hash.new(:unset) @use_defaults = defaults.delete(:use_defaults) self.config_file = defaults.delete(:config_file) # after_reload is only used by unicorn_rails, unsupported otherwise self.after_reload = defaults.delete(:after_reload) set.merge!(DEFAULTS) if @use_defaults defaults.each { |key, value| self.__send__(key, value) } Hash === set[:listener_opts] or set[:listener_opts] = Hash.new { |hash,key| hash[key] = {} } Array === set[:listeners] or set[:listeners] = [] reload(false) end |
Instance Attribute Details
#after_reload ⇒ Object
Returns the value of attribute after_reload.
12 13 14 |
# File 'lib/unicorn/configurator.rb', line 12 def after_reload @after_reload end |
#config_file ⇒ Object
Returns the value of attribute config_file.
12 13 14 |
# File 'lib/unicorn/configurator.rb', line 12 def config_file @config_file end |
#set ⇒ Object
Returns the value of attribute set.
12 13 14 |
# File 'lib/unicorn/configurator.rb', line 12 def set @set end |
Instance Method Details
#[](key) ⇒ Object
:nodoc:
97 98 99 |
# File 'lib/unicorn/configurator.rb', line 97 def [](key) # :nodoc: set[key] end |
#after_fork(*args, &block) ⇒ Object
sets after_fork hook to a given block. This block will be called by the worker after forking. The following is an example hook which adds a per-process listener to every worker:
after_fork do |server,worker|
# per-process listener ports for debugging/admin:
addr = "127.0.0.1:#{9293 + worker.nr}"
# the negative :tries parameter indicates we will retry forever
# waiting on the existing process to exit with a 5 second :delay
# Existing options for Unicorn::Configurator#listen such as
# :backlog, :rcvbuf, :sndbuf are available here as well.
server.listen(addr, :tries => -1, :delay => 5, :backlog => 128)
# drop permissions to "www-data" in the worker
# generally there's no reason to start Unicorn as a priviledged user
# as it is not recommended to expose Unicorn to public clients.
worker.user('www-data', 'www-data') if Process.euid == 0
end
136 137 138 |
# File 'lib/unicorn/configurator.rb', line 136 def after_fork(*args, &block) set_hook(:after_fork, block_given? ? block : args[0]) end |
#before_exec(*args, &block) ⇒ Object
sets the before_exec hook to a given Proc object. This Proc object will be called by the master process right before exec()-ing the new unicorn binary. This is useful for freeing certain OS resources that you do NOT wish to share with the reexeced child process. There is no corresponding after_exec hook (for obvious reasons).
153 154 155 |
# File 'lib/unicorn/configurator.rb', line 153 def before_exec(*args, &block) set_hook(:before_exec, block_given? ? block : args[0], 1) end |
#before_fork(*args, &block) ⇒ Object
sets before_fork got be a given Proc object. This Proc object will be called by the master process before forking each worker.
143 144 145 |
# File 'lib/unicorn/configurator.rb', line 143 def before_fork(*args, &block) set_hook(:before_fork, block_given? ? block : args[0]) end |
#commit!(server, options = {}) ⇒ Object
:nodoc:
85 86 87 88 89 90 91 92 93 94 95 |
# File 'lib/unicorn/configurator.rb', line 85 def commit!(server, = {}) #:nodoc: skip = [:skip] || [] if ready_pipe = RACKUP.delete(:ready_pipe) server.ready_pipe = ready_pipe end set.each do |key, value| value == :unset and next skip.include?(key) and next server.__send__("#{key}=", value) end end |
#expand_addr(address) ⇒ Object
expands “unix:path/to/foo” to a socket relative to the current path expands pathnames of sockets if relative to “~” or “~username” expands “*:port and ”:port“ to ”0.0.0.0:port“
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 |
# File 'lib/unicorn/configurator.rb', line 441 def (address) #:nodoc return "0.0.0.0:#{address}" if Integer === address return address unless String === address case address when %r{\Aunix:(.*)\z} File.($1) when %r{\A~} File.(address) when %r{\A(?:\*:)?(\d+)\z} "0.0.0.0:#$1" when %r{\A(.*):(\d+)\z} # canonicalize the name packed = Socket.pack_sockaddr_in($2.to_i, $1) Socket.unpack_sockaddr_in(packed).reverse!.join(':') else address end end |
#listen(address, opt = {}) ⇒ Object
adds an address
to the existing listener set.
The following options may be specified (but are generally not needed):
:backlog
: this is the backlog of the listen() syscall.
Some operating systems allow negative values here to specify the maximum allowable value. In most cases, this number is only recommendation and there are other OS-specific tunables and variables that can affect this number. See the listen(2) syscall documentation of your OS for the exact semantics of this.
If you are running unicorn on multiple machines, lowering this number can help your load balancer detect when a machine is overloaded and give requests to a different machine.
Default: 1024
:rcvbuf
, :sndbuf
: maximum receive and send buffer sizes of sockets
These correspond to the SO_RCVBUF and SO_SNDBUF settings which can be set via the setsockopt(2) syscall. Some kernels (e.g. Linux 2.4+) have intelligent auto-tuning mechanisms and there is no need (and it is sometimes detrimental) to specify them.
See the socket API documentation of your operating system to determine the exact semantics of these settings and other operating system-specific knobs where they can be specified.
Defaults: operating system defaults
:tcp_nodelay
: disables Nagle’s algorithm on TCP sockets
This has no effect on UNIX sockets.
Default: operating system defaults (usually Nagle’s algorithm enabled)
:tcp_nopush
: enables TCP_CORK in Linux or TCP_NOPUSH in FreeBSD
This will prevent partial TCP frames from being sent out. Enabling tcp_nopush
is generally not needed or recommended as controlling tcp_nodelay
already provides sufficient latency reduction whereas Unicorn does not know when the best times are for flushing corked sockets.
This has no effect on UNIX sockets.
:tries
: times to retry binding a socket if it is already in use
A negative number indicates we will retry indefinitely, this is useful for migrations and upgrades when individual workers are binding to different ports.
Default: 5
:delay
: seconds to wait between successive tries
Default: 0.5 seconds
:umask
: sets the file mode creation mask for UNIX sockets
Typically UNIX domain sockets are created with more liberal file permissions than the rest of the application. By default, we create UNIX domain sockets to be readable and writable by all local users to give them the same accessibility as locally-bound TCP listeners.
This has no effect on TCP listeners.
Default: 0 (world read/writable)
:tcp_defer_accept:
defer accept() until data is ready (Linux-only)
For Linux 2.6.32 and later, this is the number of retransmits to defer an accept() for if no data arrives, but the client will eventually be accepted after the specified number of retransmits regardless of whether data is ready.
For Linux before 2.6.32, this is a boolean option, and accepts are always deferred indefinitely if no data arrives. This is similar to :accept_filter => "dataready"
under FreeBSD.
Specifying true
is synonymous for the default value(s) below, and false
or nil
is synonymous for a value of zero.
A value of 1
is a good optimization for local networks and trusted clients. For Rainbows! and Zbatery users, a higher value (e.g. 60
) provides more protection against some denial-of-service attacks. There is no good reason to ever disable this with a zero
value when serving HTTP.
Default: 1 retransmit for Unicorn, 60 for Rainbows! 0.95.0+
+:accept_filter: defer accept() until data is ready (FreeBSD-only)
This enables either the “dataready” or (default) “httpready” accept() filter under FreeBSD. This is intended as an optimization to reduce context switches with common GET/HEAD requests. For Rainbows! and Zbatery users, this provides some protection against certain denial-of-service attacks, too.
There is no good reason to change from the default.
Default: “httpready”
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 |
# File 'lib/unicorn/configurator.rb', line 321 def listen(address, opt = {}) address = (address) if String === address [ :umask, :backlog, :sndbuf, :rcvbuf, :tries ].each do |key| value = opt[key] or next Integer === value or raise ArgumentError, "not an integer: #{key}=#{value.inspect}" end [ :tcp_nodelay, :tcp_nopush ].each do |key| (value = opt[key]).nil? and next TrueClass === value || FalseClass === value or raise ArgumentError, "not boolean: #{key}=#{value.inspect}" end unless (value = opt[:delay]).nil? Numeric === value or raise ArgumentError, "not numeric: delay=#{value.inspect}" end set[:listener_opts][address].merge!(opt) end set[:listeners] << address end |
#listeners(addresses) ⇒ Object
sets listeners to the given addresses
, replacing or augmenting the current set. This is for the global listener pool shared by all worker processes. For per-worker listeners, see the after_fork example This is for internal API use only, do not use it in your Unicorn config file. Use listen instead.
208 209 210 211 212 |
# File 'lib/unicorn/configurator.rb', line 208 def listeners(addresses) # :nodoc: Array === addresses or addresses = Array(addresses) addresses.map! { |addr| (addr) } set[:listeners] = addresses end |
#logger(new) ⇒ Object
sets object to the new
Logger-like object. The new logger-like object must respond to the following methods:
+debug+, +info+, +warn+, +error+, +fatal+
The default Logger will log its output to the path specified by stderr_path
. If you’re running Unicorn daemonized, then you must specify a path to prevent error messages from going to /dev/null.
108 109 110 111 112 113 114 115 |
# File 'lib/unicorn/configurator.rb', line 108 def logger(new) %w(debug info warn error fatal).each do |m| new.respond_to?(m) and next raise ArgumentError, "logger=#{new} does not respond to method=#{m}" end set[:logger] = new end |
#pid(path) ⇒ Object
sets the path
for the PID file of the unicorn master process
345 |
# File 'lib/unicorn/configurator.rb', line 345 def pid(path); set_path(:pid, path); end |
#preload_app(bool) ⇒ Object
Enabling this preloads an application before forking worker processes. This allows memory savings when using a copy-on-write-friendly GC but can cause bad things to happen when resources like sockets are opened at load time by the master process and shared by multiple children. People enabling this are highly encouraged to look at the before_fork/after_fork hooks to properly close/reopen sockets. Files opened for logging do not have to be reopened as (unbuffered-in-userspace) files opened with the File::APPEND flag are written to atomically on UNIX.
In addition to reloading the unicorn-specific config settings, SIGHUP will reload application code in the working directory/symlink when workers are gracefully restarted when preload_app=false (the default). As reloading the application sometimes requires RubyGems updates, Gem.refresh
is always called before the application is loaded (for RubyGems users).
During deployments, care should always be taken to ensure your applications are properly deployed and running. Using preload_app=false (the default) means you must check if your application is responding properly after a deployment. Improperly deployed applications can go into a spawn loop if the application fails to load. While your children are in a spawn loop, it is is possible to fix an application by properly deploying all required code and dependencies. Using preload_app=true means any application load error will cause the master process to exit with an error.
375 376 377 378 379 380 381 382 |
# File 'lib/unicorn/configurator.rb', line 375 def preload_app(bool) case bool when TrueClass, FalseClass set[:preload_app] = bool else raise ArgumentError, "preload_app=#{bool.inspect} not a boolean" end end |
#reload(merge_defaults = true) ⇒ Object
:nodoc:
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 |
# File 'lib/unicorn/configurator.rb', line 61 def reload(merge_defaults = true) #:nodoc: if merge_defaults && @use_defaults set.merge!(DEFAULTS) if @use_defaults end instance_eval(File.read(config_file), config_file) if config_file parse_rackup_file RACKUP[:set_listener] and set[:listeners] << "#{RACKUP[:host]}:#{RACKUP[:port]}" # unicorn_rails creates dirs here after working_directory is bound after_reload.call if after_reload # working_directory binds immediately (easier error checking that way), # now ensure any paths we changed are correctly set. [ :pid, :stderr_path, :stdout_path ].each do |var| String === (path = set[var]) or next path = File.(path) File.writable?(path) || File.writable?(File.dirname(path)) or \ raise ArgumentError, "directory for #{var}=#{path} not writable" end end |
#stderr_path(path) ⇒ Object
Allow redirecting $stderr to a given path. Unlike doing this from the shell, this allows the unicorn process to know the path its writing to and rotate the file if it is used for logging. The file will be opened with the File::APPEND flag and writes synchronized to the kernel (but not necessarily to disk) so multiple processes can safely append to it.
If you are daemonizing and using the default logger
, it is important to specify this as errors will otherwise be lost to /dev/null. Some applications/libraries may also triggering warnings that go to stderr, and they will end up here.
395 396 397 |
# File 'lib/unicorn/configurator.rb', line 395 def stderr_path(path) set_path(:stderr_path, path) end |
#stdout_path(path) ⇒ Object
Same as stderr_path, except for $stdout. Not many Rack applications write to $stdout, but any that do will have their output written here. It is safe to point this to the same location a stderr_path. Like stderr_path, this defaults to /dev/null when daemonized.
403 404 405 |
# File 'lib/unicorn/configurator.rb', line 403 def stdout_path(path) set_path(:stdout_path, path) end |
#timeout(seconds) ⇒ Object
sets the timeout of worker processes to seconds
. Workers handling the request/app.call/response cycle taking longer than this time period will be forcibly killed (via SIGKILL). This timeout is enforced by the master process itself and not subject to the scheduling limitations by the worker process. Due the low-complexity, low-overhead implementation, timeouts of less than 3.0 seconds can be considered inaccurate and unsafe.
For running Unicorn behind nginx, it is recommended to set “fail_timeout=0” for in your nginx configuration like this to have nginx always retry backends that may have had workers SIGKILL-ed due to timeouts.
# See http://wiki.nginx.org/NginxHttpUpstreamModule for more details
# on nginx upstream configuration:
upstream unicorn_backend {
# for UNIX domain socket setups:
server unix:/path/to/unicorn.sock fail_timeout=0;
# for TCP setups
server 192.168.0.7:8080 fail_timeout=0;
server 192.168.0.8:8080 fail_timeout=0;
server 192.168.0.9:8080 fail_timeout=0;
}
181 182 183 184 185 186 187 |
# File 'lib/unicorn/configurator.rb', line 181 def timeout(seconds) Numeric === seconds or raise ArgumentError, "not numeric: timeout=#{seconds.inspect}" seconds >= 3 or raise ArgumentError, "too low: timeout=#{seconds.inspect}" set[:timeout] = seconds end |
#user(user, group = nil) ⇒ Object
Runs worker processes as the specified user
and group
. The master process always stays running as the user who started it. This switch will occur after calling the after_fork hook, and only if the Worker#user method is not called in the after_fork hook
431 432 433 434 435 436 |
# File 'lib/unicorn/configurator.rb', line 431 def user(user, group = nil) # raises ArgumentError on invalid user/group Etc.getpwnam(user) Etc.getgrnam(group) if group set[:user] = [ user, group ] end |
#worker_processes(nr) ⇒ Object
sets the current number of worker_processes to nr
. Each worker process will serve exactly one client at a time. You can increment or decrement this value at runtime by sending SIGTTIN or SIGTTOU respectively to the master process without reloading the rest of your Unicorn configuration. See the SIGNALS document for more information.
195 196 197 198 199 200 201 |
# File 'lib/unicorn/configurator.rb', line 195 def worker_processes(nr) Integer === nr or raise ArgumentError, "not an integer: worker_processes=#{nr.inspect}" nr >= 0 or raise ArgumentError, "not non-negative: worker_processes=#{nr.inspect}" set[:worker_processes] = nr end |
#working_directory(path) ⇒ Object
sets the working directory for Unicorn. This ensures SIGUSR2 will start a new instance of Unicorn in this directory. This may be a symlink, a common scenario for Capistrano users. Unlike all other Unicorn configuration directives, this binds immediately for error checking and cannot be undone by unsetting it in the configuration file and reloading.
413 414 415 416 417 418 419 420 421 422 423 424 425 |
# File 'lib/unicorn/configurator.rb', line 413 def working_directory(path) # just let chdir raise errors path = File.(path) if config_file && config_file[0] != ?/ && ! File.readable?("#{path}/#{config_file}") raise ArgumentError, "config_file=#{config_file} would not be accessible in" \ " working_directory=#{path}" end Dir.chdir(path) Unicorn::HttpServer::START_CTX[:cwd] = ENV["PWD"] = path end |