% 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. 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. 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. 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 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. 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 and all contributors.\ License: GPLv3 or later # SEE ALSO yahns(1)