DP - Configuration

Compilation

/etc/dp.conf

Earlier versions of Dialup PPP placed files in very specific places. dp-2.3 and later allows flexible placement of files. The only really fixed file is /etc/dp.conf. It basically contains a list of pathnames for all of the other files. It looks like this:

Solaris 2.X version: 

	#
	# Config file for Dialup PPP.
	#
	# This file specifies the paths where all the related PPP files and
	# programs are located.
	#
	DPCONF_DIR=/etc/dp		 # System Specific Files
	DPLOG_DIR=/var/adm/dp		 # Log Files and Other Writeable Files
	DPPID_DIR=${DPLOG_DIR}/Pid	 # Files for Process IDs
	DPTRACE_DIR=${DPLOG_DIR}/Trace	 # Trace Files
	DPROTARY_DIR=${DPLOG_DIR}/Rotary # Rotary Files
	DPMUX_DIR=${DPLOG_DIR}/Mux	 # Streams Mux IDs
	DPID_DIR=${DPLOG_DIR}/Id	 # Module IDs
	DP_DIR=/opt/dp			 # Common Files for All Systems
	DPBIN_DIR=${DP_DIR}/bin		 # Programs
	DPSCRIPT_DIR=${DP_DIR}/script	 # Standard Dialing Scripts
	DPACCESS_DIR=${DP_DIR}/access	 # Standard Access Files
	DPAUX_DIR=${DP_DIR}/aux		 # Auxilliary Programs
	DPCRON_DIR=${DP_DIR}/cron	 # Scripts Run from Cron
	DPMODEM_DIR=${DP_DIR}/modem	 # Modem Support Programs
	DPMODULE_DIR=${DP_DIR}/modules	 # Kernel Modules

Solaris 1.X version 

	#
	# Config file for Dialup PPP.
	#
	# This file specifies the paths where all the related PPP files and
	# programs are located.
	#
	DPCONF_DIR=/etc/dp		 # System Specific Files
	DPLOG_DIR=/var/adm/dp		 # Log Files and Other Writeable Files
	DPPID_DIR=${DPLOG_DIR}/Pid	 # Files for Process IDs
	DPTRACE_DIR=${DPLOG_DIR}/Trace	 # Trace Files
	DPROTARY_DIR=${DPLOG_DIR}/Rotary # Rotary Files
	DPMUX_DIR=${DPLOG_DIR}/Mux	 # Streams Mux IDs
	DPID_DIR=${DPLOG_DIR}/Id	 # Module IDs
	DP_DIR=/usr/dp			 # Common Files for All Systems
	DPBIN_DIR=${DP_DIR}/bin		 # Programs
	DPSCRIPT_DIR=${DP_DIR}/script	 # Standard Dialing Scripts
	DPACCESS_DIR=${DP_DIR}/access	 # Standard Access Files
	DPAUX_DIR=${DP_DIR}/aux		 # Auxilliary Programs
	DPCRON_DIR=${DP_DIR}/cron	 # Scripts Run from Cron
	DPMODEM_DIR=${DP_DIR}/modem	 # Modem Support Programs
	DPMODULE_DIR=${DP_DIR}/modules	 # Kernel Modules

The DPCONF_DIR typically contains files that are specific to a given system. The ${DPCONF_DIR}/conf file contains the bulk of the interface configuration. In addition, script and access files specific to a single system can be placed in this directory.

The DPLOG_DIR contains log files and files that get written frequently. The other directories should be relatively static from one machine to the next. The default configuration file groups them all under ${DP_DIR}. This can be changed to suit local needs.

${DPCONF_DIR}/hostnames

This file should contain a list of all the dp interfaces and include the local and remote IP address used on the interface.

If you have 3 interfaces, and all of them have the same local IP address, and you have 3 remote sites with (necessarily) unique addresses, the file would look like this: 

	dp0 local-dp remote0-dp
	dp1 local-dp remote1-dp
	dp2 local-dp remote2-dp

${DPCONF_DIR}/conf

When, the programs dpd and dplogin are started, they read a configuration file ${DPCONF_DIR}/conf. This file has a definition for each interface, each modem, and optionally a number of modem rotaries.

A definition begins in the first column of a new line. Continuation lines must begin with white space (SPACE or TAB characters). Comments can be placed anywhere in a line after a #. Strings can be delimited by double quote characters (""), if necessary.

