Method: Unicorn::Configurator#listen

Defined in:: lib/unicorn/configurator.rb

#listen(address, options = {}) ⇒ `Object`

Adds an address to the existing listener set. May be specified more than once. address may be an Integer port number for a TCP port, an “IP_ADDRESS:PORT” for TCP listeners or a pathname for UNIX domain sockets.

listen 3000 # listen to port 3000 on all TCP interfaces
listen "127.0.0.1:3000"  # listen to port 3000 on the loopback interface
listen "/path/to/.unicorn.sock" # listen on the given Unix domain socket
listen "[::1]:3000" # listen to port 3000 on the IPv6 loopback interface

When using Unix domain sockets, be sure: 1) the path matches the one used by nginx 2) uses the same filesystem namespace as the nginx process For systemd users using PrivateTmp=true (for either nginx or unicorn), this means Unix domain sockets must not be placed in /tmp

The following options may be specified (but are generally not needed):

:backlog => number of clients

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

Note: with the Linux kernel, the net.core.somaxconn sysctl defaults to 128, capping this value to 128. Raising the sysctl allows a larger backlog (which may not be desirable with multiple, load-balanced machines).

:rcvbuf => bytes, :sndbuf => bytes

Maximum receive and send buffer sizes (in bytes) 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 => true or false

Disables Nagle’s algorithm on TCP sockets if true.

Setting this to true can make streaming responses in Rails 3.1 appear more quickly at the cost of slightly higher bandwidth usage. The effect of this option is most visible if nginx is not used, but nginx remains highly recommended with unicorn.

This has no effect on UNIX sockets.

Default: true (Nagle’s algorithm disabled) in unicorn This defaulted to false in unicorn 3.x

:tcp_nopush => true or false

Enables/disables TCP_CORK in Linux or TCP_NOPUSH in FreeBSD

This prevents partial TCP frames from being sent out and reduces wakeups in nginx if it is on a different machine. Since unicorn is only designed for applications that send the response body quickly without keepalive, sockets will always be flushed on close to prevent delays.

This has no effect on UNIX sockets.

Default: false This defaulted to true in unicorn 3.4 - 3.7

:ipv6only => true or false

This option makes IPv6-capable TCP listeners IPv6-only and unable to receive IPv4 queries on dual-stack systems. A separate IPv4-only listener is required if this is true.

Enabling this option for the IPv6-only listener and having a separate IPv4 listener is recommended if you wish to support IPv6 on the same TCP port. Otherwise, the value of env will appear as an ugly IPv4-mapped-IPv6 address for IPv4 clients (e.g “:ffff:10.0.0.1” instead of just “10.0.0.1”).

Default: Operating-system dependent

:reuseport => true or false

This enables multiple, independently-started unicorn instances to bind to the same port (as long as all the processes enable this).

This option must be used when unicorn first binds the listen socket. It cannot be enabled when a socket is inherited via SIGUSR2 (but it will remain on if inherited), and it cannot be enabled directly via SIGHUP.

Note: there is a chance of connections being dropped if one of the unicorn instances is stopped while using this.

This is supported on *BSD systems and Linux 3.9 or later.

ref: lwn.net/Articles/542629/

Default: false (unset)

:tries => Integer

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

Seconds to wait between successive tries

Default: 0.5 seconds

:umask => mode

Sets the file mode creation mask for UNIX sockets. If specified, this is usually in octal notation.

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: 0000 (world-read/writable)

:tcp_defer_accept => Integer

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. There is no good reason to ever disable this with a zero value with unicorn.

Default: 1

:accept_filter => String

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.

There is no good reason to change from the default.

Default: “httpready”

# File 'lib/unicorn/configurator.rb', line 483

def listen(address, options = {})
  address = expand_addr(address)
  if String === address
    [ :umask, :backlog, :sndbuf, :rcvbuf, :tries ].each do |key|
      value = options[key] or next
      Integer === value or
        raise ArgumentError, "not an integer: #{key}=#{value.inspect}"
    end
    [ :tcp_nodelay, :tcp_nopush, :ipv6only, :reuseport ].each do |key|
      (value = options[key]).nil? and next
      TrueClass === value || FalseClass === value or
        raise ArgumentError, "not boolean: #{key}=#{value.inspect}"
    end
    unless (value = options[:delay]).nil?
      Numeric === value or
        raise ArgumentError, "not numeric: delay=#{value.inspect}"
    end
    set[:listener_opts][address].merge!(options)
  end

  set[:listeners] << address
end

Method: Unicorn::Configurator#listen

#listen(address, options = {}) ⇒ Object

#listen(address, options = {}) ⇒ `Object`