unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



chat(8)								      chat(8)



NAME

  chat - Automated conversational script with a	modem

SYNOPSIS

  /usr/sbin/chat [options] script

OPTIONS

  -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 ECHO keyword.
      When echoing is enabled, all output from the modem is echoed to stan-
      dard error.

  -f chatfile
      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.

  -r report file
      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.

  -t timeout
      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
      alternate	reply string.  A failed	script causes the chat program to
      terminate	with a nonzero error code.

  -v  Requests that the	chat script be executed	in a verbose mode.  The	chat
      program logs all text received from the modem and	the output strings
      that it sends to the syslog command.

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

  script
      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 pass-
  word,	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 specifying the \r
  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 con-
  tain 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 reason, scripts
  look for "ogin:" rather than "login:"	and "ssword:" rather than "pass-
  word:".

  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 terminate 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 CAR-
  RIER.

  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 program
  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 compilation 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 ter-
  minal	via standard error.  If	the chat program is being run by pppd, and
  pppd is running as a daemon (detached	from its controlling terminal),	stan-
  dard 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...\n"

       '' 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 following infor-
  mation 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 process-
  ing, 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 addi-
  tion,	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 compilation
  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 fol-
  lowing 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\r\n  ATD1234567
       .br
       \r\n    \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	log-
  ging in to a callback	system), chat continues	running	the script (for	exam-
  ple, waiting for the incoming	call and second	stage login prompt). When the
  incoming call	connects, you should use the HANGUP ON directive to reinstall
  normal hang up signal	behavior, as shown in the following example:

       ABORT   'BUSY'

       ''      ATZ

       OK\r\n  ATD1234567

       \r\n    \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 pass-
  word 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.

  \b	  Represents a backspace character.

  \c	  Suppresses the newline at the	end of the reply string.  This is the
	  only means of	sending	a string without a trailing return character.
	  It must be at	the end	of the send string.  For example, the
	  sequence hello\c will	send the characters h, e, l, l,	o. (Not	valid
	  in expect.)

  \d	  Delays for one second.  The program uses the sleep command, which
	  will delay to	a maximum of one second.  (Not valid in	expect.)

  \K	  Inserts a BREAK. (Not	valid in expect.)

  \n	  Sends	a newline or linefeed character.

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

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

  \q	  Suppresses writing the string	to the syslog file. The	string ??????
	  is written to	the log	in its place. (Not valid in expect.)

  \r	  Sends	or expects a carriage return.

  \s	  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	HI\sTIM	are the	same.

  \t	  Sends	or expects a tab character.

  \\	  Sends	or expects a backslash character.

  \ddd	  Collapses the	octal digits (ddd) into	a single ASCII character and
	  sends	that character.	(Some characters are not valid in expect.)

  ^C	  Substitutes the sequence with	the control character represented by
	  C. For example, the character	DC1 (17) is shown as ^Q. (Some char-
	  acters are not valid in expect.)

EXIT STATUS

  The chat program terminates with the following completion codes.

  0   The normal termination of	the program. This indicates that the script
      was executed without error to the	normal conclusion.

  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.

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

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

  4   The first	string marked as an ABORT condition occurred.

  5   The second string	marked as an ABORT condition occurred.

  6   The third	string marked as an ABORT condition occurred.

  7   The fourth string	marked as an ABORT condition occurred.

  ... The other	termination codes are also strings marked as an	ABORT condi-
      tion.

  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 succeeding during a retry.

SEE ALSO

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