chat - Automated conversational script with a modem
/usr/sbin/chat [options] script
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 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 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.
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 [Toc] [Back]
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 specifying the \r 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 reason, 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 [Toc] [Back]
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 [Toc] [Back]
Many modems report the status of the call as one of the
following strings: CONNECTED, NO CARRIER, or BUSY. It is
often desirable to terminate 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 terminates
the chat script.
CLR_ABORT STRINGS [Toc] [Back]
This sequence allows for clearing previously set ABORT
strings. The ABORT strings are kept in an array of a predetermined
size (at compilation time); CLR_ABORT reclaims
the space for cleared entries so that new strings can use
that space.
SAY STRINGS [Toc] [Back]
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...\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 following information is displayed.
Dialing your ISP...
Waiting up to 2 minutes for connection ... Connected, now
logging in ...
Logged in OK ...
REPORT STRINGS [Toc] [Back]
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 [Toc] [Back]
This sequence allows for clearing previously set REPORT
strings. The REPORT strings are kept in an array of a
predetermined size (at compilation time); CLR_REPORT
reclaims the space for cleared entries so that new strings
can use that space.
ECHO [Toc] [Back]
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 [Toc] [Back]
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 second stage login prompt). When the
incoming call connects, you should use the HANGUP ON
directive to reinstall normal hang up signal behavior, 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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 example, 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.) 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
HI\sTIM are the same. Sends or expects a tab character.
Sends or expects a backslash character. 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.)
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 succeeding during
a retry.
Commands: uucp(1), pppd(8), uucico(8)
chat(8)
[ Back ] |
