Border

FXC Operator Manual

 
 

First Draft: October 2001
 Revision 1: 17 Feb 2002 - Customization section expanded;
Revision 2: 14 Jun 2002 - Script installation added;
Revision 3: 31 Mar 2003 - Revised installation procedure;
Revision 4: 11 Mar 2004 - Security section inserted;

Border
Table of Contents

1. Basic System Description

1.1 Client Components

The client provides the interface to the user. A user guide is available that gives a detailed description of the many display functions. The FXC client is a single process that uses separate processing threads to provide a high degree of independence between various actions initiated by the user. For example, a user can request a product from the server and perform other functions, such as animation and drawing, while waiting for the server to return the requested product. The client controls one main display window and other smaller ones, depending on the function performed.

1.2 Server Components

The server consists of several computer processes and processing threads to provide maximum configuration flexibility and achieve good system response. A single Tcl/Tk script, known as the serverManager, starts the various processes on the server machine. It has a user interface that allows a user to monitor the activity, determine and control who is connected, and start or stop various processes. The eight basic processes managed by the serverManager are:

collabDepictableServer - This server process communicates internally with a product generator that runs AWIPS D2D code. When prompted by a client, it requests graphics metafiles from the product generator and returns these to all of the clients connected to it.

depictableServer - The depictableServer performs a function very similar to the collaborativeServer except it serves a single client. This allows an individual client to load products on its display without affecting the display of other clients.

chatServer - This server process allows many clients to communicate with each other using text messages similar to commercially available products such as "AOL Instant Messenger."

audioChatServer - This process was recently added to permit voice communications between clients. Although it supports voice communication between several clients, the process is designed to work best with two clients. It is anticipated that as network bandwidth and processing improve, the number of concurrent clients that can be adequately supported will increase.

scribbleServer - The scribbleServer handles the exchange of all graphics objects (i.e., drawing symbols) between several clients in a collaborative session. It caches all objects so that new users obtain all current objects when they they connect, not just those created later.


pointServer - The pointServer process has a single function, that of communicating the coordinates of a user-defined point to the D2D code for generating time series or soundings from model grids.


baselineServer - This server is similar to the pointServer in that it communicates the coordinates of the endpoints of a straight line to the D2D code for generating vertical cross sections.


baselineServer - As the name implies, the fileMonitor monitors the status of specific files. It is used to monitor the receipt of a text file from the Informix text database in response to a user request.


Another server that is not controlled by the serverManager script is the snapshotServer. This server process is actually a D2D application that is started when the user brings up a complete AWIPS D2D workstation. It is used to export an AWIPS graphics display from the main D2D window to an FXC client residing on the same computer. This makes it possible to use FXC to annotate AWIPS displays.

The various FXC servers can reside on any Linux machine on which the AWIPS software is installed. This machine can be an AWIPS workstation or a dedicated machine designed to handle a large number of FXC clients. If the server resides on the same machine as the client, then all communication is internal and the highest resolution data can be displayed without any significant delay. If the server is remote, then various on-the-fly compression techniques are available to transmit the data from the server to the client. All communication between the server and client uses Java Remote Method Invocation (RMI). Since RMI needs to communicate bidirectionally between designated IP addresses, it is not possible to communicate through proxy-servers and firewalls (without opening specific ports). In many cases an external DSL line or wireless link can circumvent this problem. The FXC system architecture allows clients to run without a server, connected to a private server, or connected to a collaborative server. Clients have complete control over choosing a server.

2. FXC Installation Scripts


 

1.1 Windows Script

Windows machines are only able to run the FXC client since they cannot execute the AWIPS code required by a server. The installation script supports machines running most versions of MS Windows: WinNT, Win2000, or WinXP.

1.1.1 Installation

The Windows installation script copies the complete FXC directory structure from a CDROM to a location specified by the user and then sets up the proper environment for running the client software. To start the installation double click on the FXCinstall.bat icon on your CD.

The installation script will first check to see if the proper version of Java is installed. Once the proper Java is installed, it will prompt the user for the location where FXC is to be installed and the (AWIPS) site localization. This will allow the script to install the code with the proper menu. Upon completion of the installation the script will place an FXC-Client icon on the desktop.