For a given definition, each variable is given a value with the variable name, an equal sign, and the value. For instance, the first entry in the definition for the dp0 interface is: 

	IF=dp0
This section defines all the possible options, their possible values, and gives some examples to show how they might be used.

Interfaces

Each interface corresponds to a logical network connection to a single remote site. Provisions are made in the interface definition to specify how calls should be made and received in order to handle traffic on that interface.

IF

The IF variable must be the first entry in the interface definition. Its value is the name of the network interface (e.g. IF=dp0).

SYS

The SYS variable can be optionally set to indicate a system name to be used when making log entries. If the SYS variable is not explicitly set, it defaults to the internet name of the remote site (as returned by gethostbyaddr()), or if that fails, the internet address of the remote site in dot notation.

MODEMS

The MODEMS variable specifies the modems or modem rotaries that should be used to make calls for this interface. At least one modem or modem rotary must be specified. If more than one modem or modem rotary is specified, when a call request is made, each entry in the list is tried in turn until an available modem is found. The names used in this list must correspond to a MODEM or ROTARY definition as specified in the configuration file.

PHONE

The PHONE variable specifies the phone number that will be passed to the DIAL_SCRIPT as defined by the modem in use on a particular call. In dp-3.1 and later, this variable can be given as a comma separated list of numbers. If a dial script returns busy, the next number in the list will be attempted.

LOGIN_SCRIPT

The LOGIN_SCRIPT variable specifies an expect script that will be used to log into the remote system for the purposes of establishing a PPP connection. These scripts are found, by default, in ${DPSCRIPT_DIR} and will be described in detail later. Scripts specific to a single system can also be placed in ${DPCONF_DIR}.

LOGIN_ARGS

The LOGIN_ARGS variable is a comma-separated list of arguments to the expect script as defined by the value of LOGIN_SCRIPT. This is typically the login and password on the remote machine.

LOGIN

The LOGIN variable has practically nothing to do with the LOGIN_SCRIPT and LOGIN_ARGS variables, both of which deal with outgoing calls. The LOGIN variable, instead, is set to allow a particular login id to be used to call in to establish a PPP connection. When dplogin is called, it knows what account was used to log into the system. It searches the configuration file for an interface where the LOGIN variable is set to that same account.

TRACE

The TRACE variable can be used to specify a trace file for the calling script. The trace files are written in ${DPTRACE_DIR}. If there is a problem with establishing a particular connection, this variable can be set to see what characters are being transferred when the DIAL_SCRIPT and LOGIN_SCRIPT are both run.

ACCESS

An ACCESS file can be specified. This file defines a number of additional variables and can be used to limit the conditions for which calls will be made. This file is located, by default, in the ${DPACCESS_DIR} directory. Access files local to a single system can be placed in the ${DPCONF_DIR}. This file will be described in detail in the its own section.

PPP_ARGS

When the PPP program ${DPBIN_DIR}/ppp is started by dpd or dplogin, you can specify additional arguments to be put in the argument list. For instance, if you are using dp.3.X to talk to a dp.2.0 installation, the default header compression negotiation has changed with the new patch level of PPP. So, in the 3.X configuration file, you can put the line: 
	PPP_ARGS=vjmode,rfc1172
This will talk to very old PPP servers. Also, in dp-3.1.3 or newer, the default VJ compression mode is rfc1332. Although negotiation should work normally, if you have trouble talking to dp-3.1.2 or earlier, you will need: 
	PPP_ARGS=vjmode,pre1332
Two new options are available in dp-3.1.3 or newe. As an example, in order to disable VJ header slot compression and set up for 4 compression slots, you would use the following PPP_ARGS: 
	PPP_ARGS=-vjccomp,vj-max-slots,4
This was tested with a Xyplex terminal server which was set up with those options.

Additionally, a new option is available called "dynamic". This should allow dynamic addressing and is available for testing. For instance to dialin to a terminal server with a fixed address (A.B.C.D) but the local address is dynamic, use he following arguments: 

	PPP_ARGS=dynamic,:A.B.C.D
This should allow the dynamic allocation of a local address. Also, please note that in Solaris 2.1 or Solaris 2.2, this option may cause problems with multiple interfaces sharing the same local address.

