Connecting to a remote Linux or UNIX server

The following documentation explains how to install the Linux or UNIX server code, start the server daemon, and make a connection to a remote Linux or UNIX server. Look here for setting up a server on Windows.

Prerequisites

To use the Remote System Explorer communications server daemon you need to install Perl. Using the daemon helps eliminate some of the manual steps when you connect to the server.

Installing the server code

Find the package that contains the server. The server code is usually packaged with the containing product and you should refer to that product's documentation for finding and installing the server package. The server is also available, however, on the Eclipse Target Management download site as the package rseserver-<version>-<os>.tar. For example, rseserver-2.0-linux.tar contains the release 2.0 server for Linux. There are servers for Linux, AIX, a generic Unix version that can be tailored to your particular flavor of Unix, and an experimental Mac OS X version.
Ensure that Perl is installed.
Ensure that a Java Runtime Environment (JRE) version 1.4 or higher is installed. An IBM, Oracle or equivalent JRE is required; The gcj-based jvm shipped with most Linux distributions does not work. If in doubt, run the command
java -version (see below) and check if there is a reference to gcj. You can download an Oracle JRE from http://www.oracle.com/technetwork/java/.
Create a directory where you want to install the server code. The remainder of these instructions will assume the directory /opt/rseserver (suitable for team sharing), but you are free to use any directory.
Upload the server package to this directory. You can use FTP.
Switch to the /opt/rseserver directory by typing:
```
cd /opt/rseserver
```
Run the following command in the /opt/rseserver directory to extract the server code from the package appropriate to your operating system. For linux this command is:
```
tar -xf rseserver-2.0-linux.tar
```

Starting the server

You can start the RSE communications server with the server daemon, or manually. Before starting the server, make sure the Java command is in your path, you can do this by running the following command:

java -version

You should see something similar to the following:

java version "1.4.1"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1)
Classic VM (build 1.4.1, J2RE 1.4.1 IBM build cxppc321411-20040301 (JIT enabled: jitc))

If you receive a "command not found" error, then try creating a symbolic link to the java command in /usr/bin by running the following command:

ln -s  /opt/IBMJava2-141/jre/bin/java /usr/bin/java

To start the server with the server daemon

Ensure that you are running using the root user ID. (If the daemon is not run under root, it will be unable to authenticate connecting users.) Run the following commands:
```
su -l root
cd /opt/rseserver
perl ./daemon.pl [daemonPort] [serverPortRange]
```

Note that the server daemon runs on port 4075 by default. You can pass the optional daemonPort argument to force a different port if you want.
If your daemon runs behind a firewall, you may want to specify the optional serverPortRange argument to restrict selected server ports to the range given:

perl ./daemon.pl 4075 10000-10010

To start the server manually

Note: In the following discussion we assume that the RSE server has been installed on Linux. If you are running on a UNIX system the script name is "server.sh" rather than "server.pl".

If you do not have root access on a remote machine, you can start the server manually for your particular user id only. Run the following commands:

cd /opt/rseserver
perl ./server.pl [port]

These commands run the server.pl script located in the /opt/rseserver directory. The port parameter to the server.pl script is optional. If you do not specify a port, then the server will pick the first one available and print the port number to standard out. By default, it is usually 4033. If you would like to use a different port, you will then have to enter this port number in port property for the Files subsystem for your connection in the Remote System Explorer (see Connecting to the Remote Server, below). Otherwise, you do not need to change this property.

Note: When you connect RSE to the server, the server will terminate as soon as you disconnect the client. The daemon, however, will not terminate.

Rexec Server Launcher

If you have Rexec access enabled to your remote system, you can also have the server started automatically by an Rexec command from the client, when you connect. To do so, use the Server Launcher Properties in the New Connection Wizard.

Running the daemon at startup

You might instead want to configure the daemon to run at start up for Linux. To do so, you need to append a call to the daemon to your startup script. Add the following lines to the bottom of the /etc/rc.d/rc.local file:

cd /opt/rseserver
perl ./daemon.pl &

SSL Encryption and Firewalls

By default the RSE DStore connection is unencrypted. You can, however, configure it to use SSL encryption.

Because all dstore data transfer is done through a single TCP/IP connection, the connection can also be tunneled through an ssh channel. In fact, the same ssh channel can also be used to start the server, like in the following example:

ssh -l moberhuber build.eclipse.org -L27127:build.eclipse.org:27127 \
  "sh -c 'cd ~/rseserver/latest; perl ./server.pl 27127'"

Here, the RSE Server is started on port 27127 through an ssh connection, and at the same time port 27127 is forwarded through ssh to the local host. You can now connect RSE to localhost:27127, and the connection will transparently be forwarded to the remote system.

Connecting to the Remote Server

To make a connection to your remote server:

Switch to the Remote System Explorer perspective. From the workbench menu, click Window > Open Perspective > Remote System Explorer.
In the Remote Systems view, New Connection is automatically expanded to show the various remote systems you can connect to through the Remote System Explorer. Expand Linux or Unix to invoke the new connection dialog box and configure a connection.
Enter a name for your first profile and click Next. (This step only occurs if you have never defined a connection before.)
Enter a connection name. This name displays in your tree view and must be unique to the profile.
Enter the name or TCP/IP address of your Linux server in the Host name field, for example, LINUX_A.
(Optional) Enter a Description. The description appears in the Properties view after the connection is created.
Click Finish to define your system.

Attention: To check your port number, right-click your connection or subsystem from the Remote Systems view and select Properties. Click Subsystem to view the relevant information. If your port is "0," then your Remote System Explorer communications server will pick any free port on the server. If you specified a port number when starting the server, you need to enter it here, for example, to work with a firewall.