yahns 1.11.0 → 1.12.0

data/Documentation/yahns.txt

@@ -1,72 +0,0 @@
-% yahns(1) yahns user manual
-%
-
-# NAME
-
-yahns - multi-threaded, non-blocking application server for Ruby
-
-# SYNOPSYS
-
-yahns -c CONFIG_FILE [-D|--daemonize]
-
-# DESCRIPTION
-
-yahns(1) is the primary interface for launching a yahns application
-server.  The configuration file is documented in yahns_config(5).  yahns
-hosts Rack HTTP applications, but may support others in the future such
-as DRb.
-
-# SIGNALS
-
-The following UNIX signals may be sent to the running yahns process.
-If yahns is configured for worker_processes (optional), signals should
-only be sent to the master process.
-
-* INT/TERM/QUIT - graceful shutdown.  If repeated (any of these signals
-  is sent twice), shutdown occurs immediately.
-* USR1 - reopen all logs owned by the master and all workers.
-  This scans the Ruby ObjectSpace for all open File objects with the O_APPEND
-  file flag and buffering disabled (IO#sync==false)
-* USR2 - reexecute the running binary.  A separate QUIT should be sent to
-* HUP - if worker_processes are not used, this will reexecute the running
-  binary and gracefully exit the running process.  If worker_processes are
-  used, this will reload config file, app, and gracefully restart all workers
-* WINCH - gracefully stops workers but keep the master running.
-  This will only work for daemonized processes and only if the
-  worker_processes configuration directive is used.
-* TTIN - increment the number of worker processes by one
-  (only if the worker_processes directive is used)
-* TTOU - decrement the number of worker processes by one
-  (only if the worker_processes directive is used)
-
-# ENVIRONMENT
-
-yahns(1) itself requires no special environment variables.  However,
-environment variables such as RACK_ENV and RAILS_ENV can affect Rack and
-Rails applications it hosts.  Ruby and C library implementation-specific
-environment variables will also affect it.
-
-yahns will update the PWD (current working directory) env if the
-working_directory directive is set (see yahns_config(5)).
-
-LISTEN_FDS and LISTEN_PID variables are used in our emulation
-of sd_listen_fds(3) function.   See sd_listen_fds(3) manpage
-for more details.
-
-# FILES
-
-See yahns_config(5) for documentation on the configuration file format.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to <yahns-public@yhbt.net>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright (C) 2013-2015 all contributors <yahns-public@yhbt.net>
-License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-yahns-rackup(1), yahns_config(5), sd_listen_fds(3)

data/Documentation/yahns_config.txt

@@ -1,584 +0,0 @@
-% 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 (C) 2013-2015 all contributors <yahns-public@yhbt.net>
-License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-yahns(1)