diff options
Diffstat (limited to 'Documentation/yahns_config.txt')
| -rw-r--r-- | Documentation/yahns_config.txt | 584 |
1 files changed, 0 insertions, 584 deletions
diff --git a/Documentation/yahns_config.txt b/Documentation/yahns_config.txt deleted file mode 100644 index c7c78d7..0000000 --- a/Documentation/yahns_config.txt +++ /dev/null @@ -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-2016 all contributors <yahns-public@yhbt.net> -License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt> - -# SEE ALSO - -yahns(1) |