Maintaining BNU

AIX Version 4.3 System Management Guide: Communications and Networks

Maintaining BNU

BNU must be maintained to work properly on your system. To maintain BNU:

Read and remove log files periodically.
Use the uuq and uustat commands to check the BNU queues to ensure jobs are transferring to remote systems properly.
Schedule automatic commands that poll remote systems for jobs, return unsent files to users, and send you periodic messages about BNU status.
Periodically update the configuration files to reflect changes in your system.

In addition, occasionally check with administrators of remote systems to keep up with changes on their systems that may affect your configuration. For example, if the supervisor of system venus changes your system's password, you will need to put the new password in the /etc/uucp/Systems file (or the appropriate Systems file specified by /etc/uucp/Sysfiles) before your system can log in to system venus.

See BNU Files, Commands, and Directories Reference for a list of commands used to maintain BNU.

Working with BNU Log Files

BNU creates log files and error files to track its own activities. These files must be checked and removed periodically to keep them from filling the storage space on your system. BNU provides several commands for use in cleaning log files:

uulog
uuclean
uucleanup
uudemon.cleanu

Run these commands manually or use entries in the /var/spool/cron/crontabs/uucp file to run the commands by the cron daemon.

Log Files in the .Log and .Old Directories

BNU creates individual log files in the /var/spool/uucp/.Log directory. BNU creates these log files for each accessible remote system, using the uucp, uuto, or uux command. BNU places status information about each transaction in the appropriate log file each time someone on the system uses BNU. When more than one BNU process is running the system cannot access the log file. Instead, it places the status information in a separate file with a .LOG prefix.

The uulog command displays a summary of uucp or uux requests, by user or by system. The uulog command displays the files. However, you can also have BNU automatically combine the log files into a primary log file. This is called compacting the log files and can be done with the uudemon.cleanu command, usually run by the cron daemon.

The cron daemon runs the uudemon.cleanu command. The uudemon.cleanu command combines the uucico and uuxqt log files on the local system and stores them in the /var/spool/uucp/.Old directory. At the same time, the command removes old log files previously stored in the .Old directory. By default, the uudemon.cleanu command saves log files that are two days old.

If storage space is a problem, consider reducing the number of days that files are kept. To track BNU transactions over a longer period of time, consider increasing the number of days that files are kept. To change the default time for saving log files, modify the shell procedure for the uudemon.cleanu command. This script is stored in the /usr/sbin/uucp directory and can be modified with root authority.

Other BNU Log Files

BNU also collects information and stores it in the /var/spool/uucp/.Admin directory. This directory contains the errors, xferstats, Foreign, and audit files. These files must be checked and removed occasionally to save storage space. BNU creates each file when it is needed.

When another system contacts your system with the uucico daemon's debugging mode on, it invokes the uucico daemon on your system with debugging turned on. The debugging messages generated by the daemon on the local system are stored in the audit file. This file can get quite large. Check and remove the audit file often.

The errors file records errors encountered by the uucico daemon. Checking this file can help you correct problems such as incorrect permissions on BNU work files.

The xferstats file contains information about the status of every file transfer. Check and remove this file occasionally.

The Foreign file is important to the security of your system. Whenever an unknown system attempts to log in to the local system, BNU calls the remote.unknown shell procedure. This shell procedure logs the attempt in the Foreign file. The Foreign file contains the names of the systems that have attempted to call the local system and been refused. If a system has been attempting frequent calls, use this information when considering whether to allow that system access.

Systemwide Log Files used by BNU

Because many BNU processes need root authority to complete their tasks, BNU creates frequent entries in the /var/spool/sulog log file. Similarly, using the cron daemon to schedule BNU tasks creates multiple entries in the /var/spool/cron/log file. When using BNU, check and clean these files.

BNU Maintenance Commands

The Basic Networking Utilities contain several commands for monitoring BNU activities and cleaning BNU directories and files.

Cleanup Commands

BNU contains three commands that clean directories and remove files that have not been sent:

uuclean	Deletes all files older than a specified number of hours, from the BNU administrative directories. Use the uuclean command to specify a directory to be cleaned or a type of file to be deleted. You can also instruct the command to notify the owners of the deleted files. The uuclean command is the Berkeley equivalent of the uucleanup command.
uucleanup	Performs functions similar to the uuclean command. However, the uucleanup command checks the age of files based on days rather than hours. Use the uucleanup command to send a warning message to users whose files have not been transferred, notifying them that the files are still in the queue. The uucleanup command also removes files relating to a specified remote system.
uudemon.cleanu	A shell procedure that issues the uulog and uucleanup commands to compress the BNU log files and remove log and work files over three days old. The uudemon.cleanu command is run by the cron daemon.

