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