PRE_AUX, POST_AUX, or FAIL_AUX

The PRE_AUX variable specifies an auxiliary program that will be run after a PPP link is established for a particular interface. The default location for these programs is ${DPAUX_DIR}. An example program is provided that checks the sendmail queue for queued messages. This could be run to make sure mail messages are sent out whenever the link is established for any reason.

The POST_AUX variable specifies an auxiliary program that will be run after a PPP link is torn down for a particular interface. The default location for these programs is ${DPAUX_DIR}. This might be used to udpate a status file or work around bugs in the terminal drivers.

The FAIL_AUX variable specifies an auxiliary program that will be run after a failed call attempt. The default location for these programs is ${DPAUX_DIR}. This might be used to udpate a status file or work around bugs in the terminal drivers.

PRE_AUX_ARGS, POST_AUX_ARGS, or FAIL_AUX_ARGS

Arguments may be provided to AUX program by specifying them here as a comma separated list of arguments, much like the PPP_ARGS variable. The last three arguments provided to the AUX script is always the system name from the SYS variable, the interface name (e.g. dp1), and the serial port device name (e.g. cua/8).

LOG_LEVEL

The Log Level can be set when dpd is started. The LOG_LEVEL variable overides the current log level for calls made to this system. In addition, dplogin will set the same LOG_LEVEL for incoming calls.

ASYNC_MAP

The PPP program can be setup to avoid using certain control characters on links that aren't totally transparent. This takes the form of a 8 digit hexadecimal string representing a 32 bit number. The lowest to highest order bits of the number correspond to the ASCII character represented by 0 through 31. If the bit is set, that character will not be transmitted on the line, but will instead be replaced by a special escape sequence. By default, the ASYNC_MAP is set to 0, which means pass all characters since we have a totally transparent link. This variable applies to all calls made to this system on any device.

Modems

A modem entry is required for each serial device that can be used to establish a connection to a remote system.

MODEM

The MODEM variable must be the first entry in the modem definition. Its value is an arbitrary (hopefully descriptive) name. This same name is used in the interface definition as a value for the MODEMS variable.

DEV

The DEV variable is set to the physical serial device path name. If the entry does not begin with a "/", then it is assumed that the device appears in the "/dev" directory. Sun has a scheme for using the same line for dial out and dial in. For most configurations, you should use the name of the dial out device.

Under Solaris 1, you may have to make this device as follows. The dialout device the one with the 0x80 bit set in the minor number. As an example, assume we are using "ttya" and we want to make a dialout device "cua0". Here are some example commands run as root to make the device. 

	# ls -lg /dev/ttya
	crw--w--w-  1 root     wheel     12,   0 May 21 12:30 /dev/ttya
	# /etc/mknod /dev/cua0 c 12 128
	# chmod 660 /dev/cua0
	# /etc/chown uucp.uucp /dev/cua0
	# ls -lg /dev/ttya /dev/cua0
	crw--w--w-  1 root     wheel     12,   0 May 21 12:30 /dev/ttya
	crw-rw----  1 uucp     uucp      12, 128 May 21 12:30 /dev/cua0
Then, you would put DEV=cua0 in your modem definitions to use this device.

DIAL_SCRIPT

The DIAL_SCRIPT variable is the name of a script file. The directories ${DPCONF_DIR} and ${DPSCRIPT_DIR} are searched for these files. By convention, common scripts are placed in ${DPSCRIPT_DIR} while system-specific scripts are placed in ${DPCONF_DIR}. This script will be used to interact with the modem and make the call. The phone number is passed as the first and only argument to the script.

The next section describes modem rotaries. If all the modems in a rotary use the same DIAL_SCRIPT, it is not necessary to set each one individually. The DIAL_SCRIPT variable is set from the ROTARY definition.

BAUD

The BAUD variable is the baud rate to use for outgoing calls on this modem.

The next section describes modem rotaries. If all the modems in a rotary use the same baud rate, it is not necessary to set each one individually. The BAUD variable is set from the ROTARY definition.

DIAL_CHARMAP

This variable is set in order to map characters embedded in phone numbers to the appropriate modem-specific control character. For instance, it may be a common practice to include a '=' in phone numbers when you have to wait for a secondary dial tone and a '-' when you just have to pause for a second. For US Robotics or Telebit modems, then the remapping would be performed with: 
    DIAL_CHARMAP==W-,
