7 .Nd Automated conversational script with a modem
12 .Op Fl r Ar report-file
13 .Op Fl T Ar phone-number
15 .Op Fl U Ar phone-number2
20 program defines a conversational exchange between the
21 computer and the modem.
22 Its primary purpose is to establish the
23 connection between the Point-to-Point Protocol Daemon
25 and the remote's pppd process.
27 .Bl -tag -width indent
29 Start with the echo option turned on.
30 Echoing may also be turned on
31 or off at specific points in the chat script by using the ECHO
33 When echoing is enabled, all output from the modem is echoed
37 Read the chat script from the chat file.
38 The use of this option
39 is mutually exclusive with the chat script parameters.
41 have read access to the file.
42 Multiple lines are permitted in the file.
43 Space or horizontal tab characters should be used to separate
45 .It Fl r Ar report-file
46 Set the file for output of the report strings.
47 If you use the keyword
49 the resulting strings are written to this file.
51 option is not used and you still use
55 file is used for the report strings.
59 By default, error messages are sent to
63 will prevent both log messages from
65 and error messages from being sent to
72 and all error messages will be
75 .It Fl T Ar phone-number
76 Pass in an arbitrary string, usually a phone number, that will be
77 substituted for the \\T substitution metacharacter in a send string.
79 Set the timeout for the expected string to be received.
81 is not received within the time limit then the reply string is not
83 An alternate reply may be sent or the script will fail if there
84 is no alternate reply string.
85 A failed script will cause the
87 program to terminate with a non-zero error code.
88 .It Fl U Ar phone-number2
89 Pass in a second string, usually a phone number, that will be
90 substituted for the \\U substitution metacharacter in a send string.
91 This is useful when dialing an ISDN terminal adapter that requires two
96 script be executed in a
101 program will then log all text received from the
102 modem and the output strings sent to the modem to the stderr device.
104 device is usually the local console at the station running the chat or
109 script be executed in a verbose mode.
112 program will then log the execution state of the chat
113 script as well as all text received from the modem and the output
114 strings sent to the modem.
115 The default is to log through
117 the logging method may be altered with the
122 Logging is done to the
126 for verbose tracing and level
133 script defines the communications.
134 A script consists of one or more "expect-send" pairs of strings,
135 separated by spaces, with an optional "subexpect-subsend" string pair,
136 separated by a dash as in the following example:
138 .D1 ogin:-BREAK-ogin: ppp ssword: hello2u2
140 This line indicates that the
142 program should expect the string "ogin:".
143 If it fails to receive a login prompt within the time interval
144 allotted, it is to send a break sequence to the remote and then expect the
146 If the first "ogin:" is received then the break sequence is
149 Once it received the login prompt the
151 program will send the
152 string ppp and then expect the prompt "ssword:".
154 prompt for the password, it will send the password hello2u2.
156 A carriage return is normally sent following the reply string.
158 expected in the "expect" string unless it is specifically requested by using
159 the \\r character sequence.
161 The expect sequence should contain only what is needed to identify the
163 Since it is normally stored on a disk file, it should not contain
164 variable information.
165 It is generally not acceptable to look for time
166 strings, network identification strings, or other variable pieces of data as
169 To help correct for characters which may be corrupted during the initial
170 sequence, look for the string "ogin:" rather than "login:".
172 that the leading "l" character may be received in error and you may never
173 find the string even though it was sent by the system.
175 scripts look for "ogin:" rather than "login:" and "ssword:" rather than
178 A very simple script might look like this:
180 .D1 ogin: ppp ssword: hello2u2
182 In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2.
184 In actual practice, simple scripts are rare.
185 At the vary least, you
186 should include sub-expect sequences should the original string not be
188 For example, consider the following script:
190 .D1 ogin:--ogin: ppp ssword: hello2u2
192 This would be a better script than the simple one used earlier.
194 for the same login: prompt, however, if one was not received, a single
195 return sequence is sent and then it will look for login: again.
197 noise obscure the first login prompt then sending the empty line will
198 usually generate a login prompt again.
200 Comments can be embedded in the chat script.
201 A comment is a line which
202 starts with the # (hash) character in column 1.
204 lines are just ignored by the chat program.
205 If a '#' character is to
206 be expected as the first character of the expect sequence, you should
207 quote the expect string.
208 If you want to wait for a prompt that starts with a # (hash)
209 character, you would have to write something like this:
210 .Bd -literal -offset indent
211 # Now wait for the prompt and send logout string
215 Many modems will report the status of the call as a string.
222 It is often desirable to terminate the script should the modem fail to
223 connect to the remote.
224 The difficulty is that a script would not know
225 exactly which modem string it may receive.
226 On one attempt, it may receive
228 while the next time it may receive
231 These "abort" strings may be specified in the script using the ABORT
233 It is written in the script as in the following example:
235 .D1 ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT
237 This sequence will expect nothing; and then send the string ATZ.
238 The expected response to this is the string
242 the string ATDT5551212 to dial the telephone.
243 The expected string is
247 is received the remainder of the
249 However, should the modem find a busy telephone, it will
252 This will cause the string to match the abort
254 The script will then fail because it found a match to
256 If it received the string
260 Either string may be received.
265 .Sh CLR_ABORT STRINGS
266 This sequence allows for clearing previously set
270 strings are kept in an array of a pre-determined size (at
271 compilation time); CLR_ABORT will reclaim the space for cleared
272 entries so that new strings can use that space.
276 directive allows the script to send strings to the user
277 at the terminal via standard error.
281 pppd, and pppd is running as a daemon (detached from its controlling
282 terminal), standard error will normally be redirected to the file
283 .Pa /etc/ppp/connect-errors .
286 strings must be enclosed in single or double quotes.
287 If carriage return and line feed are needed in the string to be output,
288 you must explicitly add them to your string.
292 strings could be used to give progress messages in sections of
293 the script where you want to have 'ECHO OFF' but still let the user
294 know what is happening.
296 .Bd -literal -offset indent
299 SAY "Dialling your ISP...\\n"
302 SAY "Waiting up to 2 minutes for connection ... "
304 SAY "Connected, now logging in ...\\n"
307 $ SAY "Logged in OK ...\\n" \fIetc ...\fR
310 This sequence will only present the
312 strings to the user and all
313 the details of the script will remain hidden.
315 above script works, the user will see:
316 .Bd -literal -offset indent
318 Waiting up to 2 minutes for connection ... Connected, now logging in ...
322 A report string is similar to the
326 is that the strings, and all characters to the next control character
327 such as a carriage return, are written to the report file.
329 The report strings may be used to isolate the transmission rate of the
330 modem's connect string and return the value to the chat user.
332 analysis of the report string logic occurs in conjunction with the
333 other string processing such as looking for the expect string.
335 of the same string for a report and abort sequence is probably not
336 very useful, however, it is possible.
338 The report strings to no change the completion code of the program.
340 These "report" strings may be specified in the script using the
343 It is written in the script as in the following example:
345 .D1 REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account
347 This sequence will expect nothing; and then send the string
348 ATDT5551212 to dial the telephone.
349 The expected string is
353 is received the remainder
354 of the script is executed.
355 In addition the program will write to the
356 expect-file the string "CONNECT" plus any characters which follow it
357 such as the connection rate.
358 .Sh CLR_REPORT STRINGS
359 This sequence allows for clearing previously set
363 strings are kept in an array of a pre-determined size (at
364 compilation time); CLR_REPORT will reclaim the space for cleared
365 entries so that new strings can use that space.
367 The echo options controls whether the output from the modem is echoed
370 This option may be set with the
373 it can also be controlled by the
382 With this keyword you can select which parts of the
383 conversation should be visible.
384 For instance, with the following
386 .Bd -literal -offset indent
397 all output resulting from modem configuration and dialing is not visible,
398 but starting with the
407 options control whether a modem hangup should be considered
409 This option is useful in scripts for dialling
410 systems which will hang up and call your system back.
422 and the modem hangs up (e.g., after the first
423 stage of logging in to a callback system),
426 running the script (e.g., waiting for the incoming call and second
428 As soon as the incoming call is connected, you
431 directive to reinstall normal hang up
433 Here is a (simple) example script:
434 .Bd -literal -offset indent
440 \&'Callback login:' call_back_ID
443 \&'Callback Password:' Call_back_password
448 ogin:--BREAK--ogin: real_account
452 The initial timeout value is 45 seconds.
453 This may be changed using the
457 To change the timeout value for the next expect string, the following
459 .Bd -literal -offset indent
460 ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2
463 This will change the timeout to 10 seconds when it expects the login:
465 The timeout is then changed to 5 seconds when it looks for the
468 The timeout, once changed, remains in effect until it is changed again.
470 The special reply string of
472 indicates that the chat program
475 character to the remote.
477 End-of-file character sequence.
478 A return character is not sent
484 sequence may be embedded into the send string using the
487 The special reply string of
489 will cause a break condition
491 The break is a special signal on the transmitter.
493 normal processing on the receiver is to change the transmission rate.
494 It may be used to cycle through the available transmission rates on
495 the remote until you are able to receive a valid login prompt.
497 The break sequence may be embedded into the send string using the
500 The expect and reply strings may contain escape sequences.
502 sequences are legal in the reply string.
503 Many are legal in the expect.
504 Those which are not valid in the expect sequence are so indicated.
505 .Bl -tag -width indent
507 Expects or sends a null string.
508 If you send a null string then it will still
509 send the return character.
510 This sequence may either be a pair of apostrophe
513 represents a backspace character.
515 Suppresses the newline at the end of the reply string.
517 method to send a string without a trailing return character.
519 be at the end of the send string.
521 the sequence hello\\c will simply send the characters h, e, l, l, o
522 .Pq Em not valid in expect .
524 Delay for one second.
525 The program uses sleep(1) which will delay to a
526 maximum of one second
527 .Pq Em not valid in expect .
531 .Pq Em not valid in expect .
533 Send a newline or linefeed character.
535 Send a null character.
536 The same sequence may be represented by \\0
537 .Pq Em not valid in expect .
539 Pause for a fraction of a second.
540 The delay is 1/10th of a second
541 .Pq Em not valid in expect .
543 Suppress writing the string to
546 written to the log in its place
547 .Pq Em not valid in expect .
549 Send or expect a carriage return.
551 Represents a space character in the string.
552 This may be used when it
553 is not desirable to quote the strings which contains spaces.
555 sequence 'HI TIM' and HI\\sTIM are the same.
557 Send or expect a tab character.
559 Send or expect a backslash character.
561 Collapse the octal digits (ddd) into a single ASCII character and send that
563 .Pq Em some characters are not valid in expect .
565 Substitute the sequence with the control character represented by C.
566 For example, the character DC1 (17) is shown as \^^Q
567 .Pq Em some characters are not valid in expect .
569 .Sh TERMINATION CODES
572 program will terminate with the following completion
574 .Bl -tag -width indent
576 The normal termination of the program.
577 This indicates that the script
578 was executed without error to the normal conclusion.
580 One or more of the parameters are invalid or an expect string was too
581 large for the internal buffers.
582 This indicates that the program as not
585 An error occurred during the execution of the program.
587 to a read or write operation failing for some reason or chat receiving
591 A timeout event occurred when there was an
594 having a "-subsend" string.
595 This may mean that you did not program the
596 script correctly for the condition or that some unexpected event has
597 occurred and the expected string could not be found.
599 The first string marked as an
603 The second string marked as an
607 The third string marked as an
611 The fourth string marked as an
615 The other termination codes are also strings marked as an
620 Using the termination code, it is possible to determine which event
621 terminated the script.
622 It is possible to decide if the string "BUSY"
623 was received from the modem as opposed to "NO DIAL TONE".
625 first event may be retried, the second will probably have little
626 chance of succeeding during a retry.
628 Additional information about
630 scripts may be found with UUCP
634 script was taken from the ideas proposed
635 by the scripts used by the uucico program.
642 program is in public domain.
643 This is not the GNU public
645 If it breaks then you get to keep both pieces.