1chat(1M) System Administration Commands chat(1M)
2
6 chat - automated conversational exchange tool
7
9 chat [options] script
10
13 The chat program implements a conversational text-based exchange
14 between the computer and any serial device, including (but not limited
15 to) a modem, an ISDN TA, and the remote peer itself, establishing a
16 connection between the Point-To-Point Protocol daemon (pppd) and the
17 remote pppd process.
18
20 The chat command supports the following options:
21 -f <chat file> Read the chat script from the chat file. This
23 option is mutually exclusive with the chat
24 script parameters. You must have read access to
25 use the file. Multiple lines are permitted in
26 the file. Use the space or horizontal tab char‐
27 acters to separate the strings.
28 -t <timeout> Set the timeout for the expected string to be
31 received. If the string is not received within
32 the time limit, the reply string is not sent. If
33 specified, a 'subexpect' (alternate reply)
34 string can be sent. Otherwise, if no alternate
35 reply strings remain, the chat script fails.. A
36 failed script will cause the chat program to
37 terminate with a non-zero error code.
38 -r <report file> Set the file for output of the report strings.
41 If you use the keyword REPORT, the resulting
42 strings are written to this file. If the -r
43 option is not used and you use the REPORT key‐
44 word, the stderr file is used for the report
45 strings.
46 -e Start with the echo option turned on. You turn
49 echo on or off at specific points in the chat
50 script using the ECHO keyword. When echoing is
51 enabled, all output from the modem is echoed to
52 stderr.
53 -E Enables environment variable substitution within
56 chat scripts using the standard $xxx syntax.
57 -v Request that the chat script execute in a ver‐
60 bose mode. The chat program logs the execution
61 state of the chat script as well as all text
62 received from the modem and output strings sent
63 to the modem. The default is to log through sys‐
64 log(3C) with facility local2; the logging method
65 is alterable using the -S and -s options.
66 -V Request that the chat script be executed in a
69 stderr verbose mode. The chat program logs all
70 text received from the modem and output strings
71 sent to the modem to stderr. stderr is usually
72 the local console at the station running the
73 chat or pppd program.
74 -s Use stderr. Log messages from -v and error mes‐
77 sages are sent to stderr.
78 -S Do not use syslog. By default, error messages
81 are set to syslog. This option prevents log mes‐
82 sages from -v and error messages from being sent
83 to syslog.
84 -T <phone number> Pass in an arbitrary string (usually a telephone
87 number) that will be substituted for the \T sub‐
88 stitution metacharacter in a send string.
89 -U <phone number 2> Pass in a second string (usually a telephone
92 number) that will be substituted for the \U sub‐
93 stitution metacharacter in a send string. This
94 is useful when dialing an ISDN terminal adapter
95 that requires two numbers.
96 script If the script is not specified in a file with
99 the -f option, the script is included as parame‐
100 ters to the chat program.
101
104 Chat Script
105 The chat script defines communications. A script consists of one or
106 more "expect-send" pairs of strings separated by spaces, with an
107 optional "subexpect-subsend" string pair, separated by a dash (as in
108 the following example:)
109 ogin:-BREAK-ogin: ppp ssword: hello2u2
112 The example indicates that the chat program should expect the string
115 "ogin:". If it fails to receive a login prompt within the time interval
116 allotted, it sends a break sequence to the remote and then expects the
117 string "ogin:". If the first "ogin:" is received, the break sequence is
118 not generated.
119 Upon receiving the login prompt, the chat program sends the string
122 "ppp" and then expects the prompt "ssword:". When the password prompt
123 is received, it sends the password hello2u2.
124 A carriage return is normally sent following the reply string. It is
127 not expected in the "expect" string unless it is specifically requested
128 by using the \r character sequence.
129 The expect sequence should contain only what is needed to identify the
132 received data. Because it's stored on a disk file, it should not con‐
133 tain variable information. Generally it is not acceptable to look for
134 time strings, network identification strings, or other variable pieces
135 of data as an expect string.
136 To correct for characters that are corrupted during the initial
139 sequence, look for the string "ogin:" rather than "login:". The leading
140 "l" character may be received in error, creating problems in finding
141 the string. For this reason, scripts look for "ogin:" rather than
142 "login:" and "ssword:" rather than "password:".
143 An example of a simple script follows:
146 ogin: ppp ssword: hello2u2
148 The example can be intrepreted as: expect ogin:, send ppp, expect
152 ...ssword:, send hello2u2.
153 When login to a remote peer is necessary, simple scripts are rare. At
156 minimum, you should include sub-expect sequences in case the original
157 string is not received. For example, consider the following script:
158 ogin:--ogin: ppp ssword: hello2u2
160 This script is more effective than the simple one used earlier. The
164 string looks for the same login prompt; however, if one is not
165 received, a single return sequence is sent and then the script looks
166 for login: again. If line noise obscures the first login prompt, send
167 the empty line to generate a login prompt again.
168 Comments
170 Comments can be embedded in the chat script. Comment lines are ignored
171 by the chat program. A comment starts with the hash ("#") character in
172 column one. If a # character is expected as the first character of the
173 expect sequence, quote the expect string. If you want to wait for a
174 prompt that starts with a # character, write something like this:
175 # Now wait for the prompt and send logout string
177 '# ' logout
178 Sending Data From A File
181 If the string to send begins with an at sign ("@"), the remainder of
182 the string is interpreted as the name of the file that contains the
183 string. If the last character of the data read is a newline, it is
184 removed. The file can be a named pipe (or fifo) instead of a regular
185 file. This enables chat to communicate with another program, for exam‐
186 ple, a program to prompt the user and receive a password typed in.
187 Abort
189 Many modems report the status of a call as a string. These status
190 strings are often "CONNECTED" or "NO CARRIER" or "BUSY." If the modem
191 fails to connect to the remote, you can terminate the script. Abort
192 strings may be specified in the script using the ABORT sequence. For
193 example:
194 ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT
196 This sequence expects nothing and sends the string ATZ. The expected
200 response is the string OK. When OK is received, the string ATDT5551212
201 dials the telephone. The expected string is CONNECT. If CONNECT is
202 received, the remainder of the script is executed. When the modem finds
203 a busy telephone, it sends the string BUSY, causing the string to match
204 the abort character sequence. The script fails because it found a match
205 to the abort string. If the NO CARRIER string is received, it aborts
206 for the same reason.
207 Clr_Abort
209 The CLR_ABORT sequence clears previously set ABORT strings. ABORT
210 strings are kept in an array of a pre-determined size; CLR_ABORT
211 reclaims the space for cleared entries, enabling new strings to use
212 that space.
213 Say
215 The SAY string enables the script to send strings to a user at a termi‐
216 nal via standard error. If chat is being run by pppd and pppd is run‐
217 ning as a daemon (detached from its controlling terminal), standard
218 error is normally redirected to the /etc/ppp/connect-errors file.
219 SAY strings must be enclosed in single or double quotes. If carriage
222 return and line feed are required for the output, you must explicitly
223 add them to your string.
224 The SAY string can provide progress messages to users even with "ECHO
227 OFF." For example, add a line similar to the following to the script:
228 ABORT BUSY
230 ECHO OFF
231 SAY "Dialing your ISP...\n"
232 '' ATDT5551212
233 TIMEOUT 120
234 SAY "Waiting up to 2 minutes for connection ..."
235 CONNECT ''
236 SAY "Connected, now logging in ...\n"
237 ogin: account
238 ssword: pass
239 $ \c
240 SAY "Logged in OK ... \n"
241 This sequence hides script detail while presenting the SAY string to
245 the user. In this case, you will see:
246 Dialing your ISP...
248 Waiting up to 2 minutes for connection...Connected, now logging in...
249 Logged in OK ...
250 Report
253 REPORT is similar to the ABORT string. With REPORT, however, strings
254 and all characters to the next control character (such as a carriage
255 return), are written to the report file.
256 REPORT strings can be used to isolate a modem's transmission rate from
259 its CONNECT string and return the value to the chat user. Analysis of
260 the REPORT string logic occurs in conjunction with other string pro‐
261 cessing, such as looking for the expect string. It's possible to use
262 the same string for a REPORT and ABORT sequence, but probably not use‐
263 ful.
264 Report strings may be specified in the script using the REPORT
267 sequence. For example:
268 REPORT CONNECT
270 ABORT BUSY
271 ATDT5551212 CONNECT
272 ogin: account
273 The above sequence expects nothing, then sends the string ATDT5551212
277 to dial the telephone. The expected string is CONNECT. If CONNECT is
278 received, the remainder of the script is executed. In addition, the
279 program writes the string CONNECT to the report file (specified by -r)
280 in addition to any characters that follow.
281 Clr_Report
283 CLR_REPORT clears previously set REPORT strings. REPORT strings are
284 kept in an array of a pre-determined size; CLR_REPORT reclaims the
285 space for cleared entries so that new strings can use that space.
286 Echo
288 ECHO determines if modem output is echoed to stderr. This option may be
289 set with the -e option, but can also be controlled by the ECHO keyword.
290 The "expect-send" pair ECHO ON enables echoing, and ECHO OFF disables
291 it. With ECHO, you can select which parts of the conversation should be
292 visible. In the following script:
293 ABORT 'BUSY'
295 ABORT 'NO CARRIER'
296 "" AT&F
297 OK\r\n ATD1234567
298 \r\n \c
299 ECHO ON
300 CONNECT \c
301 ogin: account
302 All output resulting from modem configuration and dialing is not visi‐
306 ble, but output is echoed beginning with the CONNECT (or BUSY) message.
307 Hangup
309 The HANGUP option determines if a modem hangup is considered as an
310 error. HANGUP is useful for dialing systems that hang up and call your
311 system back. HANGUP can be ON or OFF. When HANGUP is set to OFF and the
312 modem hangs up (for example, following the first stage of logging in to
313 a callback system), chat continues running the script (for example,
314 waiting for the incoming call and second stage login prompt). When the
315 incoming call is connected, use the HANGUP ON string to reinstall nor‐
316 mal hang up signal behavior. An example of a simple script follows:
317 ABORT 'BUSY'
319 "" AT&F
320 OK\r\n ATD1234567
321 \r\n \c
322 CONNECT \c
323 'Callback login:' call_back_ID
324 HANGUP OFF
325 ABORT "Bad Login"
326 'Callback Password:' Call_back_password
327 TIMEOUT 120
328 CONNECT \c
329 HANGUP ON
330 ABORT "NO CARRIER"
331 ogin:--BREAK--ogin: real_account
332 Timeout
335 The initial timeout value is 45 seconds. Use the -t parameter to change
336 the intial timeout value.
337 To change the timeout value for the next expect string, the following
340 example can be used:
341 ''"AT&F
343 OK ATDT5551212
344 CONNECT \c
345 TIMEOUT 10
346 ogin:--ogin: username
347 TIMEOUT 5
348 assword: hello2u2
349 The example changes the timeout to ten seconds when it expects the
353 login: prompt. The timeout is changed to five seconds when it looks for
354 the password prompt.
355 Once changed, the timeout value remains in effect until it is changed
358 again.
359 EOT
361 The EOT special reply string instructs the chat program to send an EOT
362 character to the remote. This is equivalent to using ^D\c as the reply
363 string. The EOT string normally indicates the end-of-file character
364 sequence. A return character is not sent following the EOT. The EOT
365 sequence can embedded into the send string using the sequence ^D.
366 BREAK
368 The BREAK special reply string sends a break condition. The break is a
369 special transmitter signal. Many UNIX systems handle break by cycling
370 through available bit rates, and sending break is often needed when the
371 remote system does not support autobaud. BREAK is equivalent to
372 using \K\c as the reply string. You embed the break sequence into the
373 send string using the \K sequence.
374 Escape Sequences
376 Expect and reply strings can contain escape sequences. Reply strings
377 accept all escape sequences, while expect strings accept most
378 sequences. A list of escape sequences is presented below. Sequences
379 that are not accepted by expect strings are indicated.
380 '' Expects or sends a null string. If you send a null string,
382 chat sends the return character. If you expect a null
383 string, chat proceeds to the reply string without waiting.
384 This sequence can be a pair of apostrophes or quote mark
385 characters.
386 \b Represents a backspace character.
389 \c Suppresses the newline at the end of the reply string. This
392 is the only method to send a string without a trailing return
393 character. This sequence must be at the end of the send
394 string. For example, the sequence hello\c will simply send
395 the characters h, e, l, l, o. (Not valid in expect.)
396 \d Delay for one second. The program uses sleep(1) which delays
399 to a maximum of one second. (Not valid in expect.)
400 \K Insert a BREAK. (Not valid in expect.)
403 \n Send a newline or linefeed character.
406 \N Send a null character. The same sequence may be represented
409 by \0. (Not valid in expect.)
410 \p Pause for 1/10th of a second. (Not valid in expect.)
413 \q Suppress writing the string to syslog. The string ?????? is
416 written to the log in its place. (Not valid in expect.)
417 \r Send or expect a carriage return.
420 \s Represents a space character in the string. Can be used when
423 it is not desirable to quote the strings which contains spa‐
424 ces. The sequence 'HI TIM' and HI\sTIM are the same.
425 \t Send or expect a tab character.
428 \T Send the phone number string as specified with the -T option.
431 (Not valid in expect.)
432 \U Send the phone number 2 string as specified with the -U
435 option. (Not valid in expect.)
436 \\ Send or expect a backslash character.
439 \ddd Collapse the octal digits (ddd) into a single ASCII character
442 and send that character. (\000 is not valid in an expect
443 string.)
444 ^C Substitute the sequence with the control character repre‐
447 sented by C. For example, the character DC1 (17) is shown as
448 ^Q. (Some characters are not valid in expect.)
449
452 Environment variables are available within chat scripts if the -E
453 option is specified on the command line. The metacharacter $ introduces
454 the name of the environment variable to substitute. If the substition
455 fails because the requested environment variable is not set, nothing is
456 replaced for the variable.
457
459 The chat program terminates with the following completion codes:
460 0 Normal program termination. Indicates that the script was
462 executed without error to normal conclusion.
463 1 One or more of the parameters are invalid or an expect string
466 was too large for the internal buffers. Indicates that the
467 program was not properly executed.
468 2 An error occurred during the execution of the program. This
471 may be due to a read or write operation failing or chat
472 receiving a signal such as SIGINT.
473 3 A timeout event occurred when there was an expect string
476 without having a "-subsend" string. This indicates that you
477 may not have programmed the script correctly for the condi‐
478 tion or that an unexpected event occurred and the expected
479 string could not be found.
480 4 The first string marked as an ABORT condition occurred.
483 5 The second string marked as an ABORT condition occurred.
486 6 The third string marked as an ABORT condition occurred.
489 7 The fourth string marked as an ABORT condition occurred.
492 ... The other termination codes are also strings marked as an
495 ABORT condition.
496 To determine which event terminated the script, use the termination
500 code. It is possible to decide if the string "BUSY" was received from
501 the modem versus "NO DIALTONE." While the first event may be retried,
502 the second probably will not succeed during a retry.
503
505 See attributes(5) for descriptions of the following attributes:
506 ┌─────────────────────────────┬─────────────────────────────┐
511 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
512 ├─────────────────────────────┼─────────────────────────────┤
513 │Availability │SUNWpppdu │
514 ├─────────────────────────────┼─────────────────────────────┤
515 │Interface Stability │Evolving │
516 └─────────────────────────────┴─────────────────────────────┘
517
519 sleep(1), uucp(1C), pppd(1M), uucico(1M), syslog(3C), attributes(5)
520 Additional information on chat scripts are available with UUCP documen‐
523 tation. The chat script format was taken from scripts used by the
524 uucico program.
525SunOS 5.11 4 May 2001 chat(1M)