which means wait for dial tone is 'W', and a short pause is ','. This allows modems of different brands to be used without undue difficulty.

ASYNC_MAP

The PPP program can be setup to avoid using certain control characters on links that aren't totally transparent. This takes the form of a 8 digit hexadecimal string representing a 32 bit number. The lowest to highest order bits of the number correspond to the ASCII character represented by 0 through 31. If the bit is set, that character will not be transmitted on the line, but will instead be replaced by a special escape sequence. By default, the ASYNC_MAP is set to 0, which means pass all characters since we have a totally transparent link. This variable applies to all calls made with this specific modem.

Modem Rotaries

If you are administering a central hub machine with several modems, you may wish to define a modem rotary. When defining the interfaces, you can set the modem variable to a list of modems (or rotaries). Each one will be tried in turn until an available modem if found. For a large number of modems, this is not very tolerant to hardware failures. If the first modem in the list is broken, calls will always fail. This approach is sometimes called using the "first available" modem.

An alternative approach is to define modem rotaries. A rotary is best described as a "next available" approach. The software keeps track of the last modem used, and always starts with the next modem in the list. When the end of the list is reached, the search wraps aournd to the first modem. This reduces overhead of finding a free modem and insures that a bad modem will not totally shut down communications.

ROTARY

The ROTARY variable must be the first entry in the modem definition. Its value is an arbitrary (hopefully descriptive) name. This same name is used in the interface definition as a value for the MODEMS variable. Modems and rotaries can both be listed in the MODEMS variable equally well.

MODEMS

The MODEMS variable is set to a comma-separated list of one or more modems. The entries in the list are the names of the modems as defined by their MODEM variable. All entries in this list must be modems. Other rotaries cannot be used here.

DIAL_SCRIPT

The DIAL_SCRIPT variable is the name of a script file. The directories ${DPCONF_DIR} and ${DPSCRIPT_DIR} are searched for these files. By convention, common scripts are placed in ${DPSCRIPT_DIR} while scripts specific to single systems are placed in ${DPCONF_DIR}. This script will be used to interact with the modem and make the call. The phone number is passed as the first and only argument to the script.

This entry will be used if the MODEM definition does not define a DIAL_SCRIPT itself. This is useful when a pool of modems are all the same type and the DIAL_SCRIPT is the same for all of them.

BAUD

The BAUD variable is the baud rate to use for outgoing calls on any modem in this rotary.

This entry will be used if the MODEM definition does not define a BAUD itself. This is useful when a pool of modems are all the same type and the baudrate is the same for all of them.

DIAL_CHARMAP

This variable can be set here instead of in the MODEM definition. If all the modems in a rotary are of the same brand, it is convenient to set this variable in the ROTARY definition rather than setting it in each MODEM definition.

ASYNC_MAP

This variable can be set here instead of in the MODEM definition, and then applies to all calls made with any modem in this rotary. If all the modems in a rotary are of the same brand, it is convenient to set this variable in the rotary definition rather than setting it in each modem definition.

Access Files

An access file can be defined to describe the conditions when a call is permitted and to set the timeouts appropriately. For instance, if you have some sites that are long distance toll calls, and some that are local calls, you may wish to have shorter timeouts on the toll calls than on the locals.

In dp-3.1 and later, the format of this file has been changed significantly. The file is no longer line oriented and directives can be split among lines freely. If the first line of the file is "DPAccess 2.0", the file will be interpreted as follows. Otherwise, the old syntax is still recognized, but not described here.

Syntax

The syntax should be generally logical here. The syntax as given here is a little on the loose side to make it easier for me to express it. Exampes will be given which should make things clearer. The access file contains a list of directives of the following form: 
directive   =	times:[allow | disallow] {
		    time_expr
		}
	    =	protos:[allow | disallow ] {
		    proto_expr
		}
	    =	addrs:[allow | disallow ] {
		    addr_expr
		}
	    =	timeouts:[ | dial | answer ] {
		    expr { timeoutlist }
		    ...
		    timeoutlist
		}

