% yahns_config(5) yahns user manual
%

# NAME

yahns_config - configuration file description for yahns(1)

# DESCRIPTION

Since yahns is a Ruby application server, its configuration file is
implemented in Ruby syntax, making it dependent on the version of
Ruby it is running under.

# TOP-LEVEL DIRECTIVES

* app :TYPE, *APP_ARGUMENTS, &BLOCK

    This defines an application context for yahns to run.  :TYPE defines
    the type of application it runs.  yahns will eventually support
    application types other than :rack, but for now, only :rack is
    supported.

    The &BLOCK given configures the which sockets the app listens on,
    buffering and logging settings.

    An app with the same :TYPE and APP_ARGUMENTS may be defined multiple
    times with different &BLOCK contents (with different listeners and
    buffering settings).

    See the APP-BLOCK DIRECTIVES section for details on what goes into
    the &BLOCK.

    This directive may be specified multiple times for different or
    identical applications.

    If the "working_directory" directive is used, all app directives may
    only be specified after setting "working_directory".

    For Rack HTTP applications, see RACK APP ARGUMENTS for more
    information.

* before_exec &BLOCK

    This runs &BLOCK before Kernel#exec (execve(2) wrapper).  The command
    array to be passed to Kernel#exec may be modified within this hook:

        before_exec do |cmd|
          # you may modify ENV here inside the child process
          ENV["MALLOC_ARENA_MAX"] = ENV["MALLOC_ARENA_TEST"] = "1"

          # You may change to a different installation of Ruby or yahns
          # by doing an in-place modification of cmd:
          cmd.replace(%W(/another/install/of/yahns -c cfg.rb))
        end

    Default: (none)

* client_expire_threshold {INTEGER|FLOAT}

    yahns will start expiring idle clients when it hits this threshold.
    If the threshold is a floating point number, it is that fraction of
    the soft open file limit (RLIMIT_NOFILE ir `ulimit -S -n` in shell).
    Thus if the soft open file limit is 1024 (a typical value) and the
    client_expire_threshold is 0.3, yahns will start expiring clients once
    it hits 307 clients (0.3 * 1024).

    If given a positive integer, yahns will start expiring clients once it
    its this absolute threshold of connected clients.

    If given a negative integer, yahns will start expiring clients once it
    reaches N clients away from the the soft file limit.  That is, if
    client_expire_threshold is -666 and the soft open file limit is 1024,
    it will start expiring once it hits 358 clients.

    Clients are expired when the configured client_timeout for their
    app context is hit.

    Default: 0.5

* logger LOGGER

    Sets LOGGER as the default logger of the process.  The new
    LOGGER 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 yahns daemonized, then
    you must specify a path to prevent error messages from going
    to /dev/null

    A per-APP &BLOCK logger may also be configured inside an app &BLOCK.

    Default: Logger.new($stderr)

* pid PATHNAME

    Sets the path of the PID file for use with management/init scripts.

    Default: none

* queue [NAME] &BLOCK

    As a top-level directive, this configures or defines a queue.
    If no NAME is specified, a default queue (named :default) is
    assumed.  See the QUEUE-LEVEL DIRECTIVES section for details.

    A &BLOCK must be given if used as a top-level directive.  This
    behaves slightly differently inside an app &BLOCK.  This may also
    be given without a block to associate an app block with a named
    queue.

    Usually, only one queue is necessary.  Each queue corresponds to
    an epoll descriptor and worker thread pool.

    Default: NAME defaults to :default

* stderr_path PATHNAME

    Allow redirecting $stderr to a given path.  Unlike doing this from
    the shell, this allows the yahns 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 O_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.

    Default: /dev/null if daemonized, controlling terminal if not

* stdout_path PATHNAME

    Same as stderr_path, except for $stdout.  Not many 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.

    Default: /dev/null if daemonized, controlling terminal if not

* working_directory PATHNAME

    Sets the working directory for the process.  This ensures SIGUSR2 will
    start a new instance of yahns in this directory.  This may be
    a symlink, a common scenario for Capistrano users.  Unlike
    all other yahns configuration directives, this binds immediately
    for error checking and cannot be undone by unsetting it in the
    configuration file and reloading.

    This must be specified before any "app" directives

    Default: / if daemonized, current working directory if not

# QUEUE-LEVEL DIRECTIVES

* max_events INTEGER

    This controls the number of events a worker thread will fetch at
    once via epoll_wait(2).  There is no good reason to change this
    unless you use very few (e.g. 1) worker_threads.  Leaving this at
    1 will give the fairest load balancing behavior with epoll.

    Default: 1

* worker_threads INTEGER

    This controls the number of threads for application processing.
    Each queue has its own thread pool.  Increase this number if your
    applications are able to use more threads effectively or if either
    (or both) input/output buffering are disabled.  Lower this number if
    you do not need multi-thread concurrency at all.

    Default: 7

