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

FreeBSD Manual Pages

  
 
  

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

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

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

DESCRIPTION
     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 im-
     plementation 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 de-
     termined the proper sequence for connecting with the remote host, you can
     write a chat script to define the necessary dialing and login procedure
     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 au-
     tomatically 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 available.
     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 rene-
     gotiation,	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 (ftp://ftp.micro-
     soft.com/developr/rfc/cbcp.txt).

     Supports packet aliasing.	Packet aliasing	(a.k.a.	IP masquerading) al-
     lows computers on a private, unregistered network to access the Internet.
     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-
     lished.

     Supports server-side PPP connections.  In direct mode, ppp	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 re-
     sponse 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 mo-
     dem 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.

PERMISSIONS
     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 in-
     voked ppp.	 Refer to the `ID0' logging facility if	you're interested in
     what exactly is done as user id zero.

GETTING	STARTED
     The following command line	switches are understood	by ppp:

	-auto
	     Ppp opens the tun interface, configures it	then goes into the
	     background.  The link isn't brought up until outgoing data	is de-
	     tected 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 de-
	     fault of 2	minutes.  See the "set choked" command below.

	     At	least one "system" must	be given on the	command	line (see be-
	     low) and a	"set ifaddr" must be done in the system	profile	that
	     specifies a peer IP address to use	when configuring the inter-
	     face.  Something like "10.0.0.1/0"	is usually appropriate.	 See
	     the "pmdemand" system in /etc/ppp/ppp.conf.sample for an example.

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

	-direct
	     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" informa-
	     tion when dialing back.

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

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

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

	-alias
	     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 users 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:

	       !ppp
	       *.*<TAB>/var/log/ppp.log

	 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

	       !ppp0
	       *.*<TAB>/var/log/ppp0.log

	 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.

MANUAL DIALING
     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
	   at
	   OK
	   atdt123456
	   CONNECT
	   login: ppp
	   Password:
	   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 be-
     ing PPP packets, perhaps due to your parity settings.  To force ppp to
     start sending PPP configuration packets to	the peer, use the "~p" command
     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.

AUTOMATIC DIALING
     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" ex-
     ample in /etc/ppp/ppp.conf.sample which runs a script in the background
     after the connection is established (refer	to the "shell" and "bg"	com-
     mands 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
     change.

BACKGROUND DIALING
     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 es-
     tablish the connection immediately.  If multiple phone numbers are	speci-
     fied, 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.

DIAL ON	DEMAND
     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" command
     in	/etc/ppp/ppp.conf, (for	example, "set server +3000 mypasswd") and con-
     necting to	the diagnostic port as follows:

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

     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 argument
     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 outgo-
     ing packet	that is	received. The previous value is	unchanged if this pa-
     rameter 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 de-
     mand 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 ex-
     ample,

	   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) connec-
     tion but not the ppp program itself.  You must use	"quit all" to termi-
     nate ppp as well.

RECEIVING INCOMING PPP CONNECTIONS (Method 1)
     To	handle an incoming PPP connection request, follow these	steps:

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

     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" com-
	  mand 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" commands.
	  Refer	to their descriptions below.

RECEIVING INCOMING PPP CONNECTIONS (Method 2)
     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:

	  default:\
		  :pp=/usr/local/bin/ppplogin:\
		  .....

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

     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:

	  Pfred<TAB>xxxx
	  Pgeorge<TAB>yyyy

     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 at-
     tacks.

AUTHENTICATING INCOMING	CONNECTIONS
     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
     ppp.conf.

     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 ne-
     gotiating 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:

	   ppp-in:
	    set	timeout	0
	    set	ifaddr 10.0.4.1	10.0.4.2
	    add	10.0.1.0/24 10.0.4.2

     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)
     database.

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

	   ui-gate:
	    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 10.0.4.2	10.0.4.1
	    add	10.0.2.0/24 10.0.4.1

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

	    set	authname MyAuthName
	    set	authkey	MyAuthKey

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

	   awfulhak # ppp -background ui-gate

     The result	will be	an additional "route" on awfulhak to the 10.0.2.0/24
     network via the TCP connection, and an additional "route" on ui-gate to
     the 10.0.1.0/24 network.  The networks are	effectively bridged - the un-
     derlying TCP connection may be across a public network (such as the In-
     ternet), 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.

PACKET ALIASING
     The -alias	command	line option enables packet aliasing.  This allows the
     ppp host to act as	a masquerading gateway for other computers over	a lo-
     cal 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 ap-
     plications	(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.

PACKET FILTERING
     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 40 rules, starting from rule 0.  The en-
	 tire rule set is not effective	until rule 0 is	defined, ie. the de-
	 fault is to allow everything through.

     +o	 If no rule is matched to a packet, that packet	will be	discarded
	 (blocked).

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

     See /etc/ppp/ppp.conf.sample.

SETTING	THE IDLE TIMER
     To	check/set the idle timer, use the "show	bundle"	and "set timeout" com-
     mands:

	   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
     command

	   ppp ON awfulhak> set	timeout	0

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

PREDICTOR-1 and	DEFLATE	COMPRESSION
     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 behaviour.

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

CONTROLLING IP ADDRESS
     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 ad-
     dress. When both sides of the connection agree to accept the received re-
     quest (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 0.0.0.0, and `netmask'	de-
     faults to whatever	mask is	appropriate for	`src_addr'.  It	is only	possi-
     ble to make `netmask' smaller than	the default.  The usual	value is
     255.255.255.255, as most kernels ignore the netmask of a POINTOPOINT in-
     terface.

     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 af-
     fect the routing table unless the other side agrees with this proposed
     number.

	   set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0

     The above specification means:

     +o	 I will	first suggest that my IP address should	be 0.0.0.0, but	I will
	 only accept an	address	of 192.244.177.38.
     +o	 I strongly insist that	the peer uses 192.244.177.2 as his own address
	 and won't permit the use of any IP address but	192.244.177.2.	When
	 the peer requests another IP address, I will always suggest that it
	 uses 192.244.177.2.
     +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 192.244.177.38/24	192.244.177.2/20

     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 192.244.177.38	as my address if it is possible, but
	 I'll also accept any IP address between 192.244.177.0 and
	 192.244.177.255.
     +o	 I'd like to make him use 192.244.177.2	as his own address, but	I'll
	 also permit him to use	any IP address between 192.244.176.0 and
	 192.244.191.255.
     +o	 As you	may have already noticed, 192.244.177.2	is equivalent to say-
	 ing 192.244.177.2/32.
     +o	 As an exception, 0 is equivalent to 0.0.0.0/0,	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	 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
	 try to	insist that 192.244.177.2 be used first.

