chat(8) 						      System Manager's Manual							   chat(8)

NAME

       chat - Automated conversational script with a modem

SYNOPSIS

       /usr/sbin/chat [options] script

OPTIONS

       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 ECHO keyword.
       When echoing is enabled, all output from the modem is echoed to standard error.	Reads the chat script from the chatfile.  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.  Set the file for output of the  report  strings.	If
       you  use  the keyword REPORT, the resulting strings are written to this file. If this option is not used and you still use REPORT keywords,
       the standard error file is used for the report strings.	Sets the timeout for the expected string to be received.  If  the  string  is  not
       received within the time limit, the reply string is not sent.  An alternate reply may be sent or the script will fail if there is no alter-
       nate reply string.  A failed script causes the chat program to terminate with a nonzero error code.  Requests that the chat script be  exe-
       cuted  in  a  verbose mode.  The chat program logs all text received from the modem and the output strings that it sends to the syslog com-
       mand.  Requests that the chat script be executed in a standard error verbose mode. The chat program then logs all text  received  from  the
       modem  and  the output strings which it sends to the standard error device. This device is usually the local console at the station running
       the chat or pppd program. This option does not work properly if the standard error is redirected to the /dev/null location as is  the  case
       when  pppd  runs  in  the  detached mode. In that case, use the -v option to record the session on the SYSLOG device.  If the script is not
       specified in a file with the -f option then the script is included as parameters to the chat program.

