Penguin
Recent Changes
Annotated edit history of chat(8) version 1 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 CHAT
2 !!!CHAT
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 CHAT SCRIPT
8 COMMENTS
9 SENDING DATA FROM A FILE
10 ABORT STRINGS
11 CLR_ABORT STRINGS
12 SAY STRINGS
13 REPORT STRINGS
14 CLR_REPORT STRINGS
15 ECHO
16 HANGUP
17 TIMEOUT
18 SENDING EOT
19 GENERATING BREAK
20 ESCAPE SEQUENCES
21 ENVIRONMENT VARIABLES
22 TERMINATION CODES
23 SEE ALSO
24 COPYRIGHT
25 ----
26 !!NAME
27
28
29 chat - Automated conversational script with a modem
30 !!SYNOPSIS
31
32
33 __chat__ [[ ''options'' ] ''script''
34 !!DESCRIPTION
35
36
37 The ''chat'' program defines a conversational exchange
38 between the computer and the modem. Its primary purpose is
39 to establish the connection between the Point-to-Point
40 Protocol Daemon (''pppd'') and the remote's ''pppd''
41 process.
42 !!OPTIONS
43
44
45 __-f__ ''''
46
47
48 Read the chat script from the chat ''file''. The use of
49 this option is mutually exclusive with the chat script
50 parameters. The user must have read access to the file.
51 Multiple lines are permitted in the file. Space or
52 horizontal tab characters should be used to separate the
53 strings.
54
55
56 __-t__ ''''
57
58
59 Set the timeout for the expected string to be received. If
60 the string is not received within the time limit then the
61 reply string is not sent. An alternate reply may be sent or
62 the script will fail if there is no alternate reply string.
63 A failed script will cause the ''chat'' program to
64 terminate with a non-zero error code.
65
66
67 __-r__ ''''
68
69
70 Set the file for output of the report strings. If you use
71 the keyword ''REPORT'', the resulting strings are written
72 to this file. If this option is not used and you still use
73 ''REPORT'' keywords, the ''stderr'' file is used for
74 the report strings.
75
76
77 __-e__
78
79
80 Start with the echo option turned on. Echoing may also be
81 turned on or off at specific points in the chat script by
82 using the ''ECHO'' keyword. When echoing is enabled, all
83 output from the modem is echoed to
84 ''stderr''.
85
86
87 __-E__
88
89
90 Enables environment variable substituion within chat scripts
91 using the standard ''$xxx'' syntax.
92
93
94 __-v__
95
96
97 Request that the ''chat'' script be executed in a verbose
98 mode. The ''chat'' program will then log the execution
99 state of the chat script as well as all text received from
100 the modem and the output strings sent to the modem. The
101 default is to log through the SYSLOG; the logging method may
102 be altered with the -S and -s flags.
103
104
105 __-V__
106
107
108 Request that the ''chat'' script be executed in a stderr
109 verbose mode. The ''chat'' program will then log all text
110 received from the modem and the output strings sent to the
111 modem to the stderr device. This device is usually the local
112 console at the station running the chat or pppd
113 program.
114
115
116 __-s__
117
118
119 Use stderr. All log messages from '-v' and all error
120 messages will be sent to stderr.
121
122
123 __-S__
124
125
126 Do not use the SYSLOG. By default, error messages are sent
127 to the SYSLOG. The use of -S will prevent both log messages
128 from '-v' and error messages from being sent to the
129 SYSLOG.
130
131
132 __-T__ ''''
133
134
135 Pass in an arbitary string, usually a phone number, that
136 will be substituted for the T substitution metacharacter in
137 a send string.
138
139
140 __-U__ ''''
141
142
143 Pass in a second string, usually a phone number, that will
144 be substituted for the U substitution metacharacter in a
145 send string. This is useful when dialing an ISDN terminal
146 adapter that requires two numbers.
147
148
149 __script__
150
151
152 If the script is not specified in a file with the ''-f''
153 option then the script is included as parameters to the
154 ''chat'' program.
155 !!CHAT SCRIPT
156
157
158 The ''chat'' script defines the
159 communications.
160
161
162 A script consists of one or more
163
164
165 ogin:-BREAK-ogin: ppp ssword: hello2u2
166
167
168 This line indicates that the ''chat'' program should
169 expect the string
170 ''
171
172
173 Once it received the login prompt the ''chat'' program
174 will send the string ppp and then expect the prompt
175 ''
176
177
178 A carriage return is normally sent following the reply
179 string. It is not expected in the
180
181
182 The expect sequence should contain only what is needed to
183 identify the string. Since it is normally stored on a disk
184 file, it should not contain variable information. It is
185 generally not acceptable to look for time strings, network
186 identification strings, or other variable pieces of data as
187 an expect string.
188
189
190 To help correct for characters which may be corrupted during
191 the initial sequence, look for the string
192
193
194 A very simple script might look like this:
195
196
197 ogin: ppp ssword: hello2u2
198
199
200 In other words, expect ....ogin:, send ppp, expect
201 ...ssword:, send hello2u2.
202
203
204 In actual practice, simple scripts are rare. At the vary
205 least, you should include sub-expect sequences should the
206 original string not be received. For example, consider the
207 following script:
208
209
210 ogin:--ogin: ppp ssword: hello2u2
211
212
213 This would be a better script than the simple one used
214 earlier. This would look for the same login: prompt,
215 however, if one was not received, a single return sequence
216 is sent and then it will look for login: again. Should line
217 noise obscure the first login prompt then sending the empty
218 line will usually generate a login prompt
219 again.
220 !!COMMENTS
221
222
223 Comments can be embedded in the chat script. A comment is a
224 line which starts with the __#__ (hash) character in
225 column 1. Such comment lines are just ignored by the chat
226 program. If a '#' character is to be expected as the first
227 character of the expect sequence, you should quote the
228 expect string. If you want to wait for a prompt that starts
229 with a # (hash) character, you would have to write something
230 like this:
231
232
233 # Now wait for the prompt and send logout string
234 '# ' logout
235 !!SENDING DATA FROM A FILE
236
237
238 If the string to send starts with an at sign (@), the rest
239 of the string is taken to be the name of a file to read to
240 get the string to send. If the last character of the data
241 read is a newline, it is removed. The file can be a named
242 pipe (or fifo) instead of a regular file. This provides a
243 way for __chat__ to communicate with another program, for
244 example, a program to prompt the user and receive a password
245 typed in.
246 !!ABORT STRINGS
247
248
249 Many modems will report the status of the call as a string.
250 These strings may be __CONNECTED__ or __NO CARRIER__
251 or __BUSY__. It is often desirable to terminate the
252 script should the modem fail to connect to the remote. The
253 difficulty is that a script would not know exactly which
254 modem string it may receive. On one attempt, it may receive
255 __BUSY__ while the next time it may receive __NO
256 CARRIER__.
257
258
259 These
260 ABORT'' sequence. It is written in the
261 script as in the following example:
262
263
264 ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212
265 CONNECT
266
267
268 This sequence will expect nothing; and then send the string
269 ATZ. The expected response to this is the string ''OK''.
270 When it receives ''OK'', the string ATDT5551212 to dial
271 the telephone. The expected string is ''CONNECT''. If the
272 string ''CONNECT'' is received the remainder of the
273 script is executed. However, should the modem find a busy
274 telephone, it will send the string ''BUSY''. This will
275 cause the string to match the abort character sequence. The
276 script will then fail because it found a match to the abort
277 string. If it received the string ''NO CARRIER'', it will
278 abort for the same reason. Either string may be received.
279 Either string will terminate the ''chat''
280 script.
281 !!CLR_ABORT STRINGS
282
283
284 This sequence allows for clearing previously set
285 __ABORT__ strings. __ABORT__ strings are kept in an
286 array of a pre-determined size (at compilation time);
287 __CLR_ABORT__ will reclaim the space for cleared entries
288 so that new strings can use that space.
289 !!SAY STRINGS
290
291
292 The __SAY__ directive allows the script to send strings
293 to the user at the terminal via standard error. If
294 __chat__ is being run by pppd, and pppd is running as a
295 daemon (detached from its controlling terminal), standard
296 error will normally be redirected to the file
297 /etc/ppp/connect-errors.
298
299
300 __SAY__ strings must be enclosed in single or double
301 quotes. If carriage return and line feed are needed in the
302 string to be output, you must explicitely add them to your
303 string.
304
305
306 The SAY strings could be used to give progress messages in
307 sections of the script where you want to have 'ECHO OFF' but
308 still let the user know what is happening. An example
309 is:
310
311
312 ABORT BUSY
313 ECHO OFF
314 SAY
315 '' ATDT5551212
316 TIMEOUT 120
317 SAY
318 CONNECT ''
319 SAY
320 ogin: account
321 ssword: pass
322 $ SAY etc ...''
323
324
325 This sequence will only present the SAY strings to the user
326 and all the details of the script will remain hidden. For
327 example, if the above script works, the user will
328 see:
329
330
331 Dialling your ISP...
332 Waiting up to 2 minutes for connection ... Connected, now
333 logging in ...
334 Logged in OK ...
335 !!REPORT STRINGS
336
337
338 A __report__ string is similar to the ABORT string. The
339 difference is that the strings, and all characters to the
340 next control character such as a carriage return, are
341 written to the report file.
342
343
344 The report strings may be used to isolate the transmission
345 rate of the modem's connect string and return the value to
346 the chat user. The analysis of the report string logic
347 occurs in conjunction with the other string processing such
348 as looking for the expect string. The use of the same string
349 for a report and abort sequence is probably not very useful,
350 however, it is possible.
351
352
353 The report strings to no change the completion code of the
354 program.
355
356
357 These
358 REPORT'' sequence. It is written in
359 the script as in the following example:
360
361
362 REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin:
363 account
364
365
366 This sequence will expect nothing; and then send the string
367 ATDT5551212 to dial the telephone. The expected string is
368 ''CONNECT''. If the string ''CONNECT'' is received the
369 remainder of the script is executed. In addition the program
370 will write to the expect-file the string
371 ''
372 !!CLR_REPORT STRINGS
373
374
375 This sequence allows for clearing previously set
376 __REPORT__ strings. __REPORT__ strings are kept in an
377 array of a pre-determined size (at compilation time);
378 __CLR_REPORT__ will reclaim the space for cleared entries
379 so that new strings can use that space.
380 !!ECHO
381
382
383 The echo options controls whether the output from the modem
384 is echoed to ''stderr''. This option may be set with the
385 ''-e'' option, but it can also be controlled by the
386 ''ECHO'' keyword. The
387 ''ECHO ON'' enables echoing, and ''ECHO OFF'' disables
388 it. With this keyword you can select which parts of the
389 conversation should be visible. For instance, with the
390 following script:
391
392
393 ABORT 'BUSY'
394 ABORT 'NO CARRIER'
395 OKrn ATD1234567
396 rn c
397 ECHO ON
398 CONNECT c
399 ogin: account
400
401
402 all output resulting from modem configuration and dialing is
403 not visible, but starting with the ''CONNECT'' (or
404 ''BUSY'') message, everything will be
405 echoed.
406 !!HANGUP
407
408
409 The HANGUP options control whether a modem hangup should be
410 considered as an error or not. This option is useful in
411 scripts for dialling systems which will hang up and call
412 your system back. The HANGUP options can be __ON__ or
413 __OFF__.
414 When HANGUP is set OFF and the modem hangs up (e.g., after
415 the first stage of logging in to a callback system),
416 __chat__ will continue running the script (e.g., waiting
417 for the incoming call and second stage login prompt). As
418 soon as the incoming call is connected, you should use the
419 __HANGUP ON__ directive to reinstall normal hang up
420 signal behavior. Here is an (simple) example
421 script:
422
423
424 ABORT 'BUSY'
425 OKrn ATD1234567
426 rn c
427 CONNECT c
428 'Callback login:' call_back_ID
429 HANGUP OFF
430 ABORT
431 'Callback Password:' Call_back_password
432 TIMEOUT 120
433 CONNECT c
434 HANGUP ON
435 ABORT
436 ogin:--BREAK--ogin: real_account''
437 etc ...''
438 !!TIMEOUT
439
440
441 The initial timeout value is 45 seconds. This may be changed
442 using the __-t__ parameter.
443
444
445 To change the timeout value for the next expect string, the
446 following example may be used:
447
448
449 ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5
450 assword: hello2u2
451
452
453 This will change the timeout to 10 seconds when it expects
454 the login: prompt. The timeout is then changed to 5 seconds
455 when it looks for the password prompt.
456
457
458 The timeout, once changed, remains in effect until it is
459 changed again.
460 !!SENDING EOT
461
462
463 The special reply string of ''EOT'' indicates that the
464 chat program should send an EOT character to the remote.
465 This is normally the End-of-file character sequence. A
466 return character is not sent following the EOT. The EOT
467 sequence may be embedded into the send string using the
468 sequence ''^D''.
469 !!GENERATING BREAK
470
471
472 The special reply string of ''BREAK'' will cause a break
473 condition to be sent. The break is a special signal on the
474 transmitter. The normal processing on the receiver is to
475 change the transmission rate. It may be used to cycle
476 through the available transmission rates on the remote until
477 you are able to receive a valid login prompt. The break
478 sequence may be embedded into the send string using the
479 ''K'' sequence.
480 !!ESCAPE SEQUENCES
481
482
483 The expect and reply strings may contain escape sequences.
484 All of the sequences are legal in the reply string. Many are
485 legal in the expect. Those which are not valid in the expect
486 sequence are so indicated.
487
488
489 __''__
490
491
492 Expects or sends a null string. If you send a null string
493 then it will still send the return character. This sequence
494 may either be a pair of apostrophe or quote
495 characters.
496
497
498 __b__
499
500
501 represents a backspace character.
502
503
504 __c__
505
506
507 Suppresses the newline at the end of the reply string. This
508 is the only method to send a string without a trailing
509 return character. It must be at the end of the send string.
510 For example, the sequence helloc will simply send the
511 characters h, e, l, l, o. ''(not valid in
512 expect.)''
513
514
515 __d__
516
517
518 Delay for one second. The program uses sleep(1) which will
519 delay to a maximum of one second. ''(not valid in
520 expect.)''
521
522
523 __K__
524
525
526 Insert a BREAK ''(not valid in expect.)''
527
528
529 __n__
530
531
532 Send a newline or linefeed character.
533
534
535 __N__
536
537
538 Send a null character. The same sequence may be represented
539 by 0. ''(not valid in expect.)''
540
541
542 __p__
543
544
545 Pause for a fraction of a second. The delay is 1/10th of a
546 second. ''(not valid in expect.)''
547
548
549 __q__
550
551
552 Suppress writing the string to the SYSLOG file. The string
553 ?????? is written to the log in its place. ''(not valid in
554 expect.)''
555
556
557 __r__
558
559
560 Send or expect a carriage return.
561
562
563 __s__
564
565
566 Represents a space character in the string. This may be used
567 when it is not desirable to quote the strings which contains
568 spaces. The sequence 'HI TIM' and HIsTIM are the
569 same.
570
571
572 __t__
573
574
575 Send or expect a tab character.
576
577
578 __T__
579
580
581 Send the phone number string as specified with the ''-T''
582 option ''(not valid in expect.)''
583
584
585 __U__
586
587
588 Send the phone number 2 string as specified with the
589 ''-U'' option ''(not valid in expect.)''
590
591
592 __\__
593
594
595 Send or expect a backslash character.
596
597
598 __ddd__
599
600
601 Collapse the octal digits (ddd) into a single ASCII
602 character and send that character. ''(some characters are
603 not valid in expect.)''
604
605
606 __^C__
607
608
609 Substitute the sequence with the control character
610 represented by C. For example, the character DC1 (17) is
611 shown as ^Q. ''(some characters are not valid in
612 expect.)''
613 !!ENVIRONMENT VARIABLES
614
615
616 Environment variables are available within chat scripts, if
617 the ''-E'' option was specified in the command line. The
618 metacharacter ''$'' is used to introduce the name of the
619 environment variable to substitute. If the substition fails,
620 because the requested environment variable is not set,
621 ''nothing'' is replaced for the variable.
622 !!TERMINATION CODES
623
624
625 The ''chat'' program will terminate with the following
626 completion codes.
627
628
629 __0__
630
631
632 The normal termination of the program. This indicates that
633 the script was executed without error to the normal
634 conclusion.
635
636
637 __1__
638
639
640 One or more of the parameters are invalid or an expect
641 string was too large for the internal buffers. This
642 indicates that the program as not properly
643 executed.
644
645
646 __2__
647
648
649 An error occurred during the execution of the program. This
650 may be due to a read or write operation failing for some
651 reason or chat receiving a signal such as
652 SIGINT.
653
654
655 __3__
656
657
658 A timeout event occurred when there was an ''expect''
659 string without having a
660 ''
661
662
663 __4__
664
665
666 The first string marked as an ''ABORT'' condition
667 occurred.
668
669
670 __5__
671
672
673 The second string marked as an ''ABORT'' condition
674 occurred.
675
676
677 __6__
678
679
680 The third string marked as an ''ABORT'' condition
681 occurred.
682
683
684 __7__
685
686
687 The fourth string marked as an ''ABORT'' condition
688 occurred.
689
690
691 __...__
692
693
694 The other termination codes are also strings marked as an
695 ''ABORT'' condition.
696
697
698 Using the termination code, it is possible to determine
699 which event terminated the script. It is possible to decide
700 if the string
701 !!SEE ALSO
702
703
704 Additional information about ''chat'' scripts may be
705 found with UUCP documentation. The ''chat'' script was
706 taken from the ideas proposed by the scripts used by the
707 ''uucico'' program.
708
709
710 uucico(1), uucp(1)
711 !!COPYRIGHT
712
713
714 The ''chat'' program is in public domain. This is not the
715 GNU public license. If it breaks then you get to keep both
716 pieces.
717 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.