Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PPP(8)			FreeBSD	System Manager's Manual			PPP(8)

     ppp -- Point to Point Protocol (a.k.a. user-ppp)

     ppp [-auto	| -background |	-ddial | -direct | -dedicated] [-alias]
	 [system ...]

     This is a user process PPP	software package.  Normally, PPP is imple-
     mented as a part of the kernel (e.g. as managed by	pppd(8)) and it's thus
     somewhat hard to debug and/or modify its behaviour.  However, in this
     implementation PPP	is done	as a user process with the help	of the tunnel
     device driver (tun).

Major Features
     Provides interactive user interface.  Using its command mode, the user
     can easily	enter commands to establish the	connection with	the remote
     end, check	the status of connection and close the connection.  All	func-
     tions can also be optionally password protected for security.

     Supports both manual and automatic	dialing.  Interactive mode has a
     ``term'' command which enables you	to talk	to your	modem directly.	 When
     your modem	is connected to	the remote peer	and it starts to talk PPP, ppp
     detects it	and switches to	packet mode automatically.  Once you have
     determined	the proper sequence for	connecting with	the remote host, you
     can write a chat script to	define the necessary dialing and login proce-
     dure for later convenience.

     Supports on-demand	dialup capability.  By using -auto mode, ppp will act
     as	a daemon and wait for a	packet to be sent over the PPP link.  When
     this happens, the daemon automatically dials and establishes the connec-
     tion.  In almost the same manner -ddial mode (direct-dial mode) also
     automatically dials and establishes the connection.  However, it differs
     in	that it	will dial the remote site any time it detects the link is
     down, even	if there are no	packets	to be sent.  This mode is useful for
     full-time connections where we worry less about line charges and more
     about being connected full	time.  A third -dedicated mode is also avail-
     able.  This mode is targeted at a dedicated link between two machines.
     Ppp will never voluntarily	quit from dedicated mode - you must send it
     the ``quit	all'' command via its diagnostic socket.  A SIGHUP will	force
     an	LCP renegotiation, and a SIGTERM will force it to exit.

     Supports client callback.	Ppp can	use either the standard	LCP callback
     protocol or the Microsoft CallBack	Control	Protocol

     Supports packet aliasing.	Packet aliasing	(a.k.a.	IP masquerading)
     allows computers on a private, unregistered network to access the Inter-
     net.  The PPP host	acts as	a masquerading gateway.	 IP addresses as well
     as	TCP and	UDP port numbers are aliased for outgoing packets and de-
     aliased for returning packets.

     Supports background PPP connections.  In background mode, if ppp success-
     fully establishes the connection, it will become a	daemon.	 Otherwise, it
     will exit with an error.  This allows the setup of	scripts	that wish to
     execute certain commands only if the connection is	successfully estab-

     Supports server-side PPP connections.  In direct mode, acts as server
     which accepts incoming PPP	connections on stdin/stdout.

     Supports PAP and CHAP authentication.  With PAP or	CHAP, it is possible
     to	skip the Unix style login(1) procedure,	and use	the PPP	protocol for
     authentication instead.  If the peer requests Microsoft CHAP authentica-
     tion and ppp is compiled with DES support,	an appropriate MD4/DES
     response will be made.

     Supports Proxy Arp.  When PPP is set up as	server,	you can	also configure
     it	to do proxy arp	for your connection.

     Supports packet filtering.	 User can define four kinds of filters:	the in
     filter for	incoming packets, the out filter for outgoing packets, the
     dial filter to define a dialing trigger packet and	the alive filter for
     keeping a connection alive	with the trigger packet.

     Tunnel driver supports bpf.  The user can use tcpdump(1) to check the
     packet flow over the PPP link.

     Supports PPP over TCP capability.	If a device name is specified as
     host:port,	ppp will open a	TCP connection for transporting	data rather
     than using	a conventional serial device.

     Supports IETF draft Predictor-1 and DEFLATE compression.  ppp supports
     not only VJ-compression but also Predictor-1 and DEFLATE compression.
     Normally, a modem has built-in compression	(e.g. v42.bis) and the system
     may receive higher	data rates from	it as a	result of such compression.
     While this	is generally a good thing in most other	situations, this
     higher speed data imposes a penalty on the	system by increasing the num-
     ber of serial interrupts the system has to	process	in talking to the
     modem and also increases latency.	Unlike VJ-compression, Predictor-1 and
     DEFLATE compression pre-compresses	all network traffic flowing through
     the link, thus reducing overheads to a minimum.

     Supports Microsoft's IPCP extensions.  Name Server	Addresses and NetBIOS
     Name Server Addresses can be negotiated with clients using	the Microsoft
     PPP stack (ie. Win95, WinNT)

     Supports Multi-link PPP  It is possible to	configure ppp to open more
     than one physical connection to the peer, combining the bandwidth of all
     links for better throughput.

     Ppp is installed as user root and group network, with permissions 4554.
     By	default, ppp will not run if the invoking user id is not zero.	This
     may be overridden by using	the ``allow users'' command in
     /etc/ppp/ppp.conf.	 When running as a normal user,	ppp switches to	user
     id	0 in order to alter the	system routing table, set up system lock files
     and read the ppp configuration files.  All	external commands (executed
     via the "shell" or	"!bg" commands)	are executed as	the user id that
     invoked ppp.  Refer to the	`ID0' logging facility if you're interested in
     what exactly is done as user id zero.

     The following command line	switches are understood	by ppp:

	     Ppp opens the tun interface, configures it	then goes into the
	     background.  The link isn't brought up until outgoing data	is
	     detected on the tun interface at which point ppp attempts to
	     bring up the link.	 Packets received (including the first one)
	     while ppp is trying to bring the link up will remain queued for a
	     default of	2 minutes.  See	the ``set choked'' command below.

	     At	least one ``system'' must be given on the command line (see
	     below) and	a ``set	ifaddr'' must be done in the system profile
	     that specifies a peer IP address to use when configuring the
	     interface.	 Something like	``'' is usually appropriate.
	     See the ``pmdemand'' system in /etc/ppp/ppp.conf.sample for an

	     Here, ppp attempts	to establish a connection with the peer	imme-
	     diately.  If it succeeds, ppp goes	into the background and	the
	     parent process returns an exit code of 0.	If it fails, ppp exits
	     with a non-zero result.

	     This is used for receiving	incoming connections.  Ppp ignores the
	     ``set device'' line and uses descriptor 0 as the link.

	     If	callback is configured,	ppp will use the ``set device''	infor-
	     mation when dialing back.

	     This option is designed for machines connected with a dedicated
	     wire.  Ppp	will always keep the device open and will never	use
	     any configured chat scripts.

	     This mode is equivalent to	-auto mode except that ppp will	bring
	     the link back up any time it's dropped for	any reason.

	     This is a no-op, and gives	the same behaviour as if none of the
	     above flags have been specified.  Ppp loads any systems specified
	     on	the command line then provides an interactive prompt.

	     This flag doesn't control ppp's mode.  It does the	equivalent of
	     an	``enable alias yes''.  Additionally, if	the -auto flag is also
	     specified,	an implicit ``enable iface-alias'' is done.  See below
	     for details.

	     Enabling IP aliasing allows ppp to	act as a NAT or	masquerading
	     engine for	all machines on	an internal LAN.  Refer	to libalias(3)
	     for details.

     Additionally, one or more systems may be specified	on the command line.
     A `system'	is a configuration entry in /etc/ppp/ppp.conf.	Ppp will read
     the ``default'' system from /etc/ppp/ppp.conf at startup, followed	by
     each of the systems specifed on the command line.

     Only one of the -auto, -background, -ddial, -direct, -dedicated and
     -interactive switches may be specified.  Ppp's `mode' may subsequently be
     changed with the ``set mode'' command (see	below).

     For now, we'll stick to using interactive mode.

     When you first run	ppp you	may need to deal with some initial configura-
     tion details.

     +o	 Your kernel must include a tunnel device (the GENERIC kernel includes
	 one by	default).  If it doesn't, or if	you require more than one tun
	 interface, you'll need	to rebuild your	kernel with the	following line
	 in your kernel	configuration file:

	       pseudo-device tun N

	 where N is the	maximum	number of PPP connections you wish to support.

     +o	 Check your /dev directory for the tunnel device entries /dev/tunN,
	 where `N' represents the number of the	tun device, starting at	zero.
	 If they don't exist, you can create them by running "sh ./MAKEDEV
	 tunN".	 This will create tun devices 0	through	N.

     +o	 Make sure that	your system has	a group	named ``network'' in the
	 /etc/group file and that that group contains the names	of all users
	 expected to use ppp.  Refer to	the group(5) manual page for details.
	 Each of these uses must also be given access using the	``allow
	 users'' command in /etc/ppp/ppp.conf.

     +o	 Create	a log file.  Ppp uses syslog(3)	to log information.  A common
	 log file name is /var/log/ppp.log.  To	make output go to this file,
	 put the following lines in the	/etc/syslog.conf file:


	 Make sure you use actual TABs here.  If you use spaces, the line will
	 be silently ignored by	syslogd(8).

	 It is possible	to have	more than one PPP log file by creating a link
	 to the	ppp executable:

	       # cd /usr/sbin
	       # ln ppp	ppp0

	 and using


	 in /etc/syslog.conf.  Don't forget to send a HUP signal to syslogd(8)
	 after altering	/etc/syslog.conf.

     +o	 Although not strictly relevant	to ppps	operation, you should config-
	 ure your resolver so that it works correctly.	This can be done by
	 configuring a local DNS (using	named(8)) or by	adding the correct
	 `name-server' lines to	the file /etc/resolv.conf.  Refer to the
	 resolv.conf(5)	manual page for	details.

	 Alternatively,	if the peer supports it, ppp can be configured to ask
	 the peer for the nameserver address(es) and to	update
	 /etc/resolv.conf automatically.  Refer	to the ``enable	dns'' command
	 below for details.

     In	the following examples,	we assume that your machine name is awfulhak.
     when you invoke ppp (see PERMISSIONS above) with no arguments, you	are
     presented with a prompt:

	   ppp ON awfulhak>

     The `ON' part of your prompt should always	be in upper case.  If it is in
     lower case, it means that you must	supply a password using	the ``passwd''
     command.  This only ever happens if you connect to	a running version of
     ppp and have not authenticated yourself using the correct password.

     You can start by specifying the device name, speed	and parity for your
     modem, and	whether	CTS/RTS	signalling should be used (CTS/RTS is used by
     default).	If your	hardware does not provide CTS/RTS lines	(as may	happen
     when you are connected directly to	certain	PPP-capable terminal servers),
     ppp will never send any output through the	port; it waits for a signal
     which never comes.	 Thus, if you have a direct line and can't seem	to
     make a connection,	try turning CTS/RTS off:

	   ppp ON awfulhak> set	line /dev/cuaa0
	   ppp ON awfulhak> set	speed 38400
	   ppp ON awfulhak> set	parity even
	   ppp ON awfulhak> set	ctsrts on
	   ppp ON awfulhak> show modem
	   * Modem related information is shown	here *
	   ppp ON awfulhak>

     The term command can now be used to talk directly with your modem:

	   ppp ON awfulhak> term
	   login: ppp
	   Protocol: ppp

     When the peer starts to talk in PPP, ppp detects this automatically and
     returns to	command	mode.

	   ppp ON awfulhak>		  # No link has	been established
	   Ppp ON awfulhak>		  # We've connected & finished LCP
	   PPp ON awfulhak>		  # We've authenticated
	   PPP ON awfulhak>		  # We've agreed IP numbers

     If	it does	not, it's possible that	the peer is waiting for	your end to
     start negotiating or that ppp can't identify the incoming packets as
     being PPP packets,	perhaps	due to your parity settings.  To force ppp to
     start sending PPP configuration packets to	the peer, use the ``~p'' com-
     mand to enter packet mode.

     You are now connected!  Note that `PPP' in	the prompt has changed to cap-
     ital letters to indicate that you have a peer connection.	If only	some
     of	the three Ps go	uppercase, wait	'till either everything	is uppercase
     or	lowercase.  If they revert to lowercase, it means that ppp couldn't
     successfully negotiate with the peer.  This is probably because your PAP
     or	CHAP authentication name or key	is incorrect.  A good first step for
     troubleshooting at	this point would be to ``set log local phase''.	 Refer
     to	the ``set log''	command	description below for further details.

     When the link is established, the show command can	be used	to see how
     things are	going:

	   PPP ON awfulhak> show modem
	   * Modem related information is shown	here *
	   PPP ON awfulhak> show ccp
	   * CCP (compression) related information is shown here *
	   PPP ON awfulhak> show lcp
	   * LCP (line control)	related	information is shown here *
	   PPP ON awfulhak> show ipcp
	   * IPCP (IP) related information is shown here *
	   PPP ON awfulhak> show link
	   * Link (high	level) related information is shown here *
	   PPP ON awfulhak> show bundle
	   * Logical (high level) connection related information is shown here *

     At	this point, your machine has a host route to the peer.	This means
     that you can only make a connection with the host on the other side of
     the link.	If you want to add a default route entry (telling your machine
     to	send all packets without another routing entry to the other side of
     the PPP link), enter the following	command:

	   PPP ON awfulhak> add	default	HISADDR

     The string	`HISADDR' represents the IP address of the connected peer.  If
     the ``add'' command fails due to an existing route, you can overwrite the
     existing route using

	   PPP ON awfulhak> add! default HISADDR

     You can now use your network applications (ping, telnet, ftp etc.)	 in
     other windows on your machine.  Refer to the PPP COMMAND LIST section for
     details on	all available commands.

     To	use automatic dialing, you must	prepare	some Dial and Login chat
     scripts.  See the example definitions in /etc/ppp/ppp.conf.sample (the
     format of /etc/ppp/ppp.conf is pretty simple).  Each line contains	one
     comment, inclusion, label or command:

     +o	 A line	starting with a	(``#'')	character is treated as	a comment
	 line.	Leading	whitespace are ignored when identifying	comment	lines.

     +o	 An inclusion is a line	beginning with the word	`!include'.  It	must
	 have one argument - the file to include.  You may wish	to ``!include
	 ~/.ppp.conf'' for compatibility with older versions of	ppp.

     +o	 A label name starts in	the first column and is	followed by a colon

     +o	 A command line	must contain a space or	tab in the first column.

     The /etc/ppp/ppp.conf file	should consist of at least a ``default'' sec-
     tion.  This section is always executed.  It should	also contain one or
     more sections, named according to their purpose, for example, ``MyISP''
     would represent your ISP, and ``ppp-in'' would represent an incoming ppp
     configuration.  You can now specify the destination label name when you
     invoke ppp.  Commands associated with the ``default'' label are executed,
     followed by those associated with the destination label provided.	When
     ppp is started with no arguments, the ``default'' section is still	exe-
     cuted.  The load command can be used to manually load a section from the
     /etc/ppp/ppp.conf file:

	   PPP ON awfulhak> load MyISP

     Once the connection is made, the `ppp' portion of the prompt will change
     to	`PPP':

	   # ppp MyISP
	   ppp ON awfulhak> dial
	   Ppp ON awfulhak>
	   PPp ON awfulhak>
	   PPP ON awfulhak>

     The Ppp prompt indicates that ppp has entered the authentication phase.
     The PPp prompt indicates that ppp has entered the network phase.  The PPP
     prompt indicates that ppp has successfully	negotiated a network layer
     protocol and is in	a usable state.

     If	the /etc/ppp/ppp.linkup	file is	available, its contents	are executed
     when the PPP connection is	established.  See the provided ``pmdemand''
     example in	/etc/ppp/ppp.conf.sample which runs a script in	the background
     after the connection is established (refer	to the ``shell'' and ``bg''
     commands below for	a description of possible substition strings).	Simi-
     larly, when a connection is closed, the contents of the
     /etc/ppp/ppp.linkdown file	are executed.  Both of these files have	the
     same format as /etc/ppp/ppp.conf.

     In	previous versions of ppp, it was necessary to re-add routes such as
     the default route in the ppp.linkup file.	Ppp now	supports `sticky
     routes', where all	routes that contain the	HISADDR	or MYADDR literals
     will automatically	be updated when	the values of HISADDR and/or MYADDR

     If	you want to establish a	connection using ppp non-interactively (such
     as	from a crontab(5) entry	or an at(1) job) you should use	the
     -background option.  When -background is specified, ppp attempts to
     establish the connection immediately.  If multiple	phone numbers are
     specified,	each phone number will be tried	once.  If the attempt fails,
     ppp exits immediately with	a non-zero exit	code.  If it succeeds, then
     ppp becomes a daemon, and returns an exit status of zero to its caller.
     The daemon	exits automatically if the connection is dropped by the	remote
     system, or	it receives a TERM signal.

     Demand dialing is enabled with the	-auto or -ddial	options.  You must
     also specify the destination label	in /etc/ppp/ppp.conf to	use.  It must
     contain the ``set ifaddr''	command	to define the remote peers IP address.
     (refer to /etc/ppp/ppp.conf.sample)

	   # ppp -auto pmdemand

     When -auto	or -ddial is specified,	ppp runs as a daemon but you can still
     configure or examine its configuration by using the ``set server''	com-
     mand in /etc/ppp/ppp.conf,	(for example, ``set server +3000 mypasswd'')
     and connecting to the diagnostic port as follows:

	   # pppctl 3000   (assuming tun0 - see	the ``set server'' description)
	   PPP ON awfulhak> show who
	   tcp (	*

     The ``show	who'' command lists users that are currently connected to ppp
     itself.  If the diagnostic	socket is closed or changed to a different
     socket, all connections are immediately dropped.

     In	-auto mode, when an outgoing packet is detected, ppp will perform the
     dialing action (chat script) and try to connect with the peer.  In	-ddial
     mode, the dialing action is performed any time the	line is	found to be
     down.  If the connect fails, the default behaviour	is to wait 30 seconds
     and then attempt to connect when another outgoing packet is detected.
     This behaviour can	be changed with

	   set redial seconds|random[.nseconds|random] [dial_attempts]

     `Seconds' is the number of	seconds	to wait	before attempting to connect
     again. If the argument is `random', the delay period is a random value
     between 0 and 30 seconds.	`Nseconds' is the number of seconds to wait
     before attempting to dial the next	number in a list of numbers (see the
     ``set phone'' command).  The default is 3 seconds.	 Again,	if the argu-
     ment is `random', the delay period	is a random value between 0 and	30
     seconds.  `dial_attempts' is the number of	times to try to	connect	for
     each outgoing packet that is received. The	previous value is unchanged if
     this parameter is omitted.	 If a value of zero is specified for
     `dial_attempts', ppp will keep trying until a connection is made.

	   set redial 10.3 4

     will attempt to connect 4 times for each outgoing packet that is detected
     with a 3 second delay between each	number and a 10	second delay after all
     numbers have been tried.  If multiple phone numbers are specified,	the
     total number of attempts is still 4 (it does not attempt each number 4
     times).  Modifying	the dial delay is very useful when running ppp in
     demand dial mode on both ends of the link.	If each	end has	the same time-
     out, both ends wind up calling each other at the same time	if the link
     drops and both ends have packets queued.  At some locations, the serial
     link may not be reliable, and carrier may be lost at inappropriate	times.
     It	is possible to have ppp	redial should carrier be unexpectedly lost
     during a session.

	   set reconnect timeout ntries

     This command tells	ppp to re-establish the	connection ntries times	on
     loss of carrier with a pause of timeout seconds before each try.  For

	   set reconnect 3 5

     tells ppp that on an unexpected loss of carrier, it should	wait 3 seconds
     before attempting to reconnect.  This may happen up to 5 times before ppp
     gives up.	The default value of ntries is zero (no	reconnect).  Care
     should be taken with this option.	If the local timeout is	slightly
     longer than the remote timeout, the reconnect feature will	always be
     triggered (up to the given	number of times) after the remote side times
     out and hangs up.	NOTE:  In this context,	losing too many	LQRs consti-
     tutes a loss of carrier and will trigger a	reconnect.  If the -background
     flag is specified,	all phone numbers are dialed at	most once until	a con-
     nection is	made.  The next	number redial period specified with the	``set
     redial'' command is honoured, as is the reconnect tries value.  If	your
     redial value is less than the number of phone numbers specified, not all
     the specified numbers will	be tried.  To terminate	the program, type

	   PPP ON awfulhak> close
	   ppp ON awfulhak> quit all

     A simple ``quit'' command will terminate the pppctl(8) or telnet(1) con-
     nection but not the ppp program itself.  You must use ``quit all''	to
     terminate ppp as well.

     To	handle an incoming PPP connection request, follow these	steps:

     1.	  Make sure the	modem and (optionally) /etc/rc.serial is configured
	  +o   Use Hardware Handshake (CTS/RTS) for flow	control.
	  +o   Modem should be set to NO	echo back (ATE0) and NO	results	string

     2.	  Edit /etc/ttys to enable a getty(8) on the port where	the modem is
	  attached.  For example:

		ttyd1 /usr/libexec/getty std.38400 dialup on secure

	  Don't	forget to send a HUP signal to the init(8) process to start
	  the getty(8):

		# kill -HUP 1

     3.	  Create a /usr/local/bin/ppplogin file	with the following contents:

		#! /bin/sh
		exec /usr/sbin/ppp -direct incoming

	  Direct mode (-direct)	lets ppp work with stdin and stdout.  You can
	  also use pppctl(8) to	connect	to a configured	diagnostic port, in
	  the same manner as with client-side ppp.

	  Here,	the incoming section must be set up in /etc/ppp/ppp.conf.

	  Make sure that the incoming section contains the ``allow users''
	  command as appropriate.

     4.	  Prepare an account for the incoming user.

	  ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin

	  Refer	to the manual entries for adduser(8) and vipw(8) for details.

     5.	  Support for IPCP Domain Name Server and NetBIOS Name Server negotia-
	  tion can be enabled using the	``accept dns'' and ``set nbns''	com-
	  mands.  Refer	to their descriptions below.

     This method differs in that we use	ppp to authenticate the	connection
     rather than login(1):

     1.	  Configure your default section in /etc/gettytab with automatic ppp
	  recognition by specifying the	``pp'' capability:


     2.	  Configure your serial	device(s), enable a getty(8) and create
	  /usr/local/bin/ppplogin as in	the first three	steps for method 1

     3.	  Add either ``enable chap'' or	``enable pap'' (or both) to
	  /etc/ppp/ppp.conf under the `incoming' label (or whatever label
	  ppplogin uses).

     4.	  Create an entry in /etc/ppp/ppp.secret for each incoming user:


     Now, as soon as getty(8) detects a	ppp connection (by recognising the
     HDLC frame	headers), it runs ``/usr/local/bin/ppplogin''.

     It	is VITAL that either PAP or CHAP are enabled as	above.	If they	are
     not, you are allowing anybody to establish	ppp session with your machine
     without a password, opening yourself up to	all sorts of potential

     Normally, the receiver of a connection requires that the peer authenti-
     cates itself.  This may be	done using login(1), but alternatively,	you
     can use PAP or CHAP.  CHAP	is the more secure of the two, but some
     clients may not support it.  Once you decide which	you wish to use, add
     the command `enable chap' or `enable pap' to the relevant section of

     You must then configure the /etc/ppp/ppp.secret file.  This file contains
     one line per possible client, each	line containing	up to four fields:

	   name	key [hisaddr [label]]

     The name and key specify the client as expected.  If key is ``*'' and PAP
     is	being used, ppp	will look up the password database (passwd(5)) when
     authenticating.  If the client does not offer a suitable response based
     on	any name / key combination in ppp.secret, authentication fails.

     If	authentication is successful, hisaddr (if specified) is	used when
     negotiating IP numbers.  See the ``set ifaddr'' command for details.

     If	authentication is successful and label is specified, the current sys-
     tem label is changed to match the given label.  This will change the sub-
     sequent parsing of	the ppp.linkup and ppp.linkdown	files.

