Interactive Earthworm Installation notes

August 13, 2001

Overview:

Note that Earthworm now consists of the Automatic and Interactive portions, as described in Section 1, "Overview". The Automatic portion consists of the "real-time" modules designed to provide rapid response functions. The installation of that software is described in Section 2.1.

These notes address the installation of the Interactive Earthworm. Interactive Earthworm installation is relatively complex. It includes installation of SAC, GMT, Oracle Server, Oracle Clients, Apache, and other utilites. These notes are not meant to be a rote cook-book; they are intended to provide a rough guide only. It is presumed that the installer is familiar with Solaris administration. It is also expected that the installer will require support form the Earthworm group, or from someone familiar with the details of the installation process.

The Earthworm system can be configured to run on various hardware setups. These notes presume that the installation consists of three computers:

1. An NT system running an Oracle8 server: This machine is dedicated to the Oracle Standard Edition Server. It offers a network-based server, and nothing else. It is assumed to have fixed disc configuration: a C: drive containing the operating system and six 18-gigabyte drives to contain the DBMS tables, named e:, through j:. If the target hardware is different, the creation scripts must be edited.
2. A Solaris computer running the web server and SAC: This machine contains the Earthworm software to generate the web pages, the Apache Web server, a secure ftp server (used to support ftp down-load requests generated by web-page buttons), and SAC. In addition, it runs GMT to generate maps on request, and the "convert" package to translate the postScript maps to gif's. Note that SAC and GMT are Solaris specific. This machine also runs the Oracle Client software to permit connections to the DBMS Server on the NT machine
3. An NT system running the acquisition and processing modules of Earthworm. This machine runs the Automatic Earthworm modules, starting with the A/D converter, imports of trace data, picker, associator, locator, etc. This machine also runs the Oracle Client software to permit connections to the DBMS Server on the NT machine.

Step 1: Installing Oracle 8 Server on NT

1. Insert CD "Oracle v 8.0.5.0.0"

Auto-run displays opening window. Select "Begin Installation"

2. Select "Installation Options": "Oracle8
3. Select "Starter DB Configuration": custom installation

- Storage manager selection: something about a "Legato" manager: select NO
- Documentation to hard disk
- Select no cartridges
- Install rest of Oracle by accepting all defaults
- When installation of Oracle is finished, decline the opportunity to create an instance
- Exit the Oracle installer.

Step 2: Installing the Earthworm Instance (EWDB):

1. Download the instance installations scripts from the earthworm distribution

- Located in: EW_HOME/EW_VERSION/ora_instance_install
- Download the following files

- ewdb_create_instance.bat
- ewdbrun.sql
- initewdb.ora

- Copy initewdb.ora to c:\orant\database
- Run ewdb_create_instance script -- this will create the instance EWDB with:

- Directories for Earthworm schema datafiles named oradata\ewdb on each disk
- user system, password earthworm
- user internal, password earthworm1

- Check the output of the command -- it is logged to the file c:\ewdb_create_log

Step 3: Setting up Networking on Oracle Server on NT:

1. From "Start" Menu, select "Oracle for Windows NT".
2. From there, select "Net8 Assistant"

- Highlight "Service Names"
- From "Edit" pull-down, select "Create"

1. Service name: eqs.butte (or another of your chosing in same format)

NOTE: On NT, Net8 appends ".world" to the service name. It does not do that on Solaris. The ".world" must be removed by editing tsnames.ora, as follows: in c:\orant\net80\admin\tsnames.ora, change all occurrences of "eqs.butte.world" to "eqs.butte".

2. protocol: select TCP/IP only.
3. host name: enter IP address of Oracle Server machine
4. port number: accept default of 1521
5. Database SID: change to "ORC1". This was the default in the Server Setup procedure.
6. Database Logon:

username: "internal". This username is the default.

password: set to "password1"

NOTE: We observed that pressing the "test" button would cause a 'test successful' message. However, the Net8 Assistant was observed to be hung. We terminated Net8 Assistant , and observed that the parameters had not been recorded. We re-ran the above procedure, and selected "Finish", and from the "File" menu selected "Exit", without performing the test. That resulted in the networking becoming operational.
Step 4: Installing Solaris Client

Note: Use Enterprise v8.0.6

Most of the procedure is documented in "Oracle 8.0.6 Installation Guide". An experienced Solaris admin person is required.

1. Created group 102: "dba"
2. Created user "oracle": primary group 102, home dir: /opt/oracle
3. Log in as "oracle"
4. insert CD
5. cd /cdrom/orainst
6. execute oratab.sh

- Mount point: /opt/oracle
- Products Available: select

Client software

Net8

Documentation

Oracle Unix Installer

PL/SQL

SQL*Plus

- Legato Storage Manager: No
- Set local bin to /usr/local/bin

Step 5: Setting up networking on Solaris client:

1. In user "oracle"s .cshrc, add:

setenv ORACLE_HOME /opt/oracle/app/oracle/product/8.0.6

