1CHAT(8)                     System Manager's Manual                    CHAT(8)
2
3
4

NAME

6       chat - Automated conversational script with a modem
7

SYNOPSIS

9       chat [ options ] script
10

DESCRIPTION

12       The chat program defines a conversational exchange between the computer
13       and the modem. Its primary  purpose  is  to  establish  the  connection
14       between the Point-to-Point Protocol Daemon (pppd) and the remote's pppd
15       process.
16

OPTIONS

18       -f <chat file>
19              Read the chat script from the chat file. The use of this  option
20              is  mutually exclusive with the chat script parameters. The user
21              must have read access to the file. Multiple lines are  permitted
22              in  the  file. Space or horizontal tab characters should be used
23              to separate the strings.
24
25       -t <timeout>
26              Set the timeout for the expected string to be received.  If  the
27              string  is  not  received  within  the time limit then the reply
28              string is not sent. An alternate reply may be sent or the script
29              will fail if there is no alternate reply string. A failed script
30              will cause the chat program to terminate with a  non-zero  error
31              code.
32
33       -r <report file>
34              Set  the  file  for output of the report strings. If you use the
35              keyword REPORT, the resulting strings are written to this  file.
36              If  this  option  is not used and you still use REPORT keywords,
37              the stderr file is used for the report strings.
38
39       -e     Start with the echo option turned on. Echoing may also be turned
40              on  or  off  at  specific points in the chat script by using the
41              ECHO keyword. When echoing is enabled, all output from the modem
42              is echoed to stderr.
43
44       -E     Enables  environment  variable  substitution within chat scripts
45              using the standard $xxx syntax.
46
47       -v     Request that the chat script be executed in a verbose mode.  The
48              chat  program  will  then  log  the  execution state of the chat
49              script as well as all text received from the modem and the  out‐
50              put  strings  sent  to the modem.  The default is to log through
51              the SYSLOG; the logging method may be altered with the -S and -s
52              flags.
53
54       -V     Request  that  the  chat  script be executed in a stderr verbose
55              mode. The chat program will then log all text received from  the
56              modem  and  the  output  strings sent to the modem to the stderr
57              device. This device is usually the local console at the  station
58              running the chat or pppd program.
59
60       -s     Use  stderr.   All log messages from '-v' and all error messages
61              will be sent to stderr.
62
63       -S     Do not use the SYSLOG.  By default, error messages are  sent  to
64              the  SYSLOG.   The use of -S will prevent both log messages from
65              '-v' and error messages from being sent to the SYSLOG.
66
67       -T <phone number>
68              Pass in an arbitrary string, usually a phone number,  that  will
69              be  substituted  for the \T substitution metacharacter in a send
70              string.
71
72       -U <phone number 2>
73              Pass in a second string, usually a phone number,  that  will  be
74              substituted  for  the  \U  substitution  metacharacter in a send
75              string.  This is useful when dialing an  ISDN  terminal  adapter
76              that requires two numbers.
77
78       script If the script is not specified in a file with the -f option then
79              the script is included as parameters to the chat program.
80

CHAT SCRIPT

82       The chat script defines the communications.
83
84       A script consists of one or more "expect-send" pairs of strings,  sepa‐
85       rated by spaces, with an optional "subexpect-subsend" string pair, sep‐
86       arated by a dash as in the following example:
87
88              ogin:-BREAK-ogin: ppp ssword: hello2u2
89
90       This line indicates that the chat  program  should  expect  the  string
91       "ogin:". If it fails to receive a login prompt within the time interval
92       allotted, it is to send a break sequence to the remote and then  expect
93       the  string  "ogin:".  If  the first "ogin:" is received then the break
94       sequence is not generated.
95
96       Once it received the login prompt the chat program will send the string
97       ppp  and  then expect the prompt "ssword:". When it receives the prompt
98       for the password, it will send the password hello2u2.
99
100       A carriage return is normally sent following the reply  string.  It  is
101       not expected in the "expect" string unless it is specifically requested
102       by using the \r character sequence.
103
104       The expect sequence should contain only what is needed to identify  the
105       string.  Since it is normally stored on a disk file, it should not con‐
106       tain variable information. It is generally not acceptable to  look  for
107       time  strings, network identification strings, or other variable pieces
108       of data as an expect string.
109
110       To help correct for characters which may be corrupted during  the  ini‐
111       tial  sequence, look for the string "ogin:" rather than "login:". It is
112       possible that the leading "l" character may be received  in  error  and
113       you  may  never  find the string even though it was sent by the system.
114       For this reason, scripts look for  "ogin:"  rather  than  "login:"  and
115       "ssword:" rather than "password:".
116
117       A very simple script might look like this:
118
119              ogin: ppp ssword: hello2u2
120
121       In  other  words,  expect  ....ogin:, send ppp, expect ...ssword:, send
122       hello2u2.
123
124       In actual practice, simple scripts are rare. At  the  vary  least,  you
125       should  include  sub-expect sequences should the original string not be
126       received. For example, consider the following script:
127
128              ogin:--ogin: ppp ssword: hello2u2
129
130       This would be a better script than the simple one  used  earlier.  This
131       would  look  for  the  same  login:  prompt,  however,  if  one was not
132       received, a single return sequence is sent and then it  will  look  for
133       login:  again.  Should  line  noise obscure the first login prompt then
134       sending the empty line will usually generate a login prompt again.
135

