NAME
chat - Automated conversational script with a modem

SYNOPSIS
chat [ options ] script

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 remote’s pppd process.

OPTIONS
-f <chat file>
Read the chat script from the chat file. 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.

-l <lock file>
Perform the UUCP style locking using the indicated lock file.

If the file could not be created then the chat program will
fail. The lock file will be deleted only if the chat program
fails to perform the script for any reason. If the script is
successful the lock file will be left on the disk. It is
expected that the lock file will be deleted when the pppd
process no longer wishes to use the serial device.

The use of a lock file with chat and pppd’s lock option should
not be used at the same time. They are mutually exclusive
options and will cause one or the other program to fail to
achieve the required lock if you use both.

-t <timeout>
Set the timeout for the expected string to be received. If the
string is not received within the time limit then 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 will cause the chat program to terminate with a
non-zero error code.

-v Request that the chat script be executed in a verbose mode.
The chat program will then log all text received from the
modem and the output strings which it sends to the SYSLOG.

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.

CHAT SCRIPT
The chat script defines the communications.

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

This line indicates that the chat program should expect the string
"ogin:". If it fails to receive a login prompt within the time
interval allotted, it is to send a break sequence to the remote and
then expect the string "ogin:". If the first "ogin:" is received
then the break sequence is not generated.

Once it received the login prompt the chat program will send the
string ppp and then expect the prompt "ssword:". When it receives
the prompt for the password, it will send the password hello2u2.

A carriage return is normally sent following the reply string. It
is not expected in the "expect" string unless it is specifically character sequence.
requested by using the

The expect sequence should contain only what is 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.

To help correct for characters which may be corrupted during the
initial sequence, look for the string "ogin:" rather than "login:".
It is possible that 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 might look like this:

ogin: ppp ssword: hello2u2

In other words, expect ....ogin:, send ppp, expect ...ssword:, send
hello2u2.

In actual practice, simple scripts are rare. At the vary least, you
should include sub-expect sequences should the original string not
be received. For example, consider the following script:

ogin:--ogin: ppp ssowrd: hello2u2

This would be a better script than the simple one used earlier.
This would look for the same login: prompt, however, if one was not
received, a single return sequence is sent and then it will look
for login: again. Should line noise obscure the first login prompt
then sending the empty line will usually generate a login prompt
again.

ABORT STRINGS
Many modems will report the status of the call as a string. These
strings may be CONNECTED or NO CARRIER or BUSY. It is often
desirable to terminate the script should the modem fail to connect
to the remote. The difficulty is that a script would not know
exactly which modem string it may receive. On one attempt, it may
receive BUSY while the next time it may receive NO CARRIER.

These "abort" strings may be specified in the script using the
ABORT sequence. It is written in the script as in the following
example:

ABORT BUSY ABORT ’NO CARRIER’ " ATZ OK ATDT5551212 CONNECT

This sequence will expect nothing; and then send the string ATZ.
The expected response to this is the string OK. When it receives
OK, the string ATDT5551212 to dial the telephone. The expected
string is CONNECT. If the string CONNECT is received the remainder
of the script is executed. However, should the modem find a busy
telephone, it will send the string BUSY. This will cause the string
to match the abort character sequence. The script will then fail
because it found a match to the abort string. If it received the
string NO CARRIER, it will abort for the same reason. Either string
may be received. Either string will terminate the chat script.

TIMEOUT
The initial timeout value is 45 seconds. This may be changed using
the -t parameter.

To change the timeout value for the next expect string, the
following example may be used:

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5
assowrd: hello2u2

This will change the timeout to 10 seconds when it expects the
login: prompt. The timeout is then changed 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. 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 special reply string of BREAK will cause 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 until you are able to receive a valid login
prompt. The break sequence may be embedded into the send string
using the K sequence.

ESCAPE SEQUENCES
The expect and reply strings may contain escape sequences. All of
the sequences are legal in the reply string. Many are legal in the
expect. Those which are not valid in the expect sequence 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.

the only method to send a string without a trailing return
character. It must be at the end of the send string. For
example, the sequence hello h, e, l, l, o. (not valid in expect.)

Delay for one second. The program uses sleep(1) which will
delay to a maximum of one second. (not valid in expect.)

K Insert a BREAK (not valid in expect.)

Send a newline or linefeed character.

Send a null character. The same sequence may be represented by
. (not valid in expect.)

Pause for a fraction of a second. The delay is 1/10th of a
second. (not valid in expect.)

q Suppress writing the string to the SYSLOG file. The string
?????? is written to the log in its place. (not valid in
expect.)

Send or expect a carriage return.

Represents a space character in the string. This may be used
when it is not desirable to quote the strings which contains
spaces. The sequence ’HI TIM’ and HIM are the same.

Send or expect a tab character.

\ Send or expect a backslash character.

dd Collapse the octal digits (ddd) into a single ASCII character
and send that character. (some characters are not valid in

^C Substitute 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

EXAMPLE
The first example shows the use of chat by pppd to connect to a
remote Unix site using a Hayes modem attached to the serial port
and using the hardware flow-control device /dev/ttyfa. The chat
script expects nothing, sends a Hayes standard tone dial command
with an local seven digit phone number, expects a "CONNECT"
response from the local modem when the remote modem connection is
established, sends a carriage-return, expects the "(l)ogin:" prompt
from the remote getty process, sends the user name "ppp", expects a
"(P)assword:" prompt, and sends the password "foobar" for the ppp
account.

pppd -d connect ’chat -v "" ATDT5551212 CONNECT "" ogin: ppp
assword: foobar’ /dev/ttya

The second example shows the same connection using a CommToolBox
device (/dev/cm.out) which takes care of the modem auto-dialing
aspect of the serial line conversation.

pppd -d connect ’chat -v "" "" ogin: ppp assword: foobar’
/dev/cm.out

SEE ALSO
Additional information about chat scripts may be found with UUCP
documentation. The chat script was taken from the ideas proposed by
the scripts used by the uucico program.

uucico(1), uucp(1)

COPYRIGHT
The chat program is in public domain. This is not the GNU public
license. If it breaks then you get to keep both pieces.