Rserve - Binary R server
RForge.net

Rserve

About Rserve
Documentation
Examples
FAQ
News
Download/Files
 
GIT access
Technical Info
Check results
Package R docs

Documentation for Rserve


Introduction
         Rserve itself is the server, that is a program that responds to requests from clients. It listens for any incoming connections and processes incoming requests. You need to have R-1.5.0 or higher installed on your system in order to be able to use Rserve. For details concerning installation and start of the server, see Installation futher down.

The server is nothing without clients, therefore we have developed three client frameworks:

  • REngine Java client - located in src/client/java-new is a full client suite that allows any Java application (JDK 1.4 or higher) to access an Rserve. The suite is written entirely in Java. It provides automatic type translation for most objects such as int,double,arrays,String or Vector and classes for special R objects such as RBool, RList etc. For sample code and a small tutorial see Examples. JavaDoc documentation of the REngine-classes is available online here.
    Compared with previous Java clients (see bloew) this new client API is more flexible, with better design, has better exception handling and is aimed to support both JRI and Rserve transparently.
     
    JRclient - located in src/client/java-old is an older Java API that was used in Rserve 0.4 and earlier. It is deprecated and neew project should use the new client above (based on REngine classes).
     
  • C++ client - it is located in src/client/cxx directory in the Rserve source package and provides basic interface to Rserve from any C++ program.
     
  • R client - a small client directly in the Rserve package. As of Rserve 0.5-0 is uses special, direct communication with Rserve. As of Rserve 1.7 it has been moved to a separate RSclient pacakge.
There are several other clients written by 3rd parties: It is basically possible to write clients for any language that supports TCP/IP sockets. The separation of client/serve side allows to prevent multi-threading problems that arise when linking against R library directly.
Installation
The easiest way to install Rserve is to simply use
install.packages("Rserve",,"http://rforge.net")
in R. Unix users, please note that R must have been configured with --enable-R-shlib in order to use Rserve. This is the default on Windows and Mac OS X, but not on some Linux distributions (see below).

Alternative way is to use a source package for R. Please note that this works only for unix-based operating systems such as Linux, Solaris, AIX or Mac OS X. (There is currently a binary version available for Windows, see below.) Download the package file Rserve_1.8-15.tar.gz in the current directory. Login with enough privileges to add R packages and run:

R CMD INSTALL Rserve_1.8-15.tar.gz

This should compile and install Rserve. You can check whether Rserve is installed correctly by looking in the $RHOME/bin directory - there should be a file called Rserve.

If the compilation fails, please check that R shared library exists and is properly installed. It is located in $RHOME/bin and is named libR.so or libR.dylib. If it is missing, get an R distribution with shared library included or compile R with --enable-R-shlib configure flag.

Windows: There is a binary version of Rserve in the download section. Copy the file to the directory containing R.DLL. If you have more versions of R, make sure that you use the one most recently installed, becasue Rserve detects the location of $RHOME from the registry. Although Rserve works on Windows it is not recommended to use it on that platform. Windows lacks important features that make the separation of namespaces possible, therefore Rserve for Windows works in cooperative mode only, that is only one connection at a time is allowed and all subsequent connections share the same namespace. Briefly: don't use Windows unless you really have to. There is a DCOM interface available for R, you may be better off with that solution.

Launching Rserve
Rserve comes now as an R package, so one way to start Rserve is from within R, just type
library(Rserve)
Rserve()
That command knows how to find Rserve, how to setup the environment and how to start it, regardless of your platform.

Note: depending on how you are running R, it may require additional parameters such as --no-save (R will tell you). In that case you have to pass that parameter in the args argument such as

Rserve(args="--no-save")

However, Rserve is a stand-alone program, so it can be started directly as well. If you installed Rserve from a source package (on unix), type:

R CMD Rserve

Depending on the purpose and libraries on your computer you may want to add --gui-none or --no-save (see R documentation). Rserve passes any parameters to the underlying R engine except for Rserver-related parameters (see command line arguments). After initialization Rserve daemonizes itself to work as a server. It can be shut down gracefully (i.e. it will wait until all existing connections are finished) if it recieves shutdown command from an authorized connection. It terminates not so gracefully if it receives usual termination signals.

If no config file is supplied, Rserve accepts no remote connections, requires no authentication and file transfer is enabled. For more details about how to configure Rserve, see below.

Configuration
Rserve is configured by the configuration file /etc/Rserv.conf (can be changed at compile time by specifying -DCONFIG_FILE=..). Additional configuration files can be added by the --RS-conf command line argument. The possible configuration entries are as follows (all entries are optional; default values are in angled brackets):

workdir <path> [/tmp/Rserv]
pwdfile <file> [none=disabled]
remote enable|disable [disable]
auth required|disable [disable]
plaintext enable|disable [disable]
fileio enable|disable [enable]
interactive yes|no [yes]
(since 0.6-2)