COMMENTS

137       Comments can be embedded in the chat script. A comment is a line  which
138       starts  with the # (hash) character in column 1. Such comment lines are
139       just ignored by the chat program. If a '#' character is to be  expected
140       as  the  first  character  of the expect sequence, you should quote the
141       expect string.  If you want to wait for a prompt that starts with  a  #
142       (hash) character, you would have to write something like this:
143
144              # Now wait for the prompt and send logout string
145              '# ' logout
146

SENDING DATA FROM A FILE

148       If  the  string  to  send  starts  with an at sign (@), the rest of the
149       string is taken to be the name of a file to read to get the  string  to
150       send.   If  the  last  character  of  the data read is a newline, it is
151       removed.  The file can be a named pipe (or fifo) instead of  a  regular
152       file.   This  provides  a way for chat to communicate with another pro‐
153       gram, for example, a program to prompt the user and receive a  password
154       typed in.
155

ABORT STRINGS

157       Many  modems  will  report  the  status  of the call as a string. These
158       strings may be CONNECTED or NO CARRIER or BUSY. It is  often  desirable
159       to terminate the script should the modem fail to connect to the remote.
160       The difficulty is that a script would  not  know  exactly  which  modem
161       string  it  may  receive. On one attempt, it may receive BUSY while the
162       next time it may receive NO CARRIER.
163
164       These "abort" strings may be specified in the script  using  the  ABORT
165       sequence. It is written in the script as in the following example:
166
167              ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT
168
169       This  sequence  will  expect nothing; and then send the string ATZ. The
170       expected response to this is the string OK. When it  receives  OK,  the
171       string  ATDT5551212  to dial the telephone. The expected string is CON‐
172       NECT. If the string CONNECT is received the remainder of the script  is
173       executed. However, should the modem find a busy telephone, it will send
174       the string BUSY. This will cause the string to match the abort  charac‐
175       ter sequence. The script will then fail because it found a match to the
176       abort string. If it received the string NO CARRIER, it will  abort  for
177       the same reason. Either string may be received. Either string will ter‐
178       minate the chat script.
179

CLR_ABORT STRINGS

181       This sequence allows for clearing previously set ABORT strings.   ABORT
182       strings  are  kept in an array of a pre-determined size (at compilation
183       time); CLR_ABORT will reclaim the space for cleared entries so that new
184       strings can use that space.
185

SAY STRINGS

187       The  SAY directive allows the script to send strings to the user at the
188       terminal via standard error.  If chat is being run by pppd, and pppd is
189       running  as a daemon (detached from its controlling terminal), standard
190       error  will  normally  be  redirected  to  the  file  /var/log/ppp/con‐
191       nect-errors.
192
193       SAY  strings  must  be enclosed in single or double quotes. If carriage
194       return and line feed are needed in the string to be  output,  you  must
195       explicitly add them to your string.
196
197       The  SAY strings could be used to give progress messages in sections of
198       the script where you want to have 'ECHO OFF' but  still  let  the  user
199       know what is happening.  An example is:
200
201              ABORT BUSY
202              ECHO OFF
203              SAY "Dialling your ISP...\n"
204              '' ATDT5551212
205              TIMEOUT 120
206              SAY "Waiting up to 2 minutes for connection ... "
207              CONNECT ''
208              SAY "Connected, now logging in ...\n"
209              ogin: account
210              ssword: pass
211              $ \c
212              SAY "Logged in OK ...\n" etc ...
213
214       This sequence will only present the SAY strings to the user and all the
215       details of the script will remain hidden. For  example,  if  the  above
216       script works, the user will see:
217
218              Dialling your ISP...
219              Waiting  up  to 2 minutes for connection ... Connected, now log‐
220              ging in ...
221              Logged in OK ...
222

