GATED-IDRP AUTOMATED TESTER

USER'S GUIDE


Version: 2.34
Last updated: 5-22-96

Introduction


This program tests version of Gated for normal operation.

This program became necessary from the sheer number of different gated.conf test cases needed for even relatively simple configurations. A basic four-machine test using 12 slightly different networks and six sub-tests requires over two hundred different configuration files, and thus as many separate tests.

Accordingly, this program is designed to minimize the amount of work needed to test a given physical configuration. It was designed both to be simple and straightforward to use, and yet flexible enough to use under a wide variety of tests and conditions.

The author assumes the reader is familiar with what Gated is, what IDRP is, and the basic concepts behind networking and using Gated to establish machine- to-machine communications.

(Versions of GateD of R3_5_3 to R3_6_x are supported by this test tool including support for idrp, bgp, ospf, rip.)

Definitions


Configuration file - a file which Gated uses to read in information about a
                     particular machine - its peers, import and export policy,
                     static routes, and operating parameters.  Usually named
                     "gated.conf" or something similar.

Expected results file - a file created by the configuration file generator
                        containing the routes which are expected to be in
                        the routing table following the processing of its
                        related gated.conf file.

Sequence - a particular physical configuration of machines.  A sequence
           defines the machines used, internal and external peers for each
           one, and RDI and RIB information.

Test set - a particular test to apply to each sequence in the test.  Test
           sequences contain import and export information, and which routes
           to include or exclude.

Running the Program


Run the program "gated_setup.csh", first resetting any system-dependent values in that script to appropriate values. This script will set up a convenient alias and other necessary environment variables to run the generator.

The tester also reads the file "testg_setup.csh" to get information on working files and directories. Make sure the environment variables in this file are set appropriately. Be sure the editor you choose is implemented on your system.

To run the generator, type " testg <options>". Use the "-h" option to generate the usage message seen below.

Usage: testg [-a] [-g] [-h] [-Q] [-v] [-t ] [-s ]

Gated test driver options:

   -a   Tells driver to use AUTO mode - input from file rather than terminal
          NOTE: this is cosmetic only: use '<' on command line to specify file
   -g   Start gated when starting driver
   -h   Print this help list
   -Q   Do not use QOS table when comparing expected results
          NOTE: this is for non-QOS versions of gated-IDRP
   -s   Set sequence and test number on startup
   -t   Set test name on startup
   -v   Set verbose mode (prints more information while running)

Examples:

   In these examples below, the test name is "basic_12".

   1.  Run the tester in auto mode using a file for commands.
       % testg -a -t basic_12 &< commands.txt

   2.  Start gated, begin with sequence 4, test set number 1.
       % testg -g -t basic_12 -s 4 1

   3.  Run in auto mode (test name specified in input file), make me
       feel secure with lots of diagnostic messages.
       % testg -a -v < commands.txt

Note:  The "-a" option does NOT tell the tester to run from a file.  That
       is done by using the input redirector "<".  The -a option is there
       to prevent the Main Menu from printing when a file is used.

Commands may either be entered interactively (see "The Main Menu" below),
or read from an input file (see "Using a File for Commands").

The Main Menu


1)  Select a test sequence (1t = display current test)
  Example:  1 4 1
  Sequence is specified first, then test number.  If "1" is entered
  by itself, a secondary prompt will ask for these values.
  "1t" displays the current test name, sequence, and test set number.

2)  Check gated status
  Indicates whether or not gated is running.  Returns the process ID if it is.

3)  Start gated (3c = test current config file only)
  "3c" runs gated with the "-c" flag.  This simply checks the configuration
  file to see if it parses correctly.  Routes are not actually processed.

4)  Kill gated
  Kills the gated process if one is running.

5)  Review the net status (5m = pipe to more)
  Prints the current routing table ("netstat -rn").

6)  Compare expected test results to routing table
  Runs the comparison script to compare the current expected.txt against
  the routing table and QOS file.  See the section on "Expected Results Files"
  in the configuration file generator user's guide for more information.

7)  Send refresh signal (config file re-read) to gated
  Forces a re-read of gated.conf in the working directory.