Figure 1. Window 2000 Desktop (CDROM Drive)

Figure 2. Localization Menu (example)

Note: The installation script assumes that no special accommodations need to be made for firewalls. If the client is behind a firewall refer to the section on security for more information.

1.1.2 System Management

All changes to the system configuration, such as adding a server to the menu, must be done manually. The Windows script does not provide features for reconfiguring the system.
 

1.2 Linux Script

The Linux installation script performs the software installation and manages the client and software configuration tables. The FXC software is usually loaded from a CD, but can also be loaded from a CD or a tar files on the local disk. Furthermore, if the software has already been loaded, it can be used to merely initialize the system environment. The installation script is a separate file from the tar or zip file(s).

Figure 3. Installation Menu (top level)

The installation script performs several tasks as part of the installation. In addition to loading the application software, it creates the appropriate client menu, sets environmental variables, and updates a configuration file. If the system is also a server then it also creates the appropriate map backgrounds, saves geographic reference points, adds the server name to the menu, and inserts the server IP address in a local file.

1.2.1 Installation
 

 The command for starting the software installation is:

      FXCinstall

The installation script can be run directly from the CD by entering /mnt/cdrom/FXCinstall or first copied to a local directory. For AWIPS users, the recommended installation directory is /awips. This should allow the creation of the proper directory structure without requiring root privileges and also will provide some uniformity among sites. Make sure that the login account has the proper authorization and has a system environment that allows execution of AWIPS D2D.  All of the FXC code and even the Java VM may be installed in the same directory. The only information stored outside of that directory would be ldadWish (in /awips/fxa/bin) if it were not part of the AWIPS installation. The java and FXC environment are set automatically each time at execution time and no longer need to be set in the .cshrc file. To de-install FXC delete the installation directory (containing Java and FXC) and, if necessary, ldadWish in /awips/fxa/bin.

Setting up the desktop icon - When completed, the installation script will state: "Installation complete". If the script appears to be pausing for longer periods of time, it may be that it is reading data from the CD. After completing the installation the FXCinstall script can also be used to start the FXC client or server (FXC System Management, menu option 0). Process initiation can be simplified by setting up client and server icons on the desktop. On the Gnome desktop this can be done by clicking the right mouse button over the toolbar (or, in some cases, selecting the "foot" icon on the toolbar) and then selecting "Panel". From the subsequent next menus, select "Add to panel" and then "Launcher". The entries for the launcher dialog menus are:

    Name:  FXC
Command:  /awips/FXC/fsl/linux/run-FXCollaborate
Type: Application
Icon: /awips/FXC/fsl/data/config/buttons/FXCicon.png
    Name:  Server
Command:  /awips/FXC/fsl/linux/run-server
Type: Application
Icon: /awips/FXC/fsl/data/config/buttons/FXCserver.png
If disk space is of concern, it may be possible to delete the map backgrounds from a number of sites. The map backgrounds are stored locally on each client to improve performance and reduce network traffic. They are stored by site identifier in the FXC/fsl/data/depictables/backgrounds directory.

1.2.2 System Management

The FXCinstall script, located in the FXC/fsl/linux directory, can also be used to manage the FXC system configuration. The FXC system management functions provided by the script are:

Figure 4. System Management Menu

· View System Documentation - Allows the user to view available documentation (e.g. User Guide, and Operator Manual). Requires a browser, such as Netscape, to view the html documentation.

Figure 5. Documentation Menu

·Revise list of servers (on menu) - To add a server that is not currently on the menu requires that the system have the appropriate menu selector and also the IP address for the new server. Furthermore, the system must also have the appropriate map backgrounds and geographic coordinate information. This information can be obtained from the server site or generated locally if the host machine supports that particular AWIPS localization. The "Update site localization data" can be used to create the necessary files and import them into the client system.


·Use a different main menu - Custom menus are available for various applications and for some sites. The menus differ in the type of products they can access and in the capabilities (such as being able to reset a remote server) they possess. Menus are stored in a text format using a well-defined syntax.