CONNECTING WITH	YOUR INTERNET SERVICE PROVIDER
     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-
	  ple:

		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:

		set dial "ABORT	BUSY ABORT NO\\sCARRIER	TIMEOUT	4 \"\" \
		  ATZ OK-ATZ-OK	ATDT\\T	TIMEOUT	60 CONNECT"

	  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
	      10.0.0.2/0 (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.
	      10.0.0.1/0 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
	      1.2.3.0, you could specify 1.2.3.1/24.

	  +o   If you find that your ISP	accepts	the first IP number that you
	      suggest, specify third and forth arguments of "0.0.0.0".	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 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0

     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 (10.0.0.2 in this example).  This route is	`sticky', meaning that
	  should the value of HISADDR change, the route	will be	updated	ac-
	  cordingly.

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

	  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
	  line

		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
	  /etc/resolv.conf.

     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.

LOGGING	FACILITY
     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 `dial', `login' and	`hangup' chat script trace
		   logs.
	Command	   Log commands	executed either	from the command line or any
		   of the configuration	files.
	Connect	   Log Chat lines containing the string	"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	reports.
	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 syslogs
		   LOG_WARNING.
	Error	   Output to both the terminal device and the log file using
		   syslogs LOG_ERROR.
	Alert	   Output to the log file using	LOG_ALERT.

     The "set log" command allows you to set the logging output	level.	Multi-
     ple 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 warning, 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.

SIGNAL HANDLING
     Ppp deals with the	following signals:

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

     HUP, TERM & QUIT
	 These signals tell ppp	to exit.

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

MULTI-LINK PPP
     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, other-
     wise 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 exist-
     ing links,	where all characteristics are the same except:

     1.	  The new link has its own name	as specified on	the "clone" command
	  line.

     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" com-
     mand.

     Once a new	link has been created, command usage varies.  All link spe-
     cific commands must be prefixed with the "link name" command, specifying
     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" prefix.

     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:

	   mp:
	    set	timeout	0
	    set	log phase chat
	    set	device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
	    set	phone "123456789"
	    set	dial "ABORT BUSY ABORT NO\sCARRIER TIMEOUT 5 \"\" ATZ \
		      OK-AT-OK \\dATDT\\T TIMEOUT 45 CONNECT"
	    set	login
	    set	ifaddr 10.0.0.1/0 10.0.0.2/0
	    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
     configuration.

	     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 ne-
     gotiates multi-link mode, it will pass its	open link to any already run-
     ning process.  If there is	no already running process, ppp	will act as
     the master, creating the socket and listening for new connections.

PPP COMMAND LIST
     This section lists	the available commands and their effect.  They are us-
     able 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 re-
	 quested by us.	 "Disable" means that the option will not be requested
	 by us.

	 "Option" may be one of	the following:

	 acfcomp
	     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-
	     ible.

	 chap
	     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 au-
	     thenticator does the same,	and compares the results.  The advan-
	     tage 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 en-
	     crypting the challenge.  MS-CHAP is a combination of MD4 and DES.
	     If	ppp was	built on a machine with	DES libraries available, it
	     will respond to MS-CHAP authentication requests, but will never
	     request them.

	 deflate
	     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 ac-
	     tually 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.

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

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

	     If	"enabled," ppp will request that the peer confirms the entries
	     in	/etc/resolv.conf.  If the peer NAKs our	request	(suggesting
	     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 over-
	     ride.

	 lqr
	     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 ap-
	     propriate "reconnect" values are honoured as if the peer were re-
	     sponsible for dropping the	connection.

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

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

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

	 shortseq
	     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).

	 vjcomp
	     Default: Enabled and Accepted.  This option determines if Van Ja-
	     cobson header compression will be used.

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

	 idcheck
	     Default: Enabled.	When ppp exchanges low-level LCP, CCP and IPCP
	     configuration traffic, the	Identifier field of any	replies	is ex-
	     pected 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.

	 loopback
	     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 in-
	     terface is	also the default route as it avoids the	necessity of a
	     loopback route.

	 passwdauth
	     Default: Disabled.	 Enabling this option will tell	the PAP	au-
	     thentication 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.

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

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

	 sroutes
	     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-ap-
	     plied to the routing table.

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

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

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

	 iface-alias
	     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
	     `iface-alias'.

     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 consid-
	 ered `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 ap-
	 propriate 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 ac-
	 cess 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) fa-
	 cilities 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
	     gateway.

	 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
	     10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.

	 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 la-
		       bel may be specified on the ppp command line, via the
		       "load" or "dial"	commands and in	the ppp.secret file.

	 MYADDR	       This is replaced	with the IP number assigned to the lo-
		       cal interface.

	 PEER_ENDDISC  This is replaced	with the value of the peers endpoint
		       discriminator.

	 PROCESSID     This is replaced	with the current process id.

	 USER	       This is replaced	with the username that has been	au-
		       thenticated with	PAP or CHAP.  Normally,	this variable
		       is assigned only	in -direct mode.  This value is	avail-
		       able irrespective of whether utmp logging is enabled.

	 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" com-
	 mand 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
	 deleted.

	 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.	 In-
	     stead 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 previous
	     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 de-
	     faults to "255.255.255.255".  This	address	(the broadcast ad-
	     dress) 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 ad-
	     dress 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 as-
	     signed 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 configuration.

	 If the	"lcp" while the	LCP layer is already open, LCP will be renego-
	 tiated.  This allows various LCP options to be	changed, after which
	 "open lcp" can	be used	to put them into effect.  After	renegotiating
	 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 com-
	 mand file, ppp	will exit after	closing	all connections.  Otherwise,
	 if the	user is	connected to a diagnostic socket, the connection is
	 simply	dropped.

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

     remove|rm
	 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 re-
	 moved.

     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.

     save
	 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
	     negotiation.

	     If	used in	-direct	mode with PAP or CHAP enabled, id is used in
	     the initial authentication	request	and is normally	set to the lo-
	     cal 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 de-
	     fault 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	re-
	     quest 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
	     option.

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

	     auth    The callee	is expected to decide the callback number
		     based on authentication.  If ppp is the callee, the num-
		     ber 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 allow-
		     able 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 in-
		     ternational) number without first authenticating them-
		     selves.

	     none    If	the peer does not wish to do callback at all, ppp will
		     accept the	fact and continue without callback 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
	     default.

	 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 be-
	     tween 8 and 15.  If in-winsize is specified, ppp will insist that
	     this window size is used and will not accept any other values
	     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	de-
	     tails.  This command does not affect the IP numbers requested us-
	     ing "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 be-
	     gin with an exclamation mark ("!")	or be of the format
	     "host:port".

	     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
		   `send'
		   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"
		   below).

	       \P  This	is replaced by the current
		   authkey
		   value (see
		   "set	authkey"
		   above).

	       \U  This	is replaced by the current
		   authname
		   value (see
		   "set	authname"
		   above).

	     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 mo-
	     dem 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, oth-
	     erwise this parser	will see them as constituting an expect-send-
	     expect sequence.  When the	"!" character is seen, the execution
	     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 redirect	our
	     output to file descriptor 2 (stderr) so that ppp itself sends and
	     logs it, and in the second	example, we just output	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 us-
	     ing the LCP endpoint discriminator	option.	 The following dis-
	     criminators may be	set:

	       label
		   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
		   reset.

	       MAC
		   This	is similar to the
		   IP
		   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"
		   commands.

	       magic
		   A 20	digit random number is used.

	       psn value
		   The given
		   value
		   is used.
		   Value
		   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 al-
	     lows the user to specify a	set of characters that will be `es-
	     caped' 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 40 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 mo-
	     dem 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

		   a.b.c.d/n

	     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 0.0.0.0 in	which case it defaults
	     to	/0.

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

		   a.b.c.d[-d.e.f.g][,h.i.j.k[-l,m,n,o]]...

	     for example:

		   set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20

	     will only negotiate 10.0.0.1 as the local IP number, but may as-
	     sign any of the given 10 IP numbers to the	peer.  If the peer re-
	     quests 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-
	     tions).

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

	     It	should be noted	that in	-auto mode, ppp	will configure the in-
	     terface 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
	     AUTHENTICATING INCOMING CONNECTIONS section for details.

	     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 be-
	     fore 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.  Re-
	     fer 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
	     here.

	 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
	     `dedicated'.

	     Note: If you issue	the command "set mode auto", and have IP
	     aliasing enabled, it may be useful	to "enable iface-alias"	after-
	     wards.  This will allow ppp to do the necessary address transla-
	     tions to enable the process that triggers the connection to con-
	     nect once the link	is up despite the peer assigning us a new (dy-
	     namic) 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 in-
	     creased, 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
	     data).

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

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

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

	 set [proc]title [value]
	     The current process title as displayed by ps(1) is	changed	ac-
	     cording 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.

	     Note, if USER is required in the process title, the "set
	     proctitle"	command	must appear in ppp.linkup, as it is not	known
	     when the commands in ppp.conf are executed.

	 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 re-
	     sult 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 immedi-
	     ately follow the "open" keyword.  See the "open" description
	     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 fu-
	     ture, 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 (Fi-
	     nite 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 de-
	     spite our sending a terminate acknowledgement.  This is also use-
	     ful 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 transi-
	     tions.

	     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 ex-
	 ited.	Use the	bg command if you wish processing to happen in the
	 background.

     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").

	 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.

     term
	 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
	 mode.

MORE DETAILS
     +o	 Read the example configuration	files.	They are a good	source of in-
	 formation.

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

     +o	 The following urls contain useful information:
	 +o   http://www.FreeBSD.org/FAQ/userppp.html
	 +o   http://www.FreeBSD.org/handbook/userppp.html

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

     /etc/ppp/ppp.conf
	 System	default	configuration file.

     /etc/ppp/ppp.secret
	 An authorisation file for each	system.

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

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

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

     /var/spool/lock/LCK..*
	 tty port locking file.	 Refer to uucplock(3) for further details.

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

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

     /etc/services
	 Get port number if port number	is using service name.

     /var/run/ppp-authname-class-value
	 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.

SEE ALSO
     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)