Status-checking Commands

BNU also provides commands for checking the status of transfers and log files:

uuq	Displays jobs currently in the BNU job queue. Use the uuq command to display the status of a specified job or of all jobs. With root authority, you can use the uuq command to delete a job from the queue.
uustat	Provides information similar to that provided by the uuq command, in a different format. Use the uustat to check the status of jobs and delete jobs you own. With root authority, you can also delete jobs belonging to other users.
uulog	Displays a summary of uucp or uux requests, by user or by system. The uulog command displays the file names. See "Working with BNU Log Files".
uupoll	Forces a poll of a remote system. This is helpful when work for that system is waiting in the queue and needs to be transferred, before the system is scheduled to be called automatically.
uusnap	Displays a very brief summary of BNU status. For each remote system, this command shows the number of files awaiting transfer. However, it does not show how long they have been waiting. The uusnap command is the Berkeley equivalent of the uustat command.

Shell Procedures

BNU is delivered with two shell procedures used for maintenance:

uudemon.cleanu	Discussed under "Cleanup Commands".
uudemon.admin	Issues the uustat command The uustat command reports the status of BNU jobs. It sends the results to the uucp login ID as mail. You can modify the uudemon.admin shell procedure to send the mail elsewhere, or use a mail program to reroute all mail for the uucp login ID to the user responsible for BNU administration.

These shell procedures are stored in the /usr/sbin/uucp directory. Copy the procedures and modify the copy, if you want to change what they do. Run the procedures from the command line or schedule them to be run by the cron daemon.