·Replace/add/delete the radar (on menu) - Allows users to change the radar to coincide with that of the remote server or other available radars.


·Import/Export site localization data - Users can create localization and map files, distribute them to remote clients, and have the remote clients import them into their system. The files are stored in the FXC home directory with the names "localizationXXX" and "mapsXXX.tar".


·Modify server access list - The server site can control access to the server by group and name. Several groups can be set up with the desired numbers of users but each group must have a unique set of user names. This means that a particular client may have more than one collaboration name; based on what group he wants to join. The default system configuration allows all users to connect without restrictions.


·Start a client or a server - This provides a simple way to start a client or server process. However, it is suggested that icons be placed on the desktop to allow users to start these processes more quickly. The client and server require a fair amount of memory and it may be desirable to stop these processes when they are not needed in order to free up memory.


·Enable/disable auto-connect - In instances where the user typically connects to the same server, the user may want to configure the system so that the client will automatically connect to the server when it is started.


·Set Default scale (at startup) - Allows users to change the scale (area) to be displayed when the client is initialized and before it connects to a server.


·Create Map from D2D userfile1.shp - Makes it possible to create a new FXC background from a shape file stored in /awips/fxa/data/localizationDataSets/XXX/userfile1.shp. Selecting this option will automatically read that file and convert it to a map background file compatible with FXC


·Start client and/or server - This provides the user the ability to start FXC (client and/or server) from a menu prior to creating a desktop icon.

Figure 6. FXC Startup Menu

3. System Security
 

3.1 Client Instructions
These instructions assume that you have a firewall/router box, separate from the machine on which you are running your FXC client; that the separate machine is part of a subnet isolated from the internet by the firewall/router; and that your firewall uses network address translation (NAT).
 
(1) Determine your firewall's external IP address, i.e. the address that it presents to the world, not to your internal network. This is refered to from here on as {PUBLIC}. The IP address is assigned to you by your cable or DSL company, and it may change from time to time (floating IP).

(2) Determine your PC's internal network IP address. This is refered to as {INTERNAL} from here on.

(3) Find a port number that is not in use on your PC. Typically, 1126 or something like that. This number will be refered to as {PORT}.

(4) Add a rule to your firewall that says if any traffic comes in at the {PORT} you chose, it should be forwarded to {INTERNAL}. As you can see, that opens only one "hole" in your firewall.

(5) Modify the startup script for your FXC client (probably, if the PC is a Linux box, it is FXC/fsl/linux/run-FXCollaborate; or if a Windows machine, FXC/fsl/windows/run-FXCollaborate.bat). In the script, the last line should start with "java". You will need to add "-Dfxc.transceiver.hostaddress={PUBLIC}" to this line, somewhere between the other "-D" options and the fsl.main.FXC part, with the {PUBLIC} being the external IP address of course.

(6) Modify the same line in the same script to also hold the string "-Dfxc.transceiver.receiverport={PORT}" somewhere between the other -D options and the fsl.main.FXC part.

This way, FXC is configured to (a) pretend it's operating on the external IP address of the firewall, so that it sends that address to any server it connects to (thus allowing the server to send it back messages); and (b) use a specific port number that you've opened up in your firewall.


3.2 Server Instructions

In order to minimize the number of ports that are required it is recommended that the machine that runs the FXC server also run a message repeater. The message repeater requires only a single port to the outside and interfaces to the FXC server processes on the inside. Therefore, the firewall only needs to open up a single port to the repeater regardless of the number of clients that need to communicate with the server.

Repeater Configuration

Figure 7. Repeater Configuration

These are the steps to take to communicate through firewalls with the socket-based network communication code that comes with the latest version of FXC. It should allow clients both inside and outside the firewall to talk to the servers that are set up in this manner.

(1) Determine your firewall's external IP address, i.e. the address that it presents to the world, not to your internal network. This will be referred to from here on in these instructions as {PUBLIC}. Also determine your FXC server host machine's internal IP address; this will be referred to as {INTERNAL}.