## APP-BLOCK DIRECTIVES

* atfork_prepare, atfork_parent, atfork_child

    These are identical to the methods defined in WORKER_PROCESSES-LEVEL
    DIRECTIVES, however they are available inside the app blocks for
    convenience in case it is easier to organize per-app hooks.

    Default: (none)

* check_client_connection BOOLEAN

    When enabled, yahns will check the client connection by writing
    the beginning of the HTTP headers before calling the application.

    This can prevent calling the application for clients who have
    disconnected while their connection was waiting for a free
    worker thread.

    This only affects clients connecting over Unix domain sockets and
    TCP via loopback (127.*.*.*).  It is unlikely to detect disconnects
    if the client is on a remote host (even on a fast LAN).

    This has no effect for (rare) HTTP/0.9 clients.

    Default: false

* client_body_buffer_size INTEGER

    This controls the maximum size of a request body before it is
    buffered to the filesystem (instead of memory).  This has no effect
    if input_buffering is false.  This also governs the size of an
    individual read(2) system call when reading a request body.

    There is generally no need to change this value and this directive
    may be removed in the future.

    Default: 8192 bytes (8 kilobytes)

* client_header_buffer_size INTEGER

    This controls the size of a single read(2) syscall for reading
    client request headers.  Increase this as needed if your application
    uses large cookies or long URLs.  Lowering this may reduce GC and
    memory allocator overhead.

    Default 4000 bytes

* client_max_body_size {INTEGER|nil}

    This controls the maximum request body size before a client is
    rejected with an HTTP 413 error.

    Setting this to nil will allow unlimited-sized inputs.

    Default: 1048576 bytes (one megabyte)

* client_timeout SECONDS

    Defines the timeout expiring idle connections.

    If input_buffering is false or :lazy, this defines the maximum
    amount of time a worker thread will wait synchronously for a client
    request body.

    If output_buffering is false, this defines the maximm amount of
    time a worker thread will wait synchronously for a client socket
    to become writable.

    It makes sense to lower this to a low value (e.g. 5 seconds) if
    either output or input buffering are disabled.  The default value
    of 15 seconds is suitable for configurations with both input and
    output buffering enabled and assumes all application dispatch
    finishes in less than 15 seconds.

    Default: 15 (seconds)

* errors {IO|PATHNAME}

    For Rack applications, this controls the env["rack.errors"]
    destination.  If given a PATHNAME, it will be a writable file
    opened with O_APPEND without userspace buffering, making it suitable
    for concurrent appends by multiple processes and threads, as well as
    making it eligible for reopening via SIGUSR1 after log rotation.

    Default: $stderr

* input_buffering {:lazy|true|false}[, OPTIONS]

    This controls buffering of the HTTP request body.

    + true - fully buffers the request before application dispatch.  This is
      most suitable for slow and untrusted clients which may trickle
      the request to the server.

    + :lazy - provides streaming, but rewindable input.  This is suitable
      for fast, trusted clients and is fully-compatible with Rack 1.x
      specifications.  :lazy buffering may also be suitable for slow and
      untrusted clients if you are able and willing to run a queue with
      many worker threads.

    + false - disable input buffering completely.  This violates the
      Rack 1.x spec and is only suitable for fast, trusted clients or
      queues with many worker threads.

    HTTP request headers are always buffered in memory.

    Do not be tempted to disable any buffering because it improves
    numbers on a synthetic benchmark over a fast connection.
    Slow, real-world clients can easily overwhelm servers without both
    input and output buffering.

    Default: true

    The following OPTIONS may be specified:

      + tmpdir: DIRECTORY

        Specify an alternative temporary directory of input_buffering is
        :lazy or true.  This can be used in case the normal temporary
        directory is too small or busy to be used for input buffering.

        Default: Dir.tmpdir (usually from TMPDIR env or /tmp)

* listen ADDRESS [, OPTIONS]

    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 yahns),
    this means Unix domain sockets must not be placed in /tmp

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

      + backlog: INTEGER

        This is the backlog of the listen(2) 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

      + ipv6only: BOOLEAN

        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["REMOTE_ADDR"]
        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

      + sndbuf / rcvbuf: INTEGER

        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

      + reuseport: BOOLEAN

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

        This option must be used when yahns 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 yahns instances is stopped while using this.

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

        ref: https://lwn.net/Articles/542629/

        Default: false (unset)

      + threads: INTEGER

        Used to control the number of threads blocking on the accept(2)
        or accept4(2) system call (per listen socket).

        Usually, only one thread here is necessary, especially when
        multiple worker_processes are configured (as there'll be one
        thread per-process).  Having extra threads may increase
        contention with epoll and FD allocation within one process.

        Note: do not confuse this option with worker_threads for queues,
        each queue has their own thread pool and it makes sense to
        have multiple threads there.

        Default: 1

      + 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)

