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