(2) Determine what ports to use for the various server processes. You need to end up with a single port for the repeater, another for the dispatcher, and a range of 12 additional ports for the other server processes (if you are running 2 private and 1 collaborative servers; more will require more ports). Only one of these ports, that used by the repeater, will need to be open in the firewall, but the other ports still need to be free from use on the server host machine. Obviously, the port range cannot include the ports used by either the repeater or the dispatcher. From here on, the port you choose for the repeater will be referred to as the {REPEATERPORT}; the port of the dispatcher as {DISPATCHERPORT}; and the port range as {MINPORT} and {MAXPORT}.

(3) Modify run-server (in FXC/fsl/linux) to pass in this information; to do this, find the line:

serverManager -private 2 -collab 1

and change it to the line (this should all be one line):

serverManager -private 2 -collab 1 -hostaddress {PUBLIC} -dispatcherport {DISPATCHERPORT} -repeaterport {REPEATERPORT} -portrange {MINPORT} {MAXPORT}

(4) Now you'll need to specify a rule on the firewall machine so that it lets external clients connect to the servers through the port of the repeater. To do this, you'll need to run an iptables command as root (and presumably you'll want to run this as part of the firewall machine's boot procedure). The command should be (and again, all on one line):

/sbin/iptables -t nat -A PREROUTING -d {PUBLIC} -p tcp --dport {REPEATERPORT} -j DNAT --to-destination {INTERNAL}

replacing {PUBLIC} with the public address, {INTERNAL} with the server machine's internal address, and {REPEATERPORT} with the repeater's port number.

(5) Make sure that the FXC server machine itself does not have any firewall blocking traffic either direction. This particular' problem had us stuck for a while when we were originally determining what sort of configuration was required to deal with servers behind NAT-capable firewalls, as unbeknownst to us there was an active firewall on the test host machine...

(6) Finally, you must set up a loopback on the FXC server machine, so that when the Java servers try to communicate with each other using the firewall's address, the packets loop back to the same machine. Again, as with the iptables command above, you'll want to run this as root, and presumably as part of the server host machine's boot procedure. The three commands should be (again, each should be all on one line):

/sbin/iptables -t nat -A PREROUTING -d {PUBLIC} -p tcp --dport {REPEATERPORT} -j REDIRECT /sbin/iptables -t nat -A PREROUTING -d {PUBLIC} -p tcp --dport {DISPATCHERPORT} -j REDIRECT /sbin/iptables -t nat -A PREROUTING -d {PUBLIC} -p tcp --dport {MINPORT}:{MAXPORT} -j REDIRECT as usual replacing {PUBLIC} with the firewall machine's address, and {REPEATERPORT}, {DISPATCHERPORT}, and {MINPORT} and {MAXPORT} with the appropriate port numbers.

And that should do it! The clients connecting to this server will need to know the {PUBLIC} address, as well as the {DISPATCHERPORT} and {REPEATERPORT} port numbers, and have these recorded in their Hosts.txt files as follows (here, the server name is given as "Firewalled Server", which obviously would need to be replaced with the real server name):

"Firewalled Server" {PUBLIC}:{REPEATERPORT} {PUBLIC}:{DISPATCHERPORT}

This will direct the clients to connect to the server as if the latter were hosted by the firewall itself, via a repeater on that same machine; the firewall will redirect incoming traffic to the actual server host machine within the internal network. Since a repeater is specified, all traffic will go through that repeater (and thus through a single open port in the firewall), meaning that only one port needs to be open.

4. FXC Customization The application software contains a number of static files that control the information displayed on the screen. These files can be edited directly with a text editor or can be generated with the help of some software utilities provided with the application.

4.1 Customization Utilities

·GridKeyConversion - To add a new model to the browser menu requires that a new model.txt file be generated. This can easily be done by executing this script and extracting the necessary information from the D2D grid depict key file (the code assumes that this file resides in /awips/fxa/data/localizationDataSets/xxx). In addition to creating this file the user also needs to add the model name to the Source.menu file. It will be necessary to restart the client and the server in order for the changes to take effect. To run this routine enter: java fsl.support.GridKeyConversion [Model] [key range to search]
Location: FXC/fsl/support.


