Ref: 99980014
Title: NCS/AT Utility Summary
Date: 8/1/86

Copyright 3Com Corporation, 1991.  All rights reserved.

Utilities

This section describes the NCS/AT utilities.  Utilities are
presented in alphabetical order.  The table below summarizes the
functions of all NCS/AT utilities.

You can invoke the utilities at the utilities prompt (or via the
UTility command at the command prompt) in a Command/Utility
screen on the NCS/AT console, or by using the UTility command on
a terminal logged on through an NCS/AT serial port.

To execute a command, either use the Exit utility to leave
utilities mode and return to the command prompt, or switch to
another screen that is displaying the command prompt.

           NCS/AT Utility Summary

Utility             Description
---------------------------------------------------------------
Activenodes         Display addresses and software release
                    numbers of all active servers
Dumpedit            Edit a memory dump file stored on the NCS/AT
                    disk
Exit                Return to command prompt
Floppyformat        Format the diskette in the drive
Floppylist          Display list of files on diskette
Floppyread          Copy files from diskette to disk
Floppywrite         Copy subdirectories or files from disk to
                    diskette
Inactivenodes       Display addresses and software release
                    numbers of all inactive servers
Macroedit           Edit a macro stored on the NCS/AT disk
Ncsbackup           Back up to diskette all files in /usr/NCS
                    except daily audit trail files
Ncsrestore          Copy files from a backup diskette to disk
Net_stats           Display network statistics for all TCP/IP
                    servers
Oneachserver        Execute a command in remote mode on each
                    server
Passwd              Change NCS/AT operator's password
Plot                Graphically display selected audit trail data

You must enter the utility names in lowercase without
abbreviating and enter addresses and pathnames in the proper
case.  A few characters with special meaning to the NCS/AT must
be preceded by a backslash (\) in the command line to prevent the
characters from being misinterpreted.  These symbols are listed
below:
               SPECIAL CHARACTERS

Character      Symbol      Character         Symbol
-----------------------------------------------------

ampersand        &         dollar sign         $

apostrophe       '         exclamation point   !