To automatically run the uudemon.cleanu and uudemon.admin commands, remove the comment characters (#) from the beginning of the relevant lines in the /var/spool/cron/crontabs/uucp file.

Monitoring a BNU Remote Connection

Prerequisites

The BNU program must be installed on your system.
A link (hardwired, modem, or TCP/IP) must be set up between your system and the remote system.
The BNU configuration files, including the Systems file, Permissions file, Devices file, and Dialers file (and Sysfiles file, if applicable), must be set up for communications between your system and the remote system.
Note: You must have root user authority to modify the BNU configuration files.

Procedure

The Uutry command can help you monitor the uucico daemon process if users at your site report file-transfer problems.

Issue the uustat command to determine the status of all the transfer jobs in the current queue as follows:
```
uustat -q
```
The system displays a status report like the following:
```
venus 3C (2) 05/09-11:02 CAN'T ACCESS DEVICE
hera 1C 05/09-11:12 SUCCESSFUL
merlin 2C 5/09-10:54 NO DEVICES AVAILABLE
```
This report indicates that three command (C.*) files intended for remote system venus have been in the queue for two days. There could be several reasons for this delay. For example, perhaps system venus has been shut down for maintenance or the modem has been turned off.
Before you begin more extensive troubleshooting activities, issue the Uutry command as follows to determine whether your local system can contact system venus now:
```
/usr/sbin/uucp/Uutry -r venus
```
This command starts the uucico daemon with a moderate amount of debugging and the instruction to override the default retry time. The Uutry command directs the debugging output to a temporary file, /tmp/venus.
If your local system succeeds in establishing a connection to system venus, the debugging output contains a good deal of information. However, the final line in this script, which follows, is the most important:
```
Conversation Complete: Status SUCCEEDED
```
If the connection is successful, assume that the temporary file-transfer problems are now resolved. Issue the uustat command again to make certain that the files in the spooling directory have been transferred successfully to the remote system. If they have not, use the steps in "Monitoring a BNU File Transfer" to check for file-transfer problems between your system and the remote system.
If your local system cannot contact the remote system, the debugging output generated by the Uutry command contains the following type of information (the exact form of the output may vary):
```
mchFind called (venus)
conn (venus)
getto ret -1
Call Failed: CAN'T ACCESS DEVICE
exit code 101
Conversation Complete: Status FAILED
```
First, check the physical connections between the local and remote systems. Make sure that the remote computer is turned on and all cables are properly connected, that the ports are enabled or disabled (as appropriate) on both systems, and that the modems (if applicable) are working.
If the physical connections are correct and secure, then verify all the relevant configuration files on both the local and remote systems, including the following:
- Make certain that the entries in the Devices, Systems, and Permissions files (and Sysfiles file, if applicable) in the /etc/uucp directory are correct on both systems.
- If you are using a modem, make sure that the /etc/uucp/Dialers file (or an alternate file specified in /etc/uucp/Sysfiles) contains the proper entry. If you are using dial-code abbreviations, be sure the abbreviations are defined in the /etc/uucp/Dialcodes file.
- If you are using a TCP/IP connection, make sure that the uucpd daemon can be run on the remote system and that the configuration files contain the correct TCP entries.
Once you have checked the physical connections and configuration files, issue the Uutry command again. If the debugging output still reports that the connection failed, you may need to confer with a member of your systems support team. Save the debugging output produced by the Uutry command. This may prove helpful in diagnosing the problem.

Monitoring a BNU File Transfer

Prerequisites

The BNU program must be installed on and configured for your system.
Establish a connection to a remote system using the steps given in "Monitoring a BNU Remote Connection".

Monitoring a File Transfer

Use this procedure to monitor a file transfer to a remote system. Monitoring a file transfer is useful when file transfers to the remote system in question are failing for unknown reasons. The debugging information produced by the uucico daemon (called by the Uutry command) can help you find out what is working incorrectly.

The Uutry command enables you to monitor file transfers, as follows:

Prepare a file for transfer using the uucp command with the -r flag by entering:
```
uucp -r test1 venus!~/test2
```
The -r flag instructs the BNU program to place the test1 file in the queue but not to start the uucico daemon.
Issue the Uutry command with the -r flag to start the uucico daemon with debugging turned on by entering:
```
/usr/sbin/uucp/Uutry -r venus
```
This instructs the uucico daemon to contact remote system venus overriding the default retry time. The daemon contacts system venus, logs in, and transfers the file, while the Uutry command produces debugging output that enables you to monitor the uucico process. Press the Interrupt key sequence to stop the debugging output and return to the command prompt.
The Uutry command also stores the debugging output in the /tmp/SystemName file. If you break out of the debugging output before the connection is complete, you can page through the output file to see the outcome of the connection.

Debugging BNU Problems

BNU error messages can be linked to a specific phase in the conversation flow. Use the BNU Conversation Flow Diagram and the following error descriptions to help diagnose your BNU problems. Some of the following messages may not be sent from BNU, but are included in case another uucp version is in use.

PHASE 1 Status Messages

`Assert Error`	The local system unit is having problems. Check the error report for possible causes by issuing the command errpt -a \| pg.
`System not in Systems`	If you supply a remote system name that is not found in the Systems files, this status message is created. BNU will terminate. Use the uuname command to check the system name again.
`Wrong time to call`	The Systems file has restrictions on times to allow outgoing calls. BNU will keep trying until the time is right. Check the Systems file.
`Callback required`	The network has restricted usage either for security or economic reasons, and access is denied at this time.
`Cannot call` `No Call`	These errors mean BNU recently tried to call the remote system and failed. It will not immediately try again. They can also be caused by an old system status file being retained thus keeping uucico from trying again.

PHASE 2 Status Messages

`Dialer Script Failed`	Your Dialers file script did not complete successfully.
`No Device Available` `Can't Access Device`	The modem or the outgoing phone line from your system is busy. Check for an error in the device entry of the Systems file. Also, check the Devices and Dialers files to be sure logical devices have physical devices associated with them. The file /etc/uucp/Sysfiles may be specifying an alternate Systems, Devices, or Dialers file that is not correctly configured. Is the device in use by some other program? Check the /etc/locks directory for lock on port. If a lock file exists (for example, LCK..TTY0), check to see if the process identified by the number in the lock file is still active. If not, you can remove it (for example, `rm /etc/locks/LCK..TTY0` ). Also check the permissions on the port.
`Dial Failed` `Failed (call to system)`	These errors appear when your system dials another successfully but the other system does not answer. It may also indicate a problem in the Devices files. Enter the command `uucico -r1 -x6 -s SystemName`. It could be that BNU is expecting some string that it is not receiving. Make the connection by hand to find out what needs to be incorporated into the Systems files entry to satisfy the request. Please keep "timing" in mind; perhaps some delays in the modem's dial string are needed. This could also mean that the port is busy, you dialed an incorrect number, or BNU lost ownership of the port.
`OK` `Auto Dial`	These are informative messages only and do not indicate an error.

PHASE 3 Status Messages

`Handshake Failed (LCK)`	The device is being used by someone else; the process could not create the LCK file. Sometimes LCK files must be manually removed by the administrator. After a number of retries, see your system administrator. See if another process has control of the port (for example, another instance of uucico).
`Login Failed`	The login failed due to a bad connection or possibly a slow machine.
`Timeout`	The remote system did not respond within a set period of time. This could also indicate a problem with the chat script.
`Succeeded (Call to System)`	The call was completed.
`BNU (continued)`	These are informative messages only and do not indicate an error.

PHASE 4 Status Messages

`Startup Failed` `Remote reject after login`	After login, uucico is started on the remote system. If there is a problem initiating a conversation between the two systems, these messages are created. You may have also logged into the incorrect BNU account or the initial handshake failed.
`Wrong machine name`	A machine was called incorrectly or the machine's name was changed.
`Bad login/machine combination`	The login to the remote system failed. The problem could be an incorrect phone number, an incorrect login or password, or an error in the chat script.
`Remote has a LCK file for me`	Both systems were simultaneously trying to call each other. The local request will fail temporarily.
`OK` `Talking`	These are informative messages only and do not indicate an error.
`LOGIN:` `PASSWORD:`	If the login or password prompt is in all capital letters, the modem may be in echo mode (E1 on Hayes compatibles). This causes the modem to echo back, or send, a RING to your system when an incoming call is received. The getty command receives the string and accordingly changes the `login:` or `password:` into all caps. Change the echo mode on the modem to off (use `ATE0` for Hayes compatibles). Note: Keep in mind that once this change is made, you should use `ATE1` in the chat script of your Dialers files, or you will not get the expected `OK` back from the modem. If the remote port is set for `delay` or `getty -r` and the chat script expects key input, then the ports set for `delay` are expecting one or more carriage returns before proceeding with the login. Try beginning the chat script on the dialing system with the following: "" \r\d\r\d\r\d\r in:--in: ... Interpreted, the above reads as follows: expect nothing, send return, delay, return, delay, return, delay, return.

PHASE 5 Status Messages

`Alarm`	uucico is having trouble with the connection. Either the connection is bad or "xon/xoff" is set to yes on the modem.
`Remote access to path/file denied` `copy (failed)`	These messages indicate a permission problem; check file and path permissions.
`Bad read`	The remote system ran out of space, most likely in the spool area, or uucico could not read or write to device.
`Conversation failed`	The modem's carrier detect was lost. Possibly the modem was turned off, the cable is loose or disconnected, or the remote system crashed or is shut down. Telephone disconnection can also cause this error.
`Requested` `Copy (succeeded)`	These are informative messages only and do not indicate an error.

PHASE 6 Status Messages

`OK (Conversation Complete)`	The remote system can deny the hangup request and reverse the roles (meaning the remote system has work for the local system to do). Once the two uucicos agree that no more work exists, they hang up.
`Conversation succeeded`	This is an informative message only and does not indicate an error.

Debugging BNU Login Failures Using the uucico Daemon

Prerequisites

BNU must be installed on your system.
A link (hardwired, modem, or TCP/IP) must be set up between your system and the remote system.
The BNU configuration files, including the Sysfiles file (if applicable), the Systems file, Permissions file, Devices file, and Dialers file, must be set up for communications between your system and the remote system.
Note: You must have root user authority to modify the BNU configuration files.
You must have root user authority to invoke the uucico daemon in debugging mode.

Procedure

To produce debugging information about a local-to-remote system connection that is not working, start the uucico daemon with the -x flag as follows:
```
/usr/sbin/uucp/uucico -r 1 -s venus -x 9
```
where -r 1 specifies the master, or caller mode; -s venus, the name of the remote system to which you are trying to connect; and -x 9, the debug level that produces the most detailed debugging information.

If the expect-send sequence entry in a Systems file in the format of /etc/uucp/Systems is:

venus Any venus 1200 - "" \n in:--in: uucp1 word:
 mirror

the uucico daemon connects the local system to the remote system venus. The debugging output is similar to:

expect: ""
got it
sendthem (^J^M)
expect (in:)^
M^Jlogin:got it
sendthem (uucp1^M)
expect (word:)^
M^JPassword:got it
sendthem (mirror^M)
imsg >^M^J^PShere^@Login Successful: System=venus

where:

`expect: ""`
	Specifies that the local system will not wait for any information from the remote system.
`got it`
	Acknowledges that the message has been received.
`sendthem (^J^M)`
	Specifies that the local system will send the remote system a carriage return and a new line.
`expect (in:)`
	Specifies that the local system will expect to receive the remote system login prompt, which ends in the `in:` character string.
`^M^Jlogin:got it`
	Confirms that the local system will receive the remote login prompt.
`sendthem (uucp1^M)`
	Specifies that the local system will send the `uucp1` login ID to the remote system.
`expect (word:)`
	Specifies that the local system will expect to receive the remote system password prompt, which ends in the `word:` character string.
`^M^JPassword:got it`
	Confirms the local system will receive the remote password prompt.
`sendthem (mirror^M)`
	Specifies that the local system will send the password for the `uucp1` login ID to the remote system.
`imsg >^M^J^PShere^@Login Successful: System=venus`
	Confirms the local system is successfully logged in to remote system `venus`.

Notes:
The expect-send debugging output produced by the uucico command can come either from information in the /etc/uucp/Dialers file or from information in the /etc/uucp/Systems file. Information about communication with the modem comes from the Dialers file, while information about communication with the remote system comes from the Systems file. (Note that /etc/uucp/Systems and /etc/uucp/Dialers are default BNU configuration files. Other files can be specified in /etc/uucp/Sysfiles to serve the same role.)

To set up a connection with a remote system, you must be familiar with the login sequence of that system.

Contacting Connected UNIX Systems Using the tip Command

Use the tip command to contact any connected system running the UNIX operating system. The tip command is installed with the Basic Networking Utilities (BNU) and can use the same asynchronous connections used by BNU.

The tip command uses variables and escape signals, as well as flags, to control its operations. The flags can be entered at the command line. The escape signals can be used over a connection with a remote system to start and stop file transfers, change the direction of a file transfer, and exit to a subshell.

tip Command Variables

The tip command variables define settings such as the end-of-line character, the break signal, and the mode of file transfers. Variable settings can be initialized at run time using a .tiprc file. Variable settings can also be changed during execution using the ~s escape signal. Some variables, such as the end-of-line character, can be set for an individual system in that system's entry in the remote file.

The tip command reads three files, the phones file, remote file, and .tiprc file, to determine initial settings for its variables. The .tiprc file must always be in the user's home directory. The names and locations of the remote and phones files can vary. The names of the remote file and the phones file can be determined by environment variables:

PHONES	Specifies the name of the user's phone file. The file can have any valid file name and must be set up in the format of the file /usr/lib/phones-file. The default file is etc/phones. If a file is specified with the PHONES variable, it is used in place of (not in addition to) the /etc/phones file.
REMOTE	Specifies the name of the user's remote system definition file. The file can have any valid file name and must be set up in the format of the /usr/lib/remote-file file. The default file is /etc/remote. If a file is specified with the REMOTE variable, it is used in place of (not in addition to) the /etc/remote file.

To use an environment variable, set it before starting the tip command. As an alternative, the names of the phones and remote files can be determined using the tip command phones variable and remote variable, respectively, in the .tiprc file.

Note: The tip command reads only the last remote or phones file specified. Thus, if you specify a remote or phones file with a variable, the new file is used in place of (not in addition to) any previous files you specified.

The tip command uses variable settings in the following order:

The command checks the settings of the PHONES and REMOTE environment variables for the files to use as the phones and remote files.
The command reads the .tiprc file and sets all variables accordingly. If the phones or remote variable is set in the .tiprc file, this setting overrides the environment variable setting.
When a connection to a remote system is initiated, the command reads the remote file entry for that system. The settings in the remote file entry override settings made in the .tiprc file.
If the -BaudRate flag is used with the tip command, the specified rate overrides all previous baud rate settings.
A setting made with the ~s escape signal overrides all previous settings of a variable.
Note: Any tip user can create a .tiprc file and use this file to specify initial settings for tip variables. The .tiprc file must be placed in the user's $HOME directory.

tip Command Configuration Files

Before the tip command can connect to a remote system, the /etc/remote and /etc/phones files must be established.

/etc/remote	Defines attributes of remote systems such as the port and type of device to use to reach the system, as well as the signals to use to indicate the beginnings and endings of transmissions.
/etc/phones	Lists telephone numbers used to contact remote systems over a modem line.

To establish one of these files, copy a sample file to the correct name and modify it to suit the needs of your site. Sample remote and phones files are delivered with the bos.net.uucp package. The sample remote file is named /usr/lib/remote-file. The sample phones file is named /usr/lib/phones-file.

Note: You must have root authority to create files in the /usr/lib directory.

A tip user can also create customized remote and phones files. An individual remote file must be in the format of the /usr/lib/remote-file file and specified with the remote variable or the REMOTE environment variable. An individual phones file must be in the format of the /usr/lib/phones-file file and specified with the phones variable or the PHONES environment variable. If an individual phones or remote file is specified with one of the variables, that file is read in place of (not in addition to) the /etc/phones or /etc/remote file.

Users of tip can use combinations of individual phones and remote files. For example, a user could read the default remote file, /usr/lib/remote-file, but use an individual phones file named with the phones variable.