(since version 0.1-9):
socket <socket> [none=disabled]
port <port> [6311]
maxinbuf <size in kb> [262144]

(since version 0.3):
maxsendbuf <size in kb> [0=unlimited]
uid <uid> [none]
gid <gid> [none]
su now|server|client [none]
(since 0.6-1)

(since version 0.3-16):
source <file>
eval <expressions>

(since version 0.5 and unix only):
chroot <directory> [none]
sockmod <mode> [0=default]
umask <mask> [0]

(since version 0.5-3):
encoding native|utf8|latin1 [native]
(since version 0.6-2):

The list is now too long so best sources are the NEWS file and the rserve.conf Wiki on GitHub

Since 0.5 the following configuration options can use either hexadecimal (0x..), octal (0..) or decimal values: port, uid, gid, umask and sockmode. All other options and command-line options always assume decimal notation.

Most entries are self-explaining and their command line equivalents are described below. maxinbuf and maxsendbuf are rather special. Previous versions of Rserve had fixed buffer sizes. Since 0.1-9 internal buffers change per-connection automatically. The maxinbuf specifies (in kilobytes) the maximal allowable size of the input buffer, that is the maximal size of data transported from the client to the server. Analogously maxsendbuf sets the maximum size of the send buffer, that is the size of data sent from Rserve to the client. If your server is likely to process very many parallel connections you may want to lower this setting for security reasons. On the other hand if the server will process only few connections in parallel and you expect very large data, raise the value accorsing to your computer's memory. Baiscally the settings are present to prevent malicious users from crashing your server by supplying too large data. 0 has a special meaning telling Rserve to allow unlimited use.

uid, gid, umask and chroot are supported on unix computers only. If Rserve is run as root user, then it switches the user/group to the specified uid/gid before starting the server. Note: The directives are processed in the same sequence in which they occur in the config file. This implies that if using both uid and gid, you MUST use gid first, otherwise if setting uid first, then the user will have no right to change gid anymore! Also chroot must be used before uid as only root can use it.

A note about security: Anyone with access to R has access to the shell via "system" command, so you should consider following rules:

  • NEVER EVER run Rserv as root (unless uid/gid entries are set) - this compromises the box totally
  • Use "remote disable" whenever you don't need remote access.
  • If you need remote access use "auth required" and "plaintext disable". Consider also that anyone with the access can decipher other's passwords if he knows how to. The authentication prevents hackers from the net to break into Rserve, but it doesn't (and cannot) protect from inside attacks (since R has no security measures). You should also use a special, restricted user for running Rserv as a public server, so noone can try to hack the box it runs on.
  • don't enable plaintext unless you really have to. Passing passwords in plain text over the net is not wise and not necessary since both Rserv and JRclient provide encrypted passwords with server-side challenge (thus safe from sniffing).
  • On unix consider using su client and cachepwd yes options with a password file that is only root-readable. That will prevent client password retrieval and clients from attacking the server (see NEWS for 0.6-1).

String encoding directive was introduced in Rserve 0.5-3. This means that strings are converted to the given encoding before being sent to the client and also all strings from the client are assumed to come from the given encoding. (Previously the strings were always passed as-is with no conversion). The currently supported encodings are "native" (same as the server session locale), "utf8" and "latin1". The server default is currently "native" for compatibility with previous versions (but may change to "utf8" in the future, so explicit use of encoding in the config file is advised).

If a server is used mainly by Java clients, it is advisable to set the server encoding to "utf8" since that it the only encoding supported by Java clients. (i.e. add encoding utf8 line to the config file).

For efficiency it is still advisable to run Rserve in the same locale as the majority of clients to minimize the necessary conversions. With diverse clients UTF-8 is the most versatile encoding for the server to run in while it can still serve latin1 clients as well.

Command line arguments
Starting with Rserve 0.1-9 special command line arguments are supported in addition to the config file. Normally Rserve passes all arguments to R, but several special ones are processed and removed from the list before initializing R. Those parameters override any settings specified in the config file.
--RS-port portRserve will listen on the specified TCP port.
--RS-socket socketuse the specified local unix socket instead of TCP/IP.
--RS-workdir pathset working directory root for connections to the specified path.
--RS-conf fileload the specified config file (the default config file is still loaded, but its settings have lower priority).
--RS-dumplimit n(debug version of Rserve only) specifies the number of values to print when dumping content of packages or SEXPs (default is 128).
--RS-settingsprint current settings of the Rserve. Useful to check the current configuration.
--RS-encoding encodingset default string encoding to the given value
--helpprints a brief help screen and exits (R is not started)
--versionprints version of Rserve. This argument is retained in the list and processed by R as well.
In order to list all currently supported arguments, type:
R CMD Rserve --help