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