Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

chat(8) [osf1 man page]

chat(8) 						      System Manager's Manual							   chat(8)

chat - Automated conversational script with a modem SYNOPSIS
/usr/sbin/chat [options] script OPTIONS
Start with the echo option turned on. Echoing may also be turned on or off at specific points in the chat script by using the ECHO keyword. When echoing is enabled, all output from the modem is echoed to standard error. Reads the chat script from the chatfile. The use of this option is mutually exclusive with the chat script parameters. The user must have read access to the file. Multiple lines are permitted in the file. Space or horizontal tab characters should be used to separate the strings. Set the file for output of the report strings. If you use the keyword REPORT, the resulting strings are written to this file. If this option is not used and you still use REPORT keywords, the standard error file is used for the report strings. Sets the timeout for the expected string to be received. If the string is not received within the time limit, the reply string is not sent. An alternate reply may be sent or the script will fail if there is no alter- nate reply string. A failed script causes the chat program to terminate with a nonzero error code. Requests that the chat script be exe- cuted in a verbose mode. The chat program logs all text received from the modem and the output strings that it sends to the syslog com- mand. Requests that the chat script be executed in a standard error verbose mode. The chat program then logs all text received from the modem and the output strings which it sends to the standard error device. This device is usually the local console at the station running the chat or pppd program. This option does not work properly if the standard error is redirected to the /dev/null location as is the case when pppd runs in the detached mode. In that case, use the -v option to record the session on the SYSLOG device. If the script is not specified in a file with the -f option then the script is included as parameters to the chat program. DESCRIPTION
The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to establish the connection between the Point-to-Point Protocol Daemon (pppd) and the pppd process of the remote system. CHAT SCRIPT The chat script defines the communications between the local system and a remote system. A script consists of one or more "expect-send" pairs of strings, separated by spaces, with an optional "subexpect-subsend" string pair, separated by a dash as in the following example: ogin:-BREAK-ogin: ppp ssword: hello2u2 In the previous example, the chat program expects the string "ogin:". If it fails to receive a login prompt within the time interval allotted, the chat program sends a break sequence to the remote system, and then expects to receive the string "ogin:". If the first "ogin:" is received, the break sequence is not generated. Once it receives the login prompt, the chat program sends the string ppp, and expects to receive the "ssword:" prompt. When prompted for the password, it sends the password hello2u2. A carriage return is normally sent following the reply string. It is not expected in the "expect" string unless it is requested by speci- fying the escape sequence. The expect sequence should contain only the information needed to identify the string. Since it is normally stored on a disk file, it should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, or other variable pieces of data as an expect string. The leading "l" character may be received in error and you may never find the string even though it was sent by the system. For this rea- son, scripts look for "ogin:" rather than "login:" and "ssword:" rather than "password:". A very simple script is as follows: ogin: ppp ssword: hello2u2 In other words, expect ogin:, send ppp, expect ssword:, send hello2u2. In practice, simple scripts are rare. At the very least, you should include subexpect sequences in case the original string is not received, as in the following script: ogin:--ogin: ppp ssword: hello2u2 The preceding script is better than the simple one used earlier. This looks for the same login: prompt, but if one is not received, it sends a single return sequence and looks for login: again. If line noise obscures the first login prompt, sending an empty line usually generates a login prompt again. COMMENTS Comments can be embedded in the chat script by beginning a line with the number (#) character in column 1. Such comment lines are ignored by the chat program. If a number (#) character is expected as the first character of the expect sequence, you should quote the expect string. If you want to wait for a prompt that starts with a number (#) character, enter a text string similar to the following: # Now wait for the prompt and send logout string '# ' logout ABORT STRINGS Many modems report the status of the call as one of the following strings: CONNECTED, NO CARRIER, or BUSY. It is often desirable to termi- nate the script if the modem fails to connect to the remote system. The difficulty is that a script does not know which modem string it might receive. On one attempt, it might receive BUSY while the next time it might receive NO CARRIER. These abort strings may be specified in the script using the ABORT sequence as shown in the following example: ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT Using this sequence, the chat program expects nothing, sends the string ATZ, and then expects the string OK. When it receives OK, the pro- gram sends the string ATDT5551212 to dial the telephone, and expects the string CONNECT. If the string CONNECT is received, the remainder of the script is executed. If the telephone is busy, the modem sends the string BUSY. This causes the string to match the abort character sequence, and the script fails because it found a match to the abort string. If it receives the NO CARRIER string, it aborts for the same reason. Either string terminates the chat script. CLR_ABORT STRINGS This sequence allows for clearing previously set ABORT strings. The ABORT strings are kept in an array of a predetermined size (at compila- tion time); CLR_ABORT reclaims the space for cleared entries so that new strings can use that space. SAY STRINGS The SAY directive allows the script to send strings to the user at the terminal via standard error. If the chat program is being run by pppd, and pppd is running as a daemon (detached from its controlling terminal), standard error will normally be redirected to the /etc/ppp/connect-errors file. The SAY strings must be enclosed in single or double quotes. If carriage return and line feed characters are needed in the string to be output, you must explicitly add them to your string. The SAY strings could be used to give progress messages in sections of the script where you want to have `ECHO OFF' but still let the user know what is happening, for example: ABORT BUSY ECHO OFF SAY "Dialing your ISP... " '' ATDT5551212 TIMEOUT 120 SAY "Waiting up to 2 minutes for connection ... " CONNECT '' SAY "Connected, now logging in ...0" ogin: account ssword: pass $ SAY "Logged in OK ...0" etc ... This sequence presents the SAY strings to the user; details of the script remain hidden. For example, if the above script works, the fol- lowing information is displayed. Dialing your ISP... Waiting up to 2 minutes for connection ... Connected, now logging in ... Logged in OK ... REPORT STRINGS A REPORT string is different from the ABORT string in that the strings, and all characters to the next control character such as a carriage return, are written to the report file. The REPORT strings may be used to isolate the transmission rate of the modem's connect string and return the value to the chat user. The analysis of the report string logic occurs in conjunction with other string processing, such as looking for the expect string. The use of the same string for a report and abort sequence is probably not useful, but it is possible. The REPORT strings do not change the completion code of the program. You can specify these report strings in the script using the REPORT sequence, as shown in the following example: REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account Using this sequence the chat program expects nothing, sends the string ATDT5551212 to dial the telephone, and expects the string CONNECT. If the CONNECT string is received, the remainder of the script executes. In addition, the program writes to the expect-file the CONNECT string plus any characters, such as the connection rate which follow it. CLR_REPORT STRINGS This sequence allows for clearing previously set REPORT strings. The REPORT strings are kept in an array of a predetermined size (at com- pilation time); CLR_REPORT reclaims the space for cleared entries so that new strings can use that space. ECHO The echo option controls whether the output from the modem is echoed to standard error. This option may be set with the -e option, but it can also be controlled by the ECHO keyword. The expect-send pair ECHO ON enables echoing, and ECHO OFF disables it. With this keyword you can select which parts of the conversation should be visible. For instance, with the following script, all output resulting from modem configuration and dialing is not visible, but starting with the CONNECT (or BUSY) message, everything is echoed. ABORT 'BUSY' .br ABORT 'NO CARRIER' .br .br '' ATZ .br OK ATD1234567 .br c .br ECHO ON .br CONNECT c .br ogin: account HANGUP The HANGUP option controls whether a modem hangup is considered as an error or not. This option is useful in scripts to dial systems that hang up and call your system back. The HANGUP options can be ON or OFF. When HANGUP is set OFF and the modem hangs up (for example, after the first stage of logging in to a callback system), chat continues running the script (for example, waiting for the incoming call and sec- ond stage login prompt). When the incoming call connects, you should use the HANGUP ON directive to reinstall normal hang up signal behav- ior, as shown in the following example: ABORT 'BUSY' '' ATZ OK ATD1234567 c CONNECT c 'Callback login:' call_back_ID HANGUP OFF ABORT "Bad Login" 'Callback Password:' Call_back_password TIMEOUT 120 CONNECT c HANGUP ON ABORT "NO CARRIER" ogin:--BREAK--ogin: real_account etc ... TIMEOUT The initial timeout value of 45 seconds can be changed by using the -t timeout option, for example: ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2 This sequence changes the timeout to 10 seconds when it expects the login: prompt, then changes the timeout to 5 seconds when it looks for the password prompt. The timeout, once changed, remains in effect until it is changed again. SENDING EOT The special reply string of EOT indicates that the chat program should send an EOT character to the remote system. This is normally the End-of-file character sequence. A return character is not sent following the EOT. The EOT sequence may be embedded into the send string using the sequence ^D. GENERATING BREAK The BREAK reply string causes a break condition to be sent. The break is a special signal on the transmitter. The normal processing on the receiver is to change the transmission rate. It may be used to cycle through the available transmission rates on the remote system until you are able to receive a valid login prompt. You can embed the break sequence into the send string by using the K escape sequence. ESCAPE SEQUENCES The expect and reply strings may contain escape sequences. All of the sequences are valid in the reply string; many are legal in the expect string. Those sequences which are not valid in the expect string are so indicated. Expects or sends a null string. If you send a null string then it will still send the return character. This sequence may either be a pair of apostrophe or quote characters. Represents a backspace character. Suppresses the newline at the end of the reply string. This is the only means of sending a string without a trail- ing return character. It must be at the end of the send string. For example, the sequence helloc will send the characters h, e, l, l, o. (Not valid in expect.) Delays for one second. The program uses the sleep command, which will delay to a maximum of one second. (Not valid in expect.) Inserts a BREAK. (Not valid in expect.) Sends a newline or linefeed character. Sends a null character. The same sequence may be represented by . (Not valid in expect.) Pauses for a fraction of a second. The delay is 1/10th of a second. (Not valid in expect.) Suppresses writing the string to the syslog file. The string ?????? is written to the log in its place. (Not valid in expect.) Sends or expects a carriage return. Represents a space character in the string. Use this when it is not desirable to quote the strings that contain spaces. The sequence `HI TIM' and HIsTIM are the same. Sends or expects a tab character. Sends or expects a backslash char- acter. Collapses the octal digits (ddd) into a single ASCII character and sends that character. (Some characters are not valid in expect.) Substitutes the sequence with the control character represented by C. For example, the character DC1 (17) is shown as ^Q. (Some characters are not valid in expect.) EXIT STATUS
The chat program terminates with the following completion codes. The normal termination of the program. This indicates that the script was executed without error to the normal conclusion. One or more of the parameters are invalid or an expect string was too large for the internal buffers. This indicates that the program as not properly executed. An error occurred during the execution of the program. This may be due to failure of a read or write operation or chat receiving a signal such as SIGINT. A timeout event occurred due to an expect string without a -subsend string. This may mean that you did not program the script correctly for the condition or that some unexpected event occurred and the expected string was not found. The first string marked as an ABORT condition occurred. The second string marked as an ABORT condition occurred. The third string marked as an ABORT condition occurred. The fourth string marked as an ABORT condition occurred. The other termination codes are also strings marked as an ABORT condition. You can use the termination code to determine which event terminated the script. It is possible to decide if the string "BUSY" was received from the modem as opposed to "NO DIAL TONE". While the first event may be retried, the second will probably have little chance of succeed- ing during a retry. SEE ALSO
Commands: uucp(1), pppd(8), uucico(8) chat(8)
Man Page