usr.bin/chat/chat.8

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