chat(8)chat(8)NAMEchat - 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 stan‐
dard 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 alternate reply string.
A failed script causes the chat program to terminate with a nonzero
error code. Requests that the chat script be executed in a verbose
mode. The chat program logs all text received from the modem and the
output strings that it sends to the syslog command. Requests that the
chat script be executed in a standard error verbose mode. The chat pro‐
gram 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 SYS‐
LOG 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 allot‐
ted, 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 specify‐
ing the \r escape sequence.
The expect sequence should contain only the information needed to iden‐
tify 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 vari‐
able 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 gener‐
ates 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 (#) charac‐
ter, 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 ter‐
minate 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 program
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 termi‐
nates 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 termi‐
nal), standard error will normally be redirected to the /etc/ppp/con‐
nect-errors file.
The SAY strings must be enclosed in single or double quotes. If car‐
riage 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...\n"
'' 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 anal‐
ysis 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 compi‐
lation 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\r\n
ATD1234567 .br \r\n \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\r\n ATD1234567
\r\n \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 trailing
return character. It must be at the end of the send string. For exam‐
ple, the sequence hello\c 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 \0. (Not valid in expect.) Pauses for a fraction of a
second. The delay is 1/10th of a second. (Not valid in expect.) Sup‐
presses 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 HI\sTIM are the same. Sends or
expects a tab character. Sends or expects a backslash character. Col‐
lapses 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 inter‐
nal 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 cor‐
rectly 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 termi‐
nation 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 succeeding
during a retry.
SEE ALSO
Commands: uucp(1), pppd(8), uucico(8)chat(8)