chat - Automated conversational script with a modem

     chat [ options ] script


     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 remote's pppd process.


     -f <chat file>
          Read the chat script from the chat file. 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.

     -l <lock file>
          Perform the UUCP style locking using the indicated lock file.

          If the file could not be created then the chat  program  will  fail.
          The  lock  file  will  be  deleted only if the chat program fails to
          perform the script for any reason. If the script is  successful  the
          lock  file  will  be  left on the disk. It is expected that the lock
          file will be deleted when the pppd process no longer wishes  to  use
          the serial device.

          The use of a lock file with chat and pppd's lock option  should  not
          be  used  at  the same time. They are mutually exclusive options and
          will cause one or the other program to fail to achieve the  required
          lock if you use both.

     -t <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 chat program to terminate with a non-zero error code.

     -v   Request that the chat script be executed in a verbose mode. The chat
          program  will  then  log  all  text  received from the modem and the
          output strings which it sends to the SYSLOG.

          If the script is not specified in a file with the -f option then the
          script is included as parameters to the chat program.


     The chat script defines the communications.

     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

     This line indicates that  the  chat  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.

     Once it received the login prompt the chat 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.

     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.

     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.

     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:".

     A very simple script might look like this:

          ogin: ppp ssword: hello2u2

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

     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:

          ogin:--ogin: ppp ssowrd: hello2u2

     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.

     Many modems will report the status of the call as a string. These strings
     may  be  CONNECTED  or  NO  CARRIER  or  BUSY.  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 BUSY while the next  time  it
     may receive NO CARRIER.

     These "abort" strings may be specified in  the  script  using  the  ABORT
     sequence. It is written in the script as in the following example:


     This sequence will expect nothing; and then  send  the  string  ATZ.  The
     expected  response  to  this  is  the string OK. When it receives OK, the
     string ATDT5551212 to dial the telephone. The expected string is CONNECT.
     If  the  string  CONNECT  is  received  the  remainder  of  the script is
     executed. However, should the modem find a busy telephone, it  will  send
     the  string BUSY. 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 NO CARRIER, it will abort for the same
     reason. Either string may be received. Either string will  terminate  the
     chat script.

     The initial timeout value is 45 seconds. This may be changed using the -t

     To change the timeout value for the next  expect  string,  the  following
     example may be used:

          ATZ  OK  ATDT5551212  CONNECT  TIMEOUT  10  ogin:--ogin:  TIMEOUT  5
          assowrd: hello2u2

     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.

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

     The special reply string of EOT 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.

     The EOT sequence may be embedded into the send string using the  sequence

     The special reply string of BREAK 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.

     The break sequence may be embedded into the  send  string  using  the  \K

     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.

     ''   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.

     \b   represents a backspace character.

     \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.  (not valid
          in expect.)

     \d   Delay for one second. The program uses sleep(1) which will delay  to
          a maximum of one second.  (not valid in expect.)

     \K   Insert a BREAK (not valid in expect.)

     \n   Send a newline or linefeed character.

     \N   Send a null character. The same sequence may be represented  by  \0.
          (not valid in expect.)

     \p   Pause for a fraction of a second. The delay is 1/10th of  a  second.
          (not valid in expect.)

     \q   Suppress writing the string to the SYSLOG file. The string ?????? is
          written to the log in its place.  (not valid in expect.)

     \r   Send or expect a carriage return.

     \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.

     \t   Send or expect a tab character.

     \\   Send or expect a backslash character.

     \ddd Collapse the octal digits (ddd) into a single  ASCII  character  and
          send that character.  (some characters are not valid in expect.)

     ^C   Substitute 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.)

     Additional  information  about  chat  scripts  may  be  found  with  UUCP
     documentation.  The  chat script was taken from the ideas proposed by the
     scripts used by the uucico program.

     uucico(8), uucp(1)

     The chat program is in public domain. This is not the GNU public license.
     If it breaks then you get to keep both pieces.