PPP.SYS(5) BSD Programmer's Manual PPP.SYS(5)NAMEppp.sys - PPP and SLIP remote host description file
SYNOPSIS
/etc/ppp.sys
DESCRIPTION
The /etc/ppp.sys file contains the configuration parameters for use by
the ppp(8) daemon when establishing PPP or SLIP connections. The entries
fall into several major categories:
o General configuration options
o SLIP only options (currently there are none)
o PPP options read before authentication
o PPP options read after authentication
o Dialing options (these will be deprecated in a future release)
Earlier versions of ppp(8) used the old style two letter option names.
Most of the two letter options have now been replaced by more descriptive
names, though the old two letter option names still work.
Generic options:
Option Type Description
device (dv) STR Device to be used to call out. If the
name is a the name of a synchronous inter-
face (e.g., ntwo0) then the ppp(8) utility
will use this interface to establish sync
PPP. If the device is a full path name to
an asynchronous serial device (e.g.,
/dev/tty00) then the ppp(8) utility will
use this device to establish async PPP.
dialin (di) BOOL Mark this entry as dial-in
dialout (do) BOOL Mark this entry as dial-out
direct BOOL Indicate that this is a directly connected
line.
link-down (ld) SCRIPT This script is called whenever the link
goes into a down state for normal sessions
and when ppp(8) is about to exit (due to a
SIGHUP or SIGINT) for dial on demand ses-
sions. It is called as:
link-down link-options sysname interface
local-addr remote-addr
If not specified then the command:
ifconfig interface -alias local-addr
-link0 -link1 -link2
will be run.
link-failed (lf) SCRIPT This script is called when ppp.sys was un-
able to initialize the link. It is in-
tended to undo any effects of the link-
init script. It is called as:
link-failed link-options sysname interface
If neither of the link-failed and link-
down scripts are specified then the com-
mand:
ifconfig interface -alias local-addr
-link0 -link1 -link2
will be run on initialization failure.
link-init (li) SCRIPT This script is called once LCP negotiation
and authentication are complete, but prior
to IPCP negotiation. Dial on demand ses-
sions do not wait for LCP negotiation and
execute this script immediately. See the
notes below on authentication. It is
called as:
link-init link-options sysname interface
The link-init should initialize the inter-
face with a local and remote IP address
(unless this is a PPP session and the ad-
dresses are expected to be provided by the
remote system). If not specified then the
following command will be run:
ifconfig interface local-addr remote-addr
This script is required for SLIP.
link-options (so) STR A list of options to pass to the various
link scripts. Currently the only valid
option is -debug.
link-up (lu) SCRIPT This script is run once IPCP negotiation
has been completed, The link-up should do
any routing or ARP work which needs to be
done for this session (dial on demand ses-
sions should do the routing in the link-
init script). Use of this script is not
limited to those cases. For instance, the
link-up might cause the mail queue to be
processed so any queued mail will be sent.
It might also invoke some command that
will cause the remote system to process
its mail queue. (There is no standard
method of causing the remote system to
process its mail queue. The solution is
left as an exercise for the reader.) It
is called as:
link-up link-options sysname interface
local-addr remote-addr
proxy SCRIPT Specify a proxy program (typically
/usr/libexec/ppp_proxy) to proxy the re-
quest to gettyd(8). The script is called
as:
proxy [-x] [-s ppp.sys-file] sysname
phone-number (pn) STR A list of phone numbers separated by a
vertical bar (|). These numbers will be
passed to gettyd(8) which will cycle
through them until a connection is estab-
lished or the list is exhausted.
slip (sl) BOOL Indicate that the SLIP protocol should be
used to establish the connection instead
of the PPP protocol.
speed (br) NUM Desired DTE speed of the line
stty-modes (ms) CSV If the terminal port requires special op-
tions, hardware flow control for example,
this string can be set to a comma separat-
ed stty(1)-style option set. For exam-
ple:
:stty-modes=cts_oflow,rts_iflow:
This has no meaning for sync lines. If a
proxy is being used, this entry will be
forwarded to the proxy within the request
destined for gettyd(8).
The following options enable various debugging features (mostly for PPP)
Option Type Description
debug-all BOOL Turn on all debugging.
debug-int BOOL Turn on internal debugging messages.
debug-packet BOOL Turn on one line control packet tracing.
debug-phase BOOL Turn on major phase change debugging.
debug-state BOOL Turn on state change debugging.
packet-dump BOOL Print hex dump of every control packet.
trace BOOL Print a detailed trace of control packets.
If the ppp_proxy(8) utility is used, it will use the following entries:
Option Type Description
s0 - s9 STR String to send on the n-th step of log-in
sequence.
e0 - e9 STR String to wait for on the n-th step of
log-in sequence.
t0 - t9 STR Timeout (in seconds) for receiving the ex-
pected string on the n-th step of log-in
sequence. The default timeout is 15 sec-
onds.
f0 - f9 STR Auxiliary string to send on the n-th step
of login sequence in case the correspond-
ing expected string was not received.
The following options are only used on PPP connections:
Option Type Description
acfc (pf) BOOL Enable address and control fields com-
pression. This option reduces the size
of a PPP packet header by two bytes,
which can be useful on slow links but can
cause computational overhead on fast syn-
chronous links. This option is the de-
fault on asynchronous lines.
allow-addr-change BOOL Allow IPCP negotiation of IP addresses.
auth-retries NUM Number of times authentication attempts
are allowed before the connection is
dropped.
chap BOOL Require CHAP authentication from the re-
mote system (server side).
chap-allow BOOL Indicate that the local system is willing
to authenticate to the remote system us-
ing CHAP authentication (client side).
chap-mode NUM The numeric chap mode to use during CHAP
authentication.
chap-name STR The name used to identify the CHAP user.
chap-secret STR The name used to lookup the chap secret.
Normally the name received from the re-
mote system is used to look up the se-
cret. chap-secret is to be used when the
name of the remote system is non-deter-
ministic or not unique (i.e., there are
two or more remote machines which return
the same name). For direct dial-in
clients the chap-secret field will need
to be in the ppp_direct entry.
chap-script STR The script to use to perform CHAP authen-
tication. The script is called in the
following modes:
chap-script
Produce a challenge on stdout
chap-script user id
Given a user and id, read a chal-
lenge from stdin and produce a re-
sponse on stdout.
chap-script -v user id
Given a user and id, read the re-
sponse and the challenge from stdin.
The script should exit with a 0 if
the response matched the challenge.
If the response was incorrect, the
script should exit with a non-zero
value and issue the reason to
stderr. The input read on stdin is
a single byte which contains the
number of bytes in the response,
which follows immediately. The
challenge follows the response
(there is no length byte for the
challenge, the challenge is assumed
to continue until EOF).
cmap (cm) CMAP Map of the special characters which
should be avoided in case the equipment
uses some of them for flow control or
link control or inserts the characters
for time fill. The map can be specified
as a 32-bit hexadecimal or octal number
(if it starts from 0x or 0 respectively)
in which case the least significant bit
corresponds to the null character and the
most significant bit to the character
with code 037 (US). Alternatively, it
can be specified as the string of letters
corresponding the control characters, for
example ``:cmap= QS:'' will represent a
mask with bits 0, 17 and 19 set. The de-
fault all-zero mask will allow transmis-
sion of all control characters. The us-
age of ``@'' to represent null (0) will
not work if ``@'' directly follows ``=''.
Use `` '' (space) instead. See cget-
str(3) for more information.
rx-cmap CMAP Same as cmap, just more verbose that it
is the receive cmap.
tx-cmap CMAP Specify the minimum set of bits we will
accept for the transmit cmap. It is
specified in the same manner that cmap is
specified.
echo-freq TIME The interval at which to send out LCP
echo requests. If no echo response is
received for 3 consecutive requests the
the line is determined to be dead and the
session is dropped. If not specified no
LCP echo requests will be sent.
ed-802.1 ADDR_802 Specify an 802.1 MAC Address to send as
an Endpoint Discriminator.
ed-ip ADDR Specify an IP Address to send as an End-
point Discriminator.
ed-local BOOL Send a Local class Endpoint Discrimina-
tor. The value sent is determined auto-
matically based on the system boot time
and the host name. Though this format is
deprecated (because uniqueness is not
guaranteed), it is useful when neither an
802.1 or static IP address is available.
ed-null BOOL Send a Null class Endpoint Discriminator.
Though this is the default value for the
Endpoint Discriminator, it is not recom-
mended; instead either the ed-802.1 or
ed-ip options should be used.
first-idle BOOL When sending a packet on a multi-link
session, have the PIF interface always
scan from the beginning of the list to
find the first idle interface.
first-up BOOL When sending a packet on a multi-link
session, have the PIF interface always
scan from the beginning of the list to
find the first interface that is up, ig-
noring whether or not it is currently ac-
tive doing output.
ftel (pf) BOOL Enable high-priority queueing of ``inter-
active'' TCP packets (with source or des-
tination ports assigned to services like
telnet or control connection of ftp(1)),
effectively giving them precedence over
all other IP packets. This can reduce
response time on links with mixed file
transfer and interactive traffic. This
function is a temporary and limited sub-
stitute for the still unsupported IP low
delay TOS (type of service). This option
is the default on asynchronous lines.
idle-timeout (id) TIME Set the idle timer to drop the connection
if no outgoing data packets were pro-
cessed during the specified number of
seconds (the maximum time is 32767 sec-
onds).
immediate (im) BOOL Immediate connection. If connection is
lost try to reconnect without waiting for
network traffic. Be sure to set idle-
timeout to zero when using this option.
interface (in) NUM The interface number for the system. In-
terface names for the asynchronous PPP
links are composed from the prefix
``ppp'' and the decimal number of the in-
terface, for example ``ppp7''. If inter-
face number is not specified the first
interface which is down will be allocat-
ed. You need to allocate as many ppp in-
terfaces as you have dial-in and dial on
demand entries (or else there will be
conflicts).
ipv4 BOOL
ipv6 BOOL By specifying ipv4 and/or ipv6, you can
control which IP layer protocol ppp.sys
will negotiate. If neither is specified,
the default action is to negotiate IPv4.
local-addr ADDR If the link-init script does not assign a
local IP address to the interface, use
this value as the local address.
mru (mr) NUM Specify the maximum packet size the local
side is willing to receive. This option
can be useful on packet-switching links
to prevent link-level packet fragmenta-
tion or in case of problems with hardware
flow control. The default value for mru
is 1500 bytes.
mrru NUM Specify the maximum packet size the local
side is willing to reconstruct. Specify-
ing this option will also enable PPP Mul-
ti-link Protocol, so the multilink option
doesn't need to be specified. The de-
fault value for mrru is 1600 bytes.
multilink BOOL Enable PPP Multi-link Protocol. The de-
fault mrru value will be used.
nolastlog BOOL This option disables updating of the
lastlog database for the user. This op-
tion only applies to PAP and CHAP logins
and can only be enabled on the ppp_direct
entry. The default action is to update
the lastlog database entry for the user
when authenticating via PAP or CHAP.
next-idle BOOL When sending a packet on a multi-link
session, have the PIF interface use a
round-robin technique to find the next
idle interface. This is the default ac-
tion.
next-up BOOL When sending a packet on a multi-link
session, have the PIF interface interface
use a round-robin technique to find the
next interface that is up, ignoring
whether or not it is currently active do-
ing output.
pap BOOL Require PAP authentication. The auth-pap
entry in the /etc/login.conf (which de-
faults to the same value as the auth en-
try if not defined) is used to determine
the default authentication style to be
used for PAP authentication. Use of the
rpasswd(8) authentication style allows
the use of PAP without requiring the user
to have an entry in the
/etc/master.passwd file.
pap-passwd STR This is the password to be sent to the
PAP server. This option requires the
pap-peerid option as well and implies
that this machine is willing to provide
PAP authentication.
pap-peerid STR This is the peer name to be sent to the
PAP server. This option requires the
pap-passwd option as well and implies
that this machine is willing to provide
PAP authentication.
pfc (pf) BOOL Enable protocol field compression. This
option eliminates an extra byte in PPP
packet header, which can be useful on
slow links but can cause computational
overhead on fast synchronous links. This
option is the default on asynchronous
lines.
primary-dns ADDR An address to use in response to the non-
standard Microsoft PPP request for the
primary name server address. Use of this
option is not encouraged.
primary-nbs ADDR An address to use in response to the non-
standard Microsoft PPP request for the
primary NetBUI server address. Use of
this option is not encouraged.
remote-addr ADDR If the link-init script does not assign a
remote IP address to the interface, use
this value as the remote address.
retries (mc) NUM The number of PPP protocol option negoti-
ation attempts before giving up. The de-
fault value is 10.
retry-timeout (to) TIME PPP configure/terminate retry timeout.
The default timeout is 3 seconds. The
deprecated to version of this command ac-
cepts a NUM instead of a TIME argument
and is expressed in terms of tenths of a
second (e.g., 30 is 3 seconds).
secondary-dns ADDR An address to use in response to the non-
standard Microsoft PPP request for the
secondary name server address. Use of
this option is not encouraged.
secondary-nbs ADDR An address to use in response to the non-
standard Microsoft PPP request for the
secondary NetBUI server address. Use of
this option is not encouraged.
sseq BOOL Negotiate the use of short sequence num-
bers for multi-link fragments. This op-
tion does not enable negotiation of the
PPP Multi-link protocol, you should use
either the multilink or mrru option to
enable the PPP Multilink Protocol.
tcpc (pf) BOOL Enable Van Jacobson's TCP header compres-
sion. This option enables compression of
TCP headers by eliminating redundant in-
formation in the headers of consecutive
TCP packets, reducing the protocol over-
head by up to 100 bytes per packet, which
may be critical to the performance of in-
teractive telnet(1) or rlogin(1) ses-
sions. However, VJ TCP compression re-
quires the system to keep state informa-
tion about every TCP session on both ends
(up to 16 simultaneous sessions) and is
not really useful on fast links connect-
ing large networks. TCP compression does
not affect UDP and ICMP packets. This
option is the default on asynchronous
lines.
term-retries (mt) NUM The number of attempts to terminate the
connection gracefully before hanging up.
The default value is 3.
timeout (wt) TIME Timeout on waiting for beginning of ses-
sion. The default timeout is 60 seconds.
For direct dial-in client, that is, clients which do not use the tradi-
tional login/password sequence, there must be a ppp_direct entry. The
ppp_direct entry is used to determine generic information about the serv-
er. A ppp_direct entry should have at least one of pap or chap defined.
If PAP or CHAP authentication is used, a ppp.sys entry should exist with
the PAP/CHAP name provided by the client. If no entry if found for the
client, the entry pap_default or chap_default will be used. If no entry
is found, the connection is dropped. Once authentication has been per-
formed (LCP negotiation is complete at this point) the following configu-
ration options may re-specified in the clients' ppp.sys entry. See above
for descriptions:
allow-addr-change debug-all debug-int debug-packet
debug-phase debug-state echo-freq ed-802.1
ed-local ed-null first-idle first-up
ftel idle-timeout link-down link-failed
link-init link-options link-up local-addr
mrru multilink next-idle next-up
packet-dump primary-dns primary-nbs remote-addr
secondary-dns secondary-nbs sseq trace
tcpc
The PPP Multi-link Protocol allows multiple physical PPP links to be
treated as a single PPP connection, or bundle. To enable or allow use of
the PPP Multi-link Protocol, either the multilink or mrru option must be
specified. Then one of the ed-* options is used to identify the Endpoint
Discriminator, which is used along with authentication information (if
available) to uniquely identify to the remote host which connections from
this host should be bundled together. The preferred options are the ed-
ip and ed-802.1 options, since these should be globally unique addresses.
In the absence of either of these, the ed-local option can be specified,
and a somewhat unique 20-byte string will be generated automatically.
One of first-up, first-idle, next-up, and next-idle can be specified to
select how to choose which interface of the bundle should be used to send
a packet. If none of them are specified, the default value is next-idle,
which will use a round-robin technique to find the next idle interface.
See ifconfig(8) for more details. The sseq option can be specified to
enable negotiation of short sequence numbers (12 bits instead of the de-
fault 24 bits).
A separate copy of ppp(8) needs to be running for each link of a Multi-
link bundle. A common /etc/ppp.sys entry can be used, unless there needs
to be unique information for each link of the bundle (such as explicitly
specifying the device, or a different phone number).
OPTION TYPES
Type Description
ADDR The address is expected to be a 32 bit IP address. The ad-
dress must be in a form acceptable to gethostbyname(3). This
includes both symbolic names and dotted quads (e.g.,
10.127.42.6).
ADDR_802 The address is expected to be a 48 bit 802.1 address. The ad-
dress must be in the form xx-xx-xx-xx-xx-xx where xx is a one
or two digit hex number.
NUM A numeric value processed by the strtol(3) function. While
the standard syntax is :option=value:, the older syntax of
:option#value: is allowed, which uses the cgetnum(3) function.
SCRIPT The path name of a script (e.g., /usr/libexec/chap_md5). The
script may be any executable file which performs the desired
function.
STR A string as returned by the cgetstr(3) function.
TIME A number of seconds. The value can be any floating point num-
ber recognized by the strtod(3) function. The ability to
specify a highly accurate time (e.g., 1.0345007 seconds) does
not imply that the software will be that accurate (i.e. it
will be around 1 second).
EXAMPLES
The following three entries are boiler plate used by the default scripts
provided with the system. They are used for dial-in, dial-out out (imme-
diate mode) and dial-on-demand sessions.
Dialin:\
:dialin:\
:link-init=/etc/netscripts/Dialin.login:\
:link-up=/etc/netscripts/Dialin.up:\
:link-down=/etc/netscripts/Dialin.down:
Dialout:\
:dialout:\
:link-init=/etc/netscripts/Dialout.login:\
:link-up=/etc/netscripts/Dialout.up:\
:link-down=/etc/netscripts/Dialout.down:
Demand:\
:dialout:\
:link-init=/etc/netscripts/Demand.login:\
:link-up=/etc/netscripts/Demand.up:\
:link-down=/etc/netscripts/Demand.down:
The following two entries define dial-in ppp sessions. The first entry,
ppp_direct, is used when the dial-in session begins with LCP negotiation
rather than the traditional login:/password: sequence provided by the lo-
gin(8) program. The login(8) program can recognize LCP sequences and
call ppp directly with the name of ppp_direct when they are seen. The
second entry defines an individual session for the account Pskeeter. If
used with either the traditional login:/password: sequence via login(8),
or when using PAP authentication via the ppp_direct entry, there must be
an account in the /etc/master.passwd file for Pskeeter which is group
netdial. There must also be an entry for Pskeeter in the
/etc/netscripts/addr-map file. The entry is the single line composed of
the name Pskeeter followed by white space and the IP address to assign to
Pskeeter.
ppp_direct:\
:dialin:\
:pap:\
:chap:\
:auth-retries=3:
Pskeeter:tc=Dialin:
The next four examples define dial-out PPP sessions. In all cases
REMOTEPHONENUMBER should be replaced by the phone number of the system to
dial. YOURLOGIN, YOURPAPNAME, or YOURCHAPNAME should be replaced with
the name the remote system knows this machine as. YOURPASSWORD or
YOURPAPPASSWD should be replaced with the password used to authenticate
this machine, or if CHAP authentication is used, there must be an entry
in the /etc/chap_md5_secrets file (see chap_md5(5)). Normally the name
returned by the remote system is used to find the appropriate entry in
the /etc/chap_md5_secrets file. Use the chap-secret entry to override
this name (for use with systems which do not provide a deterministic re-
mote name).
Pdemand:\
:interface=0:\
:idle-timeout=600:\
:phone-number=REMOTEPHONENUMBER:\
:s0=\r:e0=ogin:f0=\r:\
:s1=YOURLOGIN\r:e1=word:\
:s2=YOURPASSWORD\r:\
:tc=Demand:
Palways:\
:immediate:\
:idle-timeout=0:\
:phone-number=REMOTEPHONENUMBER:\
:s0=\r:e0=ogin:f0=\r:\
:s1=YOURLOGIN\r:e1=word:\
:s2=YOURPASSWORD\r:\
:tc=Dialout:
Ppap:\
:immediate:\
:idle-timeout=0:\
:phone-number=REMOTEPHONENUMBER:\
:pap-peerid=YOURPAPNAME:\
:pap-passwd=YOURPAPPASSWD:\
:tc=Dialout:
Pchap:\
:immediate:\
:idle-timeout=0:\
:phone-number=REMOTEPHONENUMBER:\
:chap-allow:\
:chap-name=YOURCHAPNAME:\
:tc=Dialout:
Finally, the following entry, named sync, might be used with a sync line.
Note that the -s option to ppp(8) can take a literal entry, alleviating
the need to have this entry in the /etc/ppp.sys file. LIP should be re-
placed with the local IP address for this session and RIP should be re-
placed with the remote IP address. Of course, other options, such as PAP
or CHAP options, can also be provided.
sync:device=ntwo0:direct:immediate:dialout:local-addr=LIP:remote-addr=RIP:
SEE ALSOstty(1), strtod(3), strtol(3), cgetnum(3), cgetstr(3),
gethostbyname(3), login.conf(5), chap_md5(8), gettyd(8), ifconfig(8),
login(8), ppp(8), ppp_proxy(8), rpasswd(8)BSDI BSD/OS January 16, 1997 10