backslash        \         quotation mark      "
For example, to include an apostrphe in string text, enter a
backslash followed by an apostrophe (\').  To specify one
backslash (\) as part of string text, enter two backslashes (\\);
the first prevents the NCS/AT from treating the second as a
special character.

Conventions used in syntax descriptions are described below.
Include only the hyphen in the utilities you type; do not enter
the angle brackets, square brackets, vertical bar, or ellipsis.

case    All utilities must be entered in lowercase, with no
        abbreviations.

< >     Items listed in angle brackets represent variable
        parameters or value.  Do not enter the angle brackets.

[ ]     Items listed in square brackets represent option
        parameters.  Do not enter the square brackets.

|       Items separated by a vertical bar within a list represent
        mutually exclusive choices, one of which may be entered.
        Do not enter the vertical bar.

...     Items followed by an ellipsis may be repeated in the same
        command line.  Do not enter the ellipsis.

-       A letter preceded by a hyphen represents a utility
        option.  If you specify such an option, you must enter
        the hyphen.  If you use more than one option, enter only
        one hyphen, followed by an unpunctuated list of options
        (i.e., no spaces or other delimiters between option
        letters).

Pathnames specified in utilities must fullow different
conventions than those specified in commands.  Filenames
specified in utilities on the NCS/AT may be a full pathname or a
relative pathname.  The full pathname for a file is a descending
list of the subdirectories in which the file is stored beginning
with the Xenix root (/) and ending with the name of the file
itself.  The relative pathname assumes the file to be in the /usr/
NCS directory and is the subdirectory name, if any, followed by
the filename.  For example, you may specify a configuration file
bu its full pathname (/usr/NCS/CONFIGS/cfg.C009C850) or by its
relative pathname (CONFIGS/cfg.C009C850).  The case of all
characters (upper, lower, or mixed) in pathnames must be correct.

Error messages appear in the Command/Utility screen in which you
issued the utility unless otherwise indicated.

.h1;Activenodes Utility

.br;SYNTAX

.br;activenodes

.br;DESCRIPTION

The Activenodes utility displays a list of the addresses and
software release numbers of all active servers on the network.  A
server is classified as active if the NCS/AT has detected packets
from it within the last five minutes.  Every Bridge server
transmits packets across the network at regular intervals to
indicate that it is up and running.

.br;NORMAL RESPONSE

A list of the active servers, including their addresses and
associated software release numbers in the following format:
            NETWORK 192.009.200.000 MAP

    0-192.009.200.031 SW/AT-NCS-TCP     10000
    1-192.009.200.080 SW/IVECS-TCP      13002
    2-192.009.200.073 SW/1-TCP          13008
    3-192.009.200.078 SW/1-TCP          13008

This display is followed by a new prompt.

.br;ERROR MESSAGES

.br;"Usage: activenodes"

.h1;Dumpedit Utility

.br;SYNTAX

.br;dumpedit <filename>

.br;DESCRIPTION

The Dumpedit utility calls the vi text editor to allow you to add
comments to a memory dump file stored in /usr/NCS/DUMP.  Vi is
described in the SCO XENIX System V Operating System User's Guide
(reference [3}).  You can add no more than 255 characters to the
file.

Dumpedit is used to add information concerning the state of the
crashed server to the memory dump file.  ALthough no more than
255 characters can be added to the file, include as much as
possible of the following information:

*  The release number of the software running in the crashed
   system
*  The release numbers of all firmware in the crashed system
*  For Ethernet networks, the transceiver brand name and model
   number
*  The date and time at which the crash occurred, and any
   information available about the network traffic load at that
   time
*  The condition of the LED indicators on the server front panel
   and, if possible, on individual boards
*  The extend of the system affected (For example, a single port,
   several ports, or the entire unit)
*  A description of any symptoms present prior to the crash
*  The text of any error messages that appeared on the console
   terminal at the time of the crash (if one was attached)
*  For a crashed IVECS, please include:
    - The host operating system and version (for example, UNIX
    4.2 BSD or VMS Version 4.1)
    - Number of DMF32s emulated by the IVECS
    - Number of virtual ports provided by the IVECs
    - Hpst CPU load; you can determine this by executing the SHOW/
    PROCESS and SHOW/USERS commands under VMS or the w command
    under the UNIX operating system

.br;EXAMPLE

.br;dumpedit dump.C009C84E

.br;This example allows you to edit the memory dump file
"dump.C009C84E" using vi.

.br;NORMAL RESPONSE

Dumpedit echoes the name of a temporary file and displays the
number of lines and the number of characters it contains.  Then
it prompts for vi commands with a colon.

When the edited memory dump file has been written to the disk, a
message such as the following is displayed:

    "/tmp/<number>" <n> lines, <n> characters

This message is followed by a new prompt.

.br;ERROR MESSAGES

.br;"Checksum error"
.br;"Comment record not found"
.br;"Comment truncated to 255 characters"
.br;"Error on read of file header"
.br;"Incompatibile dump file"
.br;"Invalid dump filename specified"
.br;"Not a dump file"
.br;"<pathname>:No such file or directory"
.br;"Usage:dumpedit <filename>"

.br;Exit Utility

.br;SYNTAX

.br;exit

.br;DESCRIPTION

The Exit utility terminates the utility mode and returns you to
the command prompt.

.h1;Floppyformat Utility

.br;SYNTAX

.br;floppyformat

.br;DESCRIPTION

The FLoppyformat utility formats the diskette in the diskette
drive for use with XENIX.

                   ** NOTE **

The NCS/AT uses double-sided, high-density, 5 1/4-inch, 96-track-
per-inch (tpi) diskettes that have a formatted capacity of 1.2M
bytes.  Do not attempt to use any other type of diskette.

To format a diskette, insert the diskette in the drive and enter
the following:

.br;floppyformat

.br;The following prompt appears:

.br;Insert floppy in drive, hit return when ready

When you press <ENTER>, the utility begins to format the
diskette.

Floppyformat display the numbers of the track and head it is
currently formatting:

   track <nn>      head <nn>

.br;NORMAL RESPONSE

.br;A new prompt appears.

.br;ERROR MESSAGES

error on dev floppy...
      Insert disk or close floppy door"*
tar: tape read error"

 * This message appears in the Diagnostics screen.
** This message indicates a diskette read error.

.h1;Floppylist Utility

.br;SYNTAX

.br;floppylist [-1]

.br;DESCRIPTION

The Floppylist utility displays a list of the files on the
diskette in the diskette drive.

If you specify the -1 option, the display includes the mode, size
in bytes, and date last modified for each file.

.br;NORMAL RESPONSE

The NCS/AT lists the filenames on the diskette, including mode,
size and date if requested, followed by a new prompt.

.br;ERROR MESSAGES

.br;"error on dev floppy...
      Insert disk or close floppy door"*
.br;"tar:directory checksum errlr"**
.br;"tar:tape read error"***
.br;"Usage:floppylist [-1]"
.br;-----------------
  * This message appears in the Diagnostics screen.
 ** This message occurs if you attempt to list files on a newly
    formatted diskette which contains no files.
*** This message indicates a diskette read error.

.h1;Floppyread Utility

.br;SYNTAX

.br;floppyread [<filename>...]

.br;DESCRIPTION

The Floppyread utility is used to copy one or more of the files
on a diskette to the NCS/AT disk.  If you include no filenames,
all of the files on the diskette are copied.

Load the diskette containing the desired files before issuing the
Floppyread utility.  To display the contents of the diskette, use
the Floppylist utility.  Pathnames specified when invoking the
Floppyread utility must be identical to those displayed by the
Floppylist utility.

                ** CAUTION **

The Floppyread utility overwrites the files with the same
filenames in the directories on the NCS/AT disk with the files
being copied from diskette. To preserve the files on the disk, be
sure to rename them or back them up to diskette before using the
utility.

.br;EXAMPLE

.br;floppyread /usr/NCS/AUDIT_TRAIL/audit.1027

.br;This example copies the file audit.1027 from diskette to the
NCS/AT disk.

.br;NORMAL RESPONSE

.br;A list of filenames as the files are copied, followed by a
new prompt.

.br;ERROR MESSAGES

.br;"error on dev floppy...
      Insert disk or close floppy door"*
.br;"tar: tape read error"**
.br;"Usage:floppyread [<filename>...]"
___________________
 * This message appears in the Diagnostics screen.
** This message indicates a diskette read error.

.h1;Floppywrite Utility

.br;SYNTAX

.br;floppywrite <filename> .. | <directory name> ..

.br;DESCRIPTION

The Floppywrite utility is used to copy one or more specified
subdirectories or files from the NCS/AT disk to a diskette.

Load a diskette drive before issuing the Floppywrite utility.
Make sure that the diskette is not write protected.

To copy the files in one or more specific directories, enter the
directory names separated by one or more spaces.

To copy specific files, enter the filenames separated by one or
more spaces.

.br;EXAMPLE

.br;floppywrite /usr/NCS/AUDIT_TRAIL

.br;This example copies the daily audit trail files onto a
diskette.

.br;NORMAL RESPONSE

A list of filenames and sizes in blocks of 512 bytes as the files
are copied, followed by a new prompt.

.br;ERROR MESSAGES

"Floppy is write protected
     error on dev floppy..."*
"error on dev floppy...
       Insert disk or close floppy door"*
"tar:tape write error"**
"Usage:floppywrite <filename>...|<directory name>..."

-----------
 * This message appears in the Diagnostics screen.
** This message indicates a diskette read error.

.h1;Inactivenodes Utility

.br;SYNTAX

.br;inactivenodes

.br;DESCRIPTION

The Inactivenodes utility displays the addresses and software
release numbers of all inactive nodes on the network.  A server
is classified as inactive if the NCS/AT has not detected any
packets from the server for more than five minutes and less than
three days (72 hours).  A server is removed from the network map
when it has been inoperative for 72 hours.  Every Bridge server
transmits packets across the network at regular intervals to
indicate that it is up and running.

.br;NORMAL RESPONSE

A list of inactive servers, including their addresses and
associated software release numbers, in the following format:
   ***192.009.200.080 SW/IVECS-TCP  13004
   ***192.009.200.077 SW/200-TCP    13000
   ***192.009.200.073 SW/100-TCP    1300A
   ***192.009.200.078 SW/1-TCP      13002
    ***  4 inactive nodes ***

This display is followed by a new prompt.

.br;ERROR MESSAGES

.br;"Usage:inactivenodes"

.h1;Macroedit Utility

.br;SYNTAX

.br;macroedit <macro name>

.br;DESCRIPTION

THe Macroedit utility calls the vi text editor to edit macros
stored in the NCS/AT macro directory.  Vi is described in the SCO
XENIX System V Operating System User's Guide (reference [3]).

You can use Macroedit to edit existing macros or create new
macros.

To edit a macro, enter "macroedit" and the macro name in response
to the utility prompt.  The NCS/AT does not distinguish between
uppercase and lowercase characters in macro names.

When creating or editing macros, follow the guidelines listed in
the Network Management Guide.

.br;EXAMPLE

.br;macroedit tek

.br;This example calls vi to allow you to edit the macro called
tek.

.br;NORMAL RESPONSE

Macroedit echoes the name of a temporary file and displays the
number of lines and the number of characters it contains.  Then
it prompts for vi commands with a colon.

When the edited macro has been written to the disk, a message
such as the following is displayed:

    "/temp/310" 2 lines, 62 characters

When you have exited from the Macroedit utility, a message such
as the following is displayed, where "tek" is the name of the
macro:
        macro tek replaced

These messages are followed by a new prompt.

.br;ERROR MESSAGES

.br;"Can't--macro directory is full"
.br;"Macro <macro name> not found"
.br;"Usage: macroedit <macro name>"

.br;Ncsbackup Utility

.br;SYNTAX

.br;ncsbackup

.br;DESCRIPTION

The Ncsbackup utility is used to back up all of the files in the /
usr/NCS directory, except the daily audit trail files, from the
NCS/AT disk to one or more diskettes.  To back up audit trail
data to diskette, use the Floppywrite utility.

Load the diskette to which the files are to be copied before
issuing the Ncsbckup utility.  Make sure that the diskette is not
write protected.

If more than one diskette is needed, the system prompts you to
insert a new diskette and press RETURN.  Be sure to label each
diskette to indicate sequence (e.g., #1 or 3, #2 or 3, and so
on).

.br;NORMAL RESPONSE

As the files are copied, a series of messages, each including a
pathname, is displayed.  When all files have been copied, a new
prompt is displayed.

.br;ERROR MESSAGES

.br;"error on dev floppy...
       Insert disk or close floppy door"*
.br;"Floppy is write protected
       error on dev floppy..."*
.br;"tar: tape write error"**
.br;"Usage: ncsbackup"
.br;--------------
 * This message appears in the Diagnostics screen.
** This message indicates a diskette read error.

.h1;Ncsrestore Utility

.br;SYNTAX

.br;ncsrestore

.br;DESCRIPTION

THe Ncsrestore utility is used to restore the files from one or
more backup diskettes to the NCS/AT disk.  During execution of
the Ncsrestore utility, execution of other NCS/AT commands and
utilities is suspended; this makes bootstrap, configuration,
macro, and Internet name services unavailable to client servers.

Load the diskette containing the desired files before invoking
the Ncsrestore utility.  To display the contents of the diskette,
use the Floppylist utility.

If more than one diskette is needed, the system prompts you to
insert a new diskette and press RETURN.  Be sure to load the
diskettes in the correct sequence.

                     ** CAUTION **

The Ncsrestore utility overwrites the files with the same
filenames in the directories on the NCS/AT disk with the files
being copied from diskette.  To preserve the files on the disk,
be sure to back them up to diskette before using the utility.

After you execute Ncsrestore on a secondary NCS/AT, use the
BEcome Secondary command to reestablish it as a secondary NCS/AT.

.br;NORMAL RESPONSE

The normal response includes the following three actions:

1.  The following messages are displayed in the Diagnostic screen
as NCS/AT suspends its services:

na: mm/dd hh:mm:ss Internet Name Server Exit
bs: mm/dd hh:mm:ss Boot Server Exit
fs: mm/dd hh:mm:ss File Server Exit
ns: mm/dd hh:mm:ss NMUI Server Exit

2.  As the files are restored, a list of pathnames is displayed
in the screen from which the utility was invoked.  If more than
one diskette is needed, the system prompts you to insert each
additional diskette and press RETURN.  When all files have been
restored, four process number are displayed, followed by a new
prompt.

3.  As the NCS/AT reactivates its services, the following
messages are displayed in the Diagnostic screen, not necessarily
in this order:

bs: mm/dd hh:mm:ss Boot Server Started
na: mm/dd hh:mm:ss Internet Name Server Started
fs: mm/dd hh:mm:ss File Server Started
ns: mm/dd hh:mm:ss NMUI Server Started
ns: mm/dd hh:mm:ss network interface opened
fs: mm/dd hh:mm:ss network interface opened
na: mm/dd hh:mm:ss network interface opened
bs: mm/dd hh:mm:ss network interface opened

.br;These messages are followed by a new prompt.

.br;ERROR MESSAGES
"error on dev floppy...
    Insert disk or close floppy door"*
"tar: tape read error"**
"tar: first extend read is not #1
    OK to read file beginning with extend #2 (y/n)?"***
"Usage: ncsrestore"
-----------
  * This message appears in the Diagnostics screen.
 ** This message indicates a diskette read error.
*** If this message appears, you should remove the diskette from
    the drive and respond to the message by pressing <N> and
    <ENTER>; then insert the first diskette of the sequence in
    the drive and start Ncsbackup again.

.h1;Net_stats Utility

.br;SYNTAX

.br;net_stats -A| -B [s|m|<hour>|d}

.br;DESCRIPTION

.br;The Net_stats utility collects, reformats, and displays
network statistics for each server that appears in the NCS/AT's
netmap or for each server bound to the NCS/AT.

To display network statistics for all servers in the netmap, use
the -A parameter.

To display network statistics for the servers bound to the NCS/
AT, use the -B parameter.

You can limit the network statistics display to a particular
period.  To display the network statistics for the busiest sample
of the current day*, use the s parameter.  To display the network
statistics for the busiest minute of the current day, use the m
parameter.  To display the network statistics for a particular
one-hour interval, enter the hour as an integer in the range 0 to
23, inclusive.  To display the network statistics for the prior
day, use the d parameter.

.br;EXAMPLE 1

.br;net_stats -A

This example displays the network statistics for the current 24-
hour period for each server that appears in the NCS/AT's netmap.

.br;EXAMPLE 2

.br;net_stats -B m

This example displays the network statistics for the busiest
minute of the current 24-hour period for the servers bound to the
NCS/AT.

.br;------------
* The current day is the 24-hour period that begins at midnight,
the most recent reboot of the server, or the most recent
Zerostats command, whichever is later.

.br;NORMAL RESPONSE

.br;The following message appears:

.br;   polling nodes for network statistics...

Then a list of the specified servers and their network statistics
appears; for example;

    network statistics for 192.009.200.080
    DataLink        PKT/S BYTE/S ERROR: CRC ALN 2SHT 2LON COLL
    192.009.200.000  87   5169           88  85    0    0   62
.br;This display is followed by a new prompt.

.br;Network statistics reports are described in the Network
Management Guide.

.br;ERROR MESSAGES

.br;"Usage: net_stats -A|-B [s|m|<hour>|d]"

.h1;Oneachserver Utility

.br;SYNTAX

.br;oneachserver -A|-B'<command>'

.br;DESCRIPTION

The Oneachserver utility executes the specified command on each
server that appears in the NCS/AT's netmap or on each server
bound to the NCS/AT.

To execute a command on all servers in the netmap, use the -A
parameter.  The command is executed on Gateway Servers if they
appear in the netmap.  The command may be forwarded to an
attached network through an Internetwork Bridge, although the
command is not executed on the Internetwork Bridge itself.

To execute a command only on the Communications Servers bound to
the NCS/AT, use the -B parameter.

Enter the command string enclosed in a single quotes (') exactly
as though it was being entered in remote mode on a terminal
attached to a Communications Server; abbreviation within the
single quotes is allowed.

.br;EXAMPLE

.br;oneachserver -b 'setd localpassword = "newpass"'

This example sets the local network manager password on each of
the servers bound to the NCS/AT.

.br;NORMAL RESPONSE

For each server on which the specified command is executed, the
NCS/AT displays the server's address followed by the result of
the command.

.br;The display is followed by a new prompt.

.br;ERROR MESSAGES

.br;"Invalid remote command"
.br;"(timeout failure)"
.br;"Usage: oneachserver -A|-B'<command>'"

.h1;Passwd Utility

.br;SYNTAX

.br;passwd

.br;DESCRIPTION

The Passwd utility is used to change the NCS/AT operator's
password.  Only someone who knows the current password can change
it.

To change the password, enter "passwd" in response to the utility
prompt.  The Passwd utility displays the following:

.br;   Changing password for ncs
.br;   Old password:

Enter the current NCS/AT operator's password.  Press <ENTER>
after you respond to this and every other prompt.  If the
password entered does not match the current password, the Passwd
utility displays the following, and then the utility prompt:

.br;   Sorry.

If the password entered matches the current password, the Passwd
utility prompts for the new password:

.br;   Enter new password (minimum of 5 characters)
.br;   Please use a combination of upper and lowercase
.br;        letters and numbers.
.br;   New password:

Enter the new password.  The password must be five or more
characters long.  Passwords are case sensitive; for example, if
you include capital letters in the new password, then you must
enter those letters in uppercase whenever the passwork is
requested.  The Passwd utility replies:

.br;    Re-enter new password:

Enter the new password again.  If this password is not the same
as the new password entered on the previous line, the old
password is not changed.  If the same new password has been
entered twice, it becomes the NCS/AT operator's password,
replacing the old password.

.br;NORMAL RESPONSE

.br;When the password has been successfully changed, a new prompt
appears.

.br;ERROR MESSAGES

.br;"Password unchanged"
.br;"Sorry."
.br;"They don't match; try again."
.br;"Too short.  Password unchanged."

.h1;Plot Utility

.br;SYNTAX

.br;plot <plot type> <record type> [[<month>]<day>]
.br;plot <plot type> <record type> <month> <day>
[<address>[<port>]]

.br;DESCRIPTION

The Plot utility is used to display selected audit trail data
graphically.

.br;You must specify one of the following plot types:

.br;-h  ASCII histogram
.br;-l  ASCII line
.br;-c  ASCII curve

.br;ASCII plots are composed of printable ASCII characters.

The audit trail data to be plotted is selected by record type.
The record type may be one of the following:

.br;CD        Number of connections established
.br;CF        Number of connections failed
.br;DC        Number of disconections performed
.br;NU        Network utilization as a function of time
.br;TOTALCD   Net of connections and disconnections (CD - DC)

If you specify a month and day, the specified data for the date
is displayed.  Specifiy a month either as an integer in the range
1-12 or using the first three characters of the month's name
(i.e., Jan, Feb, etc.).  Enter a day as an integer in the range 1-
31.  If you enter an integer without preceding it with a month
name or with another integer and a space, the NCS/AT interprets
the integer as a day, and displays the records for that day of
the current month.  If you specify no date, the NCS/AT displays
data for the current day.

If you use the second form of the utility to specify the address
parameter, it must be the Internet address of a server and all
leading zeroes must be included (for example, 192.009.200.080,
not 192.9.200.80); an Internet name cannot be specified.  The
address parameter must be preceded by a month and day.  When the
address parameter is included, the specified data for the server
with that Internet address is displayed.

If you specify an Internet address and port identifier, the port
identifier must be preceded by a backslash and an exclamation
point (!) and must consist of three digits.  When a port
identifier is included, the specified data for that port on the
server with the specified Internet address is displayed.

To redirect an ASCII plot to the printer, give the Plot utility
as an argument to the Print utility.

.br;EXAMPLE 1

.br;plot -h CD 2 192.009.200.080

This example displays an ASCII histogram plot of connections
established on the server with the Internet address
192.009.200.080 on the 2nd day of the current month.

.br;EXAMPLE 2

.br;plot -c CF 3 30 192.009.200.080\!015

This example displays an ASCII curve plot of connections failed
on port 15 of the server with the Internet address
192.009.200.080 on the 30th of March.  the exclamation point is a
special character, so it must be preceded by a backslash.

.br;NORMAL RESPONSE

The messages "Searching through Audit Trail data file..." and
"reducing data...", followed by the requested plot and a new
prompt.

.br;ERROR MESSAGES

.br;"Audit record type <xx> is unknown"
.br;"Audit trail data file <filename> is not readable:
.br;"Audit trail data file <filename> is empty"
.br;"Input data error"
.br;"Invalid option"
.br;"Invalid axis type"
.br;"Invalid plot type"
.br;"No data point found"
.br;"Plot type "<x>" is unknown"
.br;"Usage: plot <plot type> <record type> [[<month>]<day>]
            or
    plot <plot type><record type><month><day>[<address>[<port>]]"