expr  	    = 	( expr )
	    = 	expr || expr
	    = 	expr && expr
	    = 	! expr
	    =	true
	    =	false
	    =	times:time_pat
	    =	protos:proto_pat
	    =	addrs:addrs_pat

pat	    =   rangelist		
	    =   rangelist/pat

rangelist   =	integer			# single number
		[integer,integer]	# range of numbers
		rangelist,rangelist	# list of ranges or numbers

timeoutlist =	timeout
	    =   timeout timeoutlist

timeout	    =   failedcall timeval
	    =   callwait   timeval
	    =   inactivity timeval
	    =   last_close timeval
	    =   non_stream timeval

timeval     =	seconds
	    =	minutes:seconds
	    =	hours:minutes:seconds
Expressions are all parsed left to right. The integer specified in patterns can be given symbolically and will be interpreted in the context of the pattern as given. For instance, the keywords mon, tue, ip, tcp, smtp, etc. can all be used in place of integer numbers in the appropriate places.

When specifying call conditions for times, protos, or addresses, the leading times:, protos: or addrs: can be left off.

Times

By default, calls can be placed at any time. If you wish to limit calls during certain hours of certain days, you can place a times:call or times:call:disallow entry in the access file. The days can be specified as: 
	sun	sunday
	mon	monday
	tue	tuesday
	wed	wednesday
	thu	thursday
	fri	friday
	sat	saturday
	weekdays
	weekends
For instance, if calls should only be allowed during "business" hours of monday through saturday (8-12 or 1-5), and 1-5 on Sunday with no calls in the evening or weekends, you would use the following entries: 
    times:allow {
	[mon,sat]/[8:00,12:00],[13:00-17:00] ||
	sun/[13:00-17:00]
    }

Protocols

We can limit the calls made by the protocol. Here is a sample access file entry that would not allow calls placed for delivery of smtp mail or for icmp echo requests. 
    protos:disallow {
	ip/tcp/smtp ||
	ip/icmp/echo
    }
Either protos:allow or protos:disallow can be set, but not both at the same time.

The program knows about ip, tcp, udp, and icmp protocol names.

A protocol can be prefixed with src: or dst: and will only match a packet with that protocol in the source or destination port, respectively. If a :src or :dst is appended to the protos directive, then all protocols are treated in that manner.

Hosts/Networks

To limit calls when certain hosts are involved, you can use further keywords.

In order to limit calls to packets which are destined to a list of specific hosts, you would use the addrs:allow keyword. So, if we wish calls to be placed for only hosts on the 192.100.10.0 network and the goodhost.com host, a line of the following form would be used: 

    addrs:allow {
	ip/192.100.10 ||
	goodhost.com
    }
The addresses given in these lists can be the name of a host, or an internet host or network address in dot notation.

An address can be prefixed with src: or dst: and will only match a packet with that address in the source or destination field, respectively. If a :src or :dst is appended to the addrs directive, then all addresses are treated in that manner.

Timeouts

There are five timeouts that can be specified. Normally, two of them remain the same at all times, and three of them may change for incoming and outgoing calls. Here is a sample section from an access file: 
    timeouts {
	failedcall	2:00	# time to mark network as down after failed call
	callwait	0:50	# time to allow for call to go through
    }
    timeouts:dial {
	protos:ip/tcp/70,80 {	# Handle Gopher and WWW traffic specially
	    last_close	2:00	# fast timeout after last TCP close
	    non_stream	2:00	# fast timeout for non-TCP traffic
	}
	inactivity	3:00	# time to let the connection sit idle
	last_close	0:08	# fast timeout after last TCP close
	non_stream	0:20	# fast timeout for non-TCP traffic
    }
    timeouts:answer {
	inactivity	4:00	# time to let the connection sit idle
    }
Since we are paying for outgoing calls made, we set short timers so that disconnections are prompt. For incoming calls, we set some limits just to keep the modem pool from being tied up.

Expressions can be given that limit the use of certain timeouts to certain types of packets. The packets can be filtered by protocol address, or time of day, or boolean combinations of these conditions. These tests are applied in order until all the timeout values are specified. The dial or answer timeouts are applied first depending on the nature of the connection. Then, if all timeouts are not specified, the generic timeouts are applied. Any given timeout is set to the value of the first directive that matches the conditions. The timeout specifications without a match expression apply to all packets.