REPORT STRINGS

224       A report string is similar to the ABORT string. The difference is  that
225       the strings, and all characters to the next control character such as a
226       carriage return, are written to the report file.
227
228       The report strings may be used to isolate the transmission rate of  the
229       modem's connect string and return the value to the chat user. The anal‐
230       ysis of the report string logic occurs in conjunction  with  the  other
231       string processing such as looking for the expect string. The use of the
232       same string for a report and abort sequence is probably not  very  use‐
233       ful, however, it is possible.
234
235       The report strings to no change the completion code of the program.
236
237       These  "report" strings may be specified in the script using the REPORT
238       sequence. It is written in the script as in the following example:
239
240              REPORT CONNECT  ABORT  BUSY  ''  ATDT5551212  CONNECT  ''  ogin:
241              account
242
243       This sequence will expect nothing; and then send the string ATDT5551212
244       to dial the telephone. The expected string is CONNECT.  If  the  string
245       CONNECT  is  received the remainder of the script is executed. In addi‐
246       tion the program will write to the  expect-file  the  string  "CONNECT"
247       plus any characters which follow it such as the connection rate.
248

CLR_REPORT STRINGS

250       This  sequence  allows  for  clearing  previously  set  REPORT strings.
251       REPORT strings are kept in an array of a pre-determined size (at compi‐
252       lation  time); CLR_REPORT will reclaim the space for cleared entries so
253       that new strings can use that space.
254

ECHO

256       The echo options controls whether the output from the modem  is  echoed
257       to  stderr.  This option may be set with the -e option, but it can also
258       be controlled by the ECHO  keyword.  The  "expect-send"  pair  ECHO  ON
259       enables  echoing,  and  ECHO OFF disables it. With this keyword you can
260       select which parts of the conversation should be visible. For instance,
261       with the following script:
262
263              ABORT   'BUSY'
264              ABORT   'NO CARRIER'
265              ''      ATZ
266              OK\r\n  ATD1234567
267              \r\n    \c
268              ECHO    ON
269              CONNECT \c
270              ogin:   account
271
272       all  output resulting from modem configuration and dialing is not visi‐
273       ble, but starting with the CONNECT (or BUSY) message,  everything  will
274       be echoed.
275

HANGUP

277       The  HANGUP options control whether a modem hangup should be considered
278       as an error or not.  This option is useful in scripts for dialling sys‐
279       tems  which will hang up and call your system back.  The HANGUP options
280       can be ON or OFF.
281       When HANGUP is set OFF and the modem hangs up (e.g.,  after  the  first
282       stage  of  logging in to a callback system), chat will continue running
283       the script (e.g., waiting for the incoming call and second stage  login
284       prompt).  As soon as the incoming call is connected, you should use the
285       HANGUP ON directive to reinstall normal hang up signal behavior.   Here
286       is an (simple) example script:
287
288              ABORT   'BUSY'
289              ''      ATZ
290              OK\r\n  ATD1234567
291              \r\n    \c
292              CONNECT \c
293              'Callback login:' call_back_ID
294              HANGUP OFF
295              ABORT "Bad Login"
296              'Callback Password:' Call_back_password
297              TIMEOUT 120
298              CONNECT \c
299              HANGUP ON
300              ABORT "NO CARRIER"
301              ogin:--BREAK--ogin: real_account
302              etc ...
303

TIMEOUT

305       The  initial timeout value is 45 seconds. This may be changed using the
306       -t parameter.
307
308       To change the timeout value for the next expect string,  the  following
309       example may be used:
310
311              ATZ  OK  ATDT5551212  CONNECT  TIMEOUT 10 ogin:--ogin: TIMEOUT 5
312              assword: hello2u2
313
314       This will change the timeout to 10 seconds when it expects  the  login:
315       prompt.  The timeout is then changed to 5 seconds when it looks for the
316       password prompt.
317
318       The timeout, once changed, remains in effect until it is changed again.
319

SENDING EOT

321       The special reply string of EOT indicates that the chat program  should
322       send  an  EOT character to the remote. This is normally the End-of-file
323       character sequence. A return character is not sent following  the  EOT.
324       The  EOT  sequence  may  be  embedded  into  the  send string using the
325       sequence ^D.
326

GENERATING BREAK

328       The special reply string of BREAK will cause a break  condition  to  be
329       sent. The break is a special signal on the transmitter. The normal pro‐
330       cessing on the receiver is to change the transmission rate.  It may  be
331       used  to  cycle  through the available transmission rates on the remote
332       until you are able to receive a valid login prompt.  The break sequence
333       may be embedded into the send string using the \K sequence.
334

