doc: preliminary manpages for yahns(1), yahns_config(5)

This should hopefully make yahns more appealing and easier-to-use.

1 files changed, 480 insertions, 0 deletions

diff --git a/Documentation/yahns_config.txt b/Documentation/yahns_config.txt
new file mode 100644
index 0000000..258ca8d
--- /dev/null
+++ b/Documentation/yahns_config.txt
@@ -0,0 +1,480 @@
+% 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.
+
+* 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
+
+* 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.
+
+    Default: 114688 bytes (112 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.
+
+    Default: 5 (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}
+
+    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.
+
+    Default: true
+
+* 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)
+
+      + 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
+
+    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.
+
+    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.
+
+    If output buffering is disabled, client_timeout controls the maximum
+    amount of time a worker thread will wait synchronously.
+
+    Default: true
+
+* 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.
+
+    The master process always stays running as the user who started it.
+    This switch will occur after calling the after_fork hook.
+    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
+
+* 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.
+
+    Default: nil (single process, no master/worker separation)
+
+## WORKER_PROCESSES-LEVEL DIRECTIVES
+
+* 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)