unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



pppd(8)								      pppd(8)



NAME

  pppd - Point-to-Point	Protocol (PPP) daemon

SYNOPSIS

  /usr/sbin/pppd [tty_name] [speed] [options]

FREQUENTLY USED	OPTIONS

  tty_name
      Communicates over	the named device.  The string /dev/ is prepended if
      necessary.  If no	device name is given or	if the name of the control-
      ling terminal is given, pppd uses	the controlling	terminal, and does
      not fork to put itself in	the background.	 This option is	privileged if
      you specify the noauth option.

  speed
      Sets the baud rate to speed.

  asyncmap map
      Sets the async character map to map.  This map describes those control
      characters that cannot be	successfully received over the serial line.
      The pppd daemon asks the peer to send these characters as	a 2-byte
      escape sequence. The argument is a 32-bit	hexadecimal number with	each
      bit representing a character to escape. Bit 0 (00000001) represents the
      character	0x00; bit 31 (80000000)	represents the character 0x1f or ^_.
      If multiple asyncmap options are given, the values are ORed together.
      If no asyncmap option is given, no async character map is	negotiated
      for the receive direction; the peer then escapes all control charac-
      ters.  To	escape transmitted characters, use the escape option.

  auth
      Requires the peer	to authenticate	itself before allowing network pack-
      ets to be	sent or	received.

  call name
      Reads options from the /etc/ppp/peers/name file.	This file may contain
      privileged options, such as noauth, even if pppd is not being run	by
      root.  The name string may not begin with	a slash	(/) or include two
      dots (..)	as a pathname component.  See the Options File section for a
      description of the format.

  connect p
      Uses the executable or shell command specified by	p to set up the
      serial line.  This script	would typically	use the	chat program to	dial
      the modem	and start the remote PPP session.  This	option is privileged
      if you specify the noauth	option.

  crtscts
      Uses hardware flow control (RTS/CTS) to control the flow of data on the
      serial port.  If neither crtscts nor nocrtscts is	specified, the
      hardware flow control setting for	the serial port	is not changed.

  -crtscts
      Disables hardware	flow control (RTS/CTS) on the serial port.  If nei-
      ther the crtscts nor the -crtscts	option is given, the hardware flow
      control setting for the serial port is not changed.

  -crtscts
      Same as nocrtscts, but its use is	deprecated.

  defaultroute
      Adds a default route to the system routing tables, using the peer	as
      the gateway, when	IPCP negotiation is successfully completed. This
      entry is removed when the	PPP connection is broken.  This	option is
      privileged if you	specify	the nodefaultroute option.  This option	is
      for IPv4 only.

  disconnect p
      Runs the executable or shell command specified by	p after	pppd has ter-
      minated the link.	 This script could, for	example, issue commands	to
      the modem	to cause it to hang up if hardware modem control signals were
      not available.

  escape xx,yy,...
      Specifies	that certain characters	should be escaped on transmission
      (regardless of whether the peer requests them to be escaped with its
      async control character map).  The characters to be escaped are speci-
      fied as a	list of	hexadecimal numbers separated by commas.  Note that
      almost any character can be specified for	the escape option, unlike the
      asyncmap option which only allows	control	characters to be specified.
      The characters which may not be escaped are those	with hex values	0x20
      -	0x3f or	0x5e.

  file f
      Reads options from file f.  See the Options Files	section	for a
      description of the format.

  lock
      Specifies	that pppd should use a UUCP-style lock on the serial device
      to ensure	exclusive access to the	device.

  mru n
      Sets the MRU (Maximum Receive Unit) value	to n for negotiation.  The
      pppd daemon will ask the peer to send packets of no more than n bytes.
      The minimum MRU value is 128 for IPv4 and	1298 for IPv6.	The default
      MRU value	is 1500.  A value of 296 is recommended	for slow, IPv4 links
      (40 bytes	for TCP/IP header + 256	bytes of data).

  netmask n
      Sets the interface netmask to n, a 32-bit	netmask	in dotted-decimal
      notation (for example, 255.255.255.0).  If specified, the	value is ORed
      with the default netmask.	 The default netmask is	based on the nego-
      tiated remote IPv4 address, appropriate for the class of remote IPv4
      address and ORed with netmasks for other network interfaces (not
      point-to-point) that are on the same network.  This flag is for IPv4
      only.  If	specified for IPv6, it is ignored.

  nocrtscts
      Disables hardware	flow control (RTS/CTS) on the serial port.  If nei-
      ther the crtscts nor the nocrtscts option	is given, the hardware flow
      control setting for the serial port is not changed.

  passive
      Enables the "passive" option in the LCP.	With this option, pppd
      attempts to initiate a connection; if no reply is	received from the
      peer, pppd waits for a valid LCP packet from the peer (instead of	exit-
      ing, as it does without this option).

  silent
      With this	option,	pppd does not transmit LCP packets to initiate a con-
      nection until a valid LCP	packet is received from	the peer (as for the
      "passive"	option with old	versions of pppd).


