Versions 3.2.0
Last update on October 25, 2001
Send questions, comments and corrections to MDMS
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:
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.
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.
% cd /usr/local
% tar xfv clientFei.tar .
######## 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
##########################################################
% cd $FEI_ROOT/misc
% cp -i ./krb5.conf /etc/.
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.
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:
To check your environment, run the FEI command line utility FeiCheck. It will do the following:
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.
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.
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:
% 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
% 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
% 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
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>
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.
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>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.
Some installation have multiple domain files. Here are some instances where this is appropriate:
% cd /usr/local/fei
% mkdir ops
% mkdir test
% alias feiOps setenv FEI /usr/local/fei/ops
% alias feiTest setenv FEI /usr/local/fei/test
% setenv FEI_DOMAIN $FEI/tokyoDomain
% echo FEI_DOMAIN
/usr/local/fei/tokyoDomain
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.
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
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.)
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.
Copyright © 2001 The California Institute of Technology