| blob | 9e7112e8afc999016a6f5dfff2c23b15876d4878 |
1 .\" -*- nroff -*-
2 .\" manual page [] for chat 1.8
3 .\" $FreeBSD: src/usr.bin/chat/chat.8,v 1.15.2.3 2003/02/24 22:37:41 trhodes Exp $
4 .\" $DragonFly: src/usr.bin/chat/chat.8,v 1.7 2008/05/09 20:31:04 swildner Exp $
5 .Dd September 27, 1996
6 .Dt CHAT 8
7 .Os
8 .Sh NAME
9 .Nm chat
10 .Nd Automated conversational script with a modem
11 .Sh SYNOPSIS
12 .Nm
13 .Op Fl evVsS
14 .Op Fl f Ar chat_file
15 .Op Fl r Ar report_file
16 .Op Fl t Ar timeout
17 .Op Fl T Ar phone_number
18 .Op Fl U Ar phone_number
19 .Sh DESCRIPTION
20 The
21 .Nm
22 program defines a conversational exchange between the computer and the modem.
23 Its primary purpose is to establish the
24 connection between the Point-to-Point Protocol Daemon
25 .Xr ( pppd 8 )
26 and the remote's
27 .Xr pppd 8
28 process.
29 .Sh OPTIONS
30 The following options are provided:
31 .Bl -tag -width ".Fl U Ar phone_number" -offset indent
32 .It Fl f Ar chat_file
33 Read the chat script from
34 .Ar chat_file .
35 The use of this option is mutually exclusive with the chat script parameters.
36 The user must have read access to the file.
37 Multiple lines are permitted in the file.
38 Space or horizontal tab characters should be used to separate the strings.
39 .It Fl t Ar timeout
40 Set the timeout for the expected string to be received.
41 If the string
42 is not received within the time limit then the reply string is not sent.
43 An alternate reply may be sent or the script will fail if there
44 is no alternate reply string.
45 A failed script will cause the
46 .Nm
47 program to terminate with a non-zero error code.
48 .It Fl r Ar report_file
49 Set the file for output of the report strings.
50 If you use the keyword
51 .Dq REPORT ,
52 the resulting strings are written to this file.
53 If this option is not used and you still use
54 .Dq REPORT
55 keywords, the stderr file is used for the report strings.
56 .It Fl e
57 Start with the echo option turned on.
58 Echoing may also be turned on
59 or off at specific points in the chat script by using the
60 .Dq ECHO
61 keyword.
62 When echoing is enabled, all output from the modem is echoed to stderr.
63 .It Fl v
64 Request that the
65 .Ar script
66 be executed in a verbose mode.
67 The
68 .Nm
69 program will then log the execution state of the chat
70 script as well as all text received from the modem and the output
71 strings sent to the modem.
72 The default is to log through
73 .Xr syslog 3 ;
74 the logging method may be altered with the
75 .Fl S
76 and
77 .Fl s
78 flags.
79 Logging is done to the
80 .Dq local2
81 facility at level
82 .Dq info
83 for verbose tracing and level
84 .Dq err
85 for some errors.
86 .It Fl V
87 Request that
88 .Ar script
89 be executed in a stderr verbose mode.
90 The
91 .Nm
92 program will then log all text received from the
93 modem and the output strings sent to the modem to the stderr device.
94 This
95 device is usually the local console at the station running the chat or
96 pppd program.
97 .It Fl s
98 Use stderr.
99 All log messages from
100 .Fl v
101 and all error messages will be sent to stderr.
102 .It Fl S
103 Do not use
104 .Xr syslog 3 .
105 By default, error messages are sent to
106 .Xr syslog 3 .
107 The use of
108 .Fl S
109 will prevent both log messages from
110 .Fl v
111 and error messages from being sent to
112 .Xr syslog 3 .
113 .It Fl T Ar phone_number
114 Pass in an arbitrary string, usually a phone number, that will be
115 substituted for the \eT substitution metacharacter in a send string.
116 .It Fl U Ar phone_number
117 Pass in a second string, usually a phone number, that will be
118 substituted for the \eU substitution metacharacter in a send string.
119 This is useful when dialing an ISDN terminal adapter that requires two
120 numbers.
121 .It Ar script
122 If the script is not specified in a file with the
123 .Fl f
124 option then the script is included as parameters to the
125 .Nm
126 program.
127 .El
128 .Sh CHAT SCRIPT
129 The
130 .Nm
131 script defines the communications.
132 .Pp
133 A script consists of one or more
134 .Dq expect-send
135 pairs of strings, separated by spaces, with an optional
136 .Dq subexpect-subsend
137 string pair, separated by a dash as in the following example:
138 .Pp
139 .Dl ogin:-BREAK-ogin: ppp ssword: hello2u2
140 .Pp
141 This line indicates that the
142 .Nm
143 program should expect the string
144 .Dq ogin: .
145 If it fails to receive a login prompt within the time interval
146 allotted, it is to send a break sequence to the remote and then expect the
147 string
148 .Dq ogin: .
149 If the first
150 .Dq ogin:
151 is received then the break sequence is not generated.
152 .Pp
153 Once it received the login prompt the
154 .Nm
155 program will send the string ppp and then expect the prompt
156 .Dq ssword: .
157 When it receives the
158 prompt for the password, it will send the password hello2u2.
159 .Pp
160 A carriage return is normally sent following the reply string.
161 It is not expected in the
162 .Dq expect
163 string unless it is specifically requested by using the \er character sequence.
164 .Pp
165 The expect sequence should contain only what is needed to identify the string.
166 Since it is normally stored on a disk file, it should not contain
167 variable information.
168 It is generally not acceptable to look for time
169 strings, network identification strings, or other variable pieces of data as
170 an expect string.
171 .Pp
172 To help correct for characters which may be corrupted during the initial
173 sequence, look for the string
174 .Dq ogin:
175 rather than
176 .Dq login: .
177 It is possible that the leading
178 .Dq l
179 character may be received in error and you may never
180 find the string even though it was sent by the system.
181 For this reason, scripts look for
182 .Dq ogin:
183 rather than
184 .Dq login:
185 and
186 .Dq ssword:
187 rather than
188 .Dq password: .
189 .Pp
190 A very simple script might look like this:
191 .Pp
192 .Dl ogin: ppp ssword: hello2u2
193 .Pp
194 In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2.
195 .Pp
196 In actual practice, simple scripts are rare.
197 At the vary least, you
198 should include sub-expect sequences should the original string not be
199 received.
200 For example, consider the following script:
201 .Pp
202 .Dl ogin:--ogin: ppp ssword: hello2u2
203 .Pp
204 This would be a better script than the simple one used earlier.
205 This would look
206 for the same login: prompt, however, if one was not received, a single
207 return sequence is sent and then it will look for login: again.
208 Should line
209 noise obscure the first login prompt then sending the empty line will
210 usually generate a login prompt again.
211 .Sh COMMENTS
212 Comments can be embedded in the chat script.
213 A comment is a line which
214 starts with the
215 .Sy #
216 (hash) character in column 1.
217 Such comment lines are just ignored by the chat program.
218 If a
219 .Sq #
220 character is to
221 be expected as the first character of the expect sequence, you should
222 quote the expect string.
223 If you want to wait for a prompt that starts with a # (hash)
224 character, you would have to write something like this:
225 .Bd -literal -offset indent
226 # Now wait for the prompt and send logout string
227 .br
228 \&'# ' logout
229 .Ed
230 .Sh ABORT STRINGS
231 Many modems will report the status of the call as a string.
232 These strings may be
233 .Dq CONNECTED
234 or
235 .Dq NO CARRIER
236 or
237 .Dq BUSY .
238 It is often desirable to terminate the script should the modem fail to
239 connect to the remote.
240 The difficulty is that a script would not know
241 exactly which modem string it may receive.
242 On one attempt, it may receive
243 .Dq BUSY
244 while the next time it may receive
245 .Dq NO CARRIER .
246 .Pp
247 These
248 .Dq abort
249 strings may be specified in the script using the
250 .Dq ABORT
251 sequence.
252 It is written in the script as in the following example:
253 .Pp
254 .Dl ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT
255 .Pp
256 This sequence will expect nothing; and then send the string ATZ.
257 The expected response to this is the string
258 .Dq OK .
259 When it receives
260 .Dq OK ,
261 the string ATDT5551212 to dial the telephone.
262 The expected string is
263 .Dq CONNECT .
264 If the string
265 .Dq CONNECT
266 is received the remainder of the script is executed.
267 However, should the modem find a busy telephone, it will send the string
268 .Dq BUSY .
269 This will cause the string to match the abort character sequence.
270 The script will then fail because it found a match to the abort string.
271 If it received the string
272 .Dq NO CARRIER ,
273 it will abort for the same reason.
274 Either string may be received.
275 Either string will terminate the
276 .Nm
277 script.
278 .Sh CLR_ABORT STRINGS
279 This sequence allows for clearing previously set
280 .Dq ABORT
281 strings.
282 .Dq ABORT
283 strings are kept in an array of a pre-determined size (at compilation time);
284 .Dq CLR_ABORT will reclaim the space for cleared
285 entries so that new strings can use that space.
286 .Sh SAY STRINGS
287 The
288 .Dq SAY
289 directive allows the script to send strings to the user
290 at the terminal via standard error.
291 If
292 .Nm
293 is being run by
294 pppd, and pppd is running as a daemon (detached from its controlling
295 terminal), standard error will normally be redirected to the file
296 .Pa /etc/ppp/connect-errors .
297 .Pp
298 .Dq SAY
299 strings must be enclosed in single or double quotes.
300 If carriage return and line feed are needed in the string to be output,
301 you must explicitly add them to your string.
302 .Pp
303 The
304 .Dq SAY
305 strings could be used to give progress messages in sections of
306 the script where you want to have
307 .Sq ECHO OFF
308 but still let the user know what is happening.
309 An example is:
310 .Bd -literal -offset indent
311 ABORT BUSY
312 ECHO OFF
313 SAY "Dialling your ISP...\\n"
314 .br
315 \&'' ATDT5551212
316 TIMEOUT 120
317 SAY "Waiting up to 2 min. for connection... "
318 CONNECT ''
319 SAY "Connected, now logging in...\\n"
320 ogin: account
321 ssword: pass
322 $ \c
323 SAY "Logged in OK ...\\n"
324 \&...
325 .Ed
326 .Pp
327 This sequence will only present the SAY strings to the user and all
328 the details of the script will remain hidden.
329 For example, if the above script works, the user will see:
330 .Bd -literal -offset indent
331 Dialling your ISP...
332 Waiting up to 2 min. for connection... Connected, now logging in...
333 Logged in OK ...
334 .Ed
335 .Sh REPORT STRINGS
336 A
337 .Dq report
338 string is similar to the ABORT string.
339 The difference
340 is that the strings, and all characters to the next control character
341 such as a carriage return, are written to the report file.
342 .Pp
343 The report strings may be used to isolate the transmission rate of the
344 modem's connect string and return the value to the chat user.
345 The analysis of the report string logic occurs in conjunction with the
346 other string processing such as looking for the expect string.
347 The use of the same string for a report and abort sequence is probably not
348 very useful, however, it is possible.
349 .Pp
350 The report strings to no change the completion code of the program.
351 .Pp
352 These
353 .Dq report
354 strings may be specified in the script using the
355 .Dq REPORT
356 sequence.
357 It is written in the script as in the following example:
358 .Pp
359 .Dl REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account
360 .Pp
361 This sequence will expect nothing; and then send the string
362 ATDT5551212 to dial the telephone.
363 The expected string is
364 .Dq CONNECT .
365 If the string
366 .Dq CONNECT
367 is received the remainder of the script is executed.
368 In addition the program will write to the expect-file the string
369 .Dq CONNECT
370 plus any characters which follow it such as the connection rate.
371 .Sh CLR_REPORT STRINGS
372 This sequence allows for clearing previously set
373 .Dq REPORT
374 strings.
375 .Dq REPORT
376 strings are kept in an array of a pre-determined size (at compilation time);
377 .Dq CLR_REPORT
378 will reclaim the space for cleared
379 entries so that new strings can use that space.
380 .Sh ECHO
381 The echo options controls whether the output from the modem is echoed
382 to stderr.
383 This option may be set with the
384 .Fl e
385 option, but it can also be controlled by the
386 .Dq ECHO
387 keyword.
388 The
389 .Dq expect-send
390 pair
391 .Dq ECHO ON
392 enables echoing, and
393 .Dq ECHO OFF
394 disables it.
395 With this keyword you can select which parts of the
396 conversation should be visible.
397 For instance, with the following script:
398 .Bd -literal -offset indent
399 ABORT 'BUSY'
400 ABORT 'NO CARRIER'
401 .br
402 \&'' ATZ
403 OK\\r\\n ATD1234567
404 \\r\\n \\c
405 ECHO ON
406 CONNECT \\c
407 ogin: account
408 .Ed
409 .Pp
410 all output resulting from modem configuration and dialing is not visible,
411 but starting with the
412 .Dq CONNECT
413 (or
414 .Dq BUSY )
415 message, everything will be echoed.
416 .Sh HANGUP
417 The HANGUP options control whether a modem hangup should be considered
418 as an error or not. This option is useful in scripts for dialling
419 systems which will hang up and call your system back. The HANGUP
420 options can be
421 .Dq ON
422 or
423 .Dq OFF .
424 .Pp
425 When HANGUP is set OFF and the modem hangs up (e.g., after the first
426 stage of logging in to a callback system),
427 .Nm
428 will continue
429 running the script (e.g.\&, waiting for the incoming call and second
430 stage login prompt). As soon as the incoming call is connected, you
431 should use the
432 .Dq HANGUP ON
433 directive to reinstall normal hang up signal behavior.
434 Here is a (simple) example script:
435 .Bd -literal -offset indent
436 ABORT 'BUSY'
437 .br
438 \&'' ATZ
439 OK\\r\\n ATD1234567
440 \\r\\n \\c
441 CONNECT \\c
442 .br
443 \&'Callback login:' call_back_ID
444 HANGUP OFF
445 ABORT "Bad Login"
446 .br
447 \&'Callback Password:' Call_back_password
448 TIMEOUT 120
449 CONNECT \\c
450 HANGUP ON
451 ABORT "NO CARRIER"
452 ogin:--BREAK--ogin: real_account
453 \&...
454 .Ed
455 .Sh TIMEOUT
456 The initial timeout value is 45 seconds.
457 This may be changed using the
458 .Fl t
459 parameter.
460 .Pp
461 To change the timeout value for the next expect string, the following
462 example may be used:
463 .Pp
464 .Dl ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2
465 .Pp
466 This will change the timeout to 10 seconds when it expects the login:
467 prompt.
468 The timeout is then changed to 5 seconds when it looks for the
469 password prompt.
470 .Pp
471 The timeout, once changed, remains in effect until it is changed again.
472 .Sh SENDING EOT
473 The special reply string of
474 .Dq EOT
475 indicates that the chat program should send an EOT character to the remote.
476 This is normally the End-of-file character sequence.
477 A return character is not sent following the EOT.
478 .Pp
479 The EOT sequence may be embedded into the send string using the
480 sequence
481 .Dq ^D .
482 .Sh GENERATING BREAK
483 The special reply string of
484 .Dq BREAK
485 will cause a break condition to be sent.
486 The break is a special signal on the transmitter.
487 The normal processing on the receiver is to change the transmission rate.
488 It may be used to cycle through the available transmission rates on
489 the remote until you are able to receive a valid login prompt.
490 .Pp
491 The break sequence may be embedded into the send string using the
492 .Dq \eK
493 sequence.
494 .Sh ESCAPE SEQUENCES
495 The expect and reply strings may contain escape sequences.
496 All of the sequences are legal in the reply string.
497 Many are legal in the expect.
498 Those which are not valid in the expect sequence are so indicated.
499 .Bl -tag -width ".Li \e\e000"
500 .It Li ''
501 Expects or sends a null string.
502 If you send a null string then it will still send the return character.
503 This sequence may either be a pair of apostrophe or quote characters.
504 .It Li \eb
505 represents a backspace character.
506 .It Li \ec
507 Suppresses the newline at the end of the reply string.
508 This is the only method to send a string without a trailing return character.
509 It must be at the end of the send string.
510 For example,
511 the sequence hello\ec will simply send the characters h, e, l, l, o.
512 .Em ( not valid in expect . )
513 .It Li \ed
514 Delay for one second.
515 The program uses
516 .Xr sleep 1
517 which will delay to a maximum of one second.
518 .Em ( not valid in expect . )
519 .It Li \eK
520 Insert a BREAK
521 .Em ( not valid in expect . )
522 .It Li \en
523 Send a newline or linefeed character.
524 .It Li \eN
525 Send a null character.
526 The same sequence may be represented by \e0.
527 .Em ( not valid in expect . )
528 .It Li \ep
529 Pause for a fraction of a second.
530 The delay is 1/10th of a second.
531 .Em ( not valid in expect . )
532 .It Li \eq
533 Suppress writing the string to
534 .Xr syslogd 8 .
535 The string ?????? is
536 written to the log in its place.
537 .Em ( not valid in expect . )
538 .It Li \er
539 Send or expect a carriage return.
540 .It Li \es
541 Represents a space character in the string.
542 This may be used when it
543 is not desirable to quote the strings which contains spaces.
544 The sequence
545 .Sq HI TIM
546 and
547 .Sq HI\esTIM
548 are the same.
549 .It Li \et
550 Send or expect a tab character.
551 .It Li \e\e
552 Send or expect a backslash character.
553 .It Li \e\eddd
554 Collapse the octal digits (ddd) into a single ASCII character and send that
555 character.
556 .Em ( some characters are not valid in expect . )
557 .It Li ^C
558 Substitute the sequence with the control character represented by C.
559 For example, the character DC1 (17) is shown as ^Q.
560 .Em ( some characters are not valid in expect . )
561 .El
562 .Sh TERMINATION CODES
563 The
564 .Nm
565 program will terminate with the following completion codes.
566 .Bl -tag -width ".Li ..."
567 .It Li 0
568 The normal termination of the program.
569 This indicates that the script
570 was executed without error to the normal conclusion.
571 .It Li 1
572 One or more of the parameters are invalid or an expect string was too
573 large for the internal buffers.
574 This indicates that the program as not properly executed.
575 .It Li 2
576 An error occurred during the execution of the program.
577 This may be due
578 to a read or write operation failing for some reason or chat receiving
579 a signal such as
580 .Dv SIGINT .
581 .It Li 3
582 A timeout event occurred when there was an
583 .Dq expect
584 string without having a
585 .Dq -subsend
586 string.
587 This may mean that you did not program the
588 script correctly for the condition or that some unexpected event has
589 occurred and the expected string could not be found.
590 .It Li 4
591 The first string marked as an
592 .Dq ABORT
593 condition occurred.
594 .It Li 5
595 The second string marked as an
596 .Dq ABORT
597 condition occurred.
598 .It Li 6
599 The third string marked as an
600 .Dq ABORT
601 condition occurred.
602 .It Li 7
603 The fourth string marked as an
604 .Dq ABORT
605 condition occurred.
606 .It Li ...
607 The other termination codes are also strings marked as an
608 .Dq ABORT
609 condition.
610 .El
611 .Pp
612 Using the termination code, it is possible to determine which event
613 terminated the script.
614 It is possible to decide if the string
615 .Dq BUSY
616 was received from the modem as opposed to
617 .Dq NO DIAL TONE .
618 While the first event may be retried, the second will probably have little
619 chance of succeeding during a retry.
620 .Sh SEE ALSO
621 .Xr uucico 1 ,
622 .Xr uucp 1 ,
623 .Xr syslog 3 ,
624 .Xr syslogd 8
625 .Pp
626 Additional information about
627 .Nm
628 scripts may be found with UUCP documentation.
629 The
630 .Nm
631 script was taken from the ideas proposed by the scripts used by the
632 .Xr uucico 1
633 program.
634 .Sh COPYRIGHT
635 The
636 .Nm
637 program is in public domain.
638 This is not the GNU public license.
639 If it breaks then you get to keep both pieces.