DESCRIPTION

  The Point-to-Point Protocol (PPP) provides a method for transmitting
  datagrams over serial	point-to-point links.  PPP is composed of three
  parts: a method for encapsulating datagrams over serial links, an extensi-
  ble Link Control Protocol (LCP), and a family	of Network Control Protocols
  (NCP)	for establishing and configuring different network-layer protocols.

  The encapsulation scheme is provided by driver code in the kernel. The pppd
  daemon provides the basic LCP, authentication	support, and NCPs for estab-
  lishing and configuring the Internet Protocol	Version	4 (IPv4) (called the
  IP Control Protocol, IPCP) and the Internet Protocol Version 6 (IPv6)
  (called the IP6 Control Protocol, IP6CP).

  OPTIONS


  local_IP_address:remote_IP_address
      Sets the local or	remote interface IPv4 addresses, or both.  Either one
      may be omitted.  The IPv4	addresses can be specified with	a host name
      or in decimal dot	notation (for example, 150.234.56.78).	The default
      local address is the (first) IPv4	address	of the system (unless the
      noipdefault option is given).  The remote	address	is obtained from the
      peer if not specified in any option.  Thus, in simple cases, this
      option is	not required. If a local or remote IPv4	address	is specified
      with this	option,	pppd will not accept a different value from the	peer
      in the IPCP negotiation, unless the ipcp-accept-local or ipcp-accept-
      remote options are given,	respectively.

  -all
      Does not request or allow	negotiation of any options for LCP and IPCP
      (use default values).  IP6CP negotiation is not affected by this flag.

  -ac Same as noaccomp,	but its	use is deprecated.

  -am Same as default-asyncmap,	but its	use is deprecated.

  -as <n>
      Same as asyncmap n, but its use is deprecated.

  bsdcomp nr,nt
      Requests the peer	to compress all	packets	that it	sends, using the
      BSD-Compress scheme, with	a maximum code size of nr bits,	and agrees to
      compress all packets sent	to the peer with a maximum code	size of	nt
      bits.  If	nt is not specified, it	defaults to the	value given for	nr.
      Values in	the range 9 to 15 may be used for nr and nt; larger values
      give better compression but consume more kernel memory for compression
      dictionaries. Alternatively, a value of 0	for nr or nt disables
      compression in the corresponding direction.

  -bsdcomp
      Same as nobsdcomp, but its use is	deprecated.

  +chap
      Same as require-chap, but	its use	is deprecated.

  -chap
      Same as refuse-chap, but its use is deprecated.

  chap-interval	n
      If this option is	given, pppd challenges the peer	every n	seconds.

  chap-max-challenge n
      Sets the maximum number of CHAP challenge	transmissions to n (default
      10).

  chap-restart n
      Sets the CHAP restart interval (retransmission timeout for challenges)
      to n seconds (default 3).

  -d  Same as debug, but its use is deprecated.

  debug
      Enables connection debugging facilities.	If this	option is given, pppd
      will log the contents of all control packets sent	or received in a
      readable form.  The packets are logged through syslog with facility
      local2 and level debug.  This information	can be directed	to a file by
      setting up /etc/syslog.conf appropriately	(see syslog.conf(4)).

  default-asyncmap
      Disables asyncmap	negotiation (use the default asyncmap, that is,
      escape all control characters for	both the transmit and receive direc-
      tions).

  default-mru
      Disables MRU (Maximum Receive Unit) negotiation.	The pppd daemon	uses
      the default, that	is, 1500 bytes for both	the transmit and receive
      directions.

  deflatenr,nt
      Requests that the	peer compress packets that it sends, using the
      Deflate scheme, with a maximum window size of 2**nr bytes, and agree to
      compress packets sent to the peer	with a maximum window size of 2**nt
      bytes.  If nt is not specified, it defaults to the value given for nr.
      Values in	the range 9 to 15 may be used for nr and nt; larger values
      give better compression but consume more kernel memory for compression
      dictionaries.  Alternatively, a value of 0 for nr	or nt disables
      compression in the corresponding direction.  Use nodeflate or deflate 0
      to disable Deflate compression entirely. (Note: pppd requests Deflate
      compression in preference	to BSD-Compress	if the peer can	do either.)

  demand
      Initiates	the link only when IPv4	data traffic is	present	(on demand).
      With this	option,	the remote IPv4	address	must be	specified by the user
      on the command line or in	an options file.  The pppd daemon initially
      configures the interface and enables it for IPv4 traffic without con-
      necting to the peer.  When traffic is available, pppd connects to	the
      peer and performs	negotiation, authentication, and other operations.
      When this	is completed, pppd begins passing data packets (IPv4 packets)
      across the link.

      The demand option	implies	the persist option.  If	this behavior is not
      desired, use the nopersist option	after the demand option.  The idle
      and holdoff options are also useful in conjunction with the demand
      option.

  -detach
      Same as nodetach,	but its	use is deprecated.

  domain d
      Appends the domain name d	to the local host name for authentication
      purposes.	 For example, if gethostname() returns the name	porsche, but
      the fully	qualified domain name is porsche.Quotron.COM, you would	use
      the domain option	to set the domain name to Quotron.COM.

  holdoff n
      Specifies	the amount of time (in seconds)	to wait	before re-initiating
      the link after it	terminates.  This option only has any effect if	you
      specify either the persist or demand option.  The	holdoff	period is not
      applied if the link was terminated because it was	idle.

  idle n
      Specifies	that pppd should disconnect if the link	is idle	for n
      seconds.	The link is idle when no data packets (IPv4 packets) are
      being sent or received.  Note: If	you use	this option with the persist
      option, you must also specify the	demand option. If you specify the
      active-filter option, data packets that are rejected by the specified
      activity filter also count as the	link being idle.

  -ip Same as noip, but	its use	is deprecated.

  ipcp-accept-local
      With this	option,	pppd accepts the peer's	idea of	our local IPv4
      address, even if the local IPv4 address was specified in an option.

  ipcp-accept-remote
      With this	option,	pppd accepts the peer's	idea of	its (remote) IPv4
      address, even if the remote IPv4 address was specified in	an option.

  ipcp-max-configure n
      Sets the maximum number of IPCP configure-request	transmissions to n
      (default 10).

  ipcp-max-failure n
      Sets the maximum number of IPCP configure-NAKs returned before starting
      to send configure-Rejects	instead	to n (default 10).

  ipcp-max-terminate n
      Sets the maximum number of IPCP terminate-request	transmissions to n
      (default 3).

  ipcp-restart n
      Sets the IPCP restart interval (retransmission timeout) to n seconds
      (default 3).

  ipparam string
      Specifies	a character string that	you can	pass as	the sixth parameter
      to the ip-up, ip-down, ip6-up, and ip6-down scripts.

  ip6cp-interface-id l:r
      Sets the tentative local (l) interface identifier	to use in the IP6CP
      configure-request.  If the interface identifier requested	by the peer
      is the same as the interface identifier sent in the configure-request
      by pppd, a CONFNAK message is sent to the	peer with a suggested inter-
      face identifier, r.

      Both l and r are 64-bit numbers that may be: decimal, octal (must	have
      a	leading	0), or hexadecimal (must have leading 0x).

  kdebug n
      Enables debugging	code in	the kernel-level PPP driver.  The argument n
      is a number that is the sum of the following values: 1 (enables general
      debug messages), 2 (requests that	the contents of	received packets be
      printed),	and 4 (requests	that the contents of transmitted packets be
      printed).

  lcp-echo-failure n
      If this option is	given, pppd presumes the peer to be dead if n LCP
      echo-requests are	sent without receiving a valid LCP echo-reply.	If
      this happens, pppd terminates the	connection.  Use of this option
      requires a non-zero value	for the	lcp-echo-interval parameter.  This
      option can be used to enable pppd	to terminate after the physical	con-
      nection has been broken (for example, the	modem has hung up) in situa-
      tions where no hardware modem control lines are available.

  lcp-echo-interval n
      If this option is	given, pppd sends an LCP echo-request frame to the
      peer every n seconds.

      Under Linux, the echo-request is sent when no packets have been
      received from the	peer for n seconds.  Normally the peer should respond
      to the echo-request by sending an	echo-reply.  This option can be	used
      with the lcp-echo-failure	option to detect that the peer is no longer
      connected.

  lcp-max-configure n
      Sets the maximum number of LCP configure-request transmissions to	n
      (default 10).

  lcp-max-failure n
      Sets the maximum number of LCP configure-NAKs returned before starting
      to send configure-Rejects	instead	to n (default 10).

  lcp-max-terminate n
      Sets the maximum number of LCP terminate-request transmissions to	n
      (default 3).

  lcp-restart n
      Sets the LCP restart interval (retransmission timeout) to	n seconds
      (default 3).

  local
      Does not use the modem control lines.  With this option, pppd ignores
      the state	of the CD (Carrier Detect) signal from the modem and does not
      change the state of the DTR (Data	Terminal Ready)	signal.

  login
      Uses the system password database	for authenticating the peer using
      PAP.

  maxconnect n
      Terminates the connection	after it has been available for	network
      traffic for n seconds (n seconds after the first network control proto-
      col comes	up).

  -mn Same as nomagic, but its use is deprecated.

  modem
      Uses the modem control lines.  This option is the	default.  With this
      option, pppd waits for the CD (Carrier Detect) signal from the modem to
      be asserted when opening the serial device (unless a connect script is
      specified), and it drops the DTR (Data Terminal Ready) signal briefly
      when the connection is terminated	and before executing the connect
      script.

  -mru
      Same as default-mru, but its use is deprecated.

  ms-dns addr
      If pppd is acting	as a server for	Microsoft Windows clients, this
      option allows pppd to supply one or two DNS (Domain Name Server)
      addresses	to the clients.	 The first instance of this option specifies
      the primary DNS address; the second instance (if given) specifies	the
      secondary	DNS address.  (This option was present in some older versions
      of pppd under the	name dns-addr.)

  ms-wins addr
      If pppd is acting	as a server for	Microsoft Windows or "Samba" clients,
      this option allows pppd to supply	one or two WINS	(Windows Internet
      Name Services) server addresses to the clients.  The first instance of
      this option specifies the	primary	WINS address; the second instance (if
      given) specifies the secondary WINS address.

  mtu n
      Sets the MTU (Maximum Transmit Unit) value to n.	Unless the peer
      requests a smaller value using MRU negotiation, pppd will	request	that
      the kernel networking code send data packets of no more than n bytes
      through the PPP network interface.

  name name
      Sets the name of the local system	for authentication purposes to name.
      This is a	privileged option.  If specified, pppd will search for name
      in the second field in the secrets files and will	use that secret	to
      authenticate the peer.  Unless overridden	with the user option, name
      will be sent to the peer when authenticating the local system to the
      peer.  The pppd command does not append the domain name to name.

  noaccomp
      Disables Address/Control compression in both directions (send and
      receive).

  noauth
      Does not require the peer	to authenticate	itself.	 This option is
      privileged if the	auth option is specified in the	/etc/ppp/options
      file.

  nobsdcomp
      Disables BSD-Compress compression; pppd will not request or agree	to
      compress packets using the BSD-Compress scheme.

  noccp
      Disables CCP (Compression	Control	Protocol) negotiation.	Use this
      option only if the peer is unreliable and	gets confused by requests
      from pppd	for CCP	negotiation.

  nodefaultroute
      Disables the defaultroute	option.	 If you	want to	prevent	users from
      creating default routes with pppd, include this option in	the
      /etc/ppp/options file.  This flag	is for IPv4 only.

  nodeflate
      Disables Deflate compression; pppd will not request or agree to
      compress packets using the Deflate scheme.

  nodetach
      Does not detach from the controlling terminal.  If you do	not specify
      this option, if a	serial device other than the terminal on the standard
      input is specified, pppd will fork to become a background	process.

  noip
      Disables IPv4.  The IPCP protocol	parameters are not negotiated on the
      interface.  Use this option if you want to disable IPv4 over PPP.

  noip6
      Disables IPv6.  The IP6CP	protocol parameters are	not negotiated on the
      interface.  Use this option if you want to disable IPv6 over PPP.

  noipdefault
      Disables the default behavior when no local IPv4 address is specified,
      which is to determine (if	possible) the local IPv4 address from the
      hostname.	 With this option, the peer must supply	the local IPv4
      address during IPCP negotiation, unless it is specified explicitly on
      the command line or in an	options	file.

  nomagic
      Disables magic number negotiation.  With this option, pppd cannot
      detect a looped-back line.  Use this option only with unreliable peers.

  nopcomp
      Disables protocol	field compression negotiation in both the receive and
      transmit direction.

  nopersist
      Exits once a connection has been made and	terminated.  This is the
      default unless you specify the persist or	demand option.

  nopredictor1
      Does not accept or agree to Predictor-1 compression.

  noproxyarp
      Disables the proxyarp option.  If	you want to prevent users from creat-
      ing proxy	ARP entries with pppd, put this	option in the <filename>
      /etc/ppp/options</filename> file.

  novj
      Disables Van Jacobson-style IPv4 header compression in both the
      transmit and receive directions.

      Van Jacobson compression is not supported	for this implementation	of
      IPv6 over	PPP.

  novjcomp
      Disables connection-ID compression option	in the Van Jacobson-style
      header compression.  If you specify this option, pppd will neither omit
      the connection-ID	byte from Van Jacobson compressed TCP/IP headers nor
      ask the peer to do so.

  -p  Same as the passive option, but its use is deprecated.

  +pap
      Same as the require-pap option, but its use is deprecated.

  -pap
      Same as the refuse-pap option, but its use is deprecated.

  papcrypt
      Indicates	that all secrets in the	/etc/ppp/pap-secrets file used for
      checking the identity of the peer	are encrypted.	The pppd daemon
      should not accept	a password that	(before	encryption) is identical to
      the secret from the /etc/ppp/pap-secrets file.

  pap-max-authreq n
      Sets the maximum number of PAP authenticate-request transmissions	to n
      (default 10).

  pap-restart n
      Sets the PAP restart interval (retransmission timeout) to	n seconds
      (default 3).

  pap-timeout n
      Sets the maximum time that pppd will wait	for the	peer to	authenticate
      itself with PAP to n seconds (0 means no limit).

  -pc Same as the nopcomp option, but its use is deprecated.

  persist
      Do not exit after	a connection is	terminated.  Instead, try to reopen
      the connection.

  predictor1
      Requests that the	peer compress frames that it sends using Predictor-1
      compression and agrees to	compress transmitted frames with Predictor-1,
      if requested.  This option has no	effect unless the kernel driver	sup-
      ports Predictor-1	compression.

  proxyarp
      Adds an entry to this system's ARP (Address Resolution Protocol) table
      with the IPv4 address of the peer	and the	Ethernet address of this sys-
      tem.  The	peer will appear to other systems on the local Ethernet	as
      though it	is physically connected	the the	local Ethernet.

  refuse-chap
      Does not agree to	authenticate to	the peer using CHAP.

  refuse-pap
      Does not agree to	authenticate to	the peer using PAP.

  remotename n
      Sets the assumed name of the remote system for authentication purposes
      to n.

  require-chap
      Requires the peer	to authenticate	itself using CHAP (Challenge
      Handshake	Authentication Protocol) authentication.

  require-pap
      Requires the peer	to authenticate	itself using PAP.

  silent
      With this	option,	pppd will not transmit LCP packets to initiate a con-
      nection until a valid LCP	packet is received from	the peer (as with the
      passive option with older	versions of pppd).

  +ua p
      Agrees to	authenticate using PAP (Password Authentication	Protocol) if
      requested	by the peer, and use the data in file p	for the	user and
      password to send to the peer. The	file contains the remote user name,
      followed by a newline, followed by the remote password, followed by a
      newline.	This option is obsolete.

  usehostname
      Enforces the use of the hostname as the name of the local	system for
      authentication purposes (overrides the name option).

  user u
      Sets the user name to use	for authenticating this	machine	with the peer
      using PAP	to u.

  -vj Same as the novj option, but its use is deprecated.

  vj-max-slots n
      Sets the number of connection slots to be	used by	the Van	Jacobson
      TCP/IP header compression	and decompression code to n, which must	be
      between 2	and 16 (inclusive).

  welcome script
      Runs the executable or shell command specified by	script before ini-
      tiating PPP negotiation, after the connect script	(if any) has com-
      pleted.  This option is privileged if you	specify	the noauth option.

  xonxoff
      Uses software flow control (XON/XOFF) to control the flow	of data	on
      the serial port.



  Options Files


  Options can be taken from files as well as the command line. The pppd	dae-
  mon reads options from the files /etc/ppp/options, ~/.ppprc, and
  /etc/ppp/options.ttyname, in this order,before looking at the	command	line.
  However, the command-line options are	scanned	to determine the terminal
  name before reading the options.ttyname file.	 In forming the	name of	the
  options.ttyname file,	the initial /dev/ prefix is removed and	any remaining
  slash	characters (/) are replaced with dots.

  An options file is parsed into a series of words, delimited by whitespace.
  Whitespace can be included in	a word by enclosing the	word in	double quota-
  tion marks (").  A backslash (\) quotes any character	that follows it. A
  hash mark (#)	starts a comment, which	continues until	the end	of the line.
  There	are no restrictions on using the file option or	call option within an
  options file.

  Security


  The pppd daemon provides system administrators with sufficient access	con-
  trol so that legitimate users	can have PPP access to a server	machine
  without fear of compromising the security of the server or the network.  In
  part this is provided	by the /etc/ppp/options	file, into which the adminis-
  trator can place options to require authentication whenever pppd is run,
  and in part by the PAP and CHAP secrets files, into which the	administrator
  can restrict the set of IPv4 addresses that individual users may use.

  You should set up pppd by placing the	auth option in the /etc/ppp/options
  file.	 If users want to use pppd to dial out to a peer that will refuse to
  authenticate itself (such as an Internet service provider), the system
  administrator	should create an options file under /etc/ppp/peers containing
  the noauth option, the name of the serial port to use, and the connect
  option (if required),	plus any other appropriate options.  In	this way,
  pppd can be set up to	allow non-privileged users to make unauthenticated
  connections only to trusted peers.

  As indicated previously, some	security-sensitive options are privileged.
  This means that they may not be used by an ordinary non-privileged user
  running a setuid-root	pppd, either on	the command line, in the user's
  ~/.ppprc file, or in an options file read using the file option.
  Privileged options may be used in /etc/ppp/options file or in	an options
  file read using the call option.  If pppd is being run by the	root user,
  privileged options can be used without restriction.

  Authentication


  Authentication is the	process	whereby	one peer convinces the other of	its
  identity.  This involves the first peer (the client) sending its name	to
  the other (the server), together with	some kind of secret information	that
  could	only come from the genuine authorized user of that name.  The client
  has a	name by	which it identifies itself to the server, and the server also
  has a	name by	which it identifies itself to the client.  Generally, the
  genuine client shares	some secret (or	password) with the server, and
  authenticates	itself by proving that it knows	that secret.  Very often the
  names	used for authentication	correspond to the Internet hostnames of	the
  peers, but this is not essential.

  At present, pppd supports two	authentication protocols: the Password
  Authentication Protocol (PAP)	and the	Challenge Handshake Authentication
  Protocol (CHAP).  PAP	involves the client sending its	name and a cleartext
  password to the server to authenticate itself. In contrast, the server ini-
  tiates the CHAP authentication exchange by sending a challenge to the
  client (the challenge	packet includes	the server's name).  The client	must
  respond with a response that includes	its name plus a	hash value derived
  from the shared secret and the challenge, in order to	prove that it knows
  the secret.


  The PPP protocol is symmetrical.  It allows both peers to require the	other
  to authenticate itself.  That	way, two separate and independent authentica-
  tion exchanges will occur.  The two exchanges	could use different authenti-
  cation protocols, and	in principle, could use	different names	in the two
  exchanges.

  The default behavior of pppd is to agree to authenticate if requested, and
  to not require authentication	from the peer.	However, pppd will not agree
  to authenticate itself with a	particular protocol if it has no secrets for
  that protocol.

  The pppd daemon stores secrets for use in authentication in secrets files
  (/etc/ppp/pap-secrets	for PAP	and /etc/ppp/chap-secrets for CHAP).  Both
  secrets files	have the same format.  The secrets files can contain secrets
  for pppd to use in authenticating itself to other systems, as	well as
  secrets for pppd to use when authenticating other systems to itself.

  Each line in a secrets file contains one secret.  A given secret is
  specific to a	particular combination of client and server - it can only be
  used by that client to authenticate itself to	that server.  Each line	con-
  tains	at least 3 words, in the following order:

       client  server  secret

  If any words follow the secret on the	same line, they	are the	IPv4
  addresses that the specified client may use when connecting to the speci-
  fied server.

  If there are only 3 words on the line	or if the first	word is	a dash (-),
  all IPv4 addresses are disallowed.  To allow any address, use	an asterisk
  (*). If a word starts	with an	exclamation point (!), the specified address
  is not acceptable.  An address may be	followed by a slash (/)	and a number
  n, to	indicate a whole subnet	(all addresses that have the same value	in
  the most significant n bits).	 Note that case	is significant in the client
  and server names and in the secret.

  If the secret	starts with an at sign (@), anything following it is assumed
  to be	the name of a file from	which to read the secret.  An asterisk (*) as
  the client or	server name matches any	name.  When selecting a	secret,	pppd
  takes	the best match (the match with the fewest wildcards).

				     Note

       The use of IPv6 addresses in a secrets file is not supported.

  A secrets file contains secrets for use in authenticating other hosts	and
  secrets that we use for authenticating ourselves to others.  When pppd is
  authenticating the peer (checking the	peer's identity), it chooses a secret
  with the peer's name in the first field and the name of the local system in
  the second field.  The name of the local system defaults to the hostname
  with the domain name appended, if the	domain option is used.	This default
  can be overridden with the name option, except when the usehostname option
  is used.

  When pppd is choosing	a secret to use	in authenticating itself to the	peer,
  it first determines what name	it is going to use to identify itself to the
  peer.	 This name can be specified by the user	with the user option.  If
  this option is not used, the name defaults to	the name of the	local system,
  determined as	described in the previous paragraph.  Then, pppd looks for a
  secret with this name	in the first field and the peer's name in the second
  field.  The daemon will know the name	of the peer if CHAP authentication is
  being	used because the peer will have	sent it	in the challenge packet.
  However, if PAP is being used, pppd will have	to determine the peer's	name
  from the options specified by	the user.  The user can	specify	the peer's
  name directly	with the remotename option.  Otherwise,	if the remote IP
  address was specified	by a name (rather than in numeric form), that name
  will be used as the peer's name.  Failing that, pppd will use	the null
  string as the	peer's name.

  When authenticating ourselves	using PAP,  the	supplied password is first
  compared with	the secret from	the secrets file.  If the password does	not
  match	the secret, the	password is encrypted using crypt and checked against
  the secret again.  Therefore,	secrets	for authenticating the peer can	be
  stored in encrypted form.  If	the papcrypt option is given, the first
  (unencrypted)	comparison is omitted for better security.

  If the login option was specified, the user name and password	are also
  checked against the system password database.	 Thus, the system administra-
  tor can set up the<filename> pap-secrets</filename> file to allow PPP
  access only to certain users and to restrict the set of IPv4 addresses that
  each user can	use. Typically,	when using the login option, the secret	in
  /etc/ppp/pap-secrets would be	"", to avoid the need to have the same secret
  in two places.

  Authentication must be satisfactorily	completed before IPCP (or any other
  Network Control Protocol) can	be started.  If	authentication fails, pppd
  terminates the link (by closing LCP).	 If IPCP negotiates an unacceptable
  IPv4 address for the remote host, IPCP closes.  IPv4 packets can only	be
  sent or received when	IPCP is	open.

  In some cases, you might want	to allow some hosts that cannot	authenticate
  themselves to	connect	and use	one of a restricted set	of IPv4	addresses,
  even when the	local host generally requires authentication.  If the peer
  refuses to authenticate itself when requested, pppd takes that as
  equivalent to	authenticating with PAP	using the empty	string for the user-
  name and password.  Thus, by adding a	line to	the pap-secrets	file that
  specifies the	empty string for the client and	password, it is	possible to
  allow	restricted access to hosts that	refuse to authenticate themselves.

  IPv4 Routing


  When IPCP negotiation	is completed successfully, pppd	will inform the	ker-
  nel of the local and remote IPv4 addresses for the ppp interface.  This is
  sufficient to	create a host route to the remote end of the link, which will
  enable the peers to exchange IPv4 packets.  Communication with other
  machines generally requires further modification to routing tables or	ARP
  (Address Resolution Protocol)	tables.	 In some cases this will be done
  automatically	through	the actions of the gated or routed daemons, but	in
  most cases some further intervention is required.  Use the /etc/ppp/ip-up
  script for any manual	IPv4 routing changes.

  Sometimes it is desirable to add a default route through the remote host,
  as in	the case of a machine whose only connection to the Internet is
  through the PPP interface.  The defaultroute option causes pppd to create
  such a default route when IPCP comes up, and delete it when the link is
  terminated.

  In some cases	it is desirable	to use proxy ARP, for example on a server
  machine connected to a LAN, in order to allow	other hosts to communicate
  with the remote host.	 The proxyarp option causes pppd to look for a net-
  work interface on the	same subnet as the remote host (an interface support-
  ing broadcast	and ARP, which is up and not a point-to-point or loopback
  interface).  If found, pppd creates a	permanent, published ARP entry with
  the IPv4 address of the remote host and the hardware address of the network
  interface found.

  When the demand option is used, the interface	IPv4 addresses have already
  been set at the point	when IPCP comes	up.  If	pppd has not been able to
  negotiate the	same addresses that it used to configure the interface (for
  example when the peer	is an ISP that uses dynamic IP address assignment),
  pppd has to change the interface IPv4	addresses to the negotiated
  addresses.  This may disrupt existing	connections, and the use of demand
  dialing with peers that do dynamic IPv4 address assignment is	not recom-
  mended.

  IPv6 Routing


  When IP6CP negotiation is completed successfully, IPv6 initialization	of
  the ppp interface adds routes	to the link-local unicast (fe80::/10) and the
  multicast (ff02::/10)	prefixes through the interface.

  If the system	is running as router and the ppp interface is specified	in
  the ip6rtrd configuration file, the system sends router advertisements to
  the remote host (peer) over the PPP link and activates RIPng for the PPP
  link,	depending on the options specified for the ppp interface in the
  ip6rtrd configuration	file.

  If the system	is running as a	host, IPv6 initialization adds a default
  route	to the link.  Unless other routes are specified, all destinations are
  considered to	be on link. (See the Neighbor Discovery	specification, RFC
  2461.)  The nd6hostd daemon sends router solicitations on the	PPP link.  If
  the remote system is a router, nd6hostd parses the router advertisements
  that it receives and configures default routes to the	router.

NOTES

  The following	signals	have the specified effect when sent to the pppd	pro-
  cess:

  SIGINT, SIGTERM
      Cause pppd to terminate the link (by closing LCP), restore the serial
      device settings, and exit.

  SIGHUP
      This signal causes pppd to terminate the link, restore the serial	dev-
      ice settings, and	close the serial device.  If the persist option	has
      been specified, pppd tries to reopen the serial device and start
      another connection.  Otherwise, pppd exits.

  SIGUSR1
      Toggles the state	of the debug option.

  SIGUSR2
      Causes pppd to renegotiate compression.  This can	be useful to re-
      enable compression after it has been disabled as a result	of a fatal
      decompression error.  With the BSD Compress scheme, fatal	decompression
      errors generally indicate	a severe implementation	error.

DIAGNOSTICS

  Messages are sent to the syslogd daemon using	facility LOG_LOCAL2.  To see
  the error and	debug messages,	edit your /etc/syslog.conf file	to direct the
  messages to the desired output device	or file.

  The debug option causes the contents of all control packets sent or
  received to be logged, that is, all LCP, PAP,	CHAP, or IPCP packets. This
  is useful if the PPP negotiation does	not succeed.  If debugging is enabled
  at compile time, the debug option causes additional debugging	messages to
  be logged.

  Debugging can	also be	toggled	on and off by sending a	SIGUSR1	to the pppd
  process.





EXAMPLES

  Examples 4 and 5 assume that the /etc/ppp/options file contains the auth
  option.

   1.  If you want to connect the serial ports of two machines and there is
       no getty	daemon running on the serial ports, issue a command similar
       to the following	on each	machine:
	    pppd /dev/ttya 9600	passive

   2.  If you want to connect the serial ports of two machines and one
       machine has a getty daemon running, you can log in to that machine
       from the	other machine using the	kermit or the tip command, and issue
       the following command:
	    pppd passive

       Then, exit from the communications program (making sure the connection
       is not dropped),	and issue a command similar to the following:
	    pppd /dev/ttya 9600

   3.  You can automate	the process of logging in to another machine and
       starting	pppd by	using the connect option to run	the chat command. For
       example:
	    pppd /dev/ttya 38400 connect 'chat	 "login:" "username"
	    "Password:"	"password" "% "	"exec pppd passive"'


					Note

	 Running chat in this way leaves the password visible in the parame-
	 ter list of pppd and chat.

   4.  A common	use of pppd is to dial out to an Internet Service Provider
       (ISP).  To do this, enter a command similar to the following:
	    # pppd call	isp

       The call	option reads other pppd	options	from the specified file. In
       this example, the system	administrator has created a file called	isp
       in the /etc/ppp/peers directory that contains connection	options
       specific	to the ISP he intends to contact. This file could contain the
       following lines:


	    ttyS0 19200	crtscts
	    connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
	    noauth


       As a result, the	chat command dials the ISP's modem and executes	the
       login sequence, as dictated by the chat-isp script.  The
       /etc/ppp/chat-isp file could contain the	following script:


	    ABORT "NO CARRIER"
	    ABORT "NO DIALTONE"
	    ABORT "ERROR"
	    ABORT "NO ANSWER"
	    ABORT "BUSY"
	    ABORT "Username/Password Incorrect"
	    "" "at"
	    OK "at&d0&c1"
	    OK "atdt2468135"
	    "name:" "^Umyuserid"
	    "word:" "\\qmypassword"
	    "ispts" "\\q^Uppp"
	    "~-^Uppp-~"


       See chat(8) for more information	about chat scripts.

   5.  You can also use	pppd to	provide	a dial-in PPP service for users.  If
       the users already have login accounts, the simplest way to set up the
       PPP service is to let the users log in to their accounts	and run	pppd
       (installed setuid-root) with the	following command:


	    pppd proxyarp

       To allow	a user to use the PPP facilities, you need to allocate an IP
       address for that	user's machine and create an entry in /etc/ppp/pap-
       secrets or /etc/ppp/chap-secrets	(depending on which authentication
       method the PPP implementation on	the user's machine supports), so that
       the user's machine can authenticate itself.  For	example, if Joe	has a
       machine called "joespc" that is to be allowed to	dial in	to the
       machine called "server" and use the IP address joespc.my.net, you
       would add an entry like this to /etc/ppp/pap-secrets or
       /etc/ppp/chap-secrets:


	    joespc  server  "joe's secret"  joespc.my.net

       Alternatively, you can create a username	called (for example) "ppp",
       whose login shell is pppd and whose home	directory is /etc/ppp.
       Options to be used when pppd is run this	way can	be put in
       /etc/ppp/.ppprc.

       If your serial connection is more complicated than a piece of wire,
       you might need to arrange for some control characters to	be escaped.
       In particular, it is often useful to escape XON (^Q) and	XOFF (^S),
       using asyncmap a0000.  If the path includes a telnet session, you
       probably	should escape ^] as well (asyncmap 200a0000).  If the path
       includes	an rlogin session , you	need to	use the	escape ff option on
       the end that is running the rlogin command, since many rlogin imple-
       mentations are not transparent; they remove the sequence	0xff, 0xff,
       0x73, 0x73, followed by any 8 bytes, from the stream.

FILES

  /etc/ppp/pppn.pid
      Process ID for pppd process on ppp interface unit	n.

  /etc/ppp/auth-up
      A	program	or script that is executed after the remote system success-
      fully authenticates itself.  It is executed with the parameters
      interface-name peer-name user-name tty-device speed and with its stan-
      dard input, output and error redirected to /dev/null.  This program or
      script is	executed with the real and effective user-IDs set to root,
      and with an empty	environment.  (Note that this script is	not executed
      if the peer does not authenticate	itself,	for example when the noauth
      option is	used.)

  /etc/ppp/auth-down
      A	program	or script that is executed when	the link goes down, if
      /etc/ppp/auth-up was previously executed.	 It is executed	in the same
      manner with the same parameters as /etc/ppp/auth-up.

  /etc/ppp/ip-up
      A	program	or script that is executed when	the link is available for
      sending and receiving IPv4 packets (IPCP is up).	It is executed with
      the parameters interface-name tty-device speed local-IP-address
      remote-IP-address	and with its standard input, output and	error streams
      redirected to /dev/null.

      This program or script is	executed with the same real and	effective
      user-ID as pppd, that is,	at least the effective user-ID and possibly
      the real user-ID will be root.  This is so that it can be	used to	mani-
      pulate routes and	run privileged daemons (for example, sendmail).	 Be
      careful that the contents	of the /etc/ppp/ip-up and /etc/ppp/ip-down
      scripts do not compromise	your system's security.

      This program or script is	executed with an empty environment, so you
      must either specify a PATH or use	full pathnames.

  /etc/ppp/ip-down
      A	program	or script which	is executed when the link is no	longer avail-
      able for sending and receiving IPv4 packets.  This script	can be used
      for undoing the effects of the /etc/ppp/ip-up script.  It	is invoked
      with the same parameters as the ip-up script, and	the same security
      considerations apply.

  /etc/ppp/ip6-up
      A	program	or script that is executed when	the link is available for
      sending and receiving IPv6 packets (IP6CP	is up).	 It is executed	with
      the parameters interface-name tty-device speed::local-IPv6-
      interfaceID::remote-IPv6-interfaceID and with its	standard input,	out-
      put and error streams redirected to /dev/null.

      This program or script is	executed with the same real and	effective
      user-ID as pppd, that is,	at least the effective user-ID and possibly
      the real user-ID will be root.  This is so that it can be	used to	mani-
      pulate routes, run privileged daemons (for example, sendmail).  Be
      careful that the contents	of the /etc/ppp/ip6-up and /etc/ppp/ip6-down
      scripts do not compromise	your system's security.

  /etc/ppp/ip6-down
      A	program	or script that is executed when	the link is no longer avail-
      able for sending and receiving IPv6 packets.  This script	can be used
      for undoing the effects of the /etc/ppp/ip6-up script.  It is invoked
      with the same parameters as the ip6-up script, and the same security
      considerations apply.

  /etc/ppp/pap-secrets
      Usernames, passwords and IP addresses for	PAP authentication.  This
      file should be owned by root and not readable or writable	by any other
      user.  The pppd daemon logs a warning if these conditions	are not	true.

  /etc/ppp/chap-secrets
      Names, secrets and IP addresses for CHAP authentication.	This file
      should be	owned by root and not readable or writable by any other	user.
      The pppd daemon logs a warning if	these conditions are not true.

  /etc/ppp/options
      System default options for pppd (read before user	default	options	or
      command-line options).

  ~/.ppprc
      User default options (read before	/etc/ppp/options.ttyname).

  /etc/ppp/options.ttyname
      System default options for the serial port being used (read after
      ~/.ppprc).  In forming the name of the options.ttyname file, the
      initial /dev/ prefix is removed and any remaining	slash characters (/)
      are replaced with	dots.

  /etc/ppp/peers
      A	directory containing options files that	may contain privileged
      options, even if pppd was	invoked	by a user other	than root.  The
      system administrator can create options files in this directory to per-
      mit non-privileged users to dial out without requiring the peer to
      authenticate, but	only to	certain	trusted	peers.

SEE ALSO

  Commands: chat(8), ip6rtrd(8), pppstats(8)

  Network: ppp_manual_setup(7)

  Network Administration: Connections

  RFC 1144, Jacobson, V., Compressing TCP/IP Headers for Low-speed Serial
  Links, 1990 February.

  RFC 1321, Rivest, R.,	The MD5	Message-Digest Algorithm, 1992 April.

  RFC 1332RFC1332, McGregor, G., The PPP Internet Protocol Control Protocol
  (IPCP), 1992 May (obsoletes RFC1172).

  RFC 1334RFC1334, Lloyd, B.; Simpson, W.A., PPP Authentication	Protocols,
  1992 October.

  RFC 1570RFC1570, Simpson, W.A., PPP LCP Extensions, 1994 January.

  RFC 1661RFC1661, Simpson, W.A., The Point-to-Point Protocol (PPP), 1994
  July (obsoletes RFC1548, RFC1331, RFC1171).

  RFC 1662RFC1662, Simpson, W.A., PPP in HDLC-like Framing, 1994 July
  (obsoletes RFC1549).

  RFC 2461RFC 2461, Narten, T.;	Nordmark, E.; Simpson W. A., Neighbor
  Discovery for	IP version 6 (IPV6)

  RFC 2472, Haskin, D.,	and Allen, E., IP Version 6 over PPP

ACKNOWLEDGEMENTS

  Greg Christy,	Brad Clements, Karl Fox, Brad Parker (bradATfcr.com), Drew
  Perkins, Steve Tate (srtATcs.edu)