diff options
Diffstat (limited to 'mdk-stage1/ppp/chat/chat.8')
| -rw-r--r-- | mdk-stage1/ppp/chat/chat.8 | 515 |
1 files changed, 0 insertions, 515 deletions
diff --git a/mdk-stage1/ppp/chat/chat.8 b/mdk-stage1/ppp/chat/chat.8 deleted file mode 100644 index 8d2029609..000000000 --- a/mdk-stage1/ppp/chat/chat.8 +++ /dev/null @@ -1,515 +0,0 @@ -.\" -*- nroff -*- -.\" manual page [] for chat 1.8 -.\" $Id$ -.\" SH section heading -.\" SS subsection heading -.\" LP paragraph -.\" IP indented paragraph -.\" TP hanging label -.TH CHAT 8 "22 May 1999" "Chat Version 1.22" -.SH NAME -chat \- Automated conversational script with a modem -.SH SYNOPSIS -.B chat -[ -.I options -] -.I script -.SH DESCRIPTION -.LP -The \fIchat\fR program defines a conversational exchange between the -computer and the modem. Its primary purpose is to establish the -connection between the Point-to-Point Protocol Daemon (\fIpppd\fR) and -the remote's \fIpppd\fR process. -.SH OPTIONS -.TP -.B -f \fI<chat file> -Read the chat script from the chat \fIfile\fR. The use of this option -is mutually exclusive with the chat script parameters. The user must -have read access to the file. Multiple lines are permitted in the -file. Space or horizontal tab characters should be used to separate -the strings. -.TP -.B -t \fI<timeout> -Set the timeout for the expected string to be received. If the string -is not received within the time limit then the reply string is not -sent. An alternate reply may be sent or the script will fail if there -is no alternate reply string. A failed script will cause the -\fIchat\fR program to terminate with a non-zero error code. -.TP -.B -r \fI<report file> -Set the file for output of the report strings. If you use the keyword -\fIREPORT\fR, the resulting strings are written to this file. If this -option is not used and you still use \fIREPORT\fR keywords, the -\fIstderr\fR file is used for the report strings. -.TP -.B -e -Start with the echo option turned on. Echoing may also be turned on -or off at specific points in the chat script by using the \fIECHO\fR -keyword. When echoing is enabled, all output from the modem is echoed -to \fIstderr\fR. -.TP -.B -E -Enables environment variable substituion within chat scripts using the -standard \fI$xxx\fR syntax. -.TP -.B -v -Request that the \fIchat\fR script be executed in a verbose mode. The -\fIchat\fR program will then log the execution state of the chat -script as well as all text received from the modem and the output -strings sent to the modem. The default is to log through the SYSLOG; -the logging method may be altered with the -S and -s flags. -.TP -.B -V -Request that the \fIchat\fR script be executed in a stderr verbose -mode. The \fIchat\fR program will then log all text received from the -modem and the output strings sent to the modem to the stderr device. This -device is usually the local console at the station running the chat or -pppd program. -.TP -.B -s -Use stderr. All log messages from '-v' and all error messages will be -sent to stderr. -.TP -.B -S -Do not use the SYSLOG. By default, error messages are sent to the -SYSLOG. The use of -S will prevent both log messages from '-v' and -error messages from being sent to the SYSLOG. -.TP -.B -T \fI<phone number> -Pass in an arbitary string, usually a phone number, that will be -substituted for the \\T substitution metacharacter in a send string. -.TP -.B -U \fI<phone number 2> -Pass in a second string, usually a phone number, that will be -substituted for the \\U substitution metacharacter in a send string. -This is useful when dialing an ISDN terminal adapter that requires two -numbers. -.TP -.B script -If the script is not specified in a file with the \fI-f\fR option then -the script is included as parameters to the \fIchat\fR program. -.SH CHAT SCRIPT -.LP -The \fIchat\fR script defines the communications. -.LP -A script consists of one or more "expect-send" pairs of strings, -separated by spaces, with an optional "subexpect-subsend" string pair, -separated by a dash as in the following example: -.IP -ogin:-BREAK-ogin: ppp ssword: hello2u2 -.LP -This line indicates that the \fIchat\fR program should expect the string -"ogin:". If it fails to receive a login prompt within the time interval -allotted, it is to send a break sequence to the remote and then expect the -string "ogin:". If the first "ogin:" is received then the break sequence is -not generated. -.LP -Once it received the login prompt the \fIchat\fR program will send the -string ppp and then expect the prompt "ssword:". When it receives the -prompt for the password, it will send the password hello2u2. -.LP -A carriage return is normally sent following the reply string. It is not -expected in the "expect" string unless it is specifically requested by using -the \\r character sequence. -.LP -The expect sequence should contain only what is needed to identify the -string. Since it is normally stored on a disk file, it should not contain -variable information. It is generally not acceptable to look for time -strings, network identification strings, or other variable pieces of data as -an expect string. -.LP -To help correct for characters which may be corrupted during the initial -sequence, look for the string "ogin:" rather than "login:". It is possible -that the leading "l" character may be received in error and you may never -find the string even though it was sent by the system. For this reason, -scripts look for "ogin:" rather than "login:" and "ssword:" rather than -"password:". -.LP -A very simple script might look like this: -.IP -ogin: ppp ssword: hello2u2 -.LP -In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2. -.LP -In actual practice, simple scripts are rare. At the vary least, you -should include sub-expect sequences should the original string not be -received. For example, consider the following script: -.IP -ogin:--ogin: ppp ssword: hello2u2 -.LP -This would be a better script than the simple one used earlier. This would look -for the same login: prompt, however, if one was not received, a single -return sequence is sent and then it will look for login: again. Should line -noise obscure the first login prompt then sending the empty line will -usually generate a login prompt again. -.SH COMMENTS -Comments can be embedded in the chat script. A comment is a line which -starts with the \fB#\fR (hash) character in column 1. Such comment -lines are just ignored by the chat program. If a '#' character is to -be expected as the first character of the expect sequence, you should -quote the expect string. -If you want to wait for a prompt that starts with a # (hash) -character, you would have to write something like this: -.IP -# Now wait for the prompt and send logout string -.br -\'# ' logout -.LP - -.SH SENDING DATA FROM A FILE -If the string to send starts with an at sign (@), the rest of the -string is taken to be the name of a file to read to get the string to -send. If the last character of the data read is a newline, it is -removed. The file can be a named pipe (or fifo) instead of a regular -file. This provides a way for \fBchat\fR to communicate with another -program, for example, a program to prompt the user and receive a -password typed in. -.LP - -.SH ABORT STRINGS -Many modems will report the status of the call as a string. These -strings may be \fBCONNECTED\fR or \fBNO CARRIER\fR or \fBBUSY\fR. It -is often desirable to terminate the script should the modem fail to -connect to the remote. The difficulty is that a script would not know -exactly which modem string it may receive. On one attempt, it may -receive \fBBUSY\fR while the next time it may receive \fBNO CARRIER\fR. -.LP -These "abort" strings may be specified in the script using the \fIABORT\fR -sequence. It is written in the script as in the following example: -.IP -ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT -.LP -This sequence will expect nothing; and then send the string ATZ. The -expected response to this is the string \fIOK\fR. When it receives \fIOK\fR, -the string ATDT5551212 to dial the telephone. The expected string is -\fICONNECT\fR. If the string \fICONNECT\fR is received the remainder of the -script is executed. However, should the modem find a busy telephone, it will -send the string \fIBUSY\fR. This will cause the string to match the abort -character sequence. The script will then fail because it found a match to -the abort string. If it received the string \fINO CARRIER\fR, it will abort -for the same reason. Either string may be received. Either string will -terminate the \fIchat\fR script. -.SH CLR_ABORT STRINGS -This sequence allows for clearing previously set \fBABORT\fR strings. -\fBABORT\fR strings are kept in an array of a pre-determined size (at -compilation time); \fBCLR_ABORT\fR will reclaim the space for cleared -entries so that new strings can use that space. -.SH SAY STRINGS -The \fBSAY\fR directive allows the script to send strings to the user -at the terminal via standard error. If \fBchat\fR is being run by -pppd, and pppd is running as a daemon (detached from its controlling -terminal), standard error will normally be redirected to the file -/etc/ppp/connect-errors. -.LP -\fBSAY\fR strings must be enclosed in single or double quotes. If -carriage return and line feed are needed in the string to be output, -you must explicitely add them to your string. -.LP -The SAY strings could be used to give progress messages in sections of -the script where you want to have 'ECHO OFF' but still let the user -know what is happening. An example is: -.IP -ABORT BUSY -.br -ECHO OFF -.br -SAY "Dialling your ISP...\\n" -.br -\'' ATDT5551212 -.br -TIMEOUT 120 -.br -SAY "Waiting up to 2 minutes for connection ... " -.br -CONNECT '' -.br -SAY "Connected, now logging in ...\n" -.br -ogin: account -.br -ssword: pass -.br -$ \c -SAY "Logged in OK ...\n" -\fIetc ...\fR -.LP -This sequence will only present the SAY strings to the user and all -the details of the script will remain hidden. For example, if the -above script works, the user will see: -.IP -Dialling your ISP... -.br -Waiting up to 2 minutes for connection ... Connected, now logging in ... -.br -Logged in OK ... -.LP - -.SH REPORT STRINGS -A \fBreport\fR string is similar to the ABORT string. The difference -is that the strings, and all characters to the next control character -such as a carriage return, are written to the report file. -.LP -The report strings may be used to isolate the transmission rate of the -modem's connect string and return the value to the chat user. The -analysis of the report string logic occurs in conjunction with the -other string processing such as looking for the expect string. The use -of the same string for a report and abort sequence is probably not -very useful, however, it is possible. -.LP -The report strings to no change the completion code of the program. -.LP -These "report" strings may be specified in the script using the \fIREPORT\fR -sequence. It is written in the script as in the following example: -.IP -REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account -.LP -This sequence will expect nothing; and then send the string -ATDT5551212 to dial the telephone. The expected string is -\fICONNECT\fR. If the string \fICONNECT\fR is received the remainder -of the script is executed. In addition the program will write to the -expect-file the string "CONNECT" plus any characters which follow it -such as the connection rate. -.SH CLR_REPORT STRINGS -This sequence allows for clearing previously set \fBREPORT\fR strings. -\fBREPORT\fR strings are kept in an array of a pre-determined size (at -compilation time); \fBCLR_REPORT\fR will reclaim the space for cleared -entries so that new strings can use that space. -.SH ECHO -The echo options controls whether the output from the modem is echoed -to \fIstderr\fR. This option may be set with the \fI-e\fR option, but -it can also be controlled by the \fIECHO\fR keyword. The "expect-send" -pair \fIECHO\fR \fION\fR enables echoing, and \fIECHO\fR \fIOFF\fR -disables it. With this keyword you can select which parts of the -conversation should be visible. For instance, with the following -script: -.IP -ABORT 'BUSY' -.br -ABORT 'NO CARRIER' -.br -'' ATZ -.br -OK\\r\\n ATD1234567 -.br -\\r\\n \\c -.br -ECHO ON -.br -CONNECT \\c -.br -ogin: account -.LP -all output resulting from modem configuration and dialing is not visible, -but starting with the \fICONNECT\fR (or \fIBUSY\fR) message, everything -will be echoed. -.SH HANGUP -The HANGUP options control whether a modem hangup should be considered -as an error or not. This option is useful in scripts for dialling -systems which will hang up and call your system back. The HANGUP -options can be \fBON\fR or \fBOFF\fR. -.br -When HANGUP is set OFF and the modem hangs up (e.g., after the first -stage of logging in to a callback system), \fBchat\fR will continue -running the script (e.g., waiting for the incoming call and second -stage login prompt). As soon as the incoming call is connected, you -should use the \fBHANGUP ON\fR directive to reinstall normal hang up -signal behavior. Here is an (simple) example script: -.IP -ABORT 'BUSY' -.br -'' ATZ -.br -OK\\r\\n ATD1234567 -.br -\\r\\n \\c -.br -CONNECT \\c -.br -\'Callback login:' call_back_ID -.br -HANGUP OFF -.br -ABORT "Bad Login" -.br -\'Callback Password:' Call_back_password -.br -TIMEOUT 120 -.br -CONNECT \\c -.br -HANGUP ON -.br -ABORT "NO CARRIER" -.br -ogin:--BREAK--ogin: real_account -.br -\fIetc ...\fR -.LP -.SH TIMEOUT -The initial timeout value is 45 seconds. This may be changed using the \fB-t\fR -parameter. -.LP -To change the timeout value for the next expect string, the following -example may be used: -.IP -ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2 -.LP -This will change the timeout to 10 seconds when it expects the login: -prompt. The timeout is then changed to 5 seconds when it looks for the -password prompt. -.LP -The timeout, once changed, remains in effect until it is changed again. -.SH SENDING EOT -The special reply string of \fIEOT\fR indicates that the chat program -should send an EOT character to the remote. This is normally the -End-of-file character sequence. A return character is not sent -following the EOT. -.PR -The EOT sequence may be embedded into the send string using the -sequence \fI^D\fR. -.SH GENERATING BREAK -The special reply string of \fIBREAK\fR will cause a break condition -to be sent. The break is a special signal on the transmitter. The -normal processing on the receiver is to change the transmission rate. -It may be used to cycle through the available transmission rates on -the remote until you are able to receive a valid login prompt. -.PR -The break sequence may be embedded into the send string using the -\fI\\K\fR sequence. -.SH ESCAPE SEQUENCES -The expect and reply strings may contain escape sequences. All of the -sequences are legal in the reply string. Many are legal in the expect. -Those which are not valid in the expect sequence are so indicated. -.TP -.B '' -Expects or sends a null string. If you send a null string then it will still -send the return character. This sequence may either be a pair of apostrophe -or quote characters. -.TP -.B \\\\b -represents a backspace character. -.TP -.B \\\\c -Suppresses the newline at the end of the reply string. This is the only -method to send a string without a trailing return character. It must -be at the end of the send string. For example, -the sequence hello\\c will simply send the characters h, e, l, l, o. -.I (not valid in expect.) -.TP -.B \\\\d -Delay for one second. The program uses sleep(1) which will delay to a -maximum of one second. -.I (not valid in expect.) -.TP -.B \\\\K -Insert a BREAK -.I (not valid in expect.) -.TP -.B \\\\n -Send a newline or linefeed character. -.TP -.B \\\\N -Send a null character. The same sequence may be represented by \\0. -.I (not valid in expect.) -.TP -.B \\\\p -Pause for a fraction of a second. The delay is 1/10th of a second. -.I (not valid in expect.) -.TP -.B \\\\q -Suppress writing the string to the SYSLOG file. The string ?????? is -written to the log in its place. -.I (not valid in expect.) -.TP -.B \\\\r -Send or expect a carriage return. -.TP -.B \\\\s -Represents a space character in the string. This may be used when it -is not desirable to quote the strings which contains spaces. The -sequence 'HI TIM' and HI\\sTIM are the same. -.TP -.B \\\\t -Send or expect a tab character. -.TP -.B \\\\T -Send the phone number string as specified with the \fI-T\fR option -.I (not valid in expect.) -.TP -.B \\\\U -Send the phone number 2 string as specified with the \fI-U\fR option -.I (not valid in expect.) -.TP -.B \\\\\\\\ -Send or expect a backslash character. -.TP -.B \\\\ddd -Collapse the octal digits (ddd) into a single ASCII character and send that -character. -.I (some characters are not valid in expect.) -.TP -.B \^^C -Substitute the sequence with the control character represented by C. -For example, the character DC1 (17) is shown as \^^Q. -.I (some characters are not valid in expect.) -.SH ENVIRONMENT VARIABLES -Environment variables are available within chat scripts, if the \fI-E\fR -option was specified in the command line. The metacharacter \fI$\fR is used -to introduce the name of the environment variable to substitute. If the -substition fails, because the requested environment variable is not set, -\fInothing\fR is replaced for the variable. -.SH TERMINATION CODES -The \fIchat\fR program will terminate with the following completion -codes. -.TP -.B 0 -The normal termination of the program. This indicates that the script -was executed without error to the normal conclusion. -.TP -.B 1 -One or more of the parameters are invalid or an expect string was too -large for the internal buffers. This indicates that the program as not -properly executed. -.TP -.B 2 -An error occurred during the execution of the program. This may be due -to a read or write operation failing for some reason or chat receiving -a signal such as SIGINT. -.TP -.B 3 -A timeout event occurred when there was an \fIexpect\fR string without -having a "-subsend" string. This may mean that you did not program the -script correctly for the condition or that some unexpected event has -occurred and the expected string could not be found. -.TP -.B 4 -The first string marked as an \fIABORT\fR condition occurred. -.TP -.B 5 -The second string marked as an \fIABORT\fR condition occurred. -.TP -.B 6 -The third string marked as an \fIABORT\fR condition occurred. -.TP -.B 7 -The fourth string marked as an \fIABORT\fR condition occurred. -.TP -.B ... -The other termination codes are also strings marked as an \fIABORT\fR -condition. -.LP -Using the termination code, it is possible to determine which event -terminated the script. It is possible to decide if the string "BUSY" -was received from the modem as opposed to "NO DIAL TONE". While the -first event may be retried, the second will probably have little -chance of succeeding during a retry. -.SH SEE ALSO -Additional information about \fIchat\fR scripts may be found with UUCP -documentation. The \fIchat\fR script was taken from the ideas proposed -by the scripts used by the \fIuucico\fR program. -.LP -uucico(1), uucp(1) -.SH COPYRIGHT -The \fIchat\fR program is in public domain. This is not the GNU public -license. If it breaks then you get to keep both pieces. |