8)  Flush the routing table
  Not recommended while gated is running!

9)  Spawn a shell (csh)
  When done, simply exit the shell to return to the main menu.

10) Set the test name
   Example:  10 basic_12

11) Edit the configuration file
   Edits the current gated.conf file in the working directory.  Does not
   edit the original copy in the test directory (if it was copied from there).
   Useful for making minor changes, then sending a refresh (command #7).

12) Edit the expected results file
   Edits the current expected.txt file in the working directory.  Does not
   edit the original copy in the test directory (if it was copied from there).

13) View the gated log file
   Views (read only) the current gated-idrp log file.

14) Save the gated log and routing tables to local log files
   Uses the environment variable $gated_locallog_dir as save directory.
   Saved file uses the log file name, appending the date, sequence, and
   test set number.  (Example:  gatedlog,idrp.0917.4.1)

15) Analyze memory trace calls in the log file
   Reports on the number of dynamic memory blocks allocated and freed by
   the IDRP code.  It calculates this information by reading the MEM_TRACE
   lines in the log file.  Note: the code must have been compiled with
   -DMEM_TRACE for this feature to work.  (Really a debugging feature only.)

21) Turn on auto comparison - expected results/routing table
22) Turn off auto comparison
   Example: 21 90
   Causes an automatic comparison of the routing table with the expected
   results after a test is run, waiting for the specified number of seconds
   before doing so.  This feature should be used when running commands from
   a file, to insure that gated has enough time to process route changes
   following a refresh.

23) Turn on verbose mode (print more informational messages)
24) Turn off verbose mode
   This causes the printing of more information/status messages, such as the
   names of working files and directories.  May provide a clue if something
   goes wrong.  And for the bored or curious, it provides some light on what
   goes on behind the scenes.

25) Turn on synchronization with other nodes
26) Turn off synchronization
   Example:  25 ralph norton alice
   See the section below on "Multiple Machine Synchronization."

!m) Turn off printing of Main Menu
m)  Turn on printing of Main Menu
   Useful if running in auto mode (thus no need to see menu), or you are
   familiar enough with the menu that you don't need to see it anymore.

0)  Exit this program
  Exits the tester.  Note: this does NOT shut down gated!!

Using a File for Commands


Commands read from an input file are specified and processed in the same manner as if they were entered interactively. Comment lines (lines beginning with "#") and blank lines will be ignored.

Input files are specified using the standard input redirector "<" on the command line as follows: % testg -a < <command file name<

When using a file, use of the "-a" option is highly recommended. Otherwise, the Main Menu will be printed after every command, as though commands were being entered interactively.

Multiple Machine Synchronization


The tester has a feature to allow simultaneous automatic testing on multiple machines. Using synchronization, each machine in the group will wait for the others to become ready before proceeding with the next refresh.

The synchronization list is specified using command: 25 <machine> <machine> ... <machine>

This list can be modified before the start of any test, even between tests in a sequence.

Each machine in the list creates a file in the synchronization directory, in which it writes the sequence and test set number of its next test. Before running that refresh, the machine continually checks that directory, waiting until all the other machines in the list have synchronization files which match that sequence and test set number.

If testing multiple configurations, machines which will not be used until later in the test can be "sent ahead" by turning on synchronization and setting their sequence and test set numbers. These machines will wait until the other machines reach that sequence and test set, and then proceed normally.

Synchronization is most useful when using the "auto comparison" mode, reading commands from an input file. For example, consider a test where sequence 1 uses machines "ralph" and "norton", while "alice" joins them in sequence 2. The auto input file shown below can be used for all three machines: assuming no configuration files exist in sequence 1 for "alice", that machine will skip ahead to sequence 2 and wait for the others. When "ralph" and "norton" reach sequence 2, "alice" will synchronize with them and continue.

# Set synchronization list 25 ralph norton

# Run sequence 1 1 1 1 1 1 2 1 1 3

# Add alice to the list 25 ralph norton alice

# Run sequence 2 1 2 1 1 2 2 1 2 3


Author: Jeff Jackson Merit Network, Inc. jeff@merit.edu