DESCRIPTION

       The chat 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 (pppd) and the pppd process of the remote system.

   CHAT SCRIPT
       The  chat  script  defines  the communications between the local system and a remote system. 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:

       ogin:-BREAK-ogin: ppp ssword: hello2u2

       In the previous example, the chat program expects the string "ogin:".  If it fails to receive a	login  prompt  within  the  time  interval
       allotted,  the  chat  program  sends  a	break sequence to the remote system, and then expects to receive the string "ogin:".  If the first
       "ogin:" is received, the break sequence is not generated.

       Once it receives the login prompt, the chat program sends the string ppp, and expects to receive the "ssword:" prompt.  When  prompted  for
       the password, it sends the password hello2u2.

       A  carriage return is normally sent following the reply string.	It is not expected in the "expect" string unless it is requested by speci-
       fying the 
 escape sequence.

       The expect sequence should contain only the information 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.

       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  rea-
       son, scripts look for "ogin:" rather than "login:" and "ssword:" rather than "password:".

       A very simple script is as follows:

       ogin: ppp ssword: hello2u2

       In other words, expect ogin:, send ppp, expect ssword:, send hello2u2.

       In  practice,  simple  scripts  are  rare.   At	the  very least, you should include subexpect sequences in case the original string is not
       received, as in the following script:

       ogin:--ogin: ppp ssword: hello2u2

       The preceding script is better than the simple one used earlier.  This looks for the same login: prompt, but if one  is	not  received,	it
       sends  a  single  return sequence and looks for login: again.  If line noise obscures the first login prompt, sending an empty line usually
       generates a login prompt again.

   COMMENTS
       Comments can be embedded in the chat script by beginning a line with the number (#) character in column 1. Such comment lines  are  ignored
       by  the	chat  program.	If  a  number (#) character is 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 number (#) character, enter a text string similar to the following:

       # Now wait for the prompt and send logout string '# ' logout

   ABORT STRINGS
       Many modems report the status of the call as one of the following strings: CONNECTED, NO CARRIER, or BUSY.  It is often desirable to termi-
       nate  the  script  if the modem fails to connect to the remote system.  The difficulty is that a script does not know which modem string it
       might receive.  On one attempt, it might receive BUSY while the next time it might receive NO CARRIER.

       These abort strings may be specified in the script using the ABORT sequence as shown in the following example:

       ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT

       Using this sequence, the chat program expects nothing, sends the string ATZ, and then expects the string OK.  When it receives OK, the pro-
       gram  sends the string ATDT5551212 to dial the telephone, and expects the string CONNECT.  If the string CONNECT is received, the remainder
       of the script is executed.

       If the telephone is busy, the modem sends the string BUSY.  This causes the string to match the abort character sequence,  and  the  script
       fails  because  it  found a match to the abort string.  If it receives the NO CARRIER string, it aborts for the same reason.  Either string
       terminates the chat script.

   CLR_ABORT STRINGS
       This sequence allows for clearing previously set ABORT strings. The ABORT strings are kept in an array of a predetermined size (at compila-
       tion time); CLR_ABORT reclaims the space for cleared entries so that new strings can use that space.

   SAY STRINGS
       The  SAY  directive  allows the script to send strings to the user at the terminal via standard error.  If the chat program 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
       /etc/ppp/connect-errors file.

       The  SAY  strings  must	be enclosed in single or double quotes. If carriage return and line feed characters are needed in the string to be
       output, you must explicitly add them to your string.

       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, for example:

       ABORT BUSY

       ECHO OFF

       SAY "Dialing your ISP...
"

       '' ATDT5551212

       TIMEOUT 120

       SAY "Waiting up to 2 minutes for connection ... "

       CONNECT ''

       SAY "Connected, now logging in ...0"

       ogin: account

       ssword: pass

       $ SAY "Logged in OK ...0" etc ...

       This  sequence  presents the SAY strings to the user; details of the script remain hidden. For example, if the above script works, the fol-
       lowing information is displayed.  Dialing your ISP...

       Waiting up to 2 minutes for connection ... Connected, now logging in ...

       Logged in OK ...

   REPORT STRINGS
       A REPORT string is different from the ABORT string in that the strings, and all characters to the next control character such as a carriage
       return, are written to the report file.

       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 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 useful, but it is possible.

       The REPORT strings do not change the completion code of the program.

       You can specify these report strings in the script using the REPORT sequence, as shown in the following example:

       REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account

       Using  this  sequence the chat program expects nothing, sends the string ATDT5551212 to dial the telephone, and expects the string CONNECT.
       If the CONNECT string is received, the remainder of the script executes. In addition, the program writes to  the  expect-file  the  CONNECT
       string plus any characters, such as the connection rate which follow it.

   CLR_REPORT STRINGS
       This  sequence allows for clearing previously set REPORT strings.  The REPORT strings are kept in an array of a predetermined size (at com-
       pilation time); CLR_REPORT reclaims the space for cleared entries so that new strings can use that space.

   ECHO
       The echo option controls whether the output from the modem is echoed to standard error. This option may be set with the -e option,  but	it
       can  also  be controlled by the ECHO keyword. The expect-send pair ECHO ON enables echoing, and ECHO OFF disables it. With this keyword you
       can select which parts of the conversation should be visible.  For instance, with the following script, all  output  resulting  from  modem
       configuration and dialing is not visible, but starting with the CONNECT (or BUSY) message, everything is echoed.

       ABORT	'BUSY'	.br ABORT   'NO CARRIER' .br .br ''	 ATZ .br OK
  ATD1234567 .br 
	c .br ECHO    ON .br CONNECT c .br ogin:
       account

   HANGUP
       The HANGUP option controls whether a modem hangup is considered as an error or not.  This option is useful in scripts to dial systems  that
       hang  up and call your system back.  The HANGUP options can be ON or OFF. When HANGUP is set OFF and the modem hangs up (for example, after
       the first stage of logging in to a callback system), chat continues running the script (for example, waiting for the incoming call and sec-
       ond  stage login prompt). When the incoming call connects, you should use the HANGUP ON directive to reinstall normal hang up signal behav-
       ior, as shown in the following example:

       ABORT   'BUSY'

       ''      ATZ

       OK
  ATD1234567

       
    c

       CONNECT c

       'Callback login:' call_back_ID

       HANGUP OFF

       ABORT "Bad Login"

       'Callback Password:' Call_back_password

       TIMEOUT 120

       CONNECT c

       HANGUP ON

       ABORT "NO CARRIER"

       ogin:--BREAK--ogin: real_account

       etc ...

   TIMEOUT
       The initial timeout value of 45 seconds can be changed by using the -t timeout option, for example: ATZ OK ATDT5551212 CONNECT  TIMEOUT	10
       ogin:--ogin: TIMEOUT 5 assword:  hello2u2

       This  sequence changes the timeout to 10 seconds when it expects the login: prompt, then changes the timeout to 5 seconds when it looks for
       the password prompt.

       The timeout, once changed, remains in effect until it is changed again.

   SENDING EOT
       The special reply string of EOT indicates that the chat program should send an EOT character to the remote system.  This  is  normally  the
       End-of-file character sequence.	A return character is not sent following the EOT.

       The EOT sequence may be embedded into the send string using the sequence ^D.

   GENERATING BREAK
       The  BREAK  reply  string causes 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  system
       until you are able to receive a valid login prompt.

       You can embed the break sequence into the send string by using the K escape sequence.

   ESCAPE SEQUENCES
       The  expect  and  reply	strings  may  contain escape sequences.  All of the sequences are valid in the reply string; many are legal in the
       expect string.  Those sequences which are not valid in the expect string are so indicated.  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.	Represents
       a backspace character.  Suppresses the newline at the end of the reply string.  This is the only means of sending a string without a trail-
       ing return character.  It must be at the end of the send string.  For example, the sequence helloc will send the characters h, e, l, l, o.
       (Not valid in expect.)  Delays for one second.  The program uses the sleep command, which will delay to a  maximum  of  one  second.   (Not
       valid  in  expect.)   Inserts  a  BREAK.  (Not valid in expect.)  Sends a newline or linefeed character.  Sends a null character.  The same
       sequence may be represented by . (Not valid in expect.)  Pauses for a fraction of a second.  The delay is 1/10th of a second. (Not  valid
       in expect.)  Suppresses writing the string to the syslog file. The string ?????? is written to the log in its place. (Not valid in expect.)
       Sends or expects a carriage return.  Represents a space character in the string.  Use this when it is not desirable to  quote  the  strings
       that contain spaces. The sequence `HI TIM' and HIsTIM are the same.  Sends or expects a tab character.	Sends or expects a backslash char-
       acter.  Collapses the octal digits (ddd) into a single ASCII character and sends that character. (Some characters are not valid in expect.)
       Substitutes  the sequence with the control character represented by C. For example, the character DC1 (17) is shown as ^Q. (Some characters
       are not valid in expect.)

EXIT STATUS

       The chat program terminates with the following completion codes.  The normal termination of the program. This indicates that the script was
       executed  without  error  to  the  normal  conclusion.  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.  An error occurred during the execution of  the  program.  This
       may  be	due  to failure of a read or write operation or chat receiving a signal such as SIGINT.  A timeout event occurred due to an expect
       string without a -subsend string. This may mean that you did not program the script correctly for the condition	or  that  some	unexpected
       event occurred and the expected string was not found.  The first string marked as an ABORT condition occurred.  The second string marked as
       an ABORT condition occurred.  The third string marked as an ABORT condition occurred.  The fourth  string  marked  as  an  ABORT  condition
       occurred.  The other termination codes are also strings marked as an ABORT condition.

       You can use the termination code 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  succeed-
       ing during a retry.

SEE ALSO

       Commands: uucp(1), pppd(8), uucico(8)

																	   chat(8)