 |
Index for
Section 8 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
chat(8)
NAME
chat - Automated conversational script with a modem
SYNOPSIS
/usr/sbin/chat [options] script
OPTIONS
-e 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.
-f chatfile
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.
-r report file
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.
-t timeout
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.
-v 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.
-V 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.
script
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 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
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 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
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
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
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 compilation
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 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
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.
\b Represents a backspace character.
\c 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.)
\d Delays for one second. The program uses the sleep command, which
will delay to a maximum of one second. (Not valid in expect.)
\K Inserts a BREAK. (Not valid in expect.)
\n Sends a newline or linefeed character.
\N Sends a null character. The same sequence may be represented by
\0. (Not valid in expect.)
\p Pauses for a fraction of a second. The delay is 1/10th of a
second. (Not valid in expect.)
\q Suppresses writing the string to the syslog file. The string ??????
is written to the log in its place. (Not valid in expect.)
\r Sends or expects a carriage return.
\s 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.
\t Sends or expects a tab character.
\\ Sends or expects a backslash character.
\ddd Collapses the octal digits (ddd) into a single ASCII character and
sends that character. (Some characters are not valid in expect.)
^C 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.
0 The normal termination of the program. This indicates that the script
was executed without error to the normal conclusion.
1 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.
2 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.
3 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.
4 The first string marked as an ABORT condition occurred.
5 The second string marked as an ABORT condition occurred.
6 The third string marked as an ABORT condition occurred.
7 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.
SEE ALSO
Commands: uucp(1), pppd(8), uucico(8)
|
Index for
Section 8 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|