FEI Client Installation Guide

Versions 3.2.0

Last update on October 25, 2001
Send questions, comments and corrections to MDMS


FEI Software Distribution

FEI software is normally provided as a tar file. Expanding the tar file effectively installs the software. This is a straight-forward process described in the next section.

When you expand the tar file you will have a directory structure that looks like this:



FEI Directory Tree

bin

Contains FEI executables, including the command line utilities, FEI's copy of Kerberos utilities (kinit, klist, kdelete), and GUI based applications. This directory should be part of the PATH variable for everyone using FEI.


lib

Contains the shared object libraries needed to link and run FEI programs. (Note: Windows/NT environments contain statically linked libraries because of some limitations of that system.)


include

The include, or ".h" files needed to compile programs with the FEI C++ and Java API's.


examples

Example programs that show how to write programs using the FEI API. Examples are located in two subdirectories, one for C++ development and one for Java development. (Note: FEI Version 3.0 does not support a Java API.)


docs

FEI documentation, formatted as HTML pages, are located in this directory. The root page is index.html.


misc

Miscellaneous files that don't belong in any of the categories described above. For example, a dbView macro file that allows access to FEI command line utilities from within the database query tool is located here. A set of images you can use when learning FEI commands is located here as well.


The top directory, $FEI_ROOT, is the nominal location for the FEI network connection file, feiDomain, used whenever an FEI application accesses an FEI server. For standard environments the file should remain there. If you plan to use multiple FEI Domain files, then you should read the section Using FEI Domains.

Read the Installation Guide once before installing the software. Throughout the guide there are some options that you may want to adopt when installing the software.


Installing FEI For Unix Environments

The Default Installation