·CreateLocalMaps - This utility makes it easy to generate a series of maps for all scales for a particular localization. The script requires that the Localization.txt file contain the localization information and the Maps.txt files identify the list of map backgrounds and the scales for which they apply. This script will start up an igc (AWIPS display process) that will display each map as it is being generated in a small 200x200 pixel window. The various map backgrounds will be created in a subdirectory with the identifier of the office, e.g. FXC/fsl/data/depictables/BOU/. The utility will exit without generating any maps if the directory (e.g. BOU) already exists. To run this routine enter: java fsl.support.CreateLocalMaps [site ID].
Location: FXC/fsl/support.


·makeLocalization - This is a shell script that executes the AWIPS script maksuparg to extract the localization coordinates for each geographic scale used by AWIPS for the specified office site. This script needs to be adjusted to a particular site if the NWS default scales are not correct for that site. For example, the number of scales and the name of the scale may need to be modified. The maksuparg output is the input to the FXClocalization routine that then transfers the scale data and some additional values to the Localization.txt file. Note the AWIPS localization must exist on the host machine (on which makeLocalization is run). To run this script enter: makeLocalization [site ID]
Location: FXC/fsl/support


·MakeColor - This java routine is an interim solution for generating image color tables. In the future, the netCDF file used by AWIPS will also be used by FXC. To create a new color table, modify the data arrays to contain the new color table values and then (after compilation) execute the routine to create the binary file. The binary name.lut file needs to be stored in the FXC/fsl/data/color directory. The color table name also needs to be entered in the FXC/fsl/util/ImageColorBook.java class where temporary color table reassignments are tracked. Additional changes are required to add the color table to the FXC menu. To run this routine enter: java fsl.support.MakeColor [name]
Location: FXC/fsl/support.


·MenuMaker - The MenuMaker utility allows a user to extract a new map from the MasterMenu.txt file. The routine generates a new directory (if it does not exist) with the name of the specified menu identifier and places the newly extracted menu (MenuAndToolBars.txt) in the directory. In order to make this the default menu the user also needs to modify the MENUOPTION in the GeneralConfig.txt file. To run this routine enter:
java fsl.support.MenuMaker [menu ID]
Location: FXC/fsl/support.


·ExportFromD2D - This script is run as an AWIPS application and exports a particular graphic or image displayed on the AWIPS screen. The resulting file is placed in the /tmp directory and is an image (IFF), a graphic (DGM), or a color table (text). It may be necessary to list the files in /tmp with ls -lt | more to determine the name of the latest file entered into the directory. This utility is especially useful to extract a new map for inclusion into FXC. It does not require knowledge of the D-2D depict key to display the product.
 
 

Figure 9. Export Selection on AWIPS Menu


Execution of this application from the AWIPS workstation requires entries in the following files:

Change $FXA_HOME/data/appInfo.txt
export | Export Screen | exportD2D |  |n|n|y|y|y|

Change $FXA_HOME/data/localization/nationalData/dataMenus.txt
(or $FXA_HOME/data/localizationDataSets/XXX/dataMenus.txt)
    separator
    appButton: export

Figure 10. Export Menu on AWIPS


4.2 Customization Files


·MasterMenu.txt - This text file contains the menu information for all supported menus. Keys at the beginning of each line identify the menu(s) associated with that specific line; a blank character identifies that the particular line is appropriate for all menus. The menus are described using a very simple scripting language designed specifically for this application. The syntax of this language is found in FXC/fsl/gui/MenuAndToolBarsFactory.java. The MasterMenu file is used to create the actual menu file for a particular system localization that is then executed by the client during startup. The master menu file is under configuration management and any changes to that file should be forwarded to FSL. The user can modify the extracted local file, but these changes may be overwritten by the next software release (see Customization Utilities on how to extract the local menu). Location: FXC/fsl/data/config


·Localization.txt -  The localization file is a text file that contains the coordinate transformation for all geographic scales for each office. Since the FXC client could connect to any one of a number of offices, the localization information for those offices must be available (see Customization Utilities on how to create the localization parameters for an office). Location: FXC/fsl/data/config.


