EGG Project Host-Site Setup

This is a brief and very general discussion of the installation and operation of the egg software. Please note what problems you encounter and let me know how best to improve this process. For immediate help, you can reach me by email at rdnelson@princeton.edu. This is adapted from instructions for newcomers to unix who will be using a prepared machine, but the notes may be of some use for others. For clarity, I'll type computer commands inside quotes; invoke the command by typing enter. You can retrieve recent commands with the cursor up arrow and edit them by backspacing.

1. Logging on

The GCP software should be installed in its own subdirectory within your primary directory, usually in the /home directory tree. We will assume you have made an egg directory called /home/yourdir/egg. and installed the software there. Go there by typing "cd /home/yourdir/egg". Type "ls" for a simple listing of files or "ls -l" for a more informative list with dates, sizes, and more. The eggsh executable and the .eggrc configuration file should be in the listing, and the eggsh listing should indicate it is executable. When the system is running, the eggsh program will create subdirectories for data storage, using the year and month for directory name.

Make sure the time on your computer is accurate before starting other things. The hardware (CMOS) clock should be set to GMT (or UTC) time, and you can check this time by typing "date -u". The local time is given if you simply type "date". If you are root you can set the time with the command "date -s "hh:mm:ss"" (note the quotes around the time.) Become root using the command "su". The date command can be used to set the whole date if necessary. Use the same format as the date command uses, but in quotes. Do this as accurately as you can, by getting a telephone time or other service to synchronize to. If the UTC time is off, you can set it correctly after you have set the local time accurately, by typing "clock -w". Unfortunately, PC clocks lose or gain amazing amounst of time, so you must automate the time synchronization. How to do that is described later in the section on Keeping Correct Time.

2. Egg Software

There are a few parts: the program to read, store, and transmit data, the configuration file, and the scripts for dialing the network connection. If you have an ethernet or continuous connection, it is just the main program and the configuration file.

2.1 The eggsh program

The program and configuration file should be installed in the /home/yourdir/egg directory. If you are doing dialup, you probably have the ppp and chat scripts there too. Any executable programs or scripts have to have appropriate permissions, which will show as "x" in the long listing.

The program that records, archives, and sends data is called "eggsh". It uses a configuration file called ".eggrc". The latter is normally hidden, but can be seen in a directory listing with a different switch "ls -a" or "ls -al". This file contains the information to specify the egg's name, its ID number, its IP address, its basket (the server where it will send data) and its communication parameters. This information is near the end in uncommented lines (no leading #). You can edit it using the vi editor, or a more user-friendly editor called joe. The command would be "joe .eggrc". Then type "ctrl-k h" for a help screen with commands. For example, "ctrl-k v" brings you to the end of the file, where you can use the cursor keys, delete, etc to move about and edit the necessary items. Here is a sample of the informational lines in the .eggrc:

EGG egg.name.loc 172 64.182.94.228 noosphere PERM 1
BASKET noosphere 128.112.35.133
PROTOCOL 10 10 30 200
REG PEAR 0 9600

The first line identifies your egg by name, ID, and IP address. It says the server is noosphere and the connection is permanent and attempts to communicate data occur at 1-minute intervals. You will need to edit the file to put in your actual name, ID, and IP address The second line gives the server name and IP address. Line three specifies the structure of the data packets that will be sent to the server, and the last like shows the type of REG device, which COM port it is connected to, and its transmission speed. You may need to edit the COM port designation. The 0 in the sample means COM1, a 1 would specify COM2. The long version of the .eggrc has more information in comments.

2.2 Dialup scripts

Setting up your internet connection to be made in an automated way will be your task, with which I can't help as much as I would like. Your ISP should provide some information, and there are programs that you can find on the net which may be helpful. One is called XISP, but I haven't looked into this for a while.