FEI is delivered as a tar file. You can install FEI directories and files wherever you like, but the following directions suggest placing the FEI top directory under /usr/local. You can install the software as user root or as any other user you like. (There is one exception. The Kerberos configuration file, krb5.conf must be installed in the directory /etc by root.

By convention the the top level FEI directory is referenced by the environmental variable FEI_ROOT. A second environmental variable FEI references the directory where FEI domain files are located. (Domain files allow FEI software to link to servers.) In the default installation, both FEI_ROOT and FEI reference the same directory. However, this is not always the case, particularly if you use multiple FEI environments - say one for test and another for operations. See Using FEI Domains for more information.

To install FEI software from the tar file, follow these steps.

  1. Expand the tar file clientFei.tar
    Copy the distribution from the tar file feiClient.tar into your system. We used /usr/local; you may choose a different location. The tar file will create the top level directory /fei and all subdirectories.

    % cd /usr/local
    % tar xfv clientFei.tar .


  2. Define The FEI environment
    If you're using some flavor of the C shell, add the C shell commands shown below to one of the files (Cshrc or .cshrc) that defines a user's environment. If you're using a different shell, create the commands that implement the same results as those shown below.
    To define the environment so everyone will inherit it, chose /usr/local/share/Cshrc. To define a personal environment, choose the user's $HOME/.cshrc file.

    ######## C Shell Definitions for FEI Environment #########
    # Location of FEI domain files
    setenv FEI /usr/local/fei
    # Top level FEI directory
    setenv FEI_ROOT /usr/local/fei
    # Defines the location of shared libs
    if (${?LD_LIBRARY_PATH} == 0) then
       setenv LD_LIBRARY_PATH $FEI_ROOT/lib
    else
       feiTemp=($FEI_ROOT/lib:$LD_LIBRARY_PATH)
       setenv LD_LIBRARY_PATH $feiTemp
       unset feiTemp
    endif
    # Path update
    set path=($FEI_ROOT/bin $path)
    # Uncomment next line for database access
    # setenv SYBASE /usr/local/fei
    ##########################################################


  3. Install Kerberos Security Software
    If you are not already using Kerberos version 5, copy the Kerberos configuration file $FEI_ROOT/misc/krb5.conf to the directory /etc. (You will need to be root to do this.)

    % cd $FEI_ROOT/misc
    % cp -i ./krb5.conf /etc/.

    The Kerberos kinit utility supplied with FEI is renamed FeiInit because your machine may have several copies of the Kerberos utility, and they may not all have the required functionality. DCE, for example, has its own copy. Use FeiInit to get a Kerberos ticket granting ticket when using FEI, and things should be fine. (FEI is currently shipped with Kerberos version 5 code obtained from MIT.)
    If you are already using MIT compatible version 5 Kerberos, you just need to integrate the FEI Kerberos domain information into your existing krb5.conf file. See Integrating FEI Kerberos Information Into An Existing Configuration for details. Also, just define FeiInit to point to your copy of kinit. You can safely delete kinit, klist and kdelete from $FEI_ROOT/bin if you like.
  4. FEI Documentation
    The installation package comes with documentation located in $FEI_ROOT/docs. The documents are in HTML format. The starting document is index.html. If you want to add FEI documentation to you locations Web site, just reference the starting document page, for example,
    <a href="/usr/local/fei/docs/index.html">FEI Documentation</a>

That concludes the basic installation. You should review the rest of this document just so you are aware of other installation issues. After you are satisfied with you installation, make sure things are working correctly by running FeiCheck.

Note: users can't access an FEI server and perform useful work untill they have contacted the FEI Administrator and been given individual authentication and access control capabilities, see User Access To FEI Servers.


Integrating FEI Into An Existing Unix Environment

You can integrate FEI software into your existing system. Suppose, for example, that your system uses bin, lib and include directories below /usr/local. To integrate FEI software into this environment, follow these steps:

  1. Expand the contents of the FEI tar file as explained in the Default Installation section above.
  2. Move the contents of the FEI bin, lib and include directories to the corresponding directories under /usr/local.
  3. Define the environmental variable FEI to point to /usr/local/fei so people can still get to FEI domain files and the FEI examples.
  4. Make sure that shared object libraries are accessible. This should be covered by the definition of your PATH variable.



Installing FEI for The Windows/NT Environment



Checking Your Installation

To check your environment, run the FEI command line utility FeiCheck. It will do the following:

  1. Insure that you can access the FEI command line utilities.
  2. Check that the environmental variable FEI is defined.
  3. Make sure you can access the default domain FEI domain file.
  4. Confirm that you can connect to the FEI servers managing the FEI file types listed in you default domain file.
  5. List the file types for which you have authorized access.
  6. Make sure that your system time is close to that of the Kerberos. (Kerberos tickets are time stamped. If the times amoung machines using Kerberos services is not close - 5 minutes by default - Kerberos assumes you're trying to reuse an old ticket, perhaps not your own. For that reason, it fails to grant athentication.)

Here's an example of a check with no errors:

% feiCheck
Using FEI domain file "/usr/local/fei/feiDomain".
Trying connection to file type "image"
OK
Trying connection to file type "text"
OK
%


You can also use FeiCheck with FEI domains files other than the default by including the name of the file as a command line argument, for example:

% feiCheck tokyoDomain


See section Using FEI Domains for more information about domain files.

If FeiCheck reported no errors, your done. Congratulations! Get a cup of coffee. If you're new to FEI, a good place to begin is with the Command Line Utilities Tutorial.


FEI Configuration Problems

If feiCheck reported one or more errors, see if they are like any of those listed below, and correct the problem following the recommendations. If that's not enough to correct any problems, contact your FEI Administrator or email your problem to the FEI development group.

Environmental variable "FEI" is not defined.

You need to have the environmental variable FEI defined for your process. Check you shell configuration files.

Using FEI domain file "/usr/local/fei/feiDomain".
Can't open domain file "/usr/local/fei/feiDomain":
No such file or directory

Trying to use a domain file that can't be found or opened for some reason. In this case, the file wasn't found because it wasn't located in the directory referenced to by the environmental variable FEI. Also make sure everyone has read access to the file.


Trying connection to file type "image"
Not authorized to connect.
Ticket expired (krb_rd_req)

The server was not able to authenticate you using your Kerberos credentials, or lack there of. In this case we had a ticket but it had expired. Make sure you do have a ticket by running FeiInit. If you still have problems consult you FEI Administrator to verify that you're a registered FEI user.


Trying connection to file type "text"
Could not find server "fei2", for type "text" in domain "/usr/local/fei/feiDomain".

The domain file "feiDomain" records that file type "text" should be reached by connecting to FEI server "fei2". The connection could not be made, so the entry in the domain file may be wrong, in which case you need an updated domain file, or the server may not be available, in which case you need to contact your FEI Administrator and find out what's going on.


ld.so.1: feiCheck: fatal: libFEI.so: can't open file: errno=2
Killed

Can't find FEI shared libraries. Make sure the environmental variable LD_LIBRARY_PATH points to the location of the shared libraries.



Network Configuration Problems

If you can't reach an FEI server, you may have a network configuration problem. To confirm that you can connect to the FEI servers, follow these steps:

  1. Open the default domain file, named feiDomain.
  2. The file has two sections. At the top are a list of servers and their connection information. Below that is a list of the file types bound to particular servers. "Ping" each of the servers to see that each is reachable. An example domain file, followed by the ping commands, is shown below (the server information is shown in bold type face):

    % cat $FEI/feiDomain
    # File: feiDomain
    #
    # Function: This is a test default domain file
    # for FEI version 3.
    #
    server fei2 milano 9001 JPL-FEI.JPL.NASA.GOV
    server fei3 roma 12040 JPL-FEI.JPL.NASA.GOV
    server fei3b roma 12021 JPL-FEI.JPL.NASA.GOV
    image fei3
    image1 fei3
    image2 fei3
    image3 fei3
    image4 fei3
    text fei2 fei3


    Here is an example of a successful ping:

    % ping -s roma
    PING roma.jpl.nasa.gov: 56 data bytes
    64 bytes from roma.jpl.nasa.gov (137.78.73.22): icmp_seq=0. time=28. ms
    ^C


    And here's an example that fails:

    % ping -s milano
    PING milano.jpl.nasa.gov: 56 data bytes
    ^C
    ----milano.jpl.nasa.gov PING Statistics----
    30 packets transmitted, 0 packets received, 100% packet loss


  3. If you get a failure, you've got a network problem. Here are some possible causes:



User Access To FEI Servers

Only authorized users can access FEI services. Being authorized means two things. First you're a know "principle" in the Kerberos domain used by the target FEI servers. Second, you have been given the capability to access a set of file types managed by FEI servers. Your FEI Administrator can grant you these capabilities.

Once you are authorized, you can use FEI by simply obtaining a Kerberos ticket in the target Kerberos domain. Once you have a ticket, it's good for some period of time set in your system's /etc/krb5.conf file. Typically this is between 5 and 23 hours. During the time the ticket is valid, just run an FEI utility to access data. Once the ticket expires, get a new one.

Getting a ticket is straight forward. Run FeiInit (an renamed version of Kerberos' kinit), giving your principal name as an argument to the command. When prompted for you Kerberos password, provide it. If you don't receive an error message you're ready to go. Here's an example for Kerberos principal "jake".

% feiKinit jake
SunOS (milano)
Kerberos Initialization for "jake"
Password: <jake's kerberos password>




Using FEI Domains

Every installation of FEI should contain a default FEI domain file named feiDomain, pointed to by the environmental variable FEI. Running FeiCheck, described above, following the installation of FEI, should confirm that you have a valid, accessable domain file.

In some cases you may have to use more than one domain file, or you may have to edit such a file. Before you can perform such operations, you need to understand the structure of an FEI domain file. To that end, let's describe the contents of an FEI domain file using the following example:

% cat $FEI/feiDomain
# File: feiDomain
#
# Function: This is a test default domain file
# for FEI version 3.

server fei2 milano 9001 JPL-FEI.JPL.NASA.GOV
server fei3 roma 12040 JPL-FEI.JPL.NASA.GOV
server fei3b roma 12021 JPL-FEI.JPL.NASA.GOV

image fei3
image1 fei3
image2 fei3
image3 fei3
image4 fei3
text fei2 fei3



Lines beginning with the character '#' are comment lines. Domain files can also contain bank lines as well. Each line at the top of the file that begins with "server...", defines an FEI in the domain. A server line, like:

server fei2 milano 9001 JPL-FEI.JPL.NASA.GOV


is composed of:


File types are listed following the server definitions. Each file type definition, for example

   image fei3

is defined on a single line. The definition contains the name of the file type followed by the name of the server managing the file type. The server name must be defined in one of the server definitions at the top of the domain file.



How To Obtain An FEI Domain File

You obtain one domain file for each FEI domain you will access. You can obtain the file in one or more of the of the following ways:

  1. If provided with the installation, the file feiDomain can be found under the root directory $FEI_ROOT.
  2. The domain file is provided by your FEI Administrator. It may be emailed to you or a site from which it can be downloaded may be provided.
  3. You can obtain the file directly from the FEI database if you have access to the database. This is always the most reliable method because the data obtained is the same used by the FEI servers to configure themselves. We'll use an MDMS database query utility dbview to show how to get a properly formatted domain file using the Sybase stored procedure showDomainFile:

    1>open dataFile feiDomain


    1> showDomainFile
    2> go
    # File: feiDomain
    #
    # Created: Sep 13 1997 12:39PM
    #
    server fei2 milano 9001 JPL-FEI.JPL.NASA.GOV
    #
    image fei2
    text fei2

    1> close dataFile

    1> mv feiDomain /usr/local/fei/.

Since the definitions in domain files can change with mission requirements, make sure you have the latest copy and that it's installed in the directory pointed to by the environmental variable FEI.



Using Multiple Domain Files

Some installation have multiple domain files. Here are some instances where this is appropriate:



Combining & Editing Domains

Sometime a domain file contains more file types than you need. The default domain file delivered to you may have file types for multiple missions, only one of which is of interest to you. In that case, edit the file, removing the file type information you don't want. A domain file is an ASCII file, so just use an editor to do this. (Don't use word processing software, however; that will place format tags in the file making it unreadable by FEI software.)

If you have multiple domain files and the file types in each are distinct, you can combine the server and file type information from each into a single default domain file, provided that the file type names in the combined set are distinct. This can make life easier because you have only one file to reference. Make sure you follow the domain file format when doing this, putting server information at the top and file type information following it. Here's an example of two domain files that are merged.

________________________________________________
# File: Washington domain file

server fei1 bologna 12008 KERBEROS.NASA.GOV

image fei1
________________________________________________
# File: Toyko domain file

server fei1 genova 12008 KERBEROS.NASDA.JP

pacificImage fei1
________________________________________________
# File: Combined default domain file

server washington bologna 12008 KERBEROS.NASA.GOV
server tokyo genova 12008 KERBEROS.NASDA.JP

image washington
pacificImage tokyo
________________________________________________


Notice that we had to change the server names from "fei1" in each case to "washington" and "tokyo" so file types were bound to distinct servers. The network information for the two servers remains unchanged so we can still reach them.

You can use the same technique to eliminate unwanted file types or to create a personal copy, perhaps one used just for testing as described above. Remember to have a mechanism in place to define the environmental variable FEI to point to the directory where the target domain file resides, and, if you're using the environmental variable FEI_DOMAIN to explicitly name a domain file, that must be properly defined as well.

Note: FEI_DOMAIN is used by the FEI utilities but it's use is not part of the FEI API, so software not built by the FEI development team may not support it.



Integrating FEI Kerberos Information Into An Existing Configuration

If you're already supporting one or more Kerberos Version 5 domains, you simply want to include the Kerberos domain information for FEI in your current /etc/krb5.conf file. To do this, display the contents of the FEI $FEI_ROOT/misc/krb5.conf file and copy the information shown in bold below into your existing file. (You'll need to be logged on as root to do this.)

% view /etc/krb5.conf

[libdefaults]
   ticket_lifetime = 600
   default_realm = JPL-FEI.JPL.NASA.GOV

[logging]
   kdc = FILE:/var/log/krb5kdc.log
   admin_server = FILE:/var/log/kadmin.log
  &nsp;default = FILE:/var/log/krb5lib.log

[realms]
   JPL-FEI.JPL.NASA.GOV = {
      kdc = milano.jpl.nasa.gov:88
      admin_server = milano.jpl.nasa.gov
      default_domain = jpl.nasa.gov
   }
[domain_realm]
   .jpl.nasa.gov = JPL-FEI.JPL.NASA.GOV
   jpl.nasa.gov = JPL-FEI.JPL.NASA.GOV



Installing Database Utilities Along With FEI

The FEI distribution comes with two database utilities that can be used to access Database Management System Servers. (Currently, the utilities only support Sybase servers.)

  1. dbq Executes an SQL command or stored procedure provided as a command line argument. Returns any results to stdout. This utility is useful for quickly integrating database access into scripting languages like Perl.
  2. dbView A command line utility for interactive and batch processing database access. It has several interesting features, including a macro language, report generator, and catalog (database meta-data) display.

The utilities are located in $FEI/bin. For more information on these utilities, refer to the MDMS table of contents that comes with the HTML documentation.

If you want to use these utilities, you'll have to have a Sybase interfaces file available. (This file has network connection information in it that gets you to particular database servers. You can find the names of servers by looking in the file. The names are always on a line by themselves and start a new line in the file.) A copy of an interfaces file is provided with the distribution in the $FEI_ROOT directory. For programs to access it, you must defined the SYBASE environmental variable to point to the directory where the file can be found. For example:

% setenv SYBASE /usr/local/fei

or

% SYBASE=/usr/local/fei
% export SYBASE


It's best to place this definition in a startup file accessible to all users. Check with you FEI Administrator to make sure that the interfaces file found in the distribution is indeed the one you should be using. If not, your administrator can provide you with the correct version. Note: You'll also need a DBMS login to access a database. Again, your FEI Administrator can assists you with this.

If you use dbView, you may find a couple of its standard macro files useful. Their names are standard.macros and feiUtil.macros and are found in the $FEI/misc directory. To reference them automatically within a dbView session, you need to enter the following command within a dbView session:

   1> set defaultMacroFile = /usr/local/fei/misc/standard.macros /usr/local/fei/misc/feiUtil.macros


You'll have to use a different absolute directory path if the macro files are move to some location other than /usr/local/fei/misc/.

The dbView command

   1> show macro


lists the names of all macros; and the command

   1> show macro <macro name>

shows the contents of the named macro. The comments in the macro will tell you what it does.