·Hosts.txt - This text file contains a list of server names, as defined in the menu, and their associated IP addresses. This file is easily edited with a text editor. Location: FXC/fsl/data/config.


·GeneralConfig.txt.template - This file is the default configuration file that describes the menu and the types of compression to be used for gridded data. A copy of this file, GeneralConfig.txt, is the working file used by FXC. Normally, this copy is created during software installation. Location: FXC/fsl/data/config.


·Scale.txt - The "depict" keys for all graphic displays are stored in this text file. Each key represents the unique identifier for a particular graphic display that is identical to that used in AWIPS. In addition, the file contains color attributes, compression technique, scale applicability, transparency, display type, and a text descriptor for each display. The keys apply to all non-gridded fields, including jpeg images from disk or the Web. Keys for gridded fields are stored in separate txt files that include the model name in the file name. This file is easily edited with a text editor. Location: FXC/fsl/data/keys.

·Model.txt - The specific model (e.g. AVN, or ETA) replaces the Model field of the file name. In order to improve run-time performance, only the 500 mb levels of the model are listed and other levels are computed by applying the appropriate numeric offset. These files can be generated directly from the AWIPS grid depict key files with the help of the GridKeyConversion routine (FXC/fsl/support). Location: FXC/fsl/data/keys.

·URLocators.txt - This file contains the location of a particular graphic file either as a path name for local files, or a URL for Web products. Several graphics can be loaded with a simple command by listing several locations after a "depict" key entry. Each graphic will be loaded into a different display frame (for possible animation). Location: FXC/fsl/data/config.

·Maps.txt - This is a master file that contains all maps for all the supported menus. As a result, there may be maps listed here that are not relevant to the user?s particular office. In addition to the map name, as specified in the menu, the file contains the "depict" key, color table (if appropriate), applicable scales, default scales, and the name of the file that contains the graphic data (DGM format). Location: FXC/fsl/data/config.
 

·wfoIDs.txt - This text file is only used by the FXC installation script to determine what menu identifier to put into the GeneralConfig.txt file based on the three (or more) letter identifier for the office. The office identifier is obtained by reading the environmental variable FXA_LOCAL_SITE from the local host. Location: FXC/fsl/data/config.

·radarInfoMaster.txt - This text file is a duplicate of the AWIPS file with the same name and has been slightly reformatted to simplify reading the fields with a shell script. It is only used by the FXCinstall script to identify the radar that corresponds to a specified office identifier. Location: FXC/fsl/data/config.

·Choice.menu - This file is used to specify the menu selections in the volume browser. The Choice field of the file name is replaced by the particular browser menu category desired by the user (e.g. Sources, Basic, Derived). The file lists the different choices available for the particular category (e.g. ETA, AVN, LAPS). Some of these files allow the user to specify the name used in the browser menu and the corresponding field used to locate that item in the grid depict key file (e.g. ETA.txt). Location: FXC/fsl/data/config.

·fxcenvirons.csh/bat - The environmental variables for Linux and Windows are defined in a short system script that is executed each time the client or server is started. This eliminates the need to define environmental variables in a .cshrc file or setting them from the Windows' system control menu. The critical variables in these files are CLASSPATH (used by jdk), FXC_LOCALIZATION, and FXC_HOME. Location: FXC/fsl/linux  or  FXC/fsl/windows.

·home - This text file is only found on Linux systems and contains the name of the installation directory for FXC. It is used by the various startup scripts to determine how to set the environmental variables and by FXCinstall to locate specific files. This file must be set properly in order for FXC to execute. Location: FXC/fsl/linux


4.3 Important Information


On occasions, stray AWIPS or FXC processes are left in the system that do not have a window associated with them. This could happen if the applications weren't shut down properly or processes fail to function because of resource problems. A reset command (resetSystem) is provided in the FXC/fsl/linux directory that stops all FXC server processes. It does not stop the FXC client process.

NOTE:  The purger, found in $FXC_HOME/FXC/fsl/linux should be started to ensure that the /tmp directory does not fill up after using FXC for a prolonged period of time. This runs a cron job that purges the files as specified in FXC/fsl/linux/purgeTable.