PPP OVER TCP (a.k.a Tunnelling)
     Instead of	running	ppp over a serial link,	it is possible to use a	TCP
     connection	instead	by specifying a	host and port as the device:

	   set device ui-gate:6669

     Instead of	opening	a serial device, ppp will open a TCP connection	to the
     given machine on the given	socket.	 It should be noted however that ppp
     doesn't use the telnet protocol and will be unable	to negotiate with a
     telnet server.  You should	set up a port for receiving this PPP connec-
     tion on the receiving machine (ui-gate).  This is done by first updating
     /etc/services to name the service:

	   ppp-in 6669/tcp # Incoming PPP connections over TCP

     and updating /etc/inetd.conf to tell inetd(8) how to deal with incoming
     connections on that port:

	   ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in

     Don't forget to send a HUP	signal to inetd(8) after you've	updated
     /etc/inetd.conf.  Here, we	use a label named ``ppp-in''.  The entry in
     /etc/ppp/ppp.conf on ui-gate (the receiver) should	contain	the following:

	    set	timeout	0
	    set	ifaddr

     You may also want to enable PAP or	CHAP for security.  To enable PAP, add
     the following line:

	    enable PAP

     You'll also need to create	the following entry in /etc/ppp/ppp.secret:

	   MyAuthName MyAuthPasswd

     If	MyAuthPasswd is	a (``*''), the password	is looked up in	the passwd(5)

     The entry in /etc/ppp/ppp.conf on awfulhak	(the initiator)	should contain
     the following:

	    set	escape 0xff
	    set	device ui-gate:ppp-in
	    set	dial
	    set	timeout	30
	    set	log Phase Chat Connect hdlc LCP	IPCP CCP tun
	    set	ifaddr

     Again, if you're enabling PAP, you'll also	need:

	    set	authname MyAuthName
	    set	authkey	MyAuthKey

     We're assigning the address of to	ui-gate, and the address to awfulhak.  To open the	connection, just type

	   awfulhak # ppp -background ui-gate

     The result	will be	an additional "route" on awfulhak to the
     network via the TCP connection, and an additional "route" on ui-gate to
     the network.  The networks are	effectively bridged - the
     underlying	TCP connection may be across a public network (such as the
     Internet),	and the	PPP traffic is conceptually encapsulated (although not
     packet by packet) inside the TCP stream between the two gateways.	The
     major disadvantage	of this	mechanism is that there	are two	"guaranteed
     delivery" mechanisms in place - the underlying TCP	stream and whatever
     protocol is used over the PPP link	- probably TCP again.  If packets are
     lost, both	levels will get	in each	others way trying to negotiate sending
     of	the missing packet.

     The -alias	command	line option enables packet aliasing.  This allows the
     ppp host to act as	a masquerading gateway for other computers over	a
     local area	network.  Outgoing IP packets are aliased so that they appear
     to	come from the ppp host,	and incoming packets are de-aliased so that
     they are routed to	the correct machine on the local area network.	Packet
     aliasing allows computers on private, unregistered	subnets	to have	Inter-
     net access, although they are invisible from the outside world.  In gen-
     eral, correct ppp operation should	first be verified with packet aliasing
     disabled.	Then, the -alias option	should be switched on, and network
     applications (web browser,	telnet(1), ftp(1), ping(8), traceroute(8))
     should be checked on the ppp host.	 Finally, the same or similar applica-
     tions should be checked on	other computers	in the LAN.  If	network	appli-
     cations work correctly on the ppp host, but not on	other machines in the
     LAN, then the masquerading	software is working properly, but the host is
     either not	forwarding or possibly receiving IP packets.  Check that IP
     forwarding	is enabled in /etc/rc.conf and that other machines have	desig-
     nated the ppp host	as the gateway for the LAN.

     This implementation supports packet filtering. There are four kinds of
     filters; the in filter, the out filter, the dial filter and the alive
     filter.  Here are the basics:

     +o	 A filter definition has the following syntax:

	 set filter name rule-no action	[src_addr[/width]] [dst_addr[/width]]
	 [ proto [src [cmp port]] [dst [cmp port]] [estab] [syn] [finrst] ]

	 1.   Name should be one of `in', `out', `dial'	or `alive'.

	 2.   Rule-no is a numeric value between `0' and `19' specifying the
	      rule number.  Rules are specified	in numeric order according to
	      rule-no, but only	if rule	`0' is defined.

	 3.   Action is	either `permit'	or `deny'.  If a given packet matches
	      the rule,	the associated action is taken immediately.

	 4.   [src_addr[/width]] and [dst_addr[/width]]	are the	source and
	      destination IP number specifications.  If	[/width] is specified,
	      it gives the number of relevant netmask bits, allowing the spec-
	      ification	of an address range.

	 5.   Proto must be one	of `icmp', `udp' or `tcp'.

	 6.   Cmp is one of `lt', `eq' or `gt',	meaning	less-than, equal and
	      greater-than respectively.  Port can be specified	as a numeric
	      port or by service name from /etc/services.

	 7.   The `estab', `syn', and `finrst' flags are only allowed when
	      proto is set to `tcp', and represent the TH_ACK, TH_SYN and
	      TH_FIN or	TH_RST TCP flags respectively.

     +o	 Each filter can hold up to 20 rules, starting from rule 0.  The
	 entire	rule set is not	effective until	rule 0 is defined, ie. the
	 default is to allow everything	through.

     +o	 If no rule is matched to a packet, that packet	will be	discarded

     +o	 Use ``set filter name -1'' to flush all rules.

     See /etc/ppp/ppp.conf.example.

     To	check/set the idle timer, use the ``show bundle'' and ``set timeout''

	   ppp ON awfulhak> set	timeout	600

     The timeout period	is measured in seconds,	the  default value for which
     is	180 seconds (or	3 min).	 To disable the	idle timer function, use the

	   ppp ON awfulhak> set	timeout	0

     In	-ddial and -direct modes, the idle timeout is ignored.	In -auto mode,
     when the idle timeout causes the PPP session to be	closed,	the ppp	pro-
     gram itself remains running.  Another trigger packet will cause it	to
     attempt to	re-establish the link.

     Ppp supports both Predictor type 1	and deflate compression.  By default,
     ppp will attempt to use (or be willing to accept) both compression	proto-
     cols when the peer	agrees (or requests them).  The	deflate	protocol is
     preferred by ppp.	Refer to the ``disable'' and ``deny'' commands if you
     wish to disable this functionality.

     It	is possible to use a different compression algorithm in	each direction
     by	using only one of ``disable deflate'' and ``deny deflate'' (assuming
     that the peer supports both algorithms).

     By	default, when negotiating DEFLATE, ppp will use	a window size of 15.
     Refer to the ``set	deflate'' command if you wish to change	this behav-

     A special algorithm called	DEFLATE24 is also available, and is disabled
     and denied	by default.  This is exactly the same as DEFLATE except	that
     it	uses CCP ID 24 to negotiate.  This allows ppp to successfully negoti-
     ate DEFLATE with pppd version 2.3.*.

     ppp uses IPCP to negotiate	IP addresses. Each side	of the connection
     specifies the IP address that it's	willing	to use,	and if the requested
     IP	address	is acceptable then ppp returns ACK to the requester.  Other-
     wise, ppp returns NAK to suggest that the peer use	a different IP
     address. When both	sides of the connection	agree to accept	the received
     request (and send ACK), IPCP is set to the	open state and a network level
     connection	is established.	 To control this IPCP behaviour, this imple-
     mentation has the ``set ifaddr'' command for defining the local and
     remote IP address:

	   set ifaddr [src_addr	[dst_addr [netmask [trigger_addr]]]]

     where, `src_addr' is the IP address that the local	side is	willing	to
     use, `dst_addr' is	the IP address which the remote	side should use	and
     `netmask' is the netmask that should be used.  `Src_addr' defaults	to the
     current hostname(1), `dst_addr' defaults to, and `netmask'
     defaults to whatever mask is appropriate for `src_addr'.  It is only pos-
     sible to make `netmask' smaller than the default.	The usual value	is, as most kernels ignore the netmask of a POINTOPOINT

     Some incorrect PPP	implementations	require	that the peer negotiates a
     specific IP address instead of `src_addr'.	 If this is the	case,
     `trigger_addr' may	be used	to specify this	IP number.  This will not
     affect the	routing	table unless the other side agrees with	this proposed

	   set ifaddr

     The above specification means:

     +o	 I will	first suggest that my IP address should	be, but	I will
	 only accept an	address	of
     +o	 I strongly insist that	the peer uses as his own address
	 and won't permit the use of any IP address but	When
	 the peer requests another IP address, I will always suggest that it
     +o	 The routing table entry will have a netmask of	0xffffffff.

     This is all fine when each	side has a pre-determined IP address, however
     it	is often the case that one side	is acting as a server which controls
     all IP addresses and the other side should	obey the direction from	it.
     In	order to allow more flexible behaviour,	`ifaddr' variable allows the
     user to specify IP	address	more loosely:

	   set ifaddr

     A number followed by a slash (/) represent	the number of bits significant
     in	the IP address.	 The above example signifies that:

     +o	 I'd like to use	as my address if it is possible, but
	 I'll also accept any IP address between and
     +o	 I'd like to make him use	as his own address, but	I'll
	 also permit him to use	any IP address between and
     +o	 As you	may have already noticed,	is equivalent to say-
     +o	 As an exception, 0 is equivalent to,	meaning	that I have no
	 preferred IP address and will obey the	remote peers selection.	 When
	 using zero, no	routing	table entries will be made until a connection
	 is established.
     +o means that I'll accept/permit any IP address but I'll
	 try to	insist that be used first.

     The following steps should	be taken when connecting to your ISP:

     1.	  Describe your	providers phone	number(s) in the dial script using the
	  ``set	phone''	command.  This command allows you to set multiple
	  phone	numbers	for dialing and	redialing separated by either a	pipe
	  (|) or a colon (:)

		set phone "111[|222]...[:333[|444]...]...

	  Numbers after	the first in a pipe-separated list are only used if
	  the previous number was used in a failed dial	or login script.  Num-
	  bers separated by a colon are	used sequentially, irrespective	of
	  what happened	as a result of using the previous number.  For exam-

		set phone "1234567|2345678:3456789|4567890"

	  Here,	the 1234567 number is attempted.  If the dial or login script
	  fails, the 2345678 number is used next time, but *only* if the dial
	  or login script fails.  On the dial after this, the 3456789 number
	  is used.  The	4567890	number is only used if the dial	or login
	  script using the 3456789 fails.  If the login	script of the 2345678
	  number fails,	the next number	is still the 3456789 number.  As many
	  pipes	and colons can be used as are necessary	(although a given site
	  would	usually	prefer to use either the pipe or the colon, but	not
	  both).  The next number redial timeout is used between all numbers.
	  When the end of the list is reached, the normal redial period	is
	  used before starting at the beginning	again.	The selected phone
	  number is substituted	for the	\\T string in the ``set	dial'' command
	  (see below).

     2.	  Set up your redial requirements using	``set redial''.	 For example,
	  if you have a	bad telephone line or your provider is usually engaged
	  (not so common these days), you may want to specify the following:

		set redial 10 4

	  This says that up to 4 phone calls should be attempted with a	pause
	  of 10	seconds	before dialing the first number	again.

     3.	  Describe your	login procedure	using the ``set	dial'' and ``set
	  login'' commands.  The ``set dial'' command is used to talk to your
	  modem	and establish a	link with your ISP, for	example:


	  This modem "chat" string means:

	  +o   Abort if the string "BUSY" or "NO	CARRIER" are received.

	  +o   Set the timeout to 4 seconds.

	  +o   Expect nothing.

	  +o   Send ATZ.

	  +o   Expect OK.  If that's not	received within	the 4 second timeout,
	      send ATZ and expect OK.

	  +o   Send ATDTxxxxxxx where xxxxxxx is	the next number	in the phone
	      list from	above.

	  +o   Set the timeout to 60.

	  +o   Wait for the CONNECT string.

	  Once the connection is established, the login	script is executed.
	  This script is written in the	same style as the dial script, but
	  care should be taken to avoid	having your password logged:

		set authkey MySecret
		set login "TIMEOUT 15 login:-\\r-login:	awfulhak \
		  word:	\\P ocol: PPP HELLO"

	  This login "chat" string means:

	  +o   Set the timeout to 15 seconds.

	  +o   Expect "login:".	If it's	not received, send a carriage return
	      and expect "login:" again.

	  +o   Send "awfulhak"

	  +o   Expect "word:" (the tail end of a	"Password:" prompt).

	  +o   Send whatever our	current	authkey	value is set to.

	  +o   Expect "ocol:" (the tail end of a	"Protocol:" prompt).

	  +o   Send "PPP".

	  +o   Expect "HELLO".

	  The ``set authkey'' command is logged	specially (when	using command
	  logging) so that the actual password is not compromised (it is
	  logged as `********'), and the '\P' is logged	when chat logging is
	  active rather	than the actual	password.

	  Login	scripts	vary greatly between ISPs.  If you're setting one up
	  for the first	time, ENABLE CHAT LOGGING so that you can see if your
	  script is behaving as	you expect.

     4.	  Use ``set line'' and ``set speed'' to	specify	your serial line and
	  speed, for example:

		set line /dev/cuaa0
		set speed 115200

	  Cuaa0	is the first serial port on FreeBSD.  If you're	running	ppp on
	  OpenBSD, cua00 is the	first.	A speed	of 115200 should be specified
	  if you have a	modem capable of bit rates of 28800 or more.  In gen-
	  eral,	the serial speed should	be about four times the	modem speed.

     5.	  Use the ``set	ifaddr'' command to define the IP address.

	  +o   If you know what IP address your provider	uses, then use it as
	      the remote address (dst_addr), otherwise choose something	like (see below).

	  +o   If your provider has assigned a particular IP address to you,
	      then use it as your address (src_addr).

	  +o   If your provider assigns your address dynamically, choose	a
	      suitably unobtrusive and unspecific IP number as your address. would be appropriate.	The bit	after the / specifies
	      how many bits of the address you consider	to be important, so if
	      you wanted to insist on something	in the class C network, you could specify

	  +o   If you find that your ISP	accepts	the first IP number that you
	      suggest, specify third and forth arguments of ``''.  This
	      will force your ISP to assign a number.  (The third argument
	      will be ignored as it is less restrictive	than the default mask
	      for your `src_addr'.

	  An example for a connection where you	don't know your	IP number or
	  your ISPs IP number would be:

		set ifaddr

     6.	  In most cases, your ISP will also be your default router.  If	this
	  is the case, add the line

		add default HISADDR

	  to /etc/ppp/ppp.conf.

	  This tells ppp to add	a default route	to whatever the	peer address
	  is ( in this example).  This route is	`sticky', meaning that
	  should the value of HISADDR change, the route	will be	updated

	  Previous versions of ppp required a similar entry in the
	  /etc/ppp/ppp.linkup file.  Since the advent of `sticky routes', this
	  is no	longer required.

     7.	  If your provider requests that you use PAP/CHAP authentication meth-
	  ods, add the next lines to your /etc/ppp/ppp.conf file:

		set authname MyName
		set authkey MyPassword

	  Both are accepted by default,	so ppp will provide whatever your ISP

	  It should be noted that a login script is rarely (if ever) required
	  when PAP or CHAP are in use.

     8.	  Ask your ISP to authenticate your nameserver address(es) with	the

		enable dns
	  Do NOT do this if you	are running an local DNS, as ppp will simply
	  circumvent its use by	entering some nameserver lines in

     Please refer to /etc/ppp/ppp.conf.sample and /etc/ppp/ppp.linkup.sample
     for some real examples.  The pmdemand label should	be appropriate for
     most ISPs.

     Ppp is able to generate the following log info either via syslog(3) or
     directly to the screen:

	   Async      Dump async level packet in hex
	   CBCP	      Generate CBCP (CallBack Control Protocol)	logs
	   CCP	      Generate a CCP packet trace
	   Chat	      Generate Chat script trace log
	   Command    Log commands executed
	   Connect    Log Chat lines containing	CONNECT
	   Debug      Log debug	information
	   HDLC	      Dump HDLC	packet in hex
	   ID0	      Log all function calls specifically made as user id 0.
	   IPCP	      Generate an IPCP packet trace
	   LCP	      Generate an LCP packet trace
	   LQM	      Generate LQR report
	   Phase      Phase transition log output
	   TCP/IP     Dump all TCP/IP packets
	   Timer      Log timer	manipulation
	   TUN	      Include the tun device on	each log line
	   Warning    Output to	the terminal device. If	there is currently no
		      terminal,	output is sent to the log file using LOG_WARN-
	   Error      Output to	both the terminal device and the log file
		      using LOG_ERROR.
	   Alert      Output to	the log	file using LOG_ALERT

     The ``set log'' command allows you	to set the logging output level.  Mul-
     tiple levels can be specified on a	single command line.  The default is
     equivalent	to ``set log Phase''.

     It	is also	possible to log	directly to the	screen.	 The syntax is the
     same except that the word ``local'' should	immediately follow ``set
     log''.  The default is ``set log local'' (ie. only	the un-maskable	warn-
     ing, error	and alert output).

     If	The first argument to ``set log	[local]'' begins with a	'+' or a '-'
     character,	the current log	levels are not cleared,	for example:

	   PPP ON awfulhak> set	log phase
	   PPP ON awfulhak> show log
	   Log:	  Phase	Warning	Error Alert
	   Local: Warning Error	Alert
	   PPP ON awfulhak> set	log +tcp/ip -warning
	   PPP ON awfulhak> set	log local +command
	   PPP ON awfulhak> show log
	   Log:	  Phase	TCP/IP Warning Error Alert
	   Local: Command Warning Error	Alert

     Log messages of level Warning, Error and Alert are	not controllable using
     ``set log [local]''.

     The Warning level is special in that it will not be logged	if it can be
     displayed locally.

     Ppp deals with the	following signals:

	 Receipt of this signal	causes the termination of the current connec-
	 tion (if any).	 This will cause ppp to	exit unless it is in -auto or
	 -ddial	mode.

	 These signals tell ppp	to exit.

	 This signal, tells ppp	to close any existing server socket, dropping
	 all existing diagnostic connections.

     If	you wish to use	more than one physical link to connect to a PPP	peer,
     that peer must also understand the	MULTI-LINK PPP protocol.  Refer	to RFC
     1990 for specification details.

     The peer is identified using a combination	of his ``endpoint
     discriminator'' and his ``authentication id''.  Either or both of these
     may be specified.	It is recommended that at least	one is specified, oth-
     erwise there is no	way of ensuring	that all links are actually connected
     to	the same peer program, and some	confusing lock-ups may result.
     Locally, these identification variables are specified using the ``set
     enddisc'' and ``set authname'' commands.  The `authname' (and `authkey')
     must be agreed in advance with the	peer.

     Multi-link	capabilities are enabled using the ``set mrru''	command	(set
     maximum reconstructed receive unit).  Once	multi-link is enabled, ppp
     will attempt to negotiate a multi-link connection with the	peer.

     By	default, only one `link' is available (called `deflink').  To create
     more links, the ``clone'' command is used.	 This command will clone
     existing links, where all characteristics are the same except:

     1.	  The new link has its own name	as specified on	the ``clone'' command

     2.	  The new link is an `interactive' link.  It's mode may	subsequently
	  be changed using the ``set mode'' command.

     3.	  The new link is in a `closed'	state.

     A summary of all available	links can be seen using	the ``show links''

     Once a new	link has been created, command usage varies.  All link spe-
     cific commands must be prefixed with the ``link name'' command, specify-
     ing on which link the command is to be applied.  When only	a single link
     is	available, ppp is smart	enough not to require the ``link name''	pre-

     Some commands can still be	used without specifying	a link - resulting in
     an	operation at the `bundle' level.  For example, once two	or more	links
     are available, the	command	``show ccp'' will show CCP configuration and
     statistics	at the multi-link level, and ``link deflink show ccp'' will
     show the same information at the ``deflink'' link level.

     Armed with	this information, the following	configuration might be used:

	    set	timeout	0
	    set	log phase chat
	    set	device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
	    set	phone "123456789"
	    set	login
	    set	ifaddr
	    set	authname ppp
	    set	authkey	ppppassword

	    set	mrru 1500
	    clone 1,2,3
	    link deflink remove

     Note how all cloning is done at the end of	the configuration.  Usually,
     the link will be configured first,	then cloned.  If you wish all links to
     be	up all the time, you can add the following line	to the end of your

	     link 1,2,3	set mode ddial

     If	you want the links to dial on demand, this command could be used:

	     link * set	mode auto

     Links may be tied to specific names by removing the ``set device''	line
     above, and	specifying the following after the ``clone'' command:

	    link 1 set device /dev/cuaa0
	    link 2 set device /dev/cuaa1
	    link 3 set device /dev/cuaa2

     Use the ``help'' command to see which commands require context (using the
     ``link'' command),	which have optional context and	which should not have
     any context.

     When ppp has negotiated MULTI-LINK	mode with the peer, it creates a local
     domain socket in the /var/run directory.  This socket is used to pass
     link information (including the actual link file descriptor) between dif-
     ferent ppp	invocations.  This facilitates ppps ability to be run from a
     getty(8) or directly from /etc/gettydefs (using the `pp=' capability),
     without needing to	have initial control of	the serial line.  Once ppp
     negotiates	multi-link mode, it will pass its open link to any already
     running process.  If there	is no already running process, ppp will	act as
     the master, creating the socket and listening for new connections.

     This section lists	the available commands and their effect.  They are
     usable either from	an interactive ppp session, from a configuration file
     or	from a pppctl(8) or telnet(1) session.

     accept|deny|enable|disable	option....
	 These directives tell ppp how to negotiate the	initial	connection
	 with the peer.	 Each ``option'' has a default of either accept	or
	 deny and enable or disable.  ``Accept'' means that the	option will be
	 ACK'd if the peer asks	for it.	 ``Deny'' means	that the option	will
	 be NAK'd if the peer asks for it.  ``Enable'' means that the option
	 will be requested by us.  ``Disable'' means that the option will not
	 be requested by us.

	 ``Option'' may	be one of the following:

	     Default: Enabled and Accepted.  ACFComp stands for	Address	and
	     Control Field Compression.	 Non LCP packets usually have very
	     similar address and control fields	- making them easily compress-

	     Default: Disabled and Accepted.  CHAP stands for Challenge	Hand-
	     shake Authentication Protocol.  Only one of CHAP and PAP (below)
	     may be negotiated.	 With CHAP, the	authenticator sends a "chal-
	     lenge" message to its peer.  The peer uses	a one-way hash func-
	     tion to encrypt the challenge and sends the result	back.  The
	     authenticator does	the same, and compares the results.  The
	     advantage of this mechanism is that no passwords are sent across
	     the connection.  A	challenge is made when the connection is first
	     made.  Subsequent challenges may occur.  If you want to have your
	     peer authenticate itself, you must	``enable chap''.  in
	     /etc/ppp/ppp.conf,	and have an entry in /etc/ppp/ppp.secret for
	     the peer.

	     When using	CHAP as	the client, you	need only specify ``AuthName''
	     and ``AuthKey'' in	/etc/ppp/ppp.conf.  CHAP is accepted by
	     default.  Some PPP	implementations	use "MS-CHAP" rather than MD5
	     when encrypting the challenge.  MS-CHAP is	a combination of MD4
	     and DES.  If ppp was built	on a machine with DES libraries	avail-
	     able, it will respond to MS-CHAP authentication requests, but
	     will never	request	them.

	     Default: Enabled and Accepted.  This option decides if deflate
	     compression will be used by the Compression Control Protocol
	     (CCP).  This is the same algorithm	as used	by the gzip(1) pro-
	     gram.  Note: There	is a problem negotiating deflate capabilities
	     with pppd(8) - a PPP implementation available under many operat-
	     ing systems.  Pppd	(version 2.3.1)	incorrectly attempts to	nego-
	     tiate deflate compression using type 24 as	the CCP	configuration
	     type rather than type 26 as specified in rfc1979.	Type 24	is
	     actually specified	as ``PPP Magna-link Variable Resource
	     Compression'' in rfc1975!	Ppp is capable of negotiating with
	     pppd, but only if ``deflate24'' is	enabled	and accepted.

	     Default: Disabled and Denied.  This is a variance of the deflate
	     option, allowing negotiation with the pppd(8) program.  Refer to
	     the deflate section above for details.  It	is disabled by default
	     as	it violates rfc1975.

	     Default: Disabled and Denied.  This option	allows DNS negotia-

	     If	``enabled,'' ppp will request that the peer confirms the
	     entries in	/etc/resolv.conf.  If the peer NAKs our	request	(sug-
	     gesting new IP numbers), /etc/resolv.conf is updated and another
	     request is	sent to	confirm	the new	entries.

	     If	``accepted,'' ppp will answer any DNS queries requested	by the
	     peer rather than rejecting	them.  The answer is taken from
	     /etc/resolv.conf unless the ``set dns'' command is	used as	an

	     Default: Disabled and Accepted.  This option decides if Link
	     Quality Requests will be sent or accepted.	 LQR is	a protocol
	     that allows ppp to	determine that the link	is down	without	rely-
	     ing on the	modems carrier detect.	When LQR is enabled, ppp sends
	     the QUALPROTO option (see ``set lqrperiod'' below)	as part	of the
	     LCP request.  If the peer agrees, both sides will exchange	LQR
	     packets at	the agreed frequency, allowing detailed	link quality
	     monitoring	by enabling LQM	logging.  If the peer doesn't agree,
	     ppp will send ECHO	LQR requests instead.  These packets pass no
	     information of interest, but they MUST be replied to by the peer.

	     Whether using LQR or ECHO LQR, ppp	will abruptly drop the connec-
	     tion if 5 unacknowledged packets have been	sent rather than send-
	     ing a 6th.	 A message is logged at	the PHASE level, and any
	     appropriate ``reconnect'' values are honoured as if the peer were
	     responsible for dropping the connection.

	     Default: Disabled and Accepted.  PAP stands for Password Authen-
	     tication Protocol.	 Only one of PAP and CHAP (above) may be nego-
	     tiated.  With PAP,	the ID and Password are	sent repeatedly	to the
	     peer until	authentication is acknowledged or the connection is
	     terminated.  This is a rather poor	security mechanism.  It	is
	     only performed when the connection	is first established.  If you
	     want to have your peer authenticate itself, you must ``enable
	     pap''.  in	/etc/ppp/ppp.conf, and have an entry in
	     /etc/ppp/ppp.secret for the peer (although	see the	``passwdauth''
	     option below).

	     When using	PAP as the client, you need only specify ``AuthName''
	     and ``AuthKey'' in	/etc/ppp/ppp.conf.  PAP	is accepted by

	     Default: Enabled and Accepted.  This option decides if Predictor
	     1 compression will	be used	by the Compression Control Protocol

	     Default: Enabled and Accepted.  This option is used to negotiate
	     PFC (Protocol Field Compression), a mechanism where the protocol
	     field number is reduced to	one octet rather than two.

	     Default: Enabled and Accepted.  This option determines if ppp
	     will request and accept requests for short	(12 bit) sequence num-
	     bers when negotiating multi-link mode.  This is only applicable
	     if	our MRRU is set	(thus enabling multi-link).

	     Default: Enabled and Accepted.  This option determines if Van
	     Jacobson header compression will be used.

	 The following options are not actually	negotiated with	the peer.
	 Therefore, accepting or denying them makes no sense.

	     Default: Enabled.	When ppp exchanges low-level LCP, CCP and IPCP
	     configuration traffic, the	Identifier field of any	replies	is
	     expected to be the	same as	that of	the request.  By default, ppp
	     drops any reply packets that do not contain the expected identi-
	     fier field, reporting the fact at the respective log level.  If
	     idcheck is	disabled, ppp will ignore the identifier field.

	     Default: Enabled.	When loopback is enabled, ppp will automati-
	     cally loop	back packets being sent	out with a destination address
	     equal to that of the PPP interface.  If disabled, ppp will	send
	     the packet, probably resulting in an ICMP redirect	from the other
	     end.  It is convenient to have this option	enabled	when the
	     interface is also the default route as it avoids the necessity of
	     a loopback	route.

	     Default: Disabled.	 Enabling this option will tell	the PAP
	     authentication code to use	the password database (see passwd(5))
	     to	authenticate the caller	if they	cannot be found	in the
	     /etc/ppp/ppp.secret file.	/etc/ppp/ppp.secret is always checked
	     first.  If	you wish to use	passwords from passwd(5), but also to
	     specify an	IP number or label for a given client, use ``*'' as
	     the client	password in /etc/ppp/ppp.secret.

	     Default: Disabled.	 Enabling this option will tell	ppp to proxy
	     ARP for the peer.

	     Default: Disabled.	 Enabling this will tell ppp to	add proxy arp
	     entries for every IP address in all class C or smaller subnets
	     routed via	the tun	interface.

	     Default: Enabled.	When the ``add'' command is used with the
	     HISADDR or	MYADDR values, entries are stored in the `stick	route'
	     list.  Each time HISADDR or MYADDR	change,	this list is re-
	     applied to	the routing table.

	     Disabling this option will	prevent	the re-application of sticky
	     routes, although the `stick route'	list will still	be maintained.

	     Default: Enabled.	This option tells ppp to gather	throughput
	     statistics.  Input	and output is sampled over a rolling 5 second
	     window, and current, best and total figures are retained.	This
	     data is output when the relevant PPP layer	shuts down, and	is
	     also available using the ``show'' command.	 Throughput statistics
	     are available at the ``IPCP'' and ``modem'' levels.

	     Default: Enabled.	Normally, when a user is authenticated using
	     PAP or CHAP, and when ppp is running in -direct mode, an entry is
	     made in the utmp and wtmp files for that user.  Disabling this
	     option will tell ppp not to make any utmp or wtmp entries.	 This
	     is	usually	only necessary if you require the user to both login
	     and authenticate themselves.

	     Default: Enabled if -alias	is specified.  This option simply
	     tells ppp to add new interface addresses to the interface rather
	     than replacing them.  The option can only be enabled if IP	alias-
	     ing is enabled (``alias enable yes'').

	     With this option enabled, ppp will	pass traffic for old interface
	     addresses through the IP alias engine (see	libalias(5)), result-
	     ing in the	ability	(in -auto mode)	to properly connect the
	     process that caused the PPP link to come up in the	first place.

	     Disabling IP aliasing with	``alias	enable off'' will also disable

     add[!] dest[/nn] [mask] gateway
	 Dest is the destination IP address.  The netmask is specified either
	 as a number of	bits with /nn or as an IP number using mask.  0	0 or
	 simply	0 with no mask refers to the default route.  It	is also	possi-
	 ble to	use the	literal	name `default' instead of 0.  Gateway is the
	 next hop gateway to get to the	given dest machine/network.  Refer to
	 the route(8) command for further details.

	 It is possible	to use the symbolic names `MYADDR' or `HISADDR'	as the
	 destination, and `HISADDR' as the gateway.  `MYADDR' is replaced with
	 the interface address and `HISADDR' is	replaced with the interface
	 destination (peer) address.

	 If the	add! command is	used (note the trailing	``!''),	then if	the
	 route already exists, it will be updated as with the `route change'
	 command (see route(8) for further details).

	 Routes	that contain the ``HISADDR'' or	``MYADDR'' constants are con-
	 sidered `sticky'.  They are stored in a list (use ``show ipcp'' to
	 see the list),	and each time the value	of HISADDR or MYADDR changes,
	 the appropriate routing table entries are updated.  This facility may
	 be disabled using ``disable sroutes''.

     allow command [args]
	 This command controls access to ppp and its configuration files.  It
	 is possible to	allow user-level access, depending on the configura-
	 tion file label and on	the mode that ppp is being run in.  For	exam-
	 ple, you may wish to configure	ppp so that only user `fred' may
	 access	label `fredlabel' in -background mode.

	 User id 0 is immune to	these commands.

	 allow user[s] logname...
	     By	default, only user id 0	is allowed access to ppp.  If this
	     command is	used, all of the listed	users are allowed access to
	     the section in which the ``allow users'' command is found.	 The
	     `default' section is always checked first (even though it is only
	     ever automatically	loaded at startup).  Each successive ``allow
	     users'' command overrides the previous one, so it's possible to
	     allow users access	to everything except a given label by specify-
	     ing default users in the `default'	section, and then specifying a
	     new user list for that label.

	     If	user `*' is specified, access is allowed to all	users.

	 allow mode[s] modelist...
	     By	default, access	using any ppp mode is possible.	 If this com-
	     mand is used, it restricts	the access mode	allowed	to load	the
	     label under which this command is specified.  Again, as with the
	     ``allow users'' command, each ``allow modes'' command overrides
	     the previous, and the `default' section is	always checked first.

	     Possible modes are: `interactive',	`auto',	`direct', `dedicated',
	     `ddial', `background' and `*'.

	     When running in multi-link	mode, a	section	can be loaded if it
	     allows any	of the currently existing line modes.

     alias command [args]
	 This command allows the control of the	aliasing (or masquerading)
	 facilities that are built into	ppp.  If aliasing is enabled on	your
	 system	(it may	be omitted at compile time), the following commands
	 are possible:

	 alias enable [yes|no]
	     This command either switches aliasing on or turns it off.	The
	     -alias command line flag is synonymous with ``alias enable	yes''.

	 alias port [proto targetIP:targetPORT [aliasIP:]aliasPORT]
	     This command allows us to redirect	connections arriving at
	     aliasPORT for machine aliasIP to targetPORT on targetIP.  Proto
	     may be either `tcp' or `udp', and only connections	of the given
	     protocol are matched.  This option	is useful if you wish to run
	     things like Internet phone	on the machines	behind your gateway.

	 alias addr [addr_local	addr_alias]
	     This command allows data for addr_alias to	be redirected to
	     addr_local.  It is	useful if you own a small number of real IP
	     numbers that you wish to map to specific machines behind your

	 alias deny_incoming [yes|no]
	     If	set to yes, this command will refuse all incoming connections
	     by	dropping the packets in	much the same way as a firewall	would.

	 alias help|?
	     This command gives	a summary of available alias commands.

	 alias log [yes|no]
	     This option causes	various	aliasing statistics and	information to
	     be	logged to the file /var/log/alias.log.

	 alias same_ports [yes|no]
	     When enabled, this	command	will tell the alias library attempt to
	     avoid changing the	port number on outgoing	packets.  This is use-
	     ful if you	want to	support	protocols such as RPC and LPD which
	     require connections to come from a	well known port.

	 alias use_sockets [yes|no]
	     When enabled, this	option tells the alias library to create a
	     socket so that it can guarantee a correct incoming	ftp data or
	     IRC connection.

	 alias unregistered_only [yes|no]
	     Only alter	outgoing packets with an unregistered source ad-
	     dress.  According to RFC 1918, unregistered source	addresses are, and

	 These commands	are also discussed in the file README.alias which
	 comes with the	source distribution.

     [!]bg command
	 The given command is executed in the background with the following
	 words replaced:

	 AUTHNAME      This is replaced	with the local authname	value.	See
		       the ``set authname'' command below.

	 ENDDISC       This is replaced	with the local endpoint	discriminator
		       value.  See the ``set enddisc'' command below.

	 HISADDR       This is replaced	with the peers IP number.

	 INTERFACE     This is replaced	with the name of the interface that's
		       in use.

	 LABEL	       This is replaced	with the last label name used.	A
		       label may be specified on the ppp command line, via the
		       ``load''	or ``dial'' commands and in the	ppp.secret

	 MYADDR	       This is replaced	with the IP number assigned to the
		       local interface.

	 PEER_ENDDISC  This is replaced	with the value of the peers endpoint

	 PROCESSID     This is replaced	with the current process id.

	 USER	       This is replaced	with the username that has been
		       authenticated with PAP or CHAP.	Normally, this vari-
		       able is assigned	only in	-direct	mode.  This value is
		       available irrespective of whether utmp logging is

	 These substitutions are also done by the ``set	proctitle'' command.

	 If you	wish to	pause ppp while	the command executes, use the
	 ``shell'' command instead.

     clear modem|ipcp [current|overall|peak...]
	 Clear the specified throughput	values at either the ``modem'' or
	 ``ipcp'' level.  If ``modem'' is specified, context must be given
	 (see the ``link'' command below).  If no second argument is given,
	 all values are	cleared.

     clone name[,name]...
	 Clone the specified link, creating one	or more	new links according to
	 the name argument(s).	This command must be used from the ``link''
	 command below unless you've only got a	single link (in	which case
	 that link  becomes the	default).  Links may be	removed	using the
	 ``remove'' command below.

	 The default link name is ``deflink''.

     close [lcp|ccp[!]]
	 If no arguments are given, the	relevant protocol layers will be
	 brought down and the link will	be closed.  If ``lcp'' is specified,
	 the LCP layer is brought down,	but ppp	will not bring the link
	 offline.  It is subsequently possible to use ``term'' (see below) to
	 talk to the peer machine if, for example, something like ``slirp'' is
	 being used.  If ``ccp'' is specified, only the	relevant compression
	 layer is closed.  If the ``!''	is used, the compression layer will
	 remain	in the closed state, otherwise it will re-enter	the STOPPED
	 state,	waiting	for the	peer to	initiate further CCP negotiation.  In
	 any event, this command does not disconnect the user from ppp or exit
	 ppp.  See the ``quit''	command	below.

     delete[!] dest
	 This command deletes the route	with the given dest IP address.	 If
	 dest is specified as `ALL', all non-direct entries in the routing ta-
	 ble for the current interface,	and all	`sticky	route' entries are
	 deleted.  If dest is specified	as `default', the default route	is

	 If the	delete!	command	is used	(note the trailing ``!''), ppp will
	 not complain if the route does	not already exist.

     dial|call [label]
	 When used with	no argument, this command is the same as the ``open''
	 command.  When	one or more label is specified,	a ``load'' will	be
	 done first.

     down [lcp|ccp]
	 Bring the relevant layer down ungracefully, as	if the underlying
	 layer had become unavailable.	It's not considered polite to use this
	 command on a Finite State Machine that's in the OPEN state.  If no
	 arguments are supplied, the entire link is closed (or if no context
	 is given, all links are terminated).  If `lcp'	is specified, the LCP
	 layer is terminated but the modem is not brought offline and the link
	 is not	closed.	 If `ccp' is specified,	only the relevant compression
	 layer(s) are terminated.

     help|? [command]
	 Show a	list of	available commands.  If	command	is specified, show the
	 usage string for that command.

     iface command [args]
	 This command is used to control the interface used by ppp.  Command
	 may be	one of the following:

	 iface add[!] addr[[/bits| mask] peer]
	     Add the given addr	mask peer combination to the interface.
	     Instead of	specifying mask, /bits can be used (with no space
	     between it	and addr).  If the given address already exists, the
	     command fails unless the ``!'' is used - in which case the	previ-
	     ous interface address entry is overwritten	with the new one,
	     allowing a	change of netmask or peer address.

	     If	only addr is specified,	bits defaults to ``32''	and peer
	     defaults to ``''.  This address (the broadcast
	     address) is the only duplicate peer address that ppp allows.

	 iface clear
	     If	this command is	used while ppp is in the OPENED	state or while
	     in	-auto mode, all	addresses except for the IPCP negotiated
	     address are deleted from the interface.  If ppp is	not in the
	     OPENED state and is not in	-auto mode, all	interface addresses
	     are deleted.

	 iface delete[!]|rm[!] addr
	     This command deletes the given addr from the interface.  If the
	     ``!'' is used, no error is	given if the address isn't currently
	     assigned to the interface (and no deletion	takes place).

	 iface show
	     Shows the current state and current addresses for the interface.
	     It	is much	the same as running ``ifconfig INTERFACE''.

	 iface help [sub-command]
	     This command, when	invoked	without	sub-command, will show a list
	     of	possbile ``iface'' sub-commands	and a brief synopsis for each.
	     When invoked with sub-command, only the synopsis for the given
	     sub-command is shown.

     [data]link	name[,name...] command [args]
	 This command may prefix any other command if the user wishes to spec-
	 ify which link	the command should affect.  This is only applicable
	 after multiple	links have been	created	in Multi-link mode using the
	 ``clone'' command.

	 Name specifies	the name of an existing	link.  If name is a comma sep-
	 arated	list, command is executed on each link.	 If name is ``*'',
	 command is executed on	all links.

     load [label ...]
	 Load the given	label(s) from the ppp.conf file.  If label is not
	 given,	the default label is used.

     open [lcp|ccp|ipcp]
	 This is the opposite of the ``close'' command.	 Using ``open''	with
	 no arguments is the same as using ``dial'' with no arguments, where
	 all closed links are brought up (some auto links may not come up
	 based on the ``set autoload'' command)	using the current configura-

	 If the	``lcp''	while the LCP layer is already open, LCP will be rene-
	 gotiated.  This allows	various	LCP options to be changed, after which
	 ``open	lcp'' can be used to put them into effect.  After renegotiat-
	 ing LCP, any agreed authentication will also take place.

	 If the	``ccp''	argument is used, the relevant compression layer is
	 opened.  Again, if it is already open,	it will	be renegotiated.

	 If the	``ipcp'' argument is used, the link will be brought up as nor-
	 mal, but if IPCP is already open, it will be renegotiated and the
	 network interface will	be reconfigured.

	 It is probably	not good practice to re-open the PPP state machines
	 like this as it's possible that the peer will not behave correctly.
	 It is however useful as a way of forcing the CCP or VJ	dictionaries
	 to be reset.

     passwd pass
	 Specify the password required for access to the full ppp command set.
	 This password is required when	connecting to the diagnostic port (see
	 the ``set server'' command).  Pass is specified on the	``set server''
	 command line.	The value of pass is not logged	when command logging
	 is active, instead, the literal string	`********' is logged.

     quit|bye [all]
	 If ``quit'' is	executed from the controlling connection or from a
	 command file, ppp will	exit after closing all connections.  Other-
	 wise, if the user is connected	to a diagnostic	socket,	the connection
	 is simply dropped.

	 If the	file ... all argument is given,	ppp will exit despite the
	 source	of the command after closing all existing connections.

	 This command removes the given	link.  It is only really useful	in
	 multi-link mode.  A link must be in the CLOSED	state before it	is

     rename|mv name
	 This command renames the given	link to	name.  It will fail if name is
	 already used by another link.

	 The default link name is `deflink'.  Renaming it to `modem', `cuaa0'
	 or `USR' may make the log file	more readable.

	 This option is	not (yet) implemented.

     set[up] var value
	 This option allows the	setting	of any of the following	variables:

	 set accmap hex-value
	     ACCMap stands for Asynchronous Control Character Map.  This is
	     always negotiated with the	peer, and defaults to a	value of
	     00000000 in hex.  This protocol is	required to defeat hardware
	     that depends on passing certain characters	from end to end	(such
	     as	XON/XOFF etc).

	     For the XON/XOFF scenario,	use ``set accmap 000a0000''.

	 set authkey|key value
	     This sets the authentication key (or password) used in client
	     mode PAP or CHAP negotiation to the given value.  It can also be
	     used to specify the password to be	used in	the dial or login
	     scripts in	place of the '\P' sequence, preventing the actual
	     password from being logged.  If command logging is	in effect,
	     value is logged as	`********' for security	reasons.

	 set authname id
	     This sets the authentication id used in client mode PAP or	CHAP

	     If	used in	-direct	mode with PAP or CHAP enabled, id is used in
	     the initial authentication	request	and is normally	set to the
	     local machine name.

	 set autoload max-duration max-load [min-duration min-load]
	     These settings apply only in multi-link mode and all default to
	     zero.  When more than one demand-dial (also known as -auto) mode
	     link is available,	only the first link is made active when	ppp
	     first reads data from the tun device.  The	next demand-dial link
	     will be opened only when at least max-load	packets	have been in
	     the send queue for	max-duration seconds.  Because both values
	     default to	zero, demand-dial links	will simply come up one	at a
	     time by default.

	     If	two or more links are open, at least one of which is a
	     demand-dial link, a demand-dial link will be closed when there is
	     less than min-packets in the queue	for more than min-duration.
	     If	min-duration is	zero, this timer is disabled.  Because both
	     values default to zero, demand-dial links will stay active	until
	     the bundle	idle timer expires.

	 set callback [none|auth|cbcp|E.164 *|number[,number]...]...
	     If	no arguments are given,	callback is disabled, otherwise, ppp
	     will request (or in -direct mode, will accept) one	of the given
	     protocols.	 In client mode, if a request is NAK'd ppp will
	     request another, until no options remain at which point ppp will
	     terminate negotiations.  In server	mode, ppp will accept any of
	     the given protocols - but the client must request one of them.
	     If	you wish callback to be	optional, you must include none	as an

	     The options are as	follows	(in this order of preference):

	     auth	   The callee is expected to decide the	callback num-
			   ber based on	authentication.	 If ppp	is the callee,
			   the number should be	specified as the fifth field
			   of the peers	entry in /etc/ppp/ppp.secret.

	     cbcp	   Microsofts callback control protocol	is used.  See
			   ``set cbcp''	below.

	     E.164 *|number[,number]...
			   The caller specifies	the number.  If	ppp is the
			   callee, number should be either a comma seperated
			   list	of allowable numbers or	a ``*'', meaning any
			   number is permitted.	 If ppp	is the caller, only a
			   single number should	be specified.

			   Note, this option is	very unsafe when used with a
			   ``*'' as a malicious	caller can tell	ppp to call
			   any (possibly international)	number without first
			   authenticating themselves.

	     none	   If the peer does not	wish to	do callback at all,
			   ppp will accept the fact and	continue without call-
			   back	rather than terminating	the connection.	 This
			   is required if you wish callback to be optional.

	 set cbcp [*|number[,number]...	[delay [retry]]]
	     If	no arguments are given,	CBCP (Microsofts CallBack Control Pro-
	     tocol) is disabled	- ie, configuring CBCP in the ``set callback''
	     command will result in ppp	requesting no callback in the CBCP
	     phase.  Otherwise,	ppp attempts to	use the	given phone number(s).

	     In	server mode (-direct), ppp will	insist that the	client uses
	     one of these numbers, unless ``*''	is used	in which case the
	     client is expected	to specify the number.

	     In	client mode, ppp will attempt to use one of the	given numbers
	     (whichever	it finds to be agreeable with the peer), or if ``*''
	     is	specified, ppp will expect the peer to specify the number.

	 set choked [timeout]
	     This sets the number of seconds that ppp will keep	a choked out-
	     put queue before dropping all pending output packets.  If timeout
	     is	less than or equal to zero or if timeout isn't specified, it
	     is	set to the default value of 120	seconds.

	     A choked output queue occurs when ppp has read a certain number
	     of	packets	from the local network for transmission, but cannot
	     send the data due to link failure (the peer is busy etc.).	 Ppp
	     will not read packets indefinitely.  Instead, it reads up to 20
	     packets (or 20 + nlinks * 2 packets in multi-link mode), then
	     stops reading the network interface until either timeout seconds
	     have passed or at least one packet	has been sent.

	     If	timeout	seconds	pass, all pending output packets are dropped.

	 set ctsrts|crtscts on|off
	     This sets hardware	flow control.  Hardware	flow control is	on by

	 set deflate out-winsize [in-winsize]
	     This sets the DEFLATE algorithms default outgoing and incoming
	     window sizes.  Both out-winsize and in-winsize must be values
	     between 8 and 15.	If in-winsize is specified, ppp	will insist
	     that this window size is used and will not	accept any other val-
	     ues from the peer.

	 set dns [primary [secondary]]
	     This command specifies DNS	overrides for the ``accept dns'' com-
	     mand.  Refer to the ``accept'' command description	above for
	     details.  This command does not affect the	IP numbers requested
	     using ``enable dns''.

	 set device|line value[,value...]
	     This sets the device(s) to	which ppp will talk to the given
	     ``value''.	 All serial device names are expected to begin with
	     /dev/.  If	``value'' does not begin with /dev/, it	must either
	     begin with	an exclamation mark (``!'') or be of the format

	     If	it begins with an exclamation mark, the	rest of	the device
	     name is treated as	a program name,	and that program is executed
	     when the device is	opened.	 Standard input, output	and error are
	     fed back to ppp and are read and written as if they were a	regu-
	     lar device.

	     If	a ``host:port''	pair is	given, ppp will	attempt	to connect to
	     the given ``host''	on the given ``port''.	Refer to the section
	     on	PPP OVER TCP above for further details.

	     If	multiple ``values'' are	specified, ppp will attempt to open
	     each one in turn until it succeeds	or runs	out of devices.

	 set dial chat-script
	     This specifies the	chat script that will be used to dial the
	     other side.  See also the ``set login'' command below.  Refer to
	     chat(8) and to the	example	configuration files for	details	of the
	     chat script format.  It is	possible to specify some special
	     `values' in your chat script as follows:

	       \c  When	used as	the last character in a
		   string, this	indicates that a newline should	not be appended.

	       \d  When	the chat script	encounters this	sequence, it delays two	seconds.

	       \p  When	the chat script	encounters this	sequence, it delays for	one quarter of
		   a second.

	       \n  This	is replaced with a newline character.

	       \r  This	is replaced with a carriage return character.

	       \s  This	is replaced with a space character.

	       \t  This	is replaced with a tab character.

	       \T  This	is replaced by the current phone number	(see
		   ``set phone''

	       \P  This	is replaced by the current
		   value (see
		   ``set authkey''

	       \U  This	is replaced by the current
		   value (see
		   ``set authname''

	     Note that two parsers will	examine	these escape sequences,	so in
	     order to have the `chat parser' see the escape character, it is
	     necessary to escape it from the `command parser'.	This means
	     that in practice you should use two escapes, for example:

		   set dial "... ATDT\\T CONNECT"

	     It	is also	possible to execute external commands from the chat
	     script.  To do this, the first character of the expect or send
	     string is an exclamation mark (``!'').  When the command is exe-
	     cuted, standard input and standard	output are directed to the
	     modem device (see the ``set device'' command), and	standard error
	     is	read by	ppp and	substituted as the expect or send string.  If
	     ppp is running in interactive mode, file descriptor 3 is attached
	     to	/dev/tty.

	     For example (wrapped for readability);

		   set login "TIMEOUT 5	\"\" \"\" login:--login: ppp \
		   word: ppp \"!sh \\\\-c \\\"echo \\\\-n label: >&2\\\"\" \
		   \"!/bin/echo	in\" HELLO"

	     would result in the following chat	sequence (output using the
	     `set log local chat' command before dialing):

		   Dial	attempt	1 of 1
		   dial	OK!
		   Chat: Expecting:
		   Chat: Sending:
		   Chat: Expecting: login:--login:
		   Chat: Wait for (5): login:
		   Chat: Sending: ppp
		   Chat: Expecting: word:
		   Chat: Wait for (5): word:
		   Chat: Sending: ppp
		   Chat: Expecting: !sh	\-c "echo \-n label: >&2"
		   Chat: Exec: sh -c "echo -n label: >&2"
		   Chat: Wait for (5): !sh \-c "echo \-n label:	>&2" --> label:
		   Chat: Exec: /bin/echo in
		   Chat: Sending:
		   Chat: Expecting: HELLO
		   Chat: Wait for (5): HELLO
		   login OK!

	     Note (again) the use of the escape	character, allowing many lev-
	     els of nesting.  Here, there are four parsers at work.  The first
	     parses the	original line, reading it as three arguments.  The
	     second parses the third argument, reading it as 11	arguments.  At
	     this point, it is important that the ``-''	signs are escaped,
	     otherwise this parser will	see them as constituting an expect-
	     send-expect sequence.  When the ``!'' character is	seen, the exe-
	     cution parser reads the first command as three arguments, and
	     then sh(1)	itself expands the argument after the -c.  As we wish
	     to	send the output	back to	the modem, in the first	example	we re-
	     direct our	output to file descriptor 2 (stderr) so	that ppp
	     itself sends and logs it, and in the second example, we just out-
	     put to stdout, which is attached directly to the modem.

	     This, of course means that	it is possible to execute an entirely
	     external ``chat'' command rather than using the internal one.
	     See chat(8) for a good alternative.

	 set enddisc [label|IP|MAC|magic|psn value]
	     This command sets our local endpoint discriminator.  If set prior
	     to	LCP negotiation, ppp will send the information to the peer
	     using the LCP endpoint discriminator option.  The following dis-
	     criminators may be	set:

		   The current label is	used.

	       IP  Our local IP	number is used.	 As LCP	is negotiated prior to IPCP, it	is
		   possible that the IPCP layer	will subsequently change this value.  If
		   it does, the	endpoint discriminator stays at	the old	value unless manually

		   This	is similar to the
		   option above, except	that the MAC address associated	with the local IP
		   number is used.  If the local IP number is not resident on any Ethernet
		   interface, the command will fail.

		   As the local	IP number defaults to whatever the machine host	name is,
		   ``set enddisc mac''
		   is usually done prior to any
		   ``set ifaddr''

		   A 20	digit random number is used.

	       psn value
		   The given
		   is used.
		   should be set to an absolute	public switched	network	number with the
		   country code	first.

	     If	no arguments are given,	the endpoint discriminator is reset.

	 set escape value...
	     This option is similar to the ``set accmap'' option above.	 It
	     allows the	user to	specify	a set of characters that will be
	     `escaped' as they travel across the link.

	 set filter dial|alive|in|out rule-no permit|deny [src_addr/width]
	     [dst_addr/width] [proto [src [lt|eq|gt port]] [dst	[lt|eq|gt
	     port]] [estab] [syn] [finrst]]
	     Ppp supports four filter sets.  The alive filter specifies	pack-
	     ets that keep the connection alive	- reseting the idle timer.
	     The dial filter specifies packets that cause ppp to dial when in
	     -auto mode.  The in filter	specifies packets that are allowed to
	     travel into the machine and the out filter	specifies packets that
	     are allowed out of	the machine.

	     Filtering is done prior to	any IP alterations that	might be done
	     by	the alias engine.  By default all filter sets allow all	pack-
	     ets to pass.  Rules are processed in order	according to rule-no.
	     Up	to 20 rules may	be given for each set.	If a packet doesn't
	     match any of the rules in a given set, it is discarded.  In the
	     case of in	and out	filters, this means that the packet is
	     dropped.  In the case of alive filters it means that the packet
	     will not reset the	idle timer and in the case of dial filters it
	     means that	the packet will	not trigger a dial.  A packet failing
	     to	trigger	a dial will be dropped rather than queued.  Refer to
	     the section on PACKET FILTERING above for further details.

	 set hangup chat-script
	     This specifies the	chat script that will be used to reset the
	     modem before it is	closed.	 It should not normally	be necessary,
	     but can be	used for devices that fail to reset themselves prop-
	     erly on close.

	 set help|? [command]
	     This command gives	a summary of available set commands, or	if
	     command is	specified, the command usage is	shown.

	 set ifaddr [myaddr [hisaddr [netmask [triggeraddr]]]]
	     This command specifies the	IP addresses that will be used during
	     IPCP negotiation.	Addresses are specified	using the format


	     Where a.b.c.d is the preferred IP,	but n specifies	how many bits
	     of	the address we will insist on.	If /n is omitted, it defaults
	     to	/32 unless the IP address is in	which case it defaults
	     to	/0.

	     Hisaddr may also be specified as a	range of IP numbers in the


	     for example:

		   set ifaddr,

	     will only negotiate as the local IP number, but may
	     assign any	of the given 10	IP numbers to the peer.	 If the	peer
	     requests one of these numbers, and	that number is not already in
	     use, ppp will grant the peers request.  This is useful if the
	     peer wants	to re-establish	a link using the same IP number	as was
	     previously	allocated (thus	maintaining any	existing tcp connec-

	     If	the peer requests an IP	number that's either outside of	this
	     range or is already in use, ppp will suggest a random unused IP
	     number from the range.

	     If	triggeraddr is specified, it is	used in	place of myaddr	in the
	     initial IPCP negotiation.	However, only an address in the	myaddr
	     range will	be accepted.  This is useful when negotiating with
	     some PPP implementations that will	not assign an IP number	unless
	     their peer	requests

	     It	should be noted	that in	-auto mode, ppp	will configure the
	     interface immediately upon	reading	the ``set ifaddr'' line	in the
	     config file.  In any other	mode, these values are just used for
	     IPCP negotiations,	and the	interface isn't	configured until the
	     IPCP layer	is up.

	     Note that the HISADDR argument may	be overridden by the third
	     field in the ppp.secret file once the client has authenticated
	     itself (if	PAP or CHAP are	``enabled'').  Refer to	the

	     In	all cases, if the interface is already configured, ppp will
	     try to maintain the interface IP numbers so that any existing
	     bound sockets will	remain valid.

	 set ccpretry period

	 set chapretry period

	 set ipcpretry period

	 set lcpretry period

	 set papretry period
	     These commands set	the number of seconds that ppp will wait
	     before resending Finite State Machine (FSM) Request packets.  The
	     default period for	all FSMs is 3 seconds (which should suffice in
	     most cases).

	 set log [local] [+|-]value...
	     This command allows the adjustment	of the current log level.
	     Refer to the Logging Facility section for further details.

	 set login chat-script
	     This chat-script compliments the dial-script.  If both are	speci-
	     fied, the login script will be executed after the dial script.
	     Escape sequences available	in the dial script are also available

	 set lqrperiod frequency
	     This command sets the frequency in	seconds	at which LQR or	ECHO
	     LQR packets are sent.  The	default	is 30 seconds.	You must also
	     use the ``enable lqr'' command if you wish	to send	LQR requests
	     to	the peer.

	 set mode interactive|auto|ddial|background
	     This command allows you to	change the `mode' of the specified
	     link.  This is normally only useful in multi-link mode, but may
	     also be used in uni-link mode.

	     It	is not possible	to change a link that is `direct' or

	     Note: If you issue	the command ``set mode auto'', and have	IP
	     aliasing enabled, it may be useful	to ``enable iface-alias''
	     afterwards.  This will allow ppp to do the	necessary address
	     translations to enable the	process	that triggers the connection
	     to	connect	once the link is up despite the	peer assigning us a
	     new (dynamic) IP address.

	 set mrru [value]
	     Setting this option enables Multi-link PPP	negotiations, also
	     known as Multi-link Protocol or MP.  There	is no default MRRU
	     (Maximum Reconstructed Receive Unit) value.  If no	argument is
	     given, multi-link mode is disabled.

	 set mru [value]
	     The default MRU (Maximum Receive Unit) is 1500.  If it is
	     increased,	the other side *may* increase its mtu.	There is no
	     point in decreasing the MRU to below the default as the PPP pro-
	     tocol *must* be able to accept packets of at least	1500 octets.
	     If	no argument is given, 1500 is assumed.

	 set mtu [value]
	     The default MTU is	1500.  At negotiation time, ppp	will accept
	     whatever MRU or MRRU that the peer	wants (assuming	it's not less
	     than 296 bytes).  If the MTU is set, ppp will not accept MRU/MRRU
	     values less than value.  When negotiations	are complete, the MTU
	     is	assigned to the	interface, even	if the peer requested a	higher
	     value MRU/MRRU.  This can be useful for limiting your packet size
	     (giving better bandwidth sharing at the expense of	more header

	     If	no value is given, 1500, or whatever the peer asks for is

	 set nbns [x.x.x.x [y.y.y.y]]
	     This option allows	the setting of the Microsoft NetBIOS name
	     server values to be returned at the peers request.	 If no values
	     are given,	ppp will reject	any such requests.

	 set openmode active|passive [delay]
	     By	default, openmode is always active with	a one second delay.
	     That is, ppp will always initiate LCP/IPCP/CCP negotiation	one
	     second after the line comes up.  If you want to wait for the peer
	     to	initiate negotiations, you can use the value passive.  If you
	     want to initiate negotiations immediately or after	more than one
	     second, the appropriate delay may be specified here in seconds.

	 set parity odd|even|none|mark
	     This allows the line parity to be set.  The default value is

	 set phone telno[|telno]...[:telno[|telno]...]...
	     This allows the specification of the phone	number to be used in
	     place of the \\T string in	the dial and login chat	scripts.  Mul-
	     tiple phone numbers may be	given separated	by a pipe (|) or a
	     colon (:).	 Numbers after the pipe	are only dialed	if the dial or
	     login script for the previous number failed.  Numbers separated
	     by	a colon	are tried sequentially,	irrespective of	the reason the
	     line was dropped.	If multiple numbers are	given, ppp will	dial
	     them according to these rules until a connection is made, retry-
	     ing the maximum number of times specified by ``set	redial''
	     below.  In	-background mode, each number is attempted at most

	 set [proc]title [value]
	     The current process title as displayed by ps(1) is	changed
	     according to value.  If value is not specified, the original
	     process title is restored.	 All the word replacements done	by the
	     shell commands (see the ``bg'' command above) are done here too.

	 set reconnect timeout ntries
	     Should the	line drop unexpectedly (due to loss of CD or LQR fail-
	     ure), a connection	will be	re-established after the given
	     timeout.  The line	will be	re-connected at	most ntries times.
	     Ntries defaults to	zero.  A value of random for timeout will
	     result in a variable pause, somewhere between 0 and 30 seconds.

	 set recvpipe [value]
	     This sets the routing table RECVPIPE value.  The optimum value is
	     just over twice the MTU value.  If	value is unspecified or	zero,
	     the default kernel	controlled value is used.

	 set redial seconds[.nseconds] [attempts]
	     Ppp can be	instructed to attempt to redial	attempts times.	 If
	     more than one phone number	is specified (see ``set	phone''
	     above), a pause of	nseconds is taken before dialing each number.
	     A pause of	seconds	is taken before	starting at the	first number
	     again.  A value of	random may be used here	in place of seconds
	     and nseconds, causing a random delay of between 0 and 30 seconds.

	     Note, this	delay will be effective, even after attempts has been
	     exceeded, so an immediate manual dial may appear to have done
	     nothing.  If an immediate dial is required, a ``!'' should	imme-
	     diately follow the	``open'' keyword.  See the ``open'' descrip-
	     tion above	for further details.

	 set sendpipe [value]
	     This sets the routing table SENDPIPE value.  The optimum value is
	     just over twice the MTU value.  If	value is unspecified or	zero,
	     the default kernel	controlled value is used.

	 set server|socket TcpPort|LocalName|none password [mask]
	     This command tells	ppp to listen on the given socket or
	     `diagnostic port' for incoming command connections.

	     The word none instructs ppp to close any existing socket.

	     If	you wish to specify a local domain socket, LocalName must be
	     specified as an absolute file name, otherwise it is assumed to be
	     the name or number	of a TCP port.	You may	specify	the octal
	     umask that	should be used with local domain sockets as a four
	     character octal number beginning with `0'.	 Refer to umask(2) for
	     umask details.  Refer to services(5) for details of how to	trans-
	     late TCP port names.

	     You must also specify the password	that must be entered by	the
	     client (using the ``passwd'' command above) when connecting to
	     this socket.  If the password is specified	as an empty string, no
	     password is required for connecting clients.

	     When specifying a local domain socket, the	first ``%d'' sequence
	     found in the socket name will be replaced with the	current	inter-
	     face unit number.	This is	useful when you	wish to	use the	same
	     profile for more than one connection.

	     In	a similar manner TCP sockets may be prefixed with the ``+''
	     character,	in which case the current interface unit number	is
	     added to the port number.

	     When using	ppp with a server socket, the pppctl(8)	command	is the
	     preferred mechanism of communications.  Currently,	telnet(1) can
	     also be used, but link encryption may be implemented in the
	     future, so	telnet(1) should not be	relied upon.

	 set speed value
	     This sets the speed of the	serial device.

	 set stopped [LCPseconds [CCPseconds]]
	     If	this option is set, ppp	will time out after the	given FSM
	     (Finite State Machine) has	been in	the stopped state for the
	     given number of ``seconds''.  This	option may be useful if	the
	     peer sends	a terminate request, but never actually	closes the
	     connection	despite	our sending a terminate	acknowledgement.  This
	     is	also useful if you wish	to ``set openmode passive'' and	time
	     out if the	peer doesn't send a Configure Request within the given
	     time.  Use	``set log +lcp +ccp'' to make ppp log the appropriate
	     state transitions.

	     The default value is zero,	where ppp doesn't time out in the
	     stopped state.

	     This value	should not be set to less than the openmode delay (see
	     ``set openmode'' above).

	 set timeout idleseconds
	     This command allows the setting of	the idle timer.	 Refer to the
	     section titled ``SETTING THE IDLE TIMER'' for further details.

	 set vj	slotcomp on|off
	     This command tells	ppp whether it should attempt to negotiate VJ
	     slot compression.	By default, slot compression is	turned on.

	 set vj	slots nslots
	     This command sets the initial number of slots that	ppp will try
	     to	negotiate with the peer	when VJ	compression is enabled (see
	     the `enable' command above).  It defaults to a value of 16.
	     Nslots must be between 4 and 16 inclusive.

     shell|! [command]
	 If command is not specified a shell is	invoked	according to the SHELL
	 environment variable.	Otherwise, the given command is	executed.
	 Word replacement is done in the same way as for the ``!bg'' commanad
	 as described above.

	 Use of	the ! character	requires a following space as with any of the
	 other commands.  You should note that this command is executed	in the
	 foreground - ppp will not continue running until this process has
	 exited.  Use the bg command if	you wish processing to happen in the

     show var
	 This command allows the user to examine the following:

	 show bundle
	     Show the current bundle settings.

	 show ccp
	     Show the current CCP compression statistics.

	 show compress
	     Show the current VJ compression statistics.

	 show escape
	     Show the current escape characters.

	 show filter [name]
	     List the current rules for	the given filter.  If name is not
	     specified,	all filters are	shown.

	 show hdlc
	     Show the current HDLC statistics.

	 show help|?
	     Give a summary of available show commands.

	 show iface
	     Show the current interface	information (the same as ``iface

	 show ipcp
	     Show the current IPCP statistics.

	 show lcp
	     Show the current LCP statistics.

	 show [data]link
	     Show high level link information.

	 show links
	     Show a list of available logical links.

	 show log
	     Show the current log values.

	 show mem
	     Show current memory statistics.

	 show modem
	     Show low level link information.

	 show proto
	     Show current protocol totals.

	 show route
	     Show the current routing tables.

	 show stopped
	     Show the current stopped timeouts.

	 show timer
	     Show the active alarm timers.

	 show version
	     Show the current version number of	ppp.

	 Go into terminal mode.	 Characters typed at the keyboard are sent to
	 the modem.  Characters	read from the modem are	displayed on the
	 screen.  When a ppp peer is detected on the other side	of the modem,
	 ppp automatically enables Packet Mode and goes	back into command

     +o	 Read the example configuration	files.	They are a good	source of

     +o	 Use ``help'', ``alias''?, ``enable''?,	``set''?  and ``show''?	 to
	 get online information	about what's available.

     +o	 The following urls contain useful information:

     Ppp refers	to four	files: ppp.conf, ppp.linkup, ppp.linkdown and
     ppp.secret.  These	files are placed in the	/etc/ppp directory.

	 System	default	configuration file.

	 An authorisation file for each	system.

	 A file	to check when ppp establishes a	network	level connection.

	 A file	to check when ppp closes a network level connection.

	 Logging and debugging information file.  Note,	this name is specified
	 in /etc/syslogd.conf.	See syslog.conf(5) for further details.

	 tty port locking file.	 Refer to uucplock(3) for further details.

	 The process id	(pid) of the ppp program connected to the tunN device,
	 where `N' is the number of the	device.

	 The tun interface used	by this	port.  Again, this file	is only	cre-
	 ated in -background, -auto and	-ddial modes.

	 Get port number if port number	is using service name.

	 In multi-link mode, local domain sockets are created using the	peer
	 authentication	name (`authname'), the peer endpoint discriminator
	 class (`class') and the peer endpoint discriminator value (`value').
	 As the	endpoint discriminator value may be a binary value, it is
	 turned	to HEX to determine the	actual file name.

	 This socket is	used to	pass links between different instances of ppp.

     at(1), ftp(1), gzip(1), hostname(1), login(1), tcpdump(1),	telnet(1),
     syslog(3),	uucplock(3), crontab(5), group(5), passwd(5), resolv.conf(5),
     syslog.conf(5), adduser(8), chat(8), getty(8), inetd(8), init(8),
     named(8), ping(8),	pppctl(8), pppd(8), route(8), syslogd(8),
     traceroute(8), vipw(8)

     This program was originally written by Toshiharu OHNO (,
     and was submitted to FreeBSD-2.0.5	by Atsushi Murai (

     It	was substantially modified during 1997 by Brian	Somers (brian@Awful-, and was ported to OpenBSD in November that year (just after the
     2.2 release).

     Most of the code was rewritten by Brian Somers in early 1998 when multi-
     link ppp support was added.

FreeBSD			       20 September 1995		       FreeBSD


Want to link to this manual page? Use this URL:

home | help