ESCAPE SEQUENCES

336       The  expect  and reply strings may contain escape sequences. All of the
337       sequences are legal in the reply string. Many are legal in the  expect.
338       Those which are not valid in the expect sequence are so indicated.
339
340       ''     Expects  or  sends a null string. If you send a null string then
341              it will still send  the  return  character.  This  sequence  may
342              either be a pair of apostrophe or quote characters.
343
344       \b     represents a backspace character.
345
346       \c     Suppresses  the  newline at the end of the reply string. This is
347              the only method to send a string without a trailing return char‐
348              acter.  It  must  be at the end of the send string. For example,
349              the sequence hello\c will simply send the characters h, e, l, l,
350              o.  (not valid in expect.)
351
352       \d     Delay for one second. The program uses sleep(1) which will delay
353              to a maximum of one second.  (not valid in expect.)
354
355       \K     Insert a BREAK (not valid in expect.)
356
357       \n     Send a newline or linefeed character.
358
359       \N     Send a null character. The same sequence may be  represented  by
360              \0.  (not valid in expect.)
361
362       \p     Pause  for a fraction of a second. The delay is 1/10th of a sec‐
363              ond.  (not valid in expect.)
364
365       \q     Suppress writing the string  to  the  SYSLOG  file.  The  string
366              ??????  is  written  to  the  log  in  its place.  (not valid in
367              expect.)
368
369       \r     Send or expect a carriage return.
370
371       \s     Represents a space character in the string.  This  may  be  used
372              when  it  is  not  desirable to quote the strings which contains
373              spaces. The sequence 'HI TIM' and HI\sTIM are the same.
374
375       \t     Send or expect a tab character.
376
377       \T     Send the phone number string as specified  with  the  -T  option
378              (not valid in expect.)
379
380       \U     Send  the  phone number 2 string as specified with the -U option
381              (not valid in expect.)
382
383       \\     Send or expect a backslash character.
384
385       \ddd   Collapse the octal digits (ddd) into a  single  ASCII  character
386              and  send  that  character.   (some  characters are not valid in
387              expect.)
388
389       ^C     Substitute the sequence with the control  character  represented
390              by  C.   For  example,  the  character  DC1 (17) is shown as ^Q.
391              (some characters are not valid in expect.)
392

ENVIRONMENT VARIABLES

394       Environment variables are available within chat  scripts,  if   the  -E
395       option  was  specified in the command line. The metacharacter $ is used
396       to introduce the name of the environment variable to substitute. If the
397       substitution  fails,  because the requested environment variable is not
398       set, nothing is replaced for the variable.
399

TERMINATION CODES

401       The chat program will terminate with the following completion codes.
402
403       0      The normal termination of the program. This indicates  that  the
404              script was executed without error to the normal conclusion.
405
406       1      One  or  more  of the parameters are invalid or an expect string
407              was too large for the internal buffers. This indicates that  the
408              program as not properly executed.
409
410       2      An  error occurred during the execution of the program. This may
411              be due to a read or write operation failing for some  reason  or
412              chat receiving a signal such as SIGINT.
413
414       3      A timeout event occurred when there was an expect string without
415              having a "-subsend" string. This may mean that you did not  pro‐
416              gram  the  script correctly for the condition or that some unex‐
417              pected event has occurred and the expected string could  not  be
418              found.
419
420       4      The first string marked as an ABORT condition occurred.
421
422       5      The second string marked as an ABORT condition occurred.
423
424       6      The third string marked as an ABORT condition occurred.
425
426       7      The fourth string marked as an ABORT condition occurred.
427
428       ...    The  other termination codes are also strings marked as an ABORT
429              condition.
430
431       Using the termination code, it is possible  to  determine  which  event
432       terminated  the  script.  It is possible to decide if the string "BUSY"
433       was received from the modem as opposed to "NO  DIAL  TONE".  While  the
434       first event may be retried, the second will probably have little chance
435       of succeeding during a retry.
436

SEE ALSO

438       Additional information about chat scripts may be found with UUCP  docu‐
439       mentation.  The  chat  script  was taken from the ideas proposed by the
440       scripts used by the uucico program.
441
442       uucico(1), uucp(1)
443
445       The chat program is in public  domain.  This  is  not  the  GNU  public
446       license. If it breaks then you get to keep both pieces.
447
448
449
450Chat Version 1.22                 22 May 1999                          CHAT(8)
Impressum