set path ... $ORACLE_HOME/bin

2. source .csrhc
3. execute net8asst.sh

Proceed as with the NT configuration above

NOTE: Unlike on NT, no ".world" will be appended to the service name.

NOTE: an undocumented 'feature' is that the file resolving the service names (tsnames.ora) lives in $ORACLE_HOME/network/admin. However, OCI requires that it be in /var/opt/oracle. If it isn't there, great confusion can result, since SQL*PLUS seemingly knows to try in $ORACLE_HOME/network/admin if it's not found in /var/opt/oracle and runs ok, but OCI seemingly does not, and so the programs using it crash. So, be sure to: cp /opt/oracle/app/oracle/product/8.0.6/tsnames.ora /var/opt/oracle

Step 6: Installing NT Client:

1. Insert CD.
2. Select "Begin Installation" from autorun window
3. Select Custom installation
4. In the Software Asset Manager window, select "Client Applications" and "Data base Administrator Products".
5. Push "Install"
6. When you return to the Software Asset Manager, push "exit".

Step 7: Setting up networking on NT Client:

1. Select Start -> Programs -> Oracle for Wondows NT -> Oracle Net8 Easy Config
2. Select "Add New Service". Service Name: ewdb.usgs. Protocol: TCP/IP. Host Name: <IP address of server machine>. Port number: 1521, or as configured on server machine.. SID: ORC1.
3. As mentioned above, do not perform the test, which seems to hang. Simply exit.
4. This will have created an entry in orant\Net80\Admin\Tnsnames.ora. As above, this entry has the form ewdb.usgs.world. Remove the .world suffix by manually editing the entry in Tnsnames.ora.
5. Test the connection by, for example, running the Storage Manager: Start -> Programs -> Oracle Enterprise Manager -> Storage Manager. Log in as Username: internal, Password: password1, Service: ewdb.usgs. If you get the window, you're in!

Step 8: Load the Earthworm distribution:
On the Solaris client machine:

1. Create user 'earthworm', with home directory /home/earthworm.
2. Login as user earthworm.
3. Ftp into "/home/earthworm" the file "vx.x.tar.Z" (Where x.x is the current version number.)
4. Unpack it with:
zcat vx.x.tar.Z | tar -xf -

On the NT machine:
Similarly, under c:\earthworm, ftp the current release (.zip), and unzip.

Step 9: Setting up the Earthworm schema:

1. Change into the EW_HOME/EW_VERSION/src/oracle/schema/sql_scripts directory
2. Edit the ewdb_create_database.sql script

- Change passwords for system and ewdb_main, if desired
- Change the name of the oracle service
- Change the location of the file where output of the script will be logged

1. Connect to the DB with SQLplus as user system
2. Run the creation script: SQL @ewdb_create_database
3. Examine the output log file for any errors.

Step 10: Inserting station lists into the DBMS server:

The general procedure is to get a hold of the current station list in hypoinverse format, and to use a program which uses that to populate the DBMS station list information. Note at this time, time-dependent station parameters have not been implemented yet.

1. ftp from the earthworm site "run_test.tar.Z", and unpack with a

zcat run_test.tar.Z | tar -xf -

2. cd /home/earthworm/run_test/params
3. There, edit "ew_sol_sparc.cmd" to set the following to the correct values:

EW_HOME /home/earthworm

EW_VERSION vx.x (where x.x is the number of the current release)

ORACLE_HOME /opt/oracle/app/oracle/product/8.0.6

NOTE: As was set in the .cshrc for user oracle

1. source ew_sol_sparc.cmd
2. Place the current hypoinverse station list into run_test/params (e.g. butte.hinv)
3. Execute the program to load the DBMS:

stalist_hinv2ora butte.hinv p3_main db_password eqs.butte

Where

butte.hinv is the hypoinverse station list

p3_main is the DBMS user

db_password is the password

eqs.butte is the service

Step 11: Installing the web interface software

Recall that the web-related software (for security purposes) is in it's own subtree. The structure is:

.../earthworm

/web

/scratch

/bin (cgi executables, etc)

/html

/images (fixed html images)

/tumble (java applet)

/log (log files from executables etc)

/params (parameters for the executables in /bin)

1. From the distribution, copy the templates for these directories:

cd .../vx.x/web_sample

cp -r html params log bin scratch /home/earthworm/web

2. Give the web server all rights to these directories:

su root

chown -R websrv *

chgrp -R apache *

chmod 775 *

3. Set the write permissions in params directory:

cd /home/earthworm/web/params

chmod 664 *.d

4. Now edit the .d files in /home/earthworm/web/params to customize according to local needs. Follow the instructions in each .d file for further information.

Step 12: Installing web utilities:

> cd to /home/earthworm

> There, create the directory tmp.
> Cd to it.

> From the Earthworm ftp site, directory EW5_utils, retrieve the utilities (utils.tar). Retrieve the README file from the same directory.

> Extract the tar tar -xf utils.tar Then follow the instructions in README file.