Appendix A. PPP Tools

This appendix is a reference for dip, pppd, and chat. These tools are used to create dial-up IP connections for the Point-to-Point Protocol (PPP). dip and chat are both scripting languages. Creating a script that initializes the modem, dials the remote server, logs in, and configures the remote server is the biggest task in configuring a PPP connection. Chapter 6 provides examples and tutorial information about all three of the programs covered here. This appendix provides a reference to the programs.

Dial-Up IP

dip is a scripting tool designed specifically for creating SLIP and PPP connections.^[154]

The syntax of the dip command is:

dip [options] [scriptfile]

The dip command is invoked with an option set, a script file specified, or both. When scriptfile is specified, dip executes the commands contained in the script file to create a point-to-point connection. Examples of scripts and dip are shown in Chapter 6. The options valid with script files are:

-v: Runs dip in verbose mode. In this mode, dip echoes each line of the script file as it is executed and displays enhanced status messages.
-m mtu: Sets the maximum transmission unit (MTU) to the number of bytes specified by mtu. The default MTU is 296 bytes.
-p proto: Selects the serial line protocol. Possible values for proto are: SLIP, CSLIP, PPP, or TERM.

The other dip command-line options are:

-k: Kills the last dip process you started. You can only kill a process you own, unless of course you’re root.
-l device: Specifies that the process to be killed is the one that has locked the specified device. This option is valid only when used with the -k option.
-i [ username ]: Runs dip as a login shell to provide a PPP server. The diplogin command is equivalent to dip -i. These two forms of the command are used interchangeably, but diplogin is the most common form. diplogin is placed in the login shell field of the /etc/passwd file entry for each PPP client. From there it is run by login. The username from the /etc/passwd file is used to retrieve additional configuration information from /etc/diphosts. If the optional username is specified with the diplogin command, that username is used to retrieve the information from the /etc/diphosts file. Chapter 6 provides a tutorial and examples of creating a PPP server.
-a: Prompts for the username and password. The -a option is valid only when used with the -i option. The diplogini command is equivalent to dip -i -a. diplogini is used as a login shell in the /etc/passwd file where it is run by login.
-t: Runs dip in test mode, which allows you to input individual script language commands directly from the keyboard. The -t option is frequently used in combination with -v so that the result of each command can be better observed. As shown in Chapter 6, this option is used to debug a dip script.

diplogin and diplogini are used only on servers and are not used with a script file. The script file is used on the PPP clients when dip is configured to dial into a remote server. The script file contains the instructions used to do this.

The dip Script File