Here is some description of an old-fashioned way to do the job, using dialup scripts you that are appended below: The scripts specify how the information should be routed, and provide necessary parameters. If you use these, they should be installed in the /home/yourdir/egg directory. One is called pppscript, and you probably will not need to edit it. The other is called pppchat, and it has the phone number that will be dialed if pppscript is invoked (it will be automatically dialed at times we can specify.) The pppchat also has the username and password information to login; these are the difficult items. The format of the login negotiation is not the same everywhere, so you must learn exactly what is required at your ISP. To actually use the pppscript file, make it executable by typing "chmod a+x pppscript".

3. Keeping correct time

The eggs must all be synchronized within a small range, and it is possible to make this a matter of seconds using programs that get correct time from "timeservers" and keep the local clock close by making small adjustments. Begin by setting the CMOS clock to UTC (also known as GMT) as indicated earlier.

3.1 The xntpd program is the preferred way to set the time, and it must be configured in the setup. It is not installed by default is some Linux distributions, so you may have to add it to your system. If this works correctly, you will need only check to be sure the time is set correctly if you reboot. Check the time occasionally by looking at the output of the eggsh program. If it appears to be drifting by more than a second or two, let me know, and we will try to correct the situation.

3.2 The xntpd configuration files require specifying timeservers. You can use the ones specified in the following, but you may prefer to use timeservers closer to home. This is the configuration information for xntpd that must be available in /etc/ntp.conf

server teilhard.global-mind.org
server www.leyline.org
driftfile /etc/ntp.drift

The driftfile should be created as an empty file; it will later have the adjustment coefficients.

4. Useful commands

mkdir (makes a new directory called "name")
cd (change directory to "name"; cd without argument goes to home directory (e.g. /home/yourusername
mount /dos_a (this might be /mnt/dos_a) (allows reading files from floppy disk)
umount /dos_a (unmounts floppy)
ls (lists files and subdirectories)
ls -l (long listing, gives much information)
more (displays files one screenfull at a time; space-bar to go on, q to quit)
ctrl-c (stops program and returns to prompt)
cp (copies files)
mv (moves or renames files)
locate (tells you where to find things)
df (tells disk usage)
ps aux |grep eggsh (will tell you the process number of eggsh program)
su (allows you to become another user or root, if you know password)
joe or vi (editors. vi is arcane, but everywhere; joe is more familiar and may be used with a little experimentation)

4.1 Documentation, man pages, info

If you want terse but useful information on commands, the man pages are excellent. Just type "man ". Be forewarned that this is very condensed reading. There are also so-called info pages that have broader information with hyperlinks; just type "info". For larger-scale questions on getting things working, there is a collection of excellent documentation in /usr/doc/HOWTO.

5. The Dialup Scripts

The "pppscript", which you will not need to modify:

#!/bin/csh

if ("$1" == "up") then
  echo "Bringing net up"

  /usr/sbin/pppd /dev/cua1 115200 connect '/usr/sbin/chat -v -f /egg/pppchat' crtscts modem defaultroute noipdefault

# Wait for connection success
  set timer = 120
  while ($timer > 0) 
    if (-e "/var/run/ppp0.pid") exit 0
    sleep 1
    @ timer = $timer - 1
  end

  echo "Couldn't get it up!"
  exit -1
endif

if ("$1" == "down") then
  echo "Bringing net down"
  if (! -e "/var/run/ppp0.pid") exit 0
  set pid = `cat /var/run/ppp0.pid`
  kill $pid

  exit 0
endif

echo "Usage: pppscript up down"
exit 1

----- The CHAT script:

ABORT BUSY
ABORT "NO CARRIER"
'' ATZ
OK ATQ0V1EX4T
# following ####### is local telephone number of ISP
OK ATDT#######
TIMEOUT 60
CONNECT ''
# following is a possible style of ISP negotiation.  There is usually
# a "challenge" and a "response"  or an expect/reply pair, but this varies
# greatly.  Get help from your ISP
sername roger
assword ------
# following is the command to start ppp on a computer named comserv at Princeton.
comserv 'ppp roger.remote.princeton.edu'
assword ------