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. An example is:
295 .Bd -literal -offset indent
298 SAY "Dialling your ISP...\\n"
301 SAY "Waiting up to 2 minutes for connection ... "
303 SAY "Connected, now logging in ...\\n"
306 $ SAY "Logged in OK ...\\n" \fIetc ...\fR
309 This sequence will only present the
311 strings to the user and all
312 the details of the script will remain hidden.
314 above script works, the user will see:
315 .Bd -literal -offset indent
317 Waiting up to 2 minutes for connection ... Connected, now logging in ...
321 A report string is similar to the
325 is that the strings, and all characters to the next control character
326 such as a carriage return, are written to the report file.
328 The report strings may be used to isolate the transmission rate of the
329 modem's connect string and return the value to the chat user.
331 analysis of the report string logic occurs in conjunction with the
332 other string processing such as looking for the expect string.
334 of the same string for a report and abort sequence is probably not
335 very useful, however, it is possible.
337 The report strings to no change the completion code of the program.
339 These "report" strings may be specified in the script using the
342 It is written in the script as in the following example:
344 .D1 REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account
346 This sequence will expect nothing; and then send the string
347 ATDT5551212 to dial the telephone.
348 The expected string is
352 is received the remainder
353 of the script is executed.
354 In addition the program will write to the
355 expect-file the string "CONNECT" plus any characters which follow it
356 such as the connection rate.
357 .Sh CLR_REPORT STRINGS
358 This sequence allows for clearing previously set
362 strings are kept in an array of a pre-determined size (at
363 compilation time); CLR_REPORT will reclaim the space for cleared
364 entries so that new strings can use that space.
366 The echo options controls whether the output from the modem is echoed
369 This option may be set with the
372 it can also be controlled by the
381 With this keyword you can select which parts of the
382 conversation should be visible.
383 For instance, with the following
385 .Bd -literal -offset indent
396 all output resulting from modem configuration and dialing is not visible,
397 but starting with the
406 options control whether a modem hangup should be considered
408 This option is useful in scripts for dialling
409 systems which will hang up and call your system back.
421 and the modem hangs up (e.g., after the first
422 stage of logging in to a callback system),
425 running the script (e.g., waiting for the incoming call and second
427 As soon as the incoming call is connected, you
430 directive to reinstall normal hang up
432 Here is a (simple) example script:
433 .Bd -literal -offset indent
439 \&'Callback login:' call_back_ID
442 \&'Callback Password:' Call_back_password
447 ogin:--BREAK--ogin: real_account
451 The initial timeout value is 45 seconds.
452 This may be changed using the
456 To change the timeout value for the next expect string, the following
458 .Bd -literal -offset indent
459 ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2
462 This will change the timeout to 10 seconds when it expects the login:
464 The timeout is then changed to 5 seconds when it looks for the
467 The timeout, once changed, remains in effect until it is changed again.
469 The special reply string of
471 indicates that the chat program
474 character to the remote.
476 End-of-file character sequence.
477 A return character is not sent
483 sequence may be embedded into the send string using the
486 The special reply string of
488 will cause a break condition
490 The break is a special signal on the transmitter.
492 normal processing on the receiver is to change the transmission rate.
493 It may be used to cycle through the available transmission rates on
494 the remote until you are able to receive a valid login prompt.
496 The break sequence may be embedded into the send string using the
499 The expect and reply strings may contain escape sequences.
501 sequences are legal in the reply string.
502 Many are legal in the expect.
503 Those which are not valid in the expect sequence are so indicated.
504 .Bl -tag -width indent
506 Expects or sends a null string.
507 If you send a null string then it will still
508 send the return character.
509 This sequence may either be a pair of apostrophe
512 represents a backspace character.
514 Suppresses the newline at the end of the reply string.
516 method to send a string without a trailing return character.
518 be at the end of the send string.
520 the sequence hello\\c will simply send the characters h, e, l, l, o
521 .Pq Em not valid in expect .
523 Delay for one second.
524 The program uses sleep(1) which will delay to a
525 maximum of one second
526 .Pq Em not valid in expect .
530 .Pq Em not valid in expect .
532 Send a newline or linefeed character.
534 Send a null character.
535 The same sequence may be represented by \\0
536 .Pq Em not valid in expect .
538 Pause for a fraction of a second.
539 The delay is 1/10th of a second
540 .Pq Em not valid in expect .
542 Suppress writing the string to
545 written to the log in its place
546 .Pq Em not valid in expect .
548 Send or expect a carriage return.
550 Represents a space character in the string.
551 This may be used when it
552 is not desirable to quote the strings which contains spaces.
554 sequence 'HI TIM' and HI\\sTIM are the same.
556 Send or expect a tab character.
558 Send or expect a backslash character.
560 Collapse the octal digits (ddd) into a single ASCII character and send that
562 .Pq Em some characters are not valid in expect .
564 Substitute the sequence with the control character represented by C.
565 For example, the character DC1 (17) is shown as \^^Q
566 .Pq Em some characters are not valid in expect .
568 .Sh TERMINATION CODES
571 program will terminate with the following completion
573 .Bl -tag -width indent
575 The normal termination of the program.
576 This indicates that the script
577 was executed without error to the normal conclusion.
579 One or more of the parameters are invalid or an expect string was too
580 large for the internal buffers.
581 This indicates that the program as not
584 An error occurred during the execution of the program.
586 to a read or write operation failing for some reason or chat receiving
590 A timeout event occurred when there was an
593 having a "-subsend" string.
594 This may mean that you did not program the
595 script correctly for the condition or that some unexpected event has
596 occurred and the expected string could not be found.
598 The first string marked as an
602 The second string marked as an
606 The third string marked as an
610 The fourth string marked as an
614 The other termination codes are also strings marked as an
619 Using the termination code, it is possible to determine which event
620 terminated the script.
621 It is possible to decide if the string "BUSY"
622 was received from the modem as opposed to "NO DIAL TONE".
624 first event may be retried, the second will probably have little
625 chance of succeeding during a retry.
627 Additional information about
629 scripts may be found with UUCP
633 script was taken from the ideas proposed
634 by the scripts used by the uucico program.
641 program is in public domain.
642 This is not the GNU public
644 If it breaks then you get to keep both pieces.