HISTORY
     This program was originally written by Toshiharu OHNO (tony-o@iij.ad.jp),
     and was submitted to FreeBSD-2.0.5	by Atsushi Murai (amurai@spec.co.jp).

     It	was substantially modified during 1997 by Brian	Somers (brian@Awful-
     hak.org), 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

NAME | SYNOPSIS | DESCRIPTION | Major Features | PERMISSIONS | GETTING STARTED | MANUAL DIALING | AUTOMATIC DIALING | BACKGROUND DIALING | DIAL ON DEMAND | RECEIVING INCOMING PPP CONNECTIONS (Method 1) | RECEIVING INCOMING PPP CONNECTIONS (Method 2) | AUTHENTICATING INCOMING CONNECTIONS | PPP OVER TCP (a.k.a Tunnelling) | PACKET ALIASING | PACKET FILTERING | SETTING THE IDLE TIMER | PREDICTOR-1 and DEFLATE COMPRESSION | CONTROLLING IP ADDRESS | CONNECTING WITH YOUR INTERNET SERVICE PROVIDER | LOGGING FACILITY | SIGNAL HANDLING | MULTI-LINK PPP | PPP COMMAND LIST | MORE DETAILS | FILES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ppp&manpath=FreeBSD+3.1-RELEASE>

home | help