rserve.conf

Rserve configuration file

Rserve supports setting of configuration directives either via arguments on the command line or from a configuration file. The configuration file is a simple text file with entries of the form

setting value

For the full list of supported settings (configuration directives), see below. The corresponding entry as an argument on the command line is --RS-set setting=value and is equivalent to the corresponding setting value entry. One exception is fork here (see special section below) which can only be used in a configuration file.

Configuration directives supported by latest Rserve version

All supported configuration directives listed by their occurrence in the source code (FIXME: someone may want to group them into logical groups)

• log.io (boolean) if enabled the content of I/O messages is logged in debug mode (has no effect in normal mode)
• daemon (boolean) if enabled Rserve will daemonize
• close.all.stdio (boolean) if enabled, stdout/stderr are closed and re-directed to /dev/null
• msg.id (boolean) if enabled Rserve uses message IDs in the headers
• remote (boolean) if enabled servers listen on all external interfaces so they can be used over the network, otherwise just loopback interface (local) is bound
• tag.argv (boolean) if enabled the program name is changed after forking to distinguish the server instance from working sessions
• forward.stdio (boolean) if enabled stdout/stderr is forwarded using OOB send
• ulog string, defining destination for logging. Can be either a path to a local socket or either of tcp://<host>[:port] or udp://<host>:[port] to send logging to and external server (if port is not specified 514 is used). The protocol is compatible with syslogd.
• keep.alive (boolean) if enabled SO_KEEPALIVE is enabled on the socket
• switch.qap.tls (boolean) if enabled TLS switch is allowed for QAP connections (i.e. enabling encryption on unencrypted QAP)
• qap.oc (boolean, alternate name rserve.oc) if enabled, Object-Capability mode (OCAP) of the QAP protocol is used (see OCAP mode)
• console.oob (boolean) if enabled R console I/O generates OOB send messages (OOB must be enabled for this to have any effect)
• console.input (boolean) if enabled R ReadConsole API invokes OOB message to query the client for input (has no effect unless console.oob is also enabled)
• websockets.qap.oc (boolean) if enabled the WebSockets QAP server uses Object-Capability mode
• random.uid (boolean) if enabled random uid is used when switching uid after connect
• random.gid (boolean) if enabled random gid is used when switching gid after connect
• random.uid.range (string of the form xxx-yyy) range for randomly generated uids
• auto.uid (boolean) if enabled uid is determined from the password file on authentication
• auto.gid (boolean) if enabled gid is determined from the password file on authentication
• default.uid (integer) uid to use as fall-back if it cannot be determined during authentication
• default.gid (integer) gid to use as fall-back if it cannot be determined during authentication
• oob.idle.interval (integer) interval in seconds after which an "idle" OOB send packet is sent to the client (mostly to prevent proxies from dropping the connection)
• qap.port (integer, alternative name port) port to use by the QAP server
• ipv6 (boolean) if enabled servers listen on IPv6
• use.idle.callback (boolean) if enabled .ocap.idle() function is called when R is idle in OCAP mode (currently if idle for 200ms)
• http.upgrade.websockets (boolean) if enabled HTTP server allows upgrade to the WebSockets protocol on the same connection
• http.raw.body (boolean) if enabled HTTP callback sends raw (unparsed) body
• websockets.port (integer) port to use for the WebSockets server
• http.port (integer) port to use for the HTTP server
• tls.key (path) path to the file containing the RSA key to be used for TLS
• tls.ca (path) path to the file (in PEM format) containing Certificate Authority certificates the be registered with TLS
• tls.cert (path) path to the file (in PEM format) containing the certificate to use for TLS servers
• tls.client (string) specification of the behavior concerning client certificates. Possible values: none (don't request, don't check), request (request, but don't check), require (request and require a valid certificate), match:..., prefix:... and suffix:... for additional filters on required certificates (see NEWS entry Rserve 1.8-8 for details).
• pid.file (path) path to the file that will hold the PID of the Rserve server process once started
• rsa.key (path) path to the RSA key to use for RSA authentication
• qap.tls.port (integer, alternative name tls.port) port of the secure server running QAP wrapped in TLS
• http.tls.port (integer, alternative name https.port) port of the secure server running HTTP wrapped in TLS
• websockets.tls.port (integer) port of the secure server running WebSockets wrapped in TLS
• qap (boolean, alternative name rserve) if enabled QAP server is started (this is the only server enabled by default)
• websockets.qap (boolean) if enabled WebSockets mode with QAP protocol is started
• websockets.text (boolean) if enabled WebSockets mode with text protocol is started (deprecated and discouraged)
• websockets (boolean) if enabled all WebSocket modes are enabled
• maxinbuf (integer) limit for the size of incoming packets in kB (default 256). This is mostly a safety setting such that incoming packets cannot exhaust the server's memory easily. Recommended to increase if the client is expected to send large data to the server.
• source (path) path to a file to use via source() in the stand-alone Rserve process prior to starting the servers. NOTE: run.Rserve() is not a stand-alone process and thus does not use this directive.
• eval (string) the string will be parsed and evaluated in the global environment in the stand-alone Rserve process prior to starting the servers
• maxsendbuf (integer) limit for the size of the output buffer in kB (default: none)
• su (string, one of now, server or client) determines the time at which a user switch is performed
• http.user (string) username to switch to when running the HTTP server
• https.user (string) username to switch to when running the HTTP/TLS server
• websockets.user (string) username to switch to when running the WebSockets server
• uid (integer/oct) user ID to switch to
• gid (integer/oct) group ID to switch to
• chroot (path) path to use as a chroot jail
• umask (integer/oct) umask to set when running the server (used after su server)
• allow (string) IP address to add to the white-list (only IPv4 is supported at this point)
• control (boolean) if enabled control commands (server eval, server source, shutdown) are allowed (NOTE: not supported since Rserve 1.8)
• shutdown (boolean) if enabled CMD_shutdown is allowed (it doesn't affect shutdown via SIGINT)
• workdir (path) path to the working directory used as root for per-connection directories
• workdir.clean (boolean) if enabled the working directory for a closed connection is removed upon exit even if it is dirty
• workdir.mode (integer/oct) mode (unix permissions) for the per-connection working directories
• workdir.parent.mode (integer/oct) more for the root of all per-connection working directories
• encoding (string) string encoding to use in the protocol. It must be an encoding recognized by R's iconv facilities. Note that many clients require UTF-8.
• socket (path) path to the local socket used for QAP
• sockmod (integer/oct) mode for the local socket
• pwdfile (path) path to the password file. The file is expected to contain one user/password pair per line, separated by a whitespace.
• auth.function (string) name of an R function to use for authentication instead of the built-in Rserve facilities.
• auth (boolean or require - only first character is checked) if enabled authentication is required before any other command can be used
• interactive (boolean) if enabled R is run in interactive mode, otherwise not
• plaintext (boolean) if enabled plain-text authentication is allowed
• oob (boolean) if enabled out-of-band (OOB) messages (send and msg) can be used by the R code run in the session
• fileio (boolean) if enabled file I/O QAP commands are allowed (non-OCAP mode only), deprecated and not recommended
• r.control (boolean, alternative name r-control) if enabled the R session can use self-command to issue control commands (as opposed to control commands initiated by the client)
• cachepwd (boolean or indefinitely) controls caching of passwords. If enabled the passwords file is read on connection (before su is executed), if disabled it is read at the time of authentication and if indefinitely then it only read at the time of server start.

Special

• fork here is a directive that can be only used in the configuration file (i.e., it cannot be used via --RS-set) and it instructs Rserve to fork the server at that point. It enables the creation of multiple server instances from a single Rserve startup, typically by using multiple port directives interspersed with fork here. (Technically, the directive is fork with the only supported parameter here at this point)

Substitutions

The shell-like form ${NAME} anywhere on the right-hand side of config directives is replaced by the value of the NAME environment variable (since 1.8-0)

Types

• boolean directives accept true values 1, true, yes and enable. In practice, only the first character is checked, so e, enable and enabled are equivalent. When used in run.Rserve the expected values are TRUE or FALSE.
• integer/oct type means that prefix 0x is interpreted as hexadecimal integer, 0 as octal integer and no prefix as decimal integer.