The script file is made up of comments, labels, variables, and commands. Any line that begins with a sharp sign (#) is a comment. A label is a line that contains only a string ending in a colon. Labels are used to divide the script into separate procedures. For example, the section of the script that dials the remote host might begin with the label:

 Dial-in:

A variable stores a value. A variable name is a string that begins with a dollar sign ($). You might, for example, create a variable to hold a loop counter and give it the name $loopcntr. It is possible to create your own variables, but this is rarely done. The variables that are used in most scripts are the special variables defined by dip. Table A-1 lists the special variables and the value that each holds.

Table A-1. dip special variables

Variable	Value stored
$errlvl	The return code of the last command
$locip	The IP address of the local host
$local	The fully qualified domain name of the local host
$rmtip	The IP address of the remote host
$remote	The fully qualified domain name of the remote host
$mtu	The maximum transmission unit in bytes
$modem	The modem type; currently this must be HAYES
$port	The name of the serial device, e.g., cua0
$speed	The transmission speed of the port

The final component of the script file is the command list. There are many script commands. Because this appendix is a reference, we cover them all. However, most scripts are built using only a few of these commands. See the sample scripts in Chapter 6 and at the end of this section for realistic dip scripts. The complete list of script commands is:

beep [ n ]

Tells the system to beep the user. Repeat n times.

bootp

Tells the system to use the BOOTP protocol to obtain the local and remote IP addresses. This command applies only to SLIP. PPP has its own protocol for assigning addresses; SLIP does not. Usually SLIP addresses are statically set inside the script. However, some SLIP servers have evolved techniques for dynamic address assignment. The most common method is for the server to display the address as clear text immediately after the connection is made. Use the get $locip remote command to retrieve the address from this type of SLIP server. Other SLIP servers require you to send them a command before they will display the address. Put the required server command in the script and follow it with the get command. Finally, a few SLIP servers use BOOTP to distribute addresses. Use the bootp command in your script to enable BOOTP when it is required by your SLIP server.

break

Sends a BREAK. Some remote servers may require a BREAK as an attention character.

chatkey keyword code

Maps a modem response keyword to a numeric code. The predefined mappings are:

0	OK
1	CONNECT
2	ERROR
3	BUSY
4	NO CARRIER
5	NO DIALTONE

config [interface|routing] [pre|up|down|post] arguments...

Modifies interface characteristics (interface) or the routing table (routing) either before (pre) the link comes up, when it is up, when it goes down, or after (post) the link is shut down. For example:

 config up routing add canary gw ibis

adds a route to canary using ibis as the gateway when the link is up. Allowing users to modify the routing table or interface characteristics is very dangerous. The config command is disabled in the DIP code and requires recompilation to be enabled.

databits 7|8

Sets the number of data bits to 7 or 8. 8 bits is recommended for PPP and SLIP links.

dec $variable [ value ]

Decrements $variable by value. The default value is 1.

default

Sets the PPP connection as the default route.

dial phonenumber [ timeout ]

Dials the phonenumber. If the remote modem does not answer within timeout seconds, the connection aborts. $errlvl is set to a numeric value based on the keyword returned by the local modem. Set chatkey for the keyword to numeric mappings.

echo on|off

Enables or disables the display of modem commands.

exit [ n ]

Exits the script, optionally returning the number n as the exit status. Clears the input buffer.

get $variable [ask | remote [ timeout ]] value

Sets $variable to value, unless ask or remote is specified. When ask is specified, the user is prompted for the value. When remote is specified, the value is read from the remote machine, optionally waiting timeout seconds for the remote system to respond.

goto label

Jumps to the section of the script identified by label.

help

Lists the dip script commands.

if expr goto label

A conditional statement that jumps to the section of the script identified by label if the expression evaluates to true. The expression must compare a variable to a constant using one of these operators: == (equal), != (not equal), < (less than), > (greater than), <= (less than or equal to), >= (greater than or equal to).

inc $variable [ value ]

Increments $variable by value. The default value is 1.

init command

Sets the command string used to initialize the modem. The default is ATE0 Q0 V1 X1.

mode SLIP|CSLIP|PPP|TERM

Selects the serial protocol. The default is SLIP, so this should be set to PPP.

modem type

Sets the modem type. Ignore this command. The only legal value is HAYES, and that is the default.

netmask mask

Sets the address mask.

parity E|O|N

Sets the parity to even (E), odd (O), or no (N). No parity (N) is recommended for SLIP and PPP links.

password

Prompts the user for the password.

proxyarp

Installs a proxy ARP entry for the remote system in the local host’s ARP table.

print $variable

Displays the contents of $variable.

psend command

Executes command through the default shell passing the output to the serial device. The command runs using the user’s real UID.

port device

Identifies the serial device, such as cua0, that attaches the modem.

quit

Exits the script with a nonzero exit status, aborting the connection.

reset

Resets the modem.

send string

Passes string to the serial device.

shell command

Executes command through the default shell. The command runs using the user’s real UID.

skey [ timeout ]

Waits for an S/Key challenge from the remote terminal server, prompts the user for the secret key, and generates and sends the response. Waits timeout seconds for the challenge. If the timer expires, $errlvl is set to 1; otherwise, it is set to 0. S/Key must be compiled into dip.

sleep time

Delays time seconds.

speed bits-per-second

Sets the port speed. The default is 38400.

stopbits 1|2

Sets the number of stop bits to 1 or 2. Enables terminal mode. In terminal mode, keyboard input is passed directly to the serial device.

timeout time

Sets the time in seconds that the line is allowed to remain inactive. When this timer expires, the link is closed.

wait text [ timeout ]

Waits timeout seconds for the text string to arrive from the remote system. If timeout is not specified, the script will wait forever.

In the next section we put some of these commands to work in a realistic script.

A sample dip script

This script is based on the PPP sample from Chapter 6. Labels and error detection have been added to create a more robust script.

# Select configuration settings 
setup: 
# Ask PPP to provide the addresses 
get $local 0.0.0.0 
# Select the port 
port cua1 
# Set the port speed 
speed 57600 
# Create a loop counter 
get $loopcntr 0 
 
# Dial the remote server 
dialin: 
# Reset the modem and clear the input buffer 
reset 
flush 
# Dial the PPP server and check the modem response 
dial *70,301-555-1234 
# If BUSY, dial again 
if $errlvl == 3 goto redial 
# If some other error, abort 
if $errlvl != 1 goto dial-error 
# Otherwise rest loop counter 
get $loopcntr 0 
# Give the server 2 seconds to get ready 
sleep 2 
 
# Login to the remote server 
login: 
# Send a carriage-return to wake up the server 
send \r 
# Wait for the Username> prompt and send the username 
wait name> 20 
if $errlvl != 0 goto try-again 
send kristin\r 
# Wait for the Password> prompt and send the password 
wait word> 10 
if $errlvl != 0 goto server-failure 
password 
# Wait for the PPP server's command-line prompt 
wait > 20 
if $errlvl != 0 goto server-failure 
# Send the command required by the PPP server 
send ppp enabled\r 
 
# Success! We're on-line 
connected: 
# Set the interface to PPP mode 
mode PPP 
# Exit the script 
exit 
 
# Error processing routines 
 
# Try dialing 3 times.  Wait 5 seconds between attempts 
redial: 
inc $loopcntr 
if $loopcntr > 3 goto busy-failure 
sleep 5 
goto dialin 
 
# Try a second carriage return 
try-again: 
inc $loopcntr 
if $loopcntr > 1 goto server-failure 
goto login 
 
 
dial-error: 
print Dial up of $remote failed. 
quit 
 
server-failure: 
print $remote failed to respond. 
quit 
 
busy-failure: 
print $remote is busy.  Try again later.
quit

This script provides a realistic example of the commands used in most scripts. However, you may encounter a particularly tough scripting problem. If you do, the abundance of scripting commands available with dip should be able to handle it. If dip can’t do the job, try expect. See Exploring Expect by Don Libes (O’Reilly & Associates) for a full description of the expect scripting language.

The PPP Daemon

The PPP Daemon (pppd) is a freely available implementation of the Point-to-Point Protocol (PPP) that runs on many Unix systems. Examples of configuring and using pppd are covered in Chapter 6. The syntax of the pppd command is:

pppd[device] [speed] [options]

device is the name of the serial port over which the PPP protocol operates and speed is the transmission speed of that port in bits per second. The complexity of this command comes not from these simple parameters but from the large number of options that it supports. There are so many options, in fact, that they are often stored in a file. There are three options files that can be used with pppd: the /etc/ppp/options file, which is used to set systemwide pppd options; the ~/.ppprc file, which is used by an individual to set personal pppd options; and the /etc/ppp/options. device file, which sets options for a serial device, e.g., /etc/ppp/options.cua0 sets options for cua0. The order of precedence for options is that those specified in the /etc/ppp/options.device file are the highest priority, followed by those defined on the command line, then those in the ~/.ppprc file, and, finally, those defined in the /etc/ppp/options file. Some options that relate to system security, once defined in the /etc/ppp/options file, cannot be overridden by the user through the command line or the ~/.ppprc file. The system administrator can override any option set by the user by setting the option in the /etc/ppp/options.device file.

The following list contains all of the pppd options except those that do not relate to TCP/IP:

local_IP_address : remote_IP_address: Defines static local and remote IP addresses. Either address may be omitted. For example, 172.16.25.3: defines only the local address, while :172.16.25.12 defines only the remote address. The default local address is the IP address associated with the local system’s hostname.
active-filter filter-expression: Defines a packet filter that determines which packets are regarded as link activity. Packets that pass through the filter reset the idle timer or cause the link to initialize when it is in demand-dial mode. The kernel and pppd must be compiled with PPP_FILTER defined.
allow-ip address: Systems using the specified IP address, which can identify individual hosts or entire networks, do not need to be authenticated.
asyncmap map: Defines the ASCII control characters that must be sent as two-character escape sequences. The first 32 ASCII characters are control characters. map is a 32-bit hex number with each bit representing a control character. Bit 0 (00000001) represents the character 0x00; bit 31 (80000000) represents the character 0x1f. If a bit is on in map, the character represented by that bit must be sent as an escape sequence. If no asyncmap option is specified, all control characters are sent as escape sequences.
auth: Requires the use of an authentication protocol. See Chapter 6 for a discussion of the authentication protocols CHAP and PAP.
bsdcomp receive , transmit: Enables the BSD-Compress scheme to compress packets. The maximum code word length used to compress packets accepted by this host is receive bits long. The maximum code word length used to compress packets sent by this host is transmit bits long. Acceptable code word length is 9 to 15 bits. Disable compression when receiving or transmitting by placing a 0 in receive or transmit, respectively.
call name: Reads options from a file named /etc/ppp/peers/ name.
cdtrcts: Tells pppd that the modem uses nonstandard hardware flow control based on the DTR and CTS signals.
chap-interval: Tells the system to use the Challenge Handshake Authentication Protocol (CHAP) to reauthenticate the remote system every n seconds.
chap-max-challenge n: Tells the system to send the CHAP challenge to the remote system a maximum of n times until the remote system responds. The default is 10.
chap-restart n: Tells the system to wait n seconds before retransmitting a CHAP challenge when the remote system fails to respond. The default is 3 seconds.
connect script: Invokes a script to create the serial connection. Any scripting language can be used, but chat is the most common. See Chapter 6 for an example of using connect to invoke an inline chat script.
connect-delay n: Waits n milliseconds after the connect script finishes for a valid PPP packet from the remote system.
crtscts: Enables hardware flow control (RTS/CTS).
debug: Logs all control packets sent or received using syslogd with facility daemon and level debug. The debug option can also be written as -d.
default-asyncmap: Disables asyncmap negotiation, forcing all control characters to be escaped.
default-mru: Disables Maximum Receive Unit negotiation and uses a default MRU of 1500 bytes.
defaultroute: Defines the PPP link as the default route. The route is removed when the connection is closed.
deflate nr , nt: Tells pppd to request Deflate packet compression. nr is the maximum receive window size expressed as a power of 2; i.e., if nr is 8, the receive window is 2 to the 8 (or 256) bytes. nt defines the maximum transmit window size expressed as a power of 2. If nt is not specified, it defaults to the value given for nr.
demand: Places the link in dial-on-demand mode. The network connection is made when network traffic is present.
disconnect script: Invokes a script to gracefully shut down the serial connection. Any scripting language can be used, but chat is the most common.
domain name: Defines the name of the local domain. Use this if hostname does not return a fully qualified name for the local system.
escape x,x,...: Specifies characters that should be transmitted as two-character escape sequences. The characters are specified in a comma-separated list of hex numbers. Any character except 0x20 - 0x3f and 0x5e can be escaped.
endpoint epdisc: Defines the endpoint discriminator sent to the remote system during multilink negotiation. The default endpoint discriminator is the MAC address of the first Ethernet interface or, if no Ethernet is found, the system’s IP address. epdisc is defined in the form type : value, where type is one of the keywords local, IP, MAC, magic, or phone, and value is either an IP address in dotted-decimal notation for the IP type, the name of an Ethernet interface for the MAC type, or a string of colon-separated hexadecimal bytes for the other types. Multilink is available only on Linux systems.
file file: Defines another options file, where file is the name of the new file. Options are normally read for /etc/ppp/options, ~/.ppprc, the command line, and /etc/ppp/options.device. See the description of these files earlier in this section.
hide-password: Hides the password string when logging the contents of Password Authentication Protocol (PAP) packets.
holdoff n: Waits n seconds before restarting the link after the link terminates.
idle n: Disconnects the link if no data packets are sent or received for n seconds.
init script: Executes script to initialize the serial line.
ipcp-accept-local: Tells the system to use the local IP address provided by the remote server even if it is defined locally.
ipcp-accept-remote: Tells the system to use the remote IP address provided by the remote server even if it is defined locally.
ipcp-max-configure n: Tells the system to send the IPCP configure-request packet a maximum of n times. The default is 10.
ipcp-max-failure n: Tells the system to accept up to n IPCP configure-NAKs before sending a configure-reject. The default is 10.
ipcp-max-terminate n: Tells the system to send no more than n IPCP terminate-request packets without receiving an acknowledgment. The default is 3.
ipcp-restart n: Tells the system to wait n seconds before resending an IPCP configure-request packet. The default is 3.
ipparam string: Passes string to the ip-up and ip-down scripts. /etc/ppp/ip-up is a shell script executed by pppd when the link comes up. /etc/ppp/ip-down is a shell script executed by pppd when the link is brought down.
ipv6 local_interface_identifier , remote_interface_identifier: Sets the local and remote 64-bit interface identifier using standard IPv6 ASCII address notation. If no identifiers are defined, the system creates a random identifier. (See also the ipv6cp-use-ipaddr and the ipv6cp-use-persistent options.)
ipv6cp-max-configure n: Send a maximum of n IPv6CP configure-request packets. The default is 10.
ipv6cp-max-failure n: Accept a maximum of n IPv6CP configure-NAK packets. The default is 10.
ipv6cp-max-terminate n: Send a maximum of n IPv6CP terminate-request packets. The default is 3.
ipv6cp-restart n: Wait n seconds before resending an IPv6CP configure-request packet. The default is 3 seconds.
ipv6cp-use-ipaddr: Use the system’s IPv4 address as the IPv6 local interface identifier.
ipv6cp-use-persistent: Use the system’s unique persistent identifier as the IPv6 local interface identifier. Most systems do not support persistent identifiers.
kdebug n: Enables kernel-level debugging. n is 1 to print general debugging messages, 2 to print received packets, and 4 to print transmitted packets.
ktune: Tells the system to allow pppd to alter kernel settings. For example, on a Linux system, pppd could enable IP forwarding by setting /proc/sys/net/ipv4/ip_forward to 1 if allowed to do so.
lcp-echo-failure n: Tells the system to terminate the connection if no reply is received to n LCP echo-requests. Normally, echo-requests are not used for this purpose because “link down” conditions are determined by the modem hardware.
lcp-echo-interval n: Tells the system to wait n seconds before sending another LCP echo-request when the remote system fails to reply.
lcp-max-configure n: Tells the system to send the LCP configure-request packet a maximum of n times. The default is 10.
lcp-max-failure n: Tells the system to accept up to n LCP configure-NAKs before sending a configure-reject. The default is 10.
lcp-max-terminate n: Tells the system to send no more than n LCP terminate-request transmissions without receiving an acknowledgment. The default is 3.
lcp-restart n: Tells the system to wait n seconds before resending an LCP configure-request packet. The default is 3.
linkname name: Sets the logical name of the link to name. pppd writes its process ID into a file named ppp- name.pid in either /var/run or /etc/ppp. This maps each instantiation of pppd to a specific link.
local: Tells the system to ignore the DCD (Data Carrier Detect) and DTR (Data Terminal Ready) modem control lines.
lock: Tells the system to use a UUCP-style lock file to ensure that pppd has exclusive access to the serial device.
logfd n: Logs messages to file descriptor n.
logfile filename: Appends messages to the log file identified by filename.
login: Tells the system to use the /etc/passwd file to authenticate PAP users. Records the login in the wtmp file.
maxconnect n: Sets the maximum connection time to n seconds. After n seconds, the connection is terminated even if it is active.
maxfail n: Stop attempting to connect to the remote system after n consecutive connection attempt failures. The default value is 10 attempts.
modem: Tells the system to use the DCD (Data Carrier Detect) and DTR (Data Terminal Ready) modem control lines; wait for the DCD signal before opening the serial device; and drop the DTR signal when terminating a connection.
mp: This is an alias for the multilink option. See multilink.
mpshortseq: Use short, 12-bit sequence numbers in multilink headers instead of the standard 24-bit sequence numbers.
mrru n: Sets the Maximum Reconstructed Receive Unit (MRRU) to n bytes. The MRRU is the maximum packet size that can be received on a multilink bundle. The value is analogous to MRU on other media.
mru n: Sets the Maximum Receive Unit (MRU) to n bytes. MRU is used to tell the remote system the maximum packet size the local system can accept. The minimum is 128. The default is 1500.
ms-dns address: Supplies Domain Name System addresses to Microsoft Windows clients.
ms-wins address: Supplies Windows Internet Name Services (WINS) server addresses to Microsoft Windows clients.
mtu n: Sets the Maximum Transmission Unit (MTU) to n bytes. MTU defines the maximum length of a packet that can be sent. The smaller of the local MTU and the remote MRU is used to define the maximum packet length.
multilink: Enables the multilink protocol, which allows multiple physical connections to be bundled together as one logical link. This is used to increase the bandwidth to a remote system. For example, two modem connections to a single remote system could be viewed as a single multilink bundle to give twice the bandwidth of one modem connection. This option is currently available only with Linux.
name name: Tells the system to use name as the name of the local system for authentication purposes.
netmask mask: Defines the subnet mask.
noaccomp: Disables Address/Control compression negotiation.
noauth: Allows unauthenticated access.
nobsdcomp: Disables BSD-Compress compression.
noccp: Disables Compression Control Protocol (CCP) negotiation.
nocrtscts: Disables all types of hardware flow control.
nodtrcts: Disables all types of hardware flow control.
nodefaultroute: Prevents users from creating a default route using the defaultroute option.
nodeflate: Disables Deflate compression.
nodetach: Prevents pppd from running as a background process. See the example in Chapter 6.
noendpoint: Tells the system not to send or accept Multilink endpoint discriminators.
noip: Disables the IPCP and IP protocols.
noipv6: Disables IPv6CP negotiation and IPv6 communication.
noipdefault: Instructs the system not to use hostname to determine the local IP address. The address must be obtained from the remote system or explicitly set by an option.
noktune: Prevents pppd from changing kernel values.
nolog: Disables logging.
nomagic: Disables magic number negotiation.
nomp: Disables the multilink protocol.
nompshortseq: Disables the use of short, 12-bit sequence numbers in the multilink protocol.
nomultilink: Disables the multilink protocol.
nopcomp: Disables protocol field compression negotiation. By default, protocol field compression is not used. Setting this option means that even if the remote end requests it, it will not be used.
nopersist: Terminates when the connection is made. This is the default.
nopredictor1: Tells the system not to use Predictor-1 compression.
noproxyarp: Disables the proxyarp option, preventing users from creating proxy ARP entries with pppd.
notty: Causes pppd to transmit characters to standard output and receive them on standard input. This option increases latency and overhead.
novj: Disables Van Jacobson header compression.
novjccomp: Disables the connection-ID compression option in Van Jacobson header compression.
papcrypt: Instructs the system not to accept passwords that are identical to those in the /etc/ppp/pap-secrets file because the ones in the file are encrypted. Therefore the transmitted password should not match an entry in the pap-secrets file until it is also encrypted.
pap-max-authreq n: Tells the system to transmit no more than n PAP authenticate-requests if the remote system does not respond. The default is 10.
pap-restart n: Tells the system to wait n seconds before retransmitting a PAP authenticate-request. The default is 3 seconds.
pap-timeout n: Tells the system to wait no more than n seconds for the remote system to authenticate itself. When n is 0, there is no time limit.
pass-filter filter-expression: Defines a packet filter that determines which packets can be sent or received over the PPP link. Packets that do not pass through the filter are silently discarded. filter-expression is defined using the syntax of tcpdump.
passive: Tells the system to wait for a Link Control Protocol (LCP) packet from the remote system even if that system does not reply to the initial LCP packet sent by the local system. Without this option, the local system aborts the connection when it does not receive a reply. The passive option can also be written as -p.
persist: Tells the system to reopen the connection if it was terminated by a SIGHUP signal.
plugin filename: Loads a shared library object as a “plugin” to pppd.
predictor1: Tells the system to ask the remote system to use Predictor-1 compression.
privgroup group-name: Allows all members of the group group-name to use privileged options.
proxyarp: Tells the system to enable proxy ARP. This adds a proxy ARP entry for the remote system to the local system’s ARP table.
pty script: Identifies a script that is run as a child process and used as the communications source in lieu of a terminal device. If used in conjunction with the record option, the child process will have pipes on its standard input and output.
receive-all: Tells the system to accept all control characters from the remote system, even those that should be discarded according to the standard asyncmap handling defined in RFC 1662.
record filename: Tells the system to log every character sent and received to filename.
remotename name: Tells the system to use name as the remote system’s name for authentication purposes.
refuse-chap: Disables the use of CHAP. This is a bad idea.
refuse-pap: Disables the use of PAP.
require-chap: Requires the use of CHAP.
require-pap: Requires the use of PAP.
show-password: Shows the password when PAP packets are logged.
silent: Tells the system to wait for an LCP packet from the remote system. Do not send the first LCP packet.
sync: Tells the system to use synchronous HDLC physical layer protocols instead of the default asynchronous protocol.
updetach: Tells the system to detach from the controlling terminal after the connection is made.
usehostname: Disables the name option, forcing the local hostname to be used for authentication purposes.
usepeerdns: Asks the remote system to provide up to two DNS server addresses. The provided addresses are passed up to the /etc/ppp/ip-up script in the environment variables DNS1 and DNS2. Additionally, pppd uses the addresses to create nameserver lines in a file named /etc/ppp/resolv.conf.
user username: Tells the system to use username for PAP authentication when challenged by a remote host.
vj-max-slots n: Tells the system to use n connection slots for Van Jacobson header compression. n must be a number from 2 to 16.
welcome script: Execute script before initiating PPP negotiation.
xonxoff: Enables software flow control (XON/XOFF).

Several of the options listed above concern PPP security. One of the strengths of PPP is its security. The Challenge Handshake Authentication Protocol (CHAP) is the preferred PPP security protocol. The Password Authentication Protocol (PAP) is less secure and is only provided for compatibility with less capable systems. The usernames, IP addresses, and secret keys used for these protocols are defined in the /etc/ppp/chap-secrets file and the /etc/ppp/pap-secrets file. Chapter 6 shows the format of these files and describes their use.

It is very important that the directory /etc/ppp and its contents not be world- or group-writable. Modifications to the chap-secrets, pap-secrets, or options files could compromise system security. In addition, the script files /etc/ppp/ip-up and /etc/ppp/ip-down may run with root privilege. If pppd finds a file with the name ip-up in the /etc/ppp directory, it executes it as soon as the PPP connection is established. The ip-up script is used to modify the routing table, process the sendmail queue, or do other tasks that depend on the presence of the network connection. The ip-down script is executed by pppd after the PPP connection is closed and is used to terminate processes that depend on the link. Clearly these scripts and the /etc/ppp directory must be protected.

Signal Processing

pppd handles the following signals:

SIGUSR1: This signal toggles debugging on or off. The first SIGUSR1 signal received by pppd turns on debugging and begins logging diagnostic messages through syslogd with facility set to daemon and level set to debug. The second SIGUSR1 signal turns off debugging and closes the log file. See the debug option described previously.
SIGUSR2: This signal causes pppd to renegotiate compression. It has limited applicability because it is needed only to restart compression after a fatal error has occurred. Most people close the PPP connection and open a new one after a fatal error.
SIGHUP: This signal closes the PPP connection, returns the serial device to its normal operating mode, and terminates pppd. If the persist option is specified, pppd opens a new connection instead of terminating.
SIGINT: This signal, or the SIGTERM signal, closes the PPP connection, returns the serial device to its normal operating mode, and terminates pppd. The persist option has no effect.

chat

chat is a general-purpose scripting language that is used to control the modem, dial the remote server, and perform the remote system login. chat is less powerful than dip but is widely used. The “expect/send” structure of a chat script is the fundamental structure used in most scripting languages.

A chat script is composed of expect/send pairs. These pairs consist of the string expected from the remote system, separated by whitespace from the response that is sent to the remote host when the expected string is received. If no string is expected from the remote system, two quotes ("") or two apostrophes ('') are used to “expect nothing.” A simple chat script is:

 "" \r name> jane word> TOga!toGA

The script expects nothing ("") until it sends the remote system a carriage return (\r). Then the script expects the remote system to send the string name>, which is part of the system’s Username> prompt. In response to this prompt, the script sends the username jane. Finally the script waits for part of the Password> prompt and responds with TOga!toGA. A script this simple can be defined directly on the chat command line:

% chat -v -t30 "" \r name> jane word> TOga!toGA

This command runs chat in verbose mode, sets the length of time the script waits for an expected string to 30 seconds, and then executes the simple login script described above.

The syntax of the chat command is:

chat [options] [script]

The chat command options are:

-e: Echo all output from the modem to stderr. This has the same effect as using the ECHO keyword inside the chat script.
-E: Enables the use of environment variables inside the chat script.
-s: Send all log entries and all error messages to stderr.
-S: Do not send log messages or error messages to the SYSLOG.
-T phone-number: Replace the \T escape sequence in the chat script with the values specified for phone-number.
-U phone-number-2: Replace the \U escape sequence in the chat script with the value specified for phone-number-2.
-v: Runs the chat script in verbose mode. Verbose mode logs informational messages via syslogd.
-V: Runs the chat script in stderr verbose mode. The stderr verbose mode displays informational messages on the stderr device. See Chapter 6 for an example of this being used with pppd.
-t timeout: Sets the maximum time to wait for an expected string. If the expected string is not received in timeout seconds, the reply string is not sent and the script terminates—unless an alternate send is defined. If defined, the alternate send (more about this later) is sent and the remote system is given one more timeout period to respond. If this fails, the script is terminated with a nonzero error code. By default, the timeout period is 45 seconds.
-f scriptfile: Reads the chat script from the scriptfile instead of from the command line. Multiple lines of expect/send pairs are permitted in the file.
-r reportfile: Writes the output generated by REPORT strings to the reportfile. By default, REPORT strings are written to stderr. The REPORT keyword is covered below.

In order to make the scripts more useful and robust, chat provides special keywords, escape sequences, and alternate send/expect pairs that can be used in the script. First let’s look at the six basic chat keywords.

Two keywords transmit special signals to the remote system. The keyword EOT sends the End of Transmission character. On Unix systems, this is usually the End of File character, which is a Ctrl-D. The BREAK keyword sends a line break to the remote system. The five remaining keywords (TIMEOUT, ABORT, REPORT, CONNECT, and SAY) define processing characteristics for the script itself.

The TIMEOUT keyword defines the amount of time to wait for an expected string. Because it is defined inside the script, the timeout value can be changed for each expected string. For example, assume you want to allow the remote server 30 seconds to display the initial Username> prompt but only 5 seconds to display Password> once the username has been sent. Enter this script command:

TIMEOUT 30 name> karen TIMEOUT 5 word> beach%PARTY

The ABORT keyword and the REPORT keyword are similar. They both define strings that, when received, cause a special action to take place. The ABORT keyword defines strings that cause the script to abort if they are received when the system is expecting the string CONNECT from the modem. The REPORT keyword defines substrings that determine what messages received on the serial port should be written to stderr or the report file. A sample chat script file illustrates both of these keywords:

REPORT CONNECT 
ABORT BUSY 
ABORT 'NO CARRIER' 
ABORT 'RING - NO ANSWER' 
SAY "Dialing your PPP server..."
"" ATDT5551234 
CONNECT \r 
name> karen
word> beach%PARTY

The first line says that any message received by the script that contains the word CONNECT will be logged. If the -r command-line option was used when chat was started, the message is logged in the file defined by that option. Otherwise the message is displayed on stderr. The point of this command is to display the modem’s connect message to the user. For example, the complete message might be CONNECT 28,800 LAPM/V, which tells the user the link speed and the transmission protocol used by the modems. The CONNECT message means success. The next three lines of the script begin with the keyword ABORT and define the modem messages that mean failure. If the modem responds with BUSY, NO CARRIER, or RING - NO ANSWER, the script aborts.

The SAY keyword sends the specified string to the user’s terminal. In this case, we are telling the user that the dialing process has begun.

The last four lines are the basic expect/send pairs we have seen repeatedly in this section. We expect nothing ("") and send the dial command to the modem (ATDT). We expect CONNECT from the modem and send a carriage return (\r) to the remote server. We expect Username> from the remote server and send karen. Finally, we expect Password> from the server and send beach%PARTY.

chat extends the standard expect/send pair with an alternate send and an alternate expect to improve robustness. You may define an alternate send string and an alternate expect value to be used when the script times out waiting for the primary expected value. The alternate send and the alternate expect are indicated in the script by preceding them with dashes. For example:

 gin:-BREAK-gin: becca

In this sample we wait for the string gin: and send the string becca. The first string and the last string compose the standard expect/send pair. The alternate send/expect is used only if the timer expires and the expected gin: string has not been received. When this occurs, the script sends a line break, restarts the timer, and waits for gin: again, because that is what our alternate send/expect pair (-BREAK-gin:) tells the script to do. Note that unlike the standard expect/send pair, in the send/expect pair a value is transmitted before a string is expected, i.e., the send comes before the expect. Another example more in keeping with our other script examples is:

 name>--name> karen

Here the script expects the name> string. If it is not received, the script sends an empty line, which is simply a carriage return, and again waits for the name> string. This action is dictated by the alternate send/expect pair, --name>. The pair begins with a dash that signals the start of the send string, but the next character is the second dash that marks the beginning of the alternate expect string. There is no send string. It is this “empty string” that causes the script to send a single return character. This example is more common than the BREAK example shown above, though a little harder to explain.

The carriage return character is not the only special character that can be sent from a chat script. chat provides several escape sequences for sending and receiving special characters. Table A-2 lists these.

Table A-2. chat escape sequences

Escape sequence	Meaning
\b	The backspace character
\	Send without the terminating return character
\d	Delay sending for one second
\K	Send a BREAK
\n	Send a newline character
\N	Send a null character
\	Delay sending 1/10th of a second
\xd5	Send the string but don’t log it
\r	The carriage return
\s	The space character
\T	Send the value provided on the chat command line by the -T argument
\t	The tab character
\U	Send the value provided on the chat command line by the -U argument
\\	The backslash character
\ddd	The ASCII character with the octal value ddd
^C	A control character

All of the escape sequences start with a backslash (\) except for the sequence used to enter a control character. Control characters are entered as a caret (^) followed by an uppercase letter. For example, control X is entered as ^X. The escape sequences that are described in Table A-2 with the words “send” or “sending” can be used only in a send string; all others can be used in either a send or expect string. Several escape sequences are used in the following example:

"" \d\d^G\p^G\p\p^GWake\sUp!\nSleepy\sHead!

Expect nothing (""). Wait two seconds (\d\d). Send three ASCII BELL characters, which is Ctrl-G on the keyboard, at intervals of 1/10 of a second (^G\p^G\p\p^G). Send the string Wake Up!. Go to a new line (\n) and send the string Sleepy Head!.

For security reasons, some servers call the client back before allowing the connection. This allows the server to verify that the client call is coming from an approved telephone number. It works this way:

The client calls the server and provides an identifying string.
The server hangs up after receiving the string.
The server uses the identifying string to find out the valid phone number for the client and calls the client back.
The client continues with the login process.

The fact that the server hangs up the connection could cause a problem for a chat script. Normally, a hangup unconditionally ends the connection. chat provides the HANGUP command to handle “callback” servers. The command HANGUP OFF prevents chat from ending the login script when the server breaks the connection. Place the HANGUP OFF command immediately after the command that sends the identifying script to the server. After the server calls back and the connection is established, use the HANGUP ON command to return to normal hangup processing. HANGUP ON is the default. With HANGUP ON, the script terminates when a hangup is detected.

When a chat script terminates, a termination code is set. A termination code is a numeric value that represents the state of the script when it exited. The basic numeric codes and what those codes mean is shown below:

0: The script terminated normally.
1: The script failed because of an invalid parameter or an expect string that overflowed the internal buffer.
2: The script shut down because of an I/O error or a termination signal (SIGINT/SIGTERM).
3: The program terminated because an expected string was not received before the timeout.
4 or more: A condition defined by an ABORT command occurred. The numeric value indicates which condition occurred. The condition defined by the first ABORT command is assigned the value 4; the condition defined by the second ABORT command is assigned the value 5; the condition defined by the third ABORT command is assigned the value 6; and so on.

The termination codes 0 through 3 are self-explanatory. An example is useful for understanding the codes above 3.

The sample script shown earlier in this section contained three ABORT commands: the first one for the BUSY condition, the second one for the NO CARRIER condition, and the third one for the RING - NO ANSWER condition. If the modem returns the BUSY string, the script aborts and returns the termination code 4. If the modem returns the string RING - NO ANSWER, the script aborts and returns the termination code 6. The codes are “position dependent.” If another user rewrote this script and placed the ABORT RING - NO ANSWER command before the other ABORT commands, aborting on the RING - NO ANSWER condition would return a termination code of 4 instead of the 6 it returns in our script.

^[154]Serial Line IP (SLIP) predates PPP. Today most serial connections are PPP, which is what this appendix emphasizes.

Previous Chapter

13. Troubleshooting TCP/IP

Next Chapter

B. A gated Reference

Table of Contents for TCP/IP Network Administration, 3rd Edition