


CHAT(8)							CHAT(8)


NAME
       chat - Automated conversational script with a modem

SYNOPSIS
       chat [ options ] script

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 Proto-
       col Daemon (pppd) and the remote's pppd process.

OPTIONS
       -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 pro-
	      gram  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  ver-
	      bose  mode. The chat program will then log all text
	      received from the	modem	and  the  output  strings
	      which it sends to the SYSLOG.

       script If  the  script is not specified in a file with the



Chat Version 1.8	  17 April 1994				1





CHAT(8)							CHAT(8)


	      -f option then the script is included as parameters
	      to the chat program.

CHAT SCRIPT
       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 fol-
       lowing 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 dur-
       ing  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 hello2u2.

       In  actual  practice, simple scripts are rare. At the vary
       least, you should include sub-expect sequences should  the



Chat Version 1.8	  17 April 1994				2





CHAT(8)							CHAT(8)


       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, how-
       ever, 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.

ABORT STRINGS
       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:

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

       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.

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

       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 sec-
       onds when it looks for the password prompt.



Chat Version 1.8	  17 April 1994				3





CHAT(8)							CHAT(8)


       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.  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 special reply string of BREAK will cause a break  con-
       dition  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 sequence.

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.

       ''     Expects or sends a null string. If you send a  null
	      string  then  it will still send the return charac-
	      ter. This sequence may either be a pair of apostro-
	      phe 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.)



Chat Version 1.8	  17 April 1994				4





CHAT(8)							CHAT(8)


       \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  charac-
	      ters 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.)

SEE ALSO
       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  pro-
       gram.

       uucico(1), uucp(1)

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





















Chat Version 1.8	  17 April 1994				5