callwait

When the kernel dp or dpif module requests a call be placed by dpd, the kernel starts the call wait timer. If no status has been reported from dpd within Callwait seconds, it is equivalent to receiving a FAILURE status from dpd.

failedcall

After a FAILURE status or after the expiration of the callwait timer, the interface is marked with the FAILEDCALL status. With that status set, no calls will be attempted. After failedcall seconds, the interface status is marked as DISCON, and call attempts will again be made.

Inactivity

If no packets have been sent or received through a PPP interface within Inactivity seconds, PPP is terminated and the interface is marked as DISCON.

tcp_close

TCP packets contain information about connections starting and ending. A count of active connections is maintained for each interface. When this count goes to zero, if no packets have been sent or received within tcp_close seconds, PPP is terminated and the interface is marked as DISCON.

non_stream

When the active TCP connection count goes to zero, and non-TCP packets are being transmitted, if no packets have been sent or received within tcp_close seconds, PPP is terminated and the interface is marked as DISCON. This timeout was renamed non_stream from non_tcp in dp-3.1. This reflects an effort to make dp flexible and not tied specifically to TCP/IP.

Script Files

The script mechanism is used by the dpd program to interact with modems and systems to make calls and log in to remote computers. It provides a full send-expect style facility, with many extensions to allow for timeouts, alternative choices and others. This is a direct extension of the DialupIP 2.0 script file mechanism with the following additions: Script files contain a sequence of lines, each with a command and zero or more arguments. Blank lines and lines beginning with # are ignored. Strings must be quoted with double quotes (") if they contain white space. Standard C escape sequences are valid (\b, \f, \n, \r, \t, or \000 where 000 is any octal number).

Several example script files are provided in the distribution for dialing several different Telebit modems directly into a remote system as follows: 

usr-dial	Dials the given number on a US Robotics Courier modem.
t1600-dial	Dials the given number on a Telebit T1600 modem.
t3000-dial	Dials the given number on a Telebit T3000 modem.
wb-dial		Dials the given number on a Telebit WorldBlazer modem.
ppp-login	Logs into a remote system directly.  The first argument
		is a login, and the second argument is the password.
		This assumes the login shell on the remote system is "dplogin",
		and performs simple synchronization with that program.
You may note that the t3000 and Worlblazer scripts are the same since we use V.32bis in both cases. For PEP usage, the WorldBlazer script will need to be modified to handle additional CONNECT messages.

abort

The abort command terminates the script with a failure code returned. Reading the script past the end of file is equivalent to the abort command.

busy

The busy command terminates the script with a busy code returned. This is similar to abort, but allows alternate phone numbers to be attempted for dial scripts.

go

The go command indicates success. For a dial script, success means that the call went through using the specific modem. For a login script, success means that PPP is started on the remote computer.

log text

This writes the given string to the log file ${DPLOG_DIR}/dp.log.

mark

As incoming bytes are received, they are saved in a buffer for possible later use by replay. The mark command indicates the beginning of where to start saving characters.

replay

Characters in the incoming buffer are replayed as if they are being received again. This replay starts at the most recent mark command.

recv "text" [ "text" ... ] timeout

The recv command is used to examine the incoming characters (which can be actual new characters, or older ones after a replay command. The command succeeds when a substring of the incoming characters matches one of the text patterns given. If the match has not succeeded in timeout seconds, the recv command returns failure. However, if the recv command is in a select block, control is passed to the next alternative.

use script [ "parameter" ... ]

The use command executes another script file and returns success or failure depending on the execution of the named script.

xmit "text"

This sends the indicated text to the remote system. A \x in the string will delay 1 second, and a \# will send a break. Also, the string $1 will be replaced by the first argument to the script, and so on. The arguments are given in the ${DPCONF_DIR}/conf file or as arguments to the use command.

Select Blocks

Select blocks allow you to specify alternatives on failure of specific recv commands.

The format is as follows: 

    {
	alternate
	    commands...
	alternate
	    commands...
    }
The {, }, and alternate keywords are actually commands and must be on separate lines. If a recv command fails, then control is passed to the next alternate. If all alternatives fail, then the select block returns a failure, and is equivalent to an abort.
Kirk Smith / ks@acn.purdue.edu Last updated: 8 August 1995