* logger LOGGER

    Configures a logger within the current app &BLOCK.
    This behaves the same as the logger directive described in
    TOP-LEVEL DIRECTIVES

    Default: uses the top-level logger

* output_buffering BOOLEAN [, OPTIONS]

    This enables or disables buffering of the HTTP response.  If enabled,
    buffering is only performed lazily.  In other words, buffering only
    happens if socket buffers (in the kernel) are filled up, and yahns
    will continously try to flush the buffered data to the socket while
    it is buffering.

    Disabling output buffering is only recommended if ALL clients
    connecting to this application context are fast, trusted or
    you are willing and able to run many worker threads.

    Do not be tempted to disable any buffering because it improves
    numbers on a synthetic benchmark over a fast connection.
    Slow, real-world clients can easily overwhelm servers without both
    input and output buffering.

    If output buffering is disabled, client_timeout controls the maximum
    amount of time a worker thread will wait synchronously.

    Default: true

    The following OPTIONS may be specified:

      + tmpdir: DIRECTORY

        Specify an alternative temporary directory of output_buffering is
        enabled.  This can be used in case the normal temporary directory
        is too small or busy to be used for output buffering.

        Default: Dir.tmpdir (usually from TMPDIR env or /tmp)

* persistent_connections BOOLEAN

    Enable or disables persistent connections and pipelining for HTTP
    connections.  Persistent connections only expire when the global
    client_expire_threshold is hit and a client hits its client_timeout.

    Default: true

* user USER [,GROUP]

    Runs application process(es) as the specified USER and GROUP.

    If using worker_processes, this only affects the workers and the
    master stays running as the user who started it.  This switch will
    occur before calling the atfork_child hook(s).

    GROUP is optional and will not change if unspecified.

    Default: none (no user switching is done)

* queue [NAME or &BLOCK]

    If given a NAME-only, this will associate this app &BLOCK with an
    existing queue.

    If given a &BLOCK-only, this will create an anonymous queue for this
    application context only.  If given a &BLOCK, this takes the same
    parameters (worker_threads and max_events) as described in
    QUEUE-LEVEL DIRECTIVES.

    NAME and &BLOCK may not be combined inside an app &BLOCK.

    Default: uses the global, :default queue if none is specified

* shutdown_timeout SECONDS

    This defines the timeout for gracefully exiting the process if there
    are still connected clients.  This should generally be higher or equal
    to the app with the highest client_timeout value.

    Increase this if your application has slow endpoints which may take
    longer than the default timeout.

    Default: max client_timeout value of all apps in the process

* worker_processes INTEGER [&BLOCK]

    This directive allows yahns to use a master/worker configuration to
    use multiple processes.  Specifying any numeric value (including 1)
    here means yahns will enable yahns to use a master/worker process
    model instead of a single process.

    If an optional &BLOCK is given, it may be used to configure
    pthread_atfork(3)-style hooks.  See WORKER_PROCESSES-LEVEL DIRECTIVES
    for details.

    Using worker_processes is strongly recommended if your application
    relies on using a SIGCHLD handler for reaping forked processes.
    Without worker_processes, yahns must reserve SIGCHLD for rolling
    back SIGUSR2 upgrades, leading to conflicts if the appplication
    expects to handle SIGCHLD.

    Default: nil (single process, no master/worker separation)

## WORKER_PROCESSES-LEVEL DIRECTIVES

Note: all of the atfork_* hooks described here are available inside the
"app" blocks, too.

* atfork_prepare &BLOCK

    This &BLOCK is executed in the parent before fork(2) operation.
    This may be useful for app directives which specify "preload: true"
    to disconnect from databases or otherwise close open file descriptors
    to prevent them from being shared with the children.

    Default: none

* atfork_parent &BLOCK

    This &BLOCK is executed in the parent after the fork(2) operation.
    This may not be useful, but exists in case somebody finds a use for it.

    Default: none

* atfork_child &BLOCK

    This &BLOCK is executed in the child after the fork(2) operation.

    This may be useful for app directives which specify "preload: true"
    to reconnect to databases or reopen closed file descriptors which
    were closed in the atfork_prepare hook.

    Default: none

# RACK APP ARGUMENTS

Rack applications take a PATHNAME to the rackup(1) config file (e.g.
"config.ru") as its first argument.

The only supported keyword argument is the preload: BOOLEAN.

preload: only makes sense if worker_processes are configured.
Preloading an app allows memory to be saved under a copy-on-write GC,
but will often require atfork_* hooks to be registered when configuring
worker_processes.  preload: defaults to false for maximum out-of-the-box
compatibility.

## RACK APP EXAMPLE

    app(:rack, "/path/to/config.ru", preload: false) do
      # APP-BLOCK DIRECTIVES GO HERE
    end

# EXAMPLES

See the examples/ directory in the git source tree.

    git clone git://yhbt.net/yahns.git

# COPYRIGHT

Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>

# SEE ALSO

yahns(1)