S-PLUS 7 Enterprise Server for UNIX/Linux (June 2005) These Release Notes are current as of June 2005. For updates to the Release Notes that are made after this date and other useful information, please see the Web site www.insightful.com/support/splusserver70unix ############################################################################ CONTENTS OF THESE RELEASE NOTES ############################################################################ * Overview of S-PLUS 7 Enterprise Server * Documentation * Contact Information * Installation Instructions * Getting Started * Creating an S-PLUS Server Chapter * Starting the S-PLUS Session Factory * Additional Authentication Options * Troubleshooting Help * Troubleshooting Slow Network Connections * Known Issues * Supported Platforms * Java Runtime Environment (JRE) ############################################################################ OVERVIEW OF S-PLUS 7 Enterprise Server ############################################################################ S-PLUS 7 Enterprise Server provides the advanced data-analysis methods and graphics of S-PLUS 7 for UNIX/Linux in a distributed environment. S-PLUS 7 Enterprise Server builds on the CONNECT/Java interface in S-PLUS, extending it from local to remote Java connectivity. This allows you to develop scalable applications that serve large numbers of users. There are three primary deployment scenarios used with S-PLUS 7 Enterprise Server: * Scenario 1: Convenient access to S-PLUS S-PLUS users can have the S-PLUS Java Graphical User Interface (GUI) on their Windows, UNIX, or Linux workstation, accessing an S-PLUS session on a UNIX or Linux server. * Scenario 2: Custom Java applications This is similar to Scenario 1, except the S-PLUS Java GUI is replaced by a custom Java application as the client. * Scenario 3: Web-based applications S-PLUS 7 Enterprise Server also enables you to provide advanced data-analysis methods and graphics to Web-based applications and other distributed environments. In this scenario, the client is not a GUI application but is instead a Java component (such as a servlet) which fits into a larger architecture. The remote Java connectivity of S-PLUS 7 Enterprise Server enables you to put the analytic engine on a separate server from your Web server, enabling it to be easily scalable. This release includes S+Java Server Pages, an example module for building Web-based applications using JavaServer Pages technology. An application using this module uses JavaServer Pages (JSP) technology to process user requests. The JSP pages contain custom tags to access S-PLUS, in addition to the text and HTML to format the output. The JSP tags incorporate normal S-PLUS commands (typically function calls) that the tags run in an S-PLUS session. Each specific type of tag expects a different type of output, which it includes in the Web page as text, as tables, or as graphs as appropriate. Full documentation and installation instructions are available in the installation directory SHOME/library/example5/AS/sjsp. For information on other types of web integration, such as integrating S-PLUS Enterprise Server, please contact Insightful Support. This document provides guidance on getting started, hints on things to try, and notes regarding known problems with S-PLUS Server. For issues relating to S-PLUS 7.x, see the text file $SHOME/RELNOTES.TXT. ($SHOME is the directory in which the S-PLUS Enterprise Server files are installed; from inside S-PLUS Enterprise Server you can see this directory path by typing getenv("SHOME") at the prompt. From outside S-PLUS Server, the shell command Splus SHOME will return the same path.) ############################################################################ DOCUMENTATION ############################################################################ In addition to these Release Notes, the installation notes are included at in $SHOME/INSTALL_SERVER.TXT. A list of bugs fixed in S-PLUS 7 is included in $SHOME/doc/FIXEDBUG.TXT. This release of S-PLUS Enterprise Server also includes ten manuals available online as Adobe Acrobat (*.pdf) files in $SHOME/doc: Getting Started getstart.pdf with S-PLUS 7 Getting Started getstart_server.pdf with S-PLUS 7 Enterprise Server S-PLUS 7 Enterprise Server usersguide_server.pdf User's Guide for UNIX S-PLUS 7 admin.pdf Installation and Administration Guide S-PLUS 7 User's Guide unixug.pdf S-PLUS 7 Enterprise Developer User's Guide usersguide_server.pdf S-PLUS 7 Programmer's Guide pg.pdf S-PLUS 7 Application adg.pdf Developer's Guide S-PLUS Guide to Statistics statman1.pdf (Volumes 1 and 2) statman2.pdf ############################################################################ CONTACT INFORMATION ############################################################################ Technical Support Global Headquarters 1700 Westlake Avenue North, Suite 500 Seattle, WA 98109 USA Tel: 206.283.8802 or 800.569.0123 Fax: 206.283.6310 e-mail: support@insightful.com Insightful AG Kägenstrasse 17 4153 Reinach Switzerland Tel: +41 61 717 9340 Fax: +41 61 717 9341 e-mail: shelp@insightful.com Insightful UK 5th Floor, Network House Basing View Basingstoke, Hampshire RG21 4HG Tel: +44 (0) 1256 339800 Fax: +44 (0) 1256 339839 e-mail: shelp@insightful.com Insightful France 7, rue Auber 31000 Toulouse France Tel: +33 0 5 62 27 70 60 Fax: +33 0 5 62 27 70 61 e-mail: shelp@insightful.com ############################################################################ INSTALLATION INSTRUCTIONS ############################################################################ For installation of S-PLUS Enterprise Server and the UNIX/Linux/Windows clients, please see the S-PLUS 7 Installation and Administration Guide (admin.pdf) or INSTALL_SERVER.TXT. Both are at the top level of your CD-ROM. ############################################################################ GETTING STARTED ############################################################################ Begin with the booklet Getting Started with S-PLUS 7 Enterprise Server. Before running an S-PLUS Server Java client for the first time, you should create a working directory on the server. This directory will contain any files you want to read into or export from S-PLUS, as well as a .Data directory to hold S-PLUS data objects, metadata objects, and help files. These working directories are called chapters, created with the S-PLUS CHAPTER utility. The first time each user runs a Server client, it creates a chapter called MySwork, which can function as a default working directory; however, it also stores more general user information. Insightful recommends creating at least one chapter separate from MySwork and using that for your day-to-day S-PLUS work. When you develop multiple projects, we recommend that you create a separate chapter for each project. Creating an S-PLUS Server Chapter The following commands will create an S-PLUS Server chapter named "myproj" for you to work in (be sure you don't already have a "myproj" directory in your home directory). This needs to be done for each user: cd mkdir myproj cd myproj Splus CHAPTER When you start the S-PLUS Java client, type this directory into the Work Directory field of the Session Profile dialog. For example, if you created the directory myproj under your home directory, then enter /homes/username/myproj as the work directory for your Session Profile. You are now ready to start S-PLUS Server. First, you must start the S-PLUS Session factory on the server, if it hasn't been started previously. Then, you can start your client. Starting the S-PLUS Session Factory The S-PLUS session factory must be started before any S-PLUS Java clients are started. The administration GUI for the S-PLUS session factory may be launched from the UNIX command line with the command: Splus SERVER -servertools [portnumber] where the optional portnumber argument may specify a non-default RMI port. Alternatively, the session factory can be started from the UNIX command line. The syntax for starting an S-Plus session factory is: Splus SERVER -factory [-limit max_sessions] [-logfile filepath] [-rotate] [portnumber] Initial testing has shown that Server is most stable and robust when the number of sessions is limited to approximately 4 sessions per CPU. On Linux server, this has a hard limit of approximately 13 sessions, because of the 512 process limit which is compiled into the Linux kernel. The number of sessions will also be affected by available memory and usage. In some cases, the Linux OS file-descriptor limit can be exceeded as well. For more information on starting the S-PLUS Enterprise Server session factory, see the S-PLUS 7 Installation and Administration Manual. Additional Authentication Options 1. Background When running S-PLUS Enterprise Server, the server must run an S-PLUS engine at the request of a client. Ideally, this engine process will run under an account associated with a particular Unix username and password. This ensures that each client is only allowed those privileges assigned to that account in performing S-PLUS analyses. By default, Server may be run by any user who has permission to access the Splus script. Once the server has been launched, clients request sessions by specifying a login profile, which includes a username/password combination indicating the account to use in running the S-PLUS engine process. Server employs telnet as a means of authenticating the account as well as launching the engine process. This use of telnet is problematic for some sites. Since the basic telnet service transmits username/password information in clear text, it is susceptible to port-snooping, and represents a security risk on the server. Hence, some sites do not permit the use of telnet. In this release, two additional authentication options have been introduced to help address situations where telnet usage is prohibited. 2. Running in "Root Server Mode" Root Server Mode is a configuration where the use of telnet is eliminated, and standard Unix authentication is performed on the server to validate the username/password provided by the clients. In order to perform this authentication, the server process must have root permission (to access restricted files such as /etc/shadow,... etc). The engine processes are then started under the account of the authenticated user. Note that the "standard Unix authentication" that is supported at this time only includes normal DES and MD5 encrypted passwords. This authentication has been tested for both local and NIS based authentication. At this time there is no support for Kerberos, PAM (pluggable authentication modules), or other more esoteric authentication schemes. To use this authentication mode, the Java property "splus.root.server" must be set to a non-null string such as "true". The steps for starting in this mode will be: 1) Log in to the server as root (or "su" to root). 2) Set the JAVA_OPTIONS environmental variable as follows: csh: > setenv JAVA_OPTIONS -Dsplus.root.server=true or sh: > JAVA_OPTIONS="-Dsplus.root.server=true" > export JAVA_OPTIONS 3) Start Server: > Splus SERVER -factory If this mode is always to be used, the setting of the environmental variable may be added to the beginning of the Splus script (using the two lines indicated for "sh"). 3. Running in "Single User Mode" Single User Mode is a configuration where authentication is entirely omitted. All engine processes are started under the same account that the server is using. This may be useful if only a small number of (trusted) analysts are accessing the server, or if the S-PLUS Enterprise Server is being used as a back-end engine for a servlet based web-app, and there is no need to associate the S-PLUS engine processes with distinct user accounts. It should be noted that this configuration introduces a further security risk, namely that anyone with access to S-PLUS Enterprise Server client software will be able to acquire an engine process from the server without any sort of authentication being performed by the server. To use this authentication mode, the Java property "splus.single.user" must be set to a non-null string such as "true". The steps for starting in this mode will be: 1) Log in to the server using the account that all session will use. 2) Set the JAVA_OPTIONS environmental variable as follows: csh: > setenv JAVA_OPTIONS -Dsplus.single.user=true or sh: > JAVA_OPTIONS="-Dsplus.single.user=true" > export JAVA_OPTIONS 3) Start Server: > Splus SERVER -factory If this mode is always to be used, the setting of the environmental variable may be added to the beginning of the Splus script (using the two lines indicated for "sh"). ############################################################################ TROUBLESHOOTING HELP ############################################################################ The help system for S-PLUS Enterprise Server uses a Web server. This may be on the server on which the S-PLUS Enterprise Server is installed, another machine on your local network, or anywhere on the Internet. You can invoke help at the command line or by clicking the Help menu. If the help system is not properly configured, you will get an error message when starting the UNIX or Linux clients, or when starting the Help Viewer: Help System Startup Failed There are two possible solutions: 1. Check that your help Web server is configured properly. 2. Try using http://www.insightful.com as your help server. On Windows clients, there will be no error message, but no help window will appear when help is requested. If this is the case, you may use www.insightful.com as your help site or you may install the help files on your network. We will maintain a server at that URL which will support the S-PLUS Server help system, but to ensure best performance, we recommend installing the help files locally. The options are explained below: 1. Modify your session profile to use www.insightful.com: Edit the Client Login Session Profile and click the Advanced button. Type www.insightful.com in the Help System URL prompt. 2. Use the Helpviewer to access www.insightful.com: Run the HELPSTART or S-PLUS Help Viewer application on your client machine. For UNIX or Linux clients, run SplusClient HELPSTART -url www.insightful.com For Windows clients, click the S-PLUS Help at www.insightful.com in the S-PLUS Server program folder. Note: using the independent help viewer allows you to browse the help files. However, invoking help at the command line does not work. 3. Set up the help files on a Web server on the Server host: Configure the Web server as described in the S-PLUS Enterprise Server User's Guide. 4. Set up the help files on a Web server on another machine on your network: Configure the webserver on that machine and specify its URL (instead of www.insightful.com) as described in options 1 or 2 above. ############################################################################ TROUBLESHOOTING SLOW NETWORK CONNECTIONS ############################################################################ Slow networks can sometimes cause client connections to time out, especially at startup. In order to aid in diagnosing such problems, S-PLUS Enterprise Server allows you to configure the query timeout, which determines how long the S-PLUS Java GUI will wait before deciding that the S-PLUS engine is hung. To set the option: Edit the script, $SHOME/cmd/SERVER, and add the line -Dsplus.query.timeout=5 \ at line #91. This time out option was implemented in this manner to avoid backward compatibility issues with existing clients. ############################################################################ KNOWN ISSUES ############################################################################ Bugs discovered while preparing this release are presented here. * Rarely, a situation will be encountered which causes a session to hang. Then, if the administrator attempts to kill the session from the server tools GUI, the server tools will hang also. In that case, the administrator will need to manually kill both processes from the UNIX command line, using kill -9 * Opening or closing a large number of graphsheets in the S-PLUS Java client GUI will sometimes cause out-of-memory errors. This is caused by the client JVM running out of heap memory space. The workaround is to boost the maximum heap using the java -Xmx option. On Windows, modify the Client Login shortcut properties to add the this option. For example, adding -Xmx128m would increase the available heap memory to 128 MB. On UNIX and Linux, set an environmental variable in the shell before starting the client, using: setenv JAVA_OPTIONS -Xmx128m // csh, tcsh or export JAVA_OPTIONS=-Xmx128m // sh, bash, ksh * Under some conditions crashed sessions are not removed from the list of sessions kept by the server. It may be necessary to stop and restart the server occasionally to eliminate these stale list entries. * When using java.graph to export graphics, such as JPEGs or BMPs, the function requires a valid XServer display to generate the graphics. If this is not accessible, the graphic file will not be created. * When starting S-PLUS Server on a display hosting a different operating system than that on which S-PLUS Server is running, you may receive a large number of warnings of the form "Font specified in font.properties not found [fontname]." * Error boxes from modal dialogs do not have "always on top" status. They may become hidden behind the dialog box where they can't be seen. * When browsing to a file using the File Transfer or Import/Export dialogs, the name of the parent directory will be left in the text field. Delete the text, and type in the name of the desired file. * Some functions, such as motif(), require a display which supports the X Window System. This may be either a UNIX display, or a PC running an X server such as X-Win32 or Reflection X. * If the S-PLUS client terminates abnormally while the Help Window is open, you may need to manually kill the Help Window process. This can be done using the Task Manager on Windows. On UNIX/Linux, type kill -9 * When transferring files between a Windows client and the server using the File Transfer utility, the end-of-line characters are not modified. This means that text files may not display properly in Notepad. The workaround is to use Wordpad instead, which will correctly interpret the end-of-line characters. * Cutting-and-pasting large amounts of text into the S-PLUS Java GUI can cause the interface to slow down and eventually hang. The workaround is to cut-and-paste small amounts of text at a time, or to use source() to execute S-PLUS commands instead. * In previous releases of this server product (S-PLUS Enterprise Server), some commands were automatically put into the background for execution. These processes are now kept active, and you can put the commands into the background by adding an ampersand ("&") after the command. Example: Splus SERVER -factory -logfile aslog.txt 4556 & This is important if you are running automated scripts from previous releases. * After confirming that Splus starts normally at the command line, try running "whoami" to confirm the user has access. A SHOME/cmd/WHOAMI script can be edited to return a valid username. In previous releases, the "whoami" command was hard-coded into the S-PLUS Server (v.2.0) product. * Remote client crashes during startup when using a different JRE than the one shipped with the client. This problem goes away if splus.help.off is set, which you can do in one of the following ways: * GUI: Enter "SplusClient" at a UNIX prompt. When the dialog is invoked, click the Edit button, then the Advanced button, and make sure the "Help viewer off at startup" checkbox is not checked. * Command line: The command line equivalent is to include -Dsplus.help.off=true when starting the client. In Windows, this is included on the command line when invoking java to run the client. * UNIX prompt: Use the -helpoff argument. * After shutting down the telnet process after running the SESSION command, the following message is expected in the log file: "Timeout with ... cmd/SESSION ... &" ############################################################################ SUPPORTED PLATFORMS ############################################################################ S-PLUS 7 Enterprise Server for UNIX/Linux is supported on the following platforms: Solaris 2.8 or 2.9 on SPARC processors (32-bit) RedHat Enterprise Linux WS 3.0 Clients: Solaris 2.8 or 2.9 on SPARC processors (32-bit) Red Hat Enterprise Linux WS 3.0 Windows 2000, Windows XP, Windows 2003 Server ############################################################################ Java Runtime Environment (JRE) ############################################################################ The Java runtime environment (JRE) version 1.4.2 is included in the S-PLUS Enterprise Server. Your operating system must support JRE 1.4.2 in order to run the Java-enabled version of S-PLUS. Note that the JRE provided by S-PLUS is installed as part of the S-PLUS distribution, and under normal circumstances, it is used only by S-PLUS. If you have a different version of the JRE on your system, the JRE used by S-PLUS should not interfere with your other JRE applications, which will continue to use the version you've previously installed. Solaris requirements for the JRE are available from http://java.sun.com/j2se/1.4.2/jre/install-solaris.html These release notes indicate the Java 2 SDK Standard Edition v1.4.2 is supported on Solaris 7, 8, and 9 operating environments. Linux requirements for the JRE are available from http://java.sun.com/j2se/1.4.2/jre/install-linux.html These release notes provide the following recommendations: "Java 2 Runtime Environment v 1.4.2 (J2RE) is supported on i586 Intel and 100% compatible platforms running Linux. For a list of supported operating systems and desktop managers, see System Configurations. A minimum of 32 megabytes of RAM are required. Recommended 48 megabytes of RAM, 16-bit color mode. You should have about 75 megabytes of free disk space before attempting to install the Java 2 Runtime Environment software."