Client / Server Fiswidgets

---

Client / Server Overview

Starting with version 2.2, the command invocation manager and Java GUI can communicate to each other from separate machines. Using features of the Java language, the two components can call methods on each other via a network connection. This new feature in Fiswidgets is called client / server mode. When put into this mode, the Java GUI becomes a client and connects to a Java program running on another machine. The Java program on the other machine is called a server. It is responsible for coordinating communication between GUIs and invocation managers. The server will receive information from a client and give it to the corresponding invocation manager to run on the server machine. If the backend commandline program generates any information that the user would need to access on the client machine, it will be sent back to the client by the server.

So far, there is little difference in running in client / server mode and not. However, there are some issues that are unique to client / server mode. Security is one issue that is very important.

Since the propose of the server is to run commands, a way is needed to prevent harmful commands from being run on the server machine. When a server is started, it runs under a username on the server machine. The server will execute commands using the same permissions as the user it is running under. The server cannot run commands that user cannot run himself. In addition, to make sure that a client may connect to a server, a username and password is sent to the server using SSL. The server receives the username and password and checks it against the password file on the server machine. If the authentication is successful, the client is granted access to the server.

Another issue is how multiple servers and clients interact with each other. An example of this interaction is that multiple clients may connect to a single server. This allows multiple applications to be run from a single server simultaneously. Also, when using a meta-application environment such as GlobalDesktop or GlobalWorkbench, it is possible to have multiple clients run on different servers or even in normal mode.

Another example of client / server interaction is that multiple servers can run on the same server machine. Since a server executes commands using the permissions of user whom started it, it is recommended that a user run his own server for client / server mode. A user may also run multiple servers from the same server machine as well. This allows a user to run a server with different settings without interfering with any currently running applications on another server.

Finally, it should be noted that not all Fiswidgets applications are capable of being run in client / server mode. Most of the applications that cannot be run in this mode cannot be easily broken down into a GUI and invocation manager. To see if an application is capable of client / server mode, please look a the button bar at the bottom of the GUI. If it is not enabled, then it cannot be run in client / server mode.
 

Client / Server setup and usage

Server side install/setup
This part should be done once on a server machine by a system administrator  who wants to install Fiswidgets.

• Install Fiswidgets environment and GUI applications  - This document assumes that you already have a normal Fiswidgets environment installed on your system. You need at least Fiswidgets version 2.2 to have client/server capability. To install the Fiswidgets environment, follow instructions provided by this link http://neurocog.lrdc.pitt.edu/fiswidgets/fisdocs/INSTALL

 
• Make sure you have rmiregistry running  -    In order for Fiswidgets to work in client/server mode, you need to make sure that you have rmiregistry daemon running on a server machine. Fiswidgets distribution provides several shell scripts that can help system administrator start rmiregistry on boot and make sure that it is running all the time. Click here for more detailed instructions on how to install and configure those shell scripts.

 
• Create a password file - For security purposes, Fiswidgets requires username and password to be entered before connecting to the server. Fiswidget client application will send encrypted username and password to the server while establishing a connection. Fiswidgets password file, which has the same format as Unix /etc/passwd, is used to authenticate users.  By default, Fiswidgets will first check for FIS_PASSWORD_FILE property in its system wide fisproperties.default file. If this property is not defined, Fiswidgets will use the default, which is /etc/jpasswd. To create and edit the password file entries, use the FisPassword utility.

• Connect to your server machine   -   The very first step is to have access to the server machine you are going to use. You can use telnet, ssh, or any other program that will get you a terminal window on your server machine. If you have an access to a physical terminal, it will work too.

 
• Start a FisServer   - FisServer is a java server program that processes requests from Fiswidget clients. There are several ways to start FisServer.
• You can type the following command line in command prompt:

java -ms128M -mx128M -Djava.rmi.server.codebase=file://<location of jar files>/fiswidgets-all.jar FisServer&
Ex. java -ms128M -mx128M -Djava.rmi.server.codebase=file:///usr/local/java/jars/fiswidgets-all.jar FisServer&
• You can use the fisserver shell script distributed with fiswidgets. This shell script sets an appropriate CLASSPATH and calls the above command to start FisServer
• Create an alias in your shell. To do that put the following line into ~/.tcshrc file (if you are using TCSH Shell)

alias fisserver java -ms128M -mx128M -Djava.rmi.server.codebase=file://<location of jar files>/fiswidgets-all.jar FisServer
Ex. alias fisserver java -ms128M -mx128M -Djava.rmi.server.codebase=file:///usr/local/java/jars/fiswidgets-all.jar FisServer


• Running a FisServer - When FisServer starts "Fiswidgets server ready" should be printed on a console. FisServer can be left running indefinitely, so it is a good idea to run it in the background. The directory in which you start FisServer becomes the server current working directory. This directory will be a starting directory for all connected client applications. This means that all browse buttons will open from that location. It is also recommended that the FisServer should be started with 128MB of memory at least. This is ensure that the FisServer will have enough memory to deal with large chunks of data.

 
• Multiple FisServers - It should be noted that it is possible to run multiple FisServers at the same time by the same user on the same server machine. If another server is started, the FisServer will printout a server number when starting up. Separate servers can be accessed by appending :<server number> to a user name when connection to a FisServer is being established from a client.  When there is more then one FisServer running, the number that needs to be used during a login procedure on a client will be displayed on the server's console.  For example if you have two FisServers running on the same machine, you will use username smith to login into the first server and smith:1 to login into the second server.

 
• Stop a FisServer - You don't have to stop FisServer after client's job completes. You may leave it running for weeks before deciding to stop it.  When you do decide to shutdown the server, you can type java FisServer -kill [server number] command on the remote machine. The [server number]  identifies which server you want to kill, since you can have several servers running.  You can skip the [server number] parameter to kill server 0. Note that FisServer will prompt you for your user password for security reasons.

Client side install/setup
This part should be done once by a system administrator on a client machine.

• Install fiswidgets environment and GUI applications  -  No special setup is required on a client machine if you already have fiswidgets version 2.2 installation or above. If you don't have fiswidgets installed please consult fiswidgets installation guide. If you have a Windows 98SE/ ME/2000/XP machine, you can download and install fiswidgets.msi package.

  It should be noted that it is not necessary to install any of the C/C++ programs on the client machine. Only the Java GUIs have to been installed.

• Start a fiswidgets GUI application -  This can be an individual application or a meta-application such as GlobalDesktop or GlobalWorkbench.

 
• Connect the application to a server - Click on the Server button in GUI button bar if your are using individual Fiswidget application or GlobalDesktop, or select Server from the Options menu if you are using GlobalWorkbench . Check the "Use remote server" check box and fill in the server name, username, and password. The user may also specify new current working directory on a server if needed. After all of the fields have been set, press the OK button to run in client/server mode. Now that you are connected to a server, your browse buttons will browse remote file system and a Run button will run an application on remote server.

 
• Testing client/server connection - The simplest way to test your client/server connection (other then the ability to browse remote file system) is to use UnixCommand Fiswidget application. Simply type in hostname as a Unix command and run it in client/server mode. The output of this command will report the hostname of the server machine.

 
• Multiple servers - When you are using a meta-application environments such as GlobalDesktop or GlobalWorkbench, you should know that you can run different applications on different servers or locally if you want. All you have to do is enter different server information in each application by clicking on application Server button.

 
• Disconnect from a server - To stop running in client / server mode, press Server button again on the client GUI. In the popup window, uncheck the "Use remote server" check box and press OK again.