Chapter 6 - Tools and Utilities
The /disk1/bin directory contains standard AT&T UNIX System V executables, plus several executables added to the system by Banyan Systems. The /disk1/banyan/util directory contains many UNIX executables that were developed or modified by Banyan.
This section describes the utilities that Banyan has added to the UNIX environment. It complements these two books from AT&T:
UNIX System V/386 Release 3.2 System Administrator's Reference Manual UNIX System V/386 Release 3.2 User's Guide
The /bin directory contains UNIX executables. Most of these are standard UNIX commands, and some are Banyan-specific. The sections that follow summarize both the standard commands and the Banyan commands.
The /bin directory contains the following standard UNIX System V commands:
For more information on these commands, refer to your UNIX System V documentation.
Banyan implementation of some of these commands differs slightly from the commands that are distributed with UNIX System V. For example, grep supports only six switches. The standard UNIX System V grep has more. This section does not document such differences. In most cases, you can display usage instructions, including all supported switches, by entering the command with no arguments.
The Banyan implementation of the ps command supports two option switches that are not available with the standard UNIX command:
-x - Displays the name of the kernel.
-z - Displays memory usage by process.
The use of these switches is described in the sections that follow. When you omit these switches, ps runs as the standard UNIX System V command.
Displaying the Kernel Name with ps -x
Including the -x switch with the ps command causes the name of the file that was used to boot the server to appear at the top of the ps report. The switch works in conjunction with the -l and -f switches.
Displaying Memory Usage by Process with ps -z
Use the -z switch to display information on how the memory that is available for processes (maxmem) is actually being used.
When -z is used in conjunction with -f or -l, a new field, PR, is added after the SZ field. The PR field contains the number of non-overhead pages currently valid in the process. The SZ field, in contrast, contains the total number of non-overhead pages in the process.
When the -z field is used without either -f or -l, a new report is generated. The new report presents memory usage from the region tables and sums the information on a process and whole-machine basis. The heading line of the report is:
F S SZ/PR/OH/SG TEXT/PR/SH DATA/PR STCK/PR COMD
Most values are represented in pages. A page is the basic unit of RAM on the server. The page size on a VINES server is 4 KB (4096 bytes).
The values in each column have the following meanings:
F - This is a flag field. Flag values are:
0x01: This process cannot be swapped out
0x02: The parent process is tracing this process.
0x04: The tracing parent's signal has stopped the process.
0x08: The process is currently in primary memory.
0x10: The process is currently in primary memory, but is waiting for the completion of an event.
0x00: The process has been terminated.
S - This is the state field. It has seven possible values.
O: This process is currently executing on the processor.
S: The process is sleeping. It is waiting for completion of an event, usually I/O.
R: The process is ready to run and is on the run queue.
I: The process is currently idle. An idle status indicates that the process is being started.
Z: The process is in a zombie state. It has terminated but its parent is not waiting.
T: The process has been stopped by its parent and is being traced.
X: SXBRK state. The process is waiting for more memory to become available.
SZ - Contains the total number of pages (including overhead pages) that are in the virtual address space of the process.
PR - Contains the total number of pages (including overhead pages) that are currently present in RAM for the process.
OH - Contains the total number of pages of overhead being used to manage the process.
SG - contains the total number of segments (regions) in the process. This is 4 on a VINES/386 system. (There is an extra region for the Weitek floating point card.)
TEXT - Contains the number of pages, excluding overhead, in the text region. This region contains the executable instructions of the process.
PR - Contains the number of text pages in RAM for the process.
SH - Contains the number of processes that are using the text region. If multiple processes use the same code, only one copy of the code is loaded into RAM.
DATA - Contains the number of pages, excluding overhead, in the data region.
PR - Contains the number of data pages in RAM for the process.
STCK - Contains the number of pages of stack segment, excluding overhead.
PR - Contains the number of stack pages in RAM for the process.
COMD - Name of the currently executing command text file as presented in the -l option.
At the bottom of the report is a line of summary information:
SIZE = n0/n1, OH=n2, REAL= n3, FREE=n4, WORKING SET = n5
SIZE - Contains two values. The n0 parameter is the total number of pages in all regions of all processes in the system. It is the sum of the SZ column corrected for shared text regions. The n1 parameter is the number of pages actually present in RAM in the system.
OH - Shows the total number of overhead pages required to support all processes on the server.
REAL - Amount of RAM in 1024-byte units that was available for processes.
FREE - Amount of RAM, in 1024-byte units, that is currently available for use by processes in the server. A value below 400 in n4 indicates a potential RAM problem and should be investigated.
WORKING SET - Percentage of all the processes that are currently in RAM. A healthy system has a working set value of around 95%.
The Banyan-specific commands in /bin are not part of standard UNIX, but come with the Banyan server software. These commands are as follows:
autoup
Script used during server upgrades.
badchk
Lists the contents of the bad block table for the logical disk. This includes the number of bad blocks used, and the number remaining.
bmenu
This large shell script runs on the console screen, and controls all system console activities. See the Server Operations Guide for more information.
cctrap
This program allows installers to abort the initial system load by pressing <Control-C>. This utility is run in the /.profile UNIX shell.
cfgsvr
This script, which is usually called from bmenu, displays the Banyan Server Configuration menu.
ckdev
This program finds each logical disk in the server, and checks each disk for compatibility with the Banyan server software. It also mounts S5 or S10 file systems, primarily during installations, and mounts tape drives and CD-ROM drives when it detects them.
ckdisk
Runs at server initialization time, and does the following:
Finds logical disks in the server. Checks each disk for a VINES-compatible structure. Checks the integrity of the UNIX file system. If necessary, runs fsck to analyze the current logical disk. (This takes a long time on a system with large disks.) Mounts file systems. Locates the tape drive and creates dev nodes for it.
doreboot
Reboots the Banyan server.
getinordie
Counts down 60 seconds to allow users to abort a script by pressing Control-C.
gzip
Used to decompress files during a server installation.
id
Prints the uid and gid of the current disk partition.
oversub
Checks to see if the disk is formatted for too many cylinders. If so, and if there is no data in the extra space, it automatically shrinks the disk.
tpcntl
Issues tape commands to any mounted tape drive from a shell script.
unixsyms
Loads symbols into the kernel for the symbolic debugger.
The /disk1/banyan/util directory contains many utilities developed by Banyan. These utilities are often run by initialization scripts contained in /disk1/banyan/install, or service scripts in the /disk1/banyan Enterprise Network Service directories.
A few of the utilities in /disk1/banyan/util are standard UNIX commands. The files in /disk1/banyan/util are as follows:
aping
Ping program for AppleTalk networks.
banlogin
Logs in to StreetTalk.
banlogout
Logs out of StreetTalk.
banrte
Manipulates the Banyan routing tables.
bantape
On a V386 server, this command backs up files to diskette.
basecheck
Checks files in the base release of VINES
bfsfile
Implements the Banyan Application Toolkit functions bfs_get, bfs_rm, and bfs_put. These toolkit functions run this file as root, even though the process that runs the file is local.
chrtbl
Creates a ctype local table.
ckacl
Checks acl entries for integrity.
cleanup
Empties script file.
comm
Standard UNIX System V utility that selects or rejects lines common to two sorted files.
commerr.tra
Tellerr database containing communications-layer errors.
concheck
Checks the consistency of VINES Files. This is done to verify that the programs in /disk1/banyan/bfs/VINESFiles exist, and have proper file integrity.
conerrpt
Script that runs concheck.
cp
Standard UNIX System V copy utility.
crash
Standard UNIX System V dump analyzer.
cut
Standard UNIX System V cut utility, used to cut out columns from a table or fields from each line of a file.
datetime
Changes the network date and time.
distpatch
Distributes patches to VINES Files executables to foreign language locations. It also update the VINES Files consistency database files, such as /disk1/banyan/bfs/condos.db or /disk1/banyan/bfs/conos2.db.
doserr.tra
Tellerr database containing DOS errors.
doswap
Configures swap space on the server. This is called by bmenu.
doswap.msb
Message file for doswap.
eaconv
Called during an upgrade to or a fresh installation of VINES 7.0 to convert the OS/2 Extended Attributes database.
extractlog
Extracts the log information for the specified services. This script allows you to specify a range of times and dates, as well as the services for which you want log information extracted.
floppy
Copies files to a diskette.
formatter
VINES log file report formatter.
fts
File Transfer utility. This application allows you to move files between servers, as long as both servers have an rs service running.
gdb
Symbolic debugger from the Free Software Foundation.
ld
Link editor / loader.
logex
Calls svclog to extract a log from every service on the system.
login
UNIX login utility.
logsort
Sorts the lines in a log file alphabetically.
ls
Standard UNIX System V file listing utility.
lx
Clears the screen and lists the executables in the current directory.
makelogdirs
Lists all the directories that should be searched for logs related to the specified service. This script is used by the /disk1/banyan/util/logex script.
manly
Mail database analyzer utility.
matalk
Appletalk Management utility. This is called by bmenu.
memsize
Displays the amount of available server memory on the screen.
mnet
UNIX version of the Banyan MNET utility. This utility is documented in detail in Monitoring and Optimizing Servers.
mon
Service monitor utility. Allows the user to see the service monitor screens of other servers in the network.
monitor
bmenu service monitor. Equivalent to mon - local.
more
Banyan version of the standard UNIX System V utility. This displays the contents of text files a screen at a time.
msginfo
runs manly -l on an intelligent messaging database file.
mtime
Displays the creation time of a given directory.
ofts
File Transfer Protocol utility. Equivalent to fts except that ofts does not require you to log in.
pack
Compresses a file.
paste
Standard UNIX System V command that concatenates corresponding lines of the given input files.
ping
IP ping program.
reload
Reloads VINES Files from tape or CD-ROM.
rmpatdirs
Removes Server service patch directories and files, such as /disk1/banyan/ss/patches.
rx
Used by Banyan support personnel to receive files from remote servers, using the xmodem protocol.
rz
Used by Banyan support personnel to receive files from remote servers, using the zmodem protocol.
sadc
This program is also run from VINES Assistant. It collects and formats information from the system.
sar
Statistical Analysis Reports. These reports are run from VINES Assistant.
savecore
Script is run by each Banyan service startup script to save any core files in the service directory to the cores directory of that service.
savelogs
Used by some services to move logs to a specified directory.
send
Sends a 25th-line message to a StreetTalk user.
setargs
Script that sets arguments for use by other scripts.
shutdownss
Shuts down Server service.
sort
Sorts and merges files.
strings
Extracts identifiable ASCII strings from a file and displays them on the screen.
strlen
Writes the length of the trailing string. For example, strlen hello writes "5" to standard output.
svclog
Sets the log level for the given service. (l = low, m = medium, h = most verbose).
sx
Used by Banyan support personnel to send files to remote servers, using the xmodem protocol.
sz
Used by Banyan support personnel to send files to remote servers, using the zmodem protocol.
tape
Used by Banyan Service developers to copy files to tape. This command is documented in the Banyan Service Developer's Guide.
tbantape
On a v386 server, this command backs up files to tape.
tcopy
Moves system dumps that are saved on tape to the server hard disk.
tellerr
Prints an English explanation of a Banyan error message.
timesrv
Establishes a schedule for connecting to the National Time Service over an asynchronous connection.
todos
Changes a text file from UNIX format to DOS format.
tosyslog
Writes error messages to a buffer in server memory. These messages are flushed to the server log files Server0.log and Server1.log when you shut down services and restart.
tstamp
Generates a six-digit hexadecimal number based on the system time. Usually used in scripts to create unique file names.
ttyinit
Runs getty to allow Banyan service developers to log in to a server using Asynchronous Terminal Emulation.
tzone
Sets the time zone for the server.
uconfig
A user interface to the /disk1/banyan/comm/config program.
uniq
Reports repeated lines in a text file.
uniquename
This program is used to prevent a script from trying to create a directory that already exists. It accepts a newdir string and a pathname, concatenates them, then tests for the existence of the resulting directory. If the directory already exists, it concatenates the string "01" (or 02 if pathname/newdir01 already exists) and returns the resulting directory name. For example, the command:
uniquename banyan /disk1
returns the string "/disk1/banyan01", since /disk1/banyan already exists on the server.
This program is used by the Banyan Intelligent Messaging service to create unique mailbox names for users with the same StreetTalk item name.
unixerr.tra
Tellerr database containing UNIX errors.
unvfs
Clears a bit in the inode. The bit indicates that a file is owned by VFS. Files outside of VFS should not have the bit set.
upsdelay
This script looks for the file ups.t in the root and prompts the user for any changes to it. It the uses the value in ups.t as the numeric value to patch the system shutdown delay for UPS-supported systems. The delay can be set to any value from 10 to 1800 seconds.
usl
A program that accepts the user limit for the server from the user.
vfsck
Does a complete disk analysis and format.
vfscklog
Log file for errors generated by vfsck.
vfstest
Tests many VFS interface function calls.
vnssvcdb
Prints any of the following information about a Banyan service:
Whether it is running or stopped Where the service executable is located Where the service meta-data is located Where the service data is located
vnsvdb
Prints any of the following information about the Banyan server:
The name of the server The hardware platform of the server (such as V386, PS/2, etc) The serial number of the server The name of the software product ("Classic" for VINES, "ENS W" for any other product) The software revision of the server
vping
VINES ping utility.
xlog
Generates a service log for any service running on the server. This is called from bmenu.
Troubleshooting a Banyan server is best done with the help of a qualified Banyan Support representative. This section describes a troubleshooting utility (Readcore) and other information that is useful when your server crashes.
System Crashes on PC-Based Servers
When a system crash occurs on a PC-based server, the system enters the Banyan Systems Debugger, from which you can perform the system dump. After you perform the system dump, you can reboot the server.
When the system enters the debugger, the console screen lists the contents of the CPU registers and displays the debugger's d: prompt, as in Figure 6-1:
If your server enters the system debugger, as shown in Figure 6-1, report the problem to your Banyan service representative. You may be assigned an incident number and asked to send in the system memory image dump on diskette or tape. If you are so instructed, use the procedure described below (diskette or tape).
System Debugger Commands
You can use the following five debugger commands (in lower case only) at the debugger's d: prompt:
help (or h) - Lists the debugger commands.
register - Displays the contents of the CPU registers.
reset - Resets the system for a reboot. Do not use this command if you need to capture the system memory image dump.
sysdump - Dumps the lowest 3.5 megabytes of system memory to the server's disk1.
stack - Prints the current stack traceback.
tapedump - Dumps all of system memory to tape.
Saving the System Memory Dump to Tape
Use the tapedump command to copy the system memory dump to tape. tapedump dumps the entire contents of memory, including the kernel and loadable device driver symbols.
To Write a System Dump to Tape Following a System Crash
1. When the server enters the debugger, write down any information that is displayed on the screen.
2. Insert a tape cartridge in the tape drive. Make sure the tape is not write-protected.
3. Enter tapedump (in lowercase letters). The contents of memory are written to tape.
After the memory dump, a message is displayed that tells you to not remove the tape because the system must later dump the kernel and driver symbols to that tape. Do not remove the tape from the drive.
After the tape dump, the system automatically reboots. After the drivers are loaded into the kernel as part of the reboot, the system writes the kernel and the driver symbols to tape.
4. After the system is running, remove the tape cartridge, set the write-protect switch on the tape cartridge, and label and date the tape cartridge.
5. Report the problem to your Banyan support representative. You may be asked to send in the tape.
Saving the System Memory Dump to Diskettes
The memory dump is saved during the reboot so that the dump is written to a swap area on the server disk. Some or all of the dump may be overwritten when the server resumes normal operation. For this reason, you should save the system memory dump to diskettese after you reboot the server, as explained in this sectiont.
Before you begin this procedure, you must have from five to more than twenty formatted high-density diskettes on hand, depending on the swap area size.
To Write a System Dump to Diskettes Following a System Crash
1. When the system enters the debugger, write down the information on the screen.
2. Enter sysdump to perform a system memory dump to disk. When the dump is complete, the system displays a message telling you to power off or reboot the server.
3. Power off the server, then power it on.
4. When the system begins to reboot, it examines the disks and warns you that a system image dump has been saved to disk. You are asked if you want to save the dump on diskettes.
If you answer N, the reboot continues.
If you answer Y, continue with the next step.
5. If you answered Y at step 4, the number of diskettes required is displayed. Note that you must use high-density, formatted diskettes. To continue, answer Y.
6. You are prompted for the required number of diskettes. Be sure to label the diskettes in the proper numerical sequence. After the final diskette, the reboot continues normally.
7. Report the problem to your Banyan support representative. You may be asked to send in the diskettes.
Regardless of whether you saved the memory dump, you are not prompted on subsequent reboots.
