diff --git a/handbook/userppp.sgml b/handbook/userppp.sgml
index c94dbcb592..4413221554 100644
--- a/handbook/userppp.sgml
+++ b/handbook/userppp.sgml
@@ -1,751 +1,909 @@
-<!-- $Id: userppp.sgml,v 1.18 1997-08-12 09:18:34 asami Exp $ -->
+<!-- $Id: userppp.sgml,v 1.19 1997-09-07 01:05:53 brian Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <sect>Setting up User PPP<label id="userppp">
 
 <!--  This FAQ/HowTo is intended to get you up and running with
-   iijppp, also known as <em>user level ppp</em> or just
+   ppp, also known as <em>user level ppp</em> or just
    simply <em>ppp</em> for FreeBSD 2.0.5 and above.
 
-<p>It also outlines how to use iijppp as a ppp server.
+<p>It also outlines how to use user ppp as a ppp server.
 
 <p>This document has originally written by Nik Clayton, and has
    turned into a collaborative effort over the years.
 
 -->
 
 <p>User PPP was introduced to FreeBSD in release 2.0.5 as an
    addition to the existing kernel implementation of PPP.  So,
    what is different about this new PPP that warrants its
    addition?  To quote from the manual page:
 
 <quote>
    This is a user process PPP software package. Normally, PPP is
    implemented as a part of the kernel (e.g. as managed by pppd) and
    it is thus somewhat hard to debug and/or modify its behavior. However,
    in this implementation PPP is done as a user process with the help of
    the tunnel device driver (tun).
 </quote>
 
   In essence, this means that rather than running a PPP daemon, the ppp
   program can be run as and when desired. No PPP interface needs to be
   compiled into the kernel, as the program can use the generic tunnel
   device to get data into and out of the kernel.
 
   From here on out, user ppp will be referred to simply as ppp unless a
   distinction needs to be made between it and any other PPP client/server
-  software.  Unless otherwise stated, all commands in this section should
-  be executed as root.
+  software such as pppd.  Unless otherwise stated, all commands in this
+  section should be executed as root.
 
 <sect1><heading>Before you start</heading>
 
 <p>This document assumes you are in roughly this position:
 
    You have an account with an Internet Service Provider (ISP) which lets you
    use PPP. Further, you have a modem (or other device) connected and
    configured correctly which allows you to connect to your ISP.
 
    You are going to need the following information to hand:
 
 <itemize>
-   <item>The IP address of your ISP's gateway.  The gateway is the
-         machine to which you will connect and will
-         be set up as your <tt>default route</tt>.
-
-   <item>Your ISP's netmask setting.  If you can't determine this,
-         assume a netmask of 0xffffff00.
-
-   <item>The IP addresses of one or more nameservers.  Normally, you
-         will be given two IP numbers.
-
-   <item>If your ISP allocates you a static IP address and/or hostname
-         then you will need that as well.  If not, you will need to know
-         from what range of IP addresses your allocated IP address will
-         belong.  If you havn't been given this range, you can accept
-         any IP number (as explained later).
+   <item><p>Your ISPs phone number(s).
+
+   <item><p>Your login name and password.  This can be either a regular
+            unix style login/password pair, or a PPP PAP or CHAP
+            login/password pair.
+
+   <item><p>The IP address of your ISP's gateway.  The gateway is the
+            machine to which you will connect and will
+            be set up as your <tt>default route</tt>.  If your ISP hasn't
+            given you this number, don't worry.  We can make one up and
+            your ISP's PPP server will tell us when we connect.
+         <p>This number is known from now on as <tt>HISADDR</tt>.
+
+   <item><p>Your ISP's netmask setting.  Again, if your ISP hasn't given
+            you this information, you can safely use a netmask of
+            255.255.255.0.
+
+   <item><p>The IP addresses of one or more nameservers.  Normally, you
+            will be given two IP numbers.  You <bf>MUST</bf> have this
+            information unless you run your own nameserver.
+
+   <item><p>If your ISP allocates you a static IP address and hostname
+            then you will need this information too.  If not, you will need
+            to know from what range of IP addresses your allocated IP address
+            will belong.  If you haven't been given this range, don't worry.
+            You can configure PPP to accept any IP number (as explained later).
 </itemize>
 
-   If you do not have any of this information then contact your ISP and make
-   sure they provide it to you.
-
-   In addition, it is assumed that because your connection to the
-   Internet is  not full time you are not running a name server
-   (<tt>named(8)</tt>).  If this is not the case, ignore any
-   information on setting up the <tt>/etc/resolv.conf</tt> file.
+   If you do not have any of the required information, contact your ISP
+   and make sure they provide it to you.
 
 <sect1><heading>Building a ppp ready kernel</heading>
 
 <p>As the description states, ``ppp'' uses the kernel ``tun'' device.
    It is necessary to make sure that your kernel has support for this
    device compiled in.
 
-   To check this, go to your kernel compile directory (probably
-   /sys/i386/conf) and examine your kernel configuration file.
+   To check this, go to your kernel compile directory (<tt>/sys/i386/conf</tt>
+   or <tt>/sys/pc98/conf</tt>) and examine your kernel configuration file.
    It needs to have the line
 
 <tscreen><verb>
    pseudo-device tun 1
 </verb></tscreen>
 
    in it somewhere. The stock GENERIC kernel has this as standard, so
    if you have not installed a custom kernel or you do not have a /sys
    directory, you do not have to change anything.
-   If your kernel configuration file does not have this line in it, or
+   <p>If your kernel configuration file does not have this line in it, or
    you need to configure more than one tun device (for example, if
    you are setting up a server and could have 16 dialup ppp connections
    at any one time then you will need to use ``16'' instead of ``1''),
    then you should add the line, re-compile, re-install and boot the new
    kernel.  Please refer to the 
    <ref id="kernelconfig" name="Configuring the FreeBSD Kernel">
    section for more information on kernel configuration.
 
 <p>You can check how many tunnel devices your current kernel has by
    typing the following:
 
 <tscreen><verb>
    # ifconfig -a
    tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
            inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff
    tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576
    tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
            inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff
    tun3: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 1500
 </verb></tscreen>
 
    which in this case shows four tunnel devices, two of which are
    currently configured and being used.
 
 <p>If you have a kernel without the tun device, and you can not
    rebuild it for some reason, all is not lost.  You should be
    able to dynamically load the code.  Refer to the appropriate
    modload(8) and lkm(4) pages for further details.
 
 <p>You may also wish to take this opportunity to configure a firewall.
    Details can be found in the <ref id="firewalls" name="Firewalls">
    section.
 
 <sect1><heading>Check the tun device</heading>
 
 <p>Most users will only require one ``tun'' device (tun0). If you have
    used more (i.e., a number other than `1' in the pseudo-device line
    in the kernel configuration file) then alter all references to ``tun0''
    below to reflect whichever device number you are using.
 
    The easiest way to make sure that the tun0 device is configured correctly
-   is to re-make it. To this end, execute the following commands:
+   is to re-make it. To do this, execute the following commands:
 
 <tscreen><verb>
    # cd /dev
    # ./MAKEDEV tun0
 </verb></tscreen>
 
 <p>If you require 16 tunnel devices in your kernel, you will need to
    create more than just tun0:
 
 <tscreen><verb>
    # cd /dev
-   # ./MAKEDEV tun0 tun1 tun2 tun3 tun4 tun5 tun6 tun7 tun8 tun9
-   # ./MAKEDEV tun10 tun11 tun12 tun13 tun14 tun15
+   # ./MAKEDEV tun15
 </verb></tscreen>
 
 <p>Also, to confirm that the kernel is configured correctly,
    the following command should give the indicated output:
 
 <tscreen><verb>
    $ ifconfig tun0
    tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 1500
    $ 
 </verb></tscreen>
 
-<sect1><heading>PPP Name Resolution Configuration</heading>
+<sect1><heading>Name Resolution Configuration</heading>
 
-<p>The resolver is the part of the networking system that turns IP
-   addresses into hostnames and vice versa.  It can be configured
-   to look for maps that describe IP to hostname mappings in one
-   of two places.  The first is a file called <tt>/etc/hosts</tt>
-   (<tt>man 5 hosts</tt>).  The second is the Internet Domain Name
-   Service (DNS), a distributed data base, the discussion of which
-   is beyond the scope of this document.
+<p>The resolver is the part of the system that turns IP addresses
+   into hostnames and vice versa.  It can be configured to look for
+   maps that describe IP to hostname mappings in one of two places.
+   The first is a file called <tt>/etc/hosts</tt> (<tt>man 5 hosts</tt>).
+   The second is the Internet Domain Name Service (DNS), a distributed
+   data base, the discussion of which is beyond the scope of this document.
 
-<p>This section describes briefly how to configure your resolver.  If
-   you are already running a DNS, this section may be skipped.
+<p>This section describes briefly how to configure your resolver.
 
 <p>The resolver is a set of system calls that do the name mappings, but
-   you have to tell them where to get their information from.  You do
+   you have to tell them where to find their information.  You do
    this by first editing the file <tt>/etc/host.conf</tt>.  Do
    <bf>not</bf> call this file <tt>/etc/hosts.conf</tt> (note the extra
    ``s'') as the results can be confusing.
 
 <sect2><heading>Edit the /etc/host.conf file</heading>
 
 <p>This file should contain the following two lines:
 
 <tscreen><verb>
    hosts
    bind
 </verb></tscreen>
    which instructs the resolver to first look in the file
    <tt>/etc/hosts</tt>, and then to consult the DNS if the
    name was not found.
 
 <sect2><heading>Edit the /etc/hosts(5) file</heading>
 
 <p>This file should contain the IP addresses and names of machines on your
    network. At a bare minimum it should contain entries for the machine
    which will be running ppp. Assuming that your machine is called
    foo.bar.com with the IP address 10.0.0.1, <tt>/etc/hosts</tt> should
    contain:
 
 <tscreen><verb>
    127.0.0.1    localhost
    10.0.0.1     foo.bar.com	       foo
 </verb></tscreen>
 
    The first line defines the alias ``localhost'' as a synonym for the
    current machine. Regardless of your own IP address, the IP address for
    this line should always be 127.0.0.1. The second line maps the name
    ``foo.bar.com'' (and the shorthand ``foo'') to the IP address 10.0.0.1.
 
-   If your provider allocates you a static IP address then use this in place
-   of 10.0.0.1.
+   If your provider allocates you a static IP address and name, then use
+   these in place of the 10.0.0.1 entry.
 
 <sect2><heading>Edit the /etc/resolv.conf file</heading>
 
-<p><tt>/etc/resolv.conf</tt> contains some extra information required when
-   you are not running a nameserver. It points the resolver routines at real
-   nameservers, and specifies some other information.
-
-   At the very least, <tt>/etc/resolv.conf</tt> should contain one line with
-   a nameserver which can be queried, but two nameservers are preferable.
-   You should enter these as IP addresses, for example:
+<p><tt>/etc/resolv.conf</tt> tells the resolver how to behave.  If you are
+   running your own DNS, you may leave this file empty.  Normally, you will
+   need to enter the following line(s):
 
 <tscreen><verb>
-   nameserver 1.2.3.4
-   nameserver 1.2.3.5
+   nameserver x.x.x.x
+   nameserver y.y.y.y
+   domain bar.com
 </verb></tscreen>
 
-   Add as many ``nameserver'' lines as your ISP provides nameservers.
-   Refer to the resolv.conf manual page for further details of entries
-   in this file.
+   The <tt>x.x.x.x</tt> and <tt>y.y.y.y</tt> addresses are those given
+   to you by your ISP.  Add as many ``nameserver'' lines as your ISP
+   provides.  The ``domain'' line defaults to your hostname's domain, and
+   is probably unnecessary.  Refer to the resolv.conf manual page for details
+   of other possible entries in this file.
 
 <sect1><heading>PPP Configuration</heading>
 
 <p>Both user ppp and pppd (the kernel level implementation of PPP)
    use configuration files located in the <tt>/etc/ppp</tt> directory.
    The sample configuration files provided are a good reference for
    user ppp, so don't delete them.
 
-<p>Configuring ppp requires that you edit up to three files, depending
+<p>Configuring ppp requires that you edit a number of files, depending
    on your requirements. What you put in them depends to some extent
    on whether your ISP allocates IP addresses statically (i.e., you get
    given one IP address, and always use that one) or dynamically (i.e.,
-   your IP address can be different during different PPP sessions).
-
-<sect2><heading>PPP and static IP addresses</heading>
+   your IP address can be different for each PPP session).
 
-<p>You will need to create three files in the <tt>/etc/ppp</tt>
-   directory.
+<sect2><heading>PPP and Static IP addresses<label id="userppp:staticIP">
+       </heading>
 
-<p>The first of these files is <tt>ppp.conf</tt>. It should look
-   similar to the example below.  Note that lines that end in a
-   ``:'' start in column 1, all other lines should be indented as
-   shown using spaces or tabs.
+<p>You will need to create a configuration file called
+   <tt>/etc/ppp/ppp.conf</tt>.  It should look similar to the example
+   below.  Note that lines that end in a ``:'' start in the first column,
+   all other lines should be indented as shown using spaces or tabs.
 
-   <tt>/etc/ppp/ppp.conf</tt>
 <tscreen><verb>
 1     default:
 2       set device /dev/cuaa0
-3       set speed 38400
+3       set speed 115200
 4       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK
 \\dATDT\\T TIMEOUT 40 CONNECT"
-5      provider:
-6        set phone 01234567890
-7        set login "TIMEOUT 10 gin:-BREAK-gin: foo word: bar col: ppp"
-8        set timeout 120
-9        set ifaddr x.x.x.x y.y.y.y
-10       delete ALL
-11       add 0 0 y.y.y.y
-12       set openmode active
+5     provider:
+6       set phone "(0123) 456 7890"
+7       set login "TIMEOUT 10 gin:-BREAK-gin: foo word: bar col: ppp"
+8       set timeout 300
+9       deny lqr
+10      set ifaddr x.x.x.x y.y.y.y
+11      delete ALL
+12      add 0 0 HISADDR
 </verb></tscreen>
    Do not include the line numbers, they are just for reference in
    this discussion.
 
 <descrip>
 <tag/Line 1:/  Identifies the default entry.  Commands in this entry are
                executed automatically when ppp is run.
 
 <tag/Line 2:/  Identifies the device to which the modem is connected.
                COM1: is <tt>/dev/cuaa0</tt> and COM2: is <tt>/dev/cuaa1</tt>.
 
-<tag/Line 3:/  Sets the speed you want to connect at.
+<tag/Line 3:/  Sets the speed you want to connect at.  If 115200 doesn't
+               work (it should with any reasonably new modem), try 38400
+               instead.
 
 <tag/Line 4:/  The dial string.  User ppp uses an expect-send syntax similar
                to the <tt>chat(8)</tt> program.  Refer to the manual page
                for information on the features of this language.
 
 <tag/Line 5:/  Identifies an entry for a provider called ``provider''.
 
 <tag/Line 6:/  Sets the phone number for this provider.  Multiple phone
-               numbers may be specified using the `:' character as a
-               seperator.
+               numbers may be specified using the ``:'' or ``|'' character as
+               a seperator.  The difference between these spearators is
+               described in the ppp manual page.  To summarize, if you want
+               to rotate through the number, use the ``:''.  If you want to
+               always attempt to dial the first number first and only use
+               the other numbers if the first number fails, use the ``|''.
+               Always quote the entire set of phone numbers as shown.
 
 <tag/Line 7:/  The login string.  The login string is of the same
                syntax as the dial string.  In this example, the string is
-	       for a service who's login session looks like
+	       for a service who's login session looks like this:
 
 <tscreen><verb>
    J. Random Provider
    login: foo
    password: bar
    protocol: ppp
 </verb></tscreen>
 
 	       You will need to alter this script to suit your own needs.
+               If you're using PAP or CHAP, there will be no login at this
+               point, so your login string can be left blank.  See
+               <ref id="userppp:PAPnCHAP" name="PAP and CHAP authentication">
+               for further details.
 
 <tag/Line 8:/  Sets the default timeout (in seconds) for the connection.
                Here, the connection will be closed automatically after
-               120 seconds of inactivity.
-
-<tag/Line 9:/  Sets the interface addresses. The string x.x.x.x should be
-               replaced by the IP address that your provider allocates you.
-               The string y.y.y.y should be replaced by the IP address that
-               your ISP indicated for their gateway (the machine to which
-               you connect).
+               300 seconds of inactivity.  If you never want to timeout,
+               set this value to zero.
+
+<tag/Line 9:/  Ppp can be configured to exchange Link Quality Report (LQR)
+               packets.  These packets describe how good the physical link
+               is.  Ppp's LQR strategy is to close the connection when a
+               number of these packets are missed.  This is useful when
+               you have a direct serial link to another machine and the
+               DSR modem signal is not available to indicate that the line
+               is up.  When data saturates the line, LQR packets are
+               sometimes ``missed'', causing ppp to close the connection
+               prematurely.  Refusing to negotiate lqr is sometimes prudent
+               (if you are going through a modem) as it avoids this whole
+               mess.  By default, ppp will not attempt to negotiate LQR,
+               but will accept LQR negotiation from the peer.
+
+<tag/Line 10:/ Sets the interface addresses. The string x.x.x.x should be
+               replaced by the IP address that your provider has allocated
+               to you.  The string y.y.y.y should be replaced by the IP
+               address that your ISP indicated for their gateway (the
+               machine to which you connect).  If your ISP hasn't given you
+               a gateway address, use <tt>10.0.0.2/0</tt>.  If you need to
+               use a ``guessed'' address, make sure that you create an entry
+               in <tt>/etc/ppp/ppp.linkup</tt> as per the instructions for
+               <ref id="userppp:dynamicIP" name="PPP and Dynamic IP addresses">.
+               If this line is omitted, ppp cannot run in <tt>-auto</tt> or
+               <tt>-dynamic</tt> mode.
+
+<tag/Line 11:/ Deletes all existing routing table entries for the acquired
+               tun device.  This should not normally be necessary, but will
+               make sure that PPP is starting with a clean bill of health.
+
+<tag/Line 12:/ Adds a default route to your ISPs gateway.  The special
+               word <tt>HISADDR</tt> is replaced with the gateway address
+               specified on line 9.  It is important that this line appears
+               after line 9, otherwise <tt>HISADDR</tt> will not yet be
+               initialized.
+</descrip>
 
-<tag/Line 10:/ Deletes all existing routing table entries for the
-               acquired tun device.
+<p>It is not necessary to add an entry to <tt>ppp.linkup</tt> when you have
+   a static IP address as your routing table entries are already correct
+   before you connect.  You may however wish to create an entry to invoke
+   programs after connection.  This is explained later with the sendmail
+   example.
 
-<tag/Line 11:/ Adds a default route to your ISPs IP number.  The IP
-               number should always be that of your ISPs gateway.
+<p>Example configuration files can be found in the <tt>/etc/ppp</tt>
+   directory.
 
-<tag/Line 12:/ Tells our side to begin negotiation.  This is not always
-               necessary, but it does no harm to have both sides initiating
-               the Line Control Protocol (LCP).
-</descrip>
+<sect2><heading>PPP and Dynamic IP addresses<label id="userppp:dynamicIP">
+       </heading>
 
-<p>The second of these files is <tt>/etc/ppp/ppp.linkup</tt>:
+<p>If your service provider does not assign static IP numbers,
+   <tt>ppp</tt> can be configured to negotiate the local and
+   remote addresses.  This is done by "guessing" an IP number
+   and allowing ppp to set it up correctly using the IP Configuration
+   Protocol (IPCP) after connecting.  The <tt>ppp.conf</tt> configuration
+   is the same as <ref id="userppp:staticIP"
+   name="PPP and Dynamic IP addresses">, with the following change:
 
 <tscreen><verb>
-   x.x.x.x:
-    delete ALL
-    add 0 0 HISADDR
+10      set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0
 </verb></tscreen>
 
-<p>Replace x.x.x.x with your IP address as before. This file is used to
-   automatically delete all existing routes for the acquired line and
-   add a default route from your ISP (who's address is automatically
-   inserted with the HISADDR macro) to you.
-
-<p>With a static IP number assigned by your ISP, you don't actually
-   need an entry in <tt>/etc/ppp.linkup</tt>, but again, it doesn't
-   do any harm to have it.
+   Again, do not include the line numbers, they are just for reference in
+   this discussion.  Indentation of at least one space is required.
 
-<p>Finally, the third of these files is <tt>/etc/ppp/ppp.secret</tt>.
-   This file allows you to set some passwords to control access to
-   your ppp server.  You may or may not want to configure this file,
-   depending on how many people have access to your ppp system.
-
-<p>Examples can be found in the <tt>/etc/ppp</tt> directory.
+<descrip>
+<tag/Line 10:/ The number after the ``/'' character is the number of bits of
+               the address that ppp will insist on.  You may wish to use
+               IP numbers more appropriate to your circumstances, but the
+               above example will almost always work.  If it fails, you may
+               be able to defeat some broken ppp implementations by
+               supplying an additional <tt>0.0.0.0</tt> arguement:
 
-<sect2><heading>PPP and Dynamic IP addresses</heading>
+<tscreen><verb>
+  set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
+</verb></tscreen>
 
-<p>If your service provider does not assign static IP numbers,
-   <tt>ppp</tt> can be configured to negotiate the local and
-   remote addresses.  This is done by "guessing" an IP number
-   and allowing ppp to set it up correctly using the LCP at
-   connection time.  Otherwise, the configuration is the same as
-   that of a static IP configuration.
+               This tells ppp to negotiate using address <tt>0.0.0.0</tt>
+               rather than <tt>10.0.0.1</tt>.  Do not use <tt>0.0.0.0/0</tt>
+               as the first argument to <tt>set ifaddr</tt> as it prevents
+               ppp from setting up an initial route in <tt>-auto</tt> and
+               <tt>-ddial</tt> mode.
+</descrip>
 
-<p>Put the following lines in your <tt>ppp.conf</tt> file:
+<p>You will also need to create an entry in <tt>/etc/ppp/ppp.linkup</tt>.
+   <tt>Ppp.linkup</tt> is used after a connection has been established.  At
+   this point, ppp will know what IP addresses should <bf>really</bf> be
+   used.  The following entry will delete the existing bogus routes, and
+   create correct ones:
 
 <tscreen><verb>
-   ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0
-   delete ALL
-   add 0 0 10.0.0.2
+1     provider:
+2       delete ALL
+3       add 0 0 HISADDR
 </verb></tscreen>
 
-<p>You should NOT use 0 as either IP address.  If you do, ppp will not be
-   able to set up the correct initial entries in the routing table.
-
-<p>The number after the ``/'' character is the number of bits of
-   the address that ppp will insist on.
-
-<p>Note also that the HISADDR macro is not yet available in
-   <tt>ppp.conf</tt>, only in <tt>ppp.linkup</tt>.
+<descrip>
+<tag/Line 1:/ On establishing a connection, ppp will look for an entry in
+              <tt>ppp.linkup</tt> according to the following rules:  First,
+              try to match the same label as we used in <tt>ppp.conf</tt>.
+              If that fails, look for an entry for the IP number of our
+              gateway.  This entry is a four-octet IP style label.  If
+              we still haven't found an entry, look for the <tt>MYADDR</tt>
+              entry.
+
+<tag/Line 2:/ This line tells ppp to delete all existing routes for the
+              acquired tun interface (except the direct route entry).
+
+<tag/Line 3:/ This line tells ppp to add a default route that points to
+              <tt>HISADDR</tt>.  <tt>HISADDR</tt> will be replaced with
+              the IP number of the gateway as negotiated in the IPCP.
+</descrip>
 
 <p>See the pmdemand entry in the files <tt>/etc/ppp/ppp.conf.sample</tt> and
    <tt>/etc/ppp/ppp.linkup.sample</tt> for a detailed example.
 
 <sect2><heading>Receiving incoming calls with PPP</heading>
 
-<p>This section describes setting up iijppp in a server role.
+<p>This section describes setting up ppp in a server role.
 
 <p>When you configure <tt>ppp</tt> to receive incoming calls, you
    must decide whether you wish to forward packets for just
    <tt>ppp</tt> connections, for all interfaces, or not at all.
    To forward for just ppp connections, include the line
 
 <tscreen><verb>
     enable proxy
 </verb></tscreen>
 
    in your <tt>ppp.conf</tt> file.  If you wish to forward packets on all
    interfaces, use the
 
 <tscreen><verb>
     gateway=YES
 </verb></tscreen>
 
    option in <tt>/etc/rc.conf</tt> (this file used to be called
    <tt>/etc/sysconfig</tt>).
 
 <sect3><heading>Which getty?</heading>
 
 <p><ref id="dialup" name="Configuring FreeBSD for Dialup Services">
    provides a good description on enabling dialup services using getty.
 
 <p>An alternative to getty is
    <url url="http://www.leo.org/~doering/mgetty/index.html" name="mgetty">,
    a smarter version of getty designed with dialup lines in mind.
 
 <p>The advantages of using mgetty is that it actively <em>talks</em> to
    modems, meaning if port is turned off in <tt>/etc/ttys</tt> then
    your modem won't answer the phone.
 
 <p>Later versions of mgetty (from 0.99beta onwards) also support the
    automatic detection of PPP streams, allowing your clients script-less
    access to your server.
 
-<p>Obtaining and configuring mgetty correctly is beyond the scope of
-   this document.
+<p>Refer to <ref id="userppp:mgetty" name="Mgetty and AutoPPP"> for more
+   information on mgetty.
+
+<sect3><heading>PPP permissions</heading>
+
+<p>PPP must normally be run as user id 0.  If however you wish to allow
+   ppp to run in server mode as a normal user by executing ppp as described
+   below, that user must be given permission to run ppp by adding them to
+   the <tt>network</tt> group in <tt>/etc/group</tt>.
 
 <sect3><heading>Setting up a PPP shell for dynamic-IP users</heading>
 
 <p>Create a file called <tt>/etc/ppp/ppp-shell</tt> containing the
    following:
 
 <tscreen><verb>
    #!/bin/sh
    IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
    CALLEDAS="$IDENT"
    TTY=`tty`
 
    if [ x$IDENT = xdialup ]; then
        IDENT=`basename $TTY`
    fi
 
    echo "PPP for $CALLEDAS on $TTY"
    echo "Starting PPP for $IDENT"
 
    exec /usr/sbin/ppp -direct $IDENT
 </verb></tscreen>
 
 <p>This script should be executable.  Now make a symbolic link called
    <tt>ppp-dialup</tt> to this script using the following commands:
 
 <tscreen><verb>
    # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-dialup
 </verb></tscreen>
 
 <p>You should use this script as the <em>shell</em> for all your dialup
    ppp users.  This is an example from <tt>/etc/password</tt>
    for a dialup PPP user with username pchilds. (remember don't directly
    edit the password file, use <tt>vipw</tt>)
 
 <tscreen><verb>
    pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup
 </verb></tscreen>
 
 <p>Create a <tt>/home/ppp</tt> directory that is world readable
    containing the following 0 byte files
 
 <tscreen><verb>
    -r--r--r--   1 root     wheel           0 May 27 02:23 .hushlogin
    -r--r--r--   1 root     wheel           0 May 27 02:22 .rhosts
 </verb></tscreen>
 
    which prevents <tt>/etc/motd</tt> from being displayed.
 
 <sect3><heading>Setting up a PPP shell for static-IP users</heading>
 
 <p>Create the <tt>ppp-shell</tt> file as above and for each account with
    statically assigned IPs create a symbolic link to <tt>ppp-shell</tt>.
 
 <p>For example, if you have three dialup customers fred, sam, and mary,
    that you route class C networks for, you would type the following:
 
 <tscreen><verb>
    # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
    # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
    # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary
 </verb></tscreen>
 
 <p>Each of these users dialup accounts should have their shell set
    to the symbolic link created above. (ie. mary's shell should be
    <tt>/etc/ppp/ppp-mary</tt>).
 
 <sect3><heading>Setting up ppp.conf for dynamic-IP users</heading>
 
 <p>The <tt>/etc/ppp/ppp.conf</tt> file should contain something along
    the lines of
 
 <tscreen><verb>
    default:
     set debug phase lcp chat
     set timeout 0
 
    ttyd0: 
     set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
     enable proxy
 
    ttyd1:
     set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
     enable proxy
 </verb></tscreen>
  
 <p>Note the indenting is important.
 
 <p>The <tt>default:</tt> section is loaded for each session.  For each
    dialup line enabled in <tt>/etc/ttys</tt> create an entry similar
    to the one for <tt>ttyd0:</tt> above.  Each line should get a unique
    IP from your pool of ip address for dynamic users.
 
 <sect3><heading>Setting up ppp.conf for static-IP users</heading>
 
 <p>Along with the contents of the sample <tt>/etc/ppp/ppp.conf</tt>
    above you should add a section for each of the statically assigned
    dialup users.  We will continue with our fred, sam, and mary example.
  
 <tscreen><verb>
    fred:
     set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
  
    sam:
     set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
  
    mary:
     set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255
 </verb></tscreen> 
 
 <p>The file <tt>/etc/ppp/ppp.linkup</tt> should also contain routing
    information for each static IP user if required.  The line below 
    would add a route for the <tt>203.14.101.0</tt> class C via 
    the client's ppp link.
 
 <tscreen><verb>
    fred:
     add 203.14.101.0 netmask 255.255.255.0 HISADDR
  
    sam:
     add 203.14.102.0 netmask 255.255.255.0 HISADDR
  
    mary:
     add 203.14.103.0 netmask 255.255.255.0 HISADDR
 </verb></tscreen> 
 
 <sect3><heading>More on mgetty, AutoPPP, and MS extensions</heading>
 
-<sect4><heading>Mgetty and AutoPPP</heading>
+<sect4><heading>Mgetty and AutoPPP<label id="userppp:mgetty">
+       </heading>
 
 <p>Configuring and compiling mgetty with the AUTO_PPP option enabled
    allows mgetty to detect the LCP phase of PPP connections and automatically
    spawn off a ppp shell.  However, since the default login/password sequence
    does not occur it is necessary to authenticate users using either PAP
    or CHAP.
 
 <p>This section assumes the user has successfully configured, compiled, and
    installed a version of mgetty with the AUTO_PPP option (v0.99beta or later)
  
 <p>Make sure your <tt>/usr/local/etc/mgetty+sendfax/login.config</tt> file
    has the following in it:
  
 <tscreen><verb>
    /AutoPPP/ -     -       /etc/ppp/ppp-pap-dialup
 </verb></tscreen>
  
 <p>This will tell mgetty to run the <tt>ppp-pap-dialup</tt> script for
    detected PPP connections.
  
 <p>Create a file called <tt>/etc/ppp/ppp-pap-dialup</tt> containing the
    following (the file should be executable):
 
 <tscreen><verb>
    #!/bin/sh
    TTY=`tty`
    IDENT=`basename $TTY`
    exec /usr/sbin/ppp -direct pap$IDENT
 </verb></tscreen>   
 
 <p>For each dialup line enabled in <tt>/etc/ttys</tt> create a corresponding
    entry in <tt>/etc/ppp/ppp.conf</tt>.  This will happily co-exist with
    the definitions we created above.
  
 <tscreen><verb>
    papttyd0:
     enable pap
     set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
     enable proxy
  
    papttyd1:
     enable pap
     set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
     enable proxy
 </verb></tscreen>
  
 <p>Each user logging in with this method will need to have a username/password
    in <tt>/etc/ppp/ppp.secret</tt> file, or alternatively add the
 
 <tscreen><verb>
   enable passwdauth
 </verb></tscreen>
 
    option to authenticate users via pap from the <tt>/etc/password</tt>d
    file. (*) 
 
 <p>(*) Note this option only available in 2.2-961014-SNAP or later, or by
    getting the updated ppp code for 2.1.x. (see MS extensions below for details)
 
 <sect4><heading>MS extentions</heading>
 
 <p>From 2.2-961014-SNAP onwards it is possible to allow the automatic
    negotiation of DNS and NetBIOS name servers with clients supporting
    this feature (namely Win95/NT clients).  See RFC1877 for more details
    on the protocol.
 
 <p>An example of enabling these extensions in your
    <tt>/etc/ppp/ppp.conf</tt> file is illustrated below.
 
 <tscreen><verb>
    default:
     set debug phase lcp chat
     set timeout 0
     enable msext
     set ns 203.14.100.1 203.14.100.2
     set nbns 203.14.100.5
 </verb></tscreen>  
 
 <p>This will tell the clients the primary and secondary
    name server addresses, and a netbios nameserver host.
 
+<sect2><heading>PAP and CHAP authentication<label id="userppp:PAPnCHAP">
+       </heading>
+
+<p>Some ISPs set their system up so that the authentication part of
+   your connection is done using either of the PAP or CHAP authentication
+   mechanisms.  If this is the case, your ISP will not give a <tt>login:</tt>
+   prompt when you connect, but will start talking PPP immediately.
+
+   PAP is less secure than CHAP, but security is not normally an issue
+   here as passwords, although being sent as plain text with PAP, are being
+   transmitted down a serial line only.  There's not much room for hackers
+   to "eavesdrop".
+
+   Referring back to the <ref id="userppp:staticIP"
+   name="PPP and Static IP addresses"> or <ref id="userppp:dynamicIP"
+   name="PPP and Dynamic IP addresses"> sections, the following alterations
+   must be made:
+
+<tscreen><verb>
+7       set login
+.....
+13      set authname MyUserName
+14      set authname MyPassword
+15      enable CHAP
+</verb></tscreen>
+
+   As always, do not include the line numbers, they are just for reference
+   in this discussion.  Indentation of at least one space is required.
+
+<descrip>
+<tag/Line 7:/  Your ISP will not normally require that you log into the
+               server if you're using PAP or CHAP.  You must therefore
+               disable your "set login" string.
+
+<tag/Line 13:/ This line specifies your PAP/CHAP user name.  You will need
+               to insert the correct value for <tt>MyUserName</tt>.
+<tag/Line 14:/ This line specifies your PAP/CHAP password.  You will need
+               to insert the correct value for <tt>MyPassword</tt>.
+<tag/Line 15:/ This line tells ppp to use CHAP with the given user name
+               and password.  If you wish to use PAP, just replace the
+               ``CHAP'' string with ``PAP''.
+</descrip>
+
+<p><bf>NOTE:</bf> Your <tt>authkey</tt> will be logged if you have
+command logging turned on (<tt>set log +command</tt>).  Care should be
+taken when deciding the ppp log file permissions.
+
+<sect2><heading>Changing your ppp configuration on the fly</heading>
+
+<p>It is possible to talk to the ppp program while it is running in
+   the background, but only if a suitable password has been set up.
+
+<p>By default, ppp will listen to a TCP port of 3000 + <tt>tunno</tt>,
+   where <tt>tunno</tt> is the number of the tun device acquired, however,
+   if a password for the local machine is not set up in
+   <tt>/etc/ppp/ppp.secret</tt>, no server connection will be created.
+   To set your password, put the following line in
+   <tt>/etc/ppp/ppp.secret</tt>:
+
+<tscreen><verb>
+foo MyPassword
+</verb></tscreen>
+
+   where <tt>foo</tt> is your local hostname (run <tt>hostname -s</tt> to
+   determine the correct name), and <tt>MyPassword</tt> is the unencrypted
+   password that you wish to use.  <tt>/etc/ppp/ppp.secret</tt> should
+   <bf>NOT</bf> be accessable by anyone without user id 0.  This means that
+   <tt>/</tt>, <tt>/etc</tt> and <tt>/etc/ppp</tt> should not be writable,
+   and <tt>ppp.secret</tt> should be owned by user id 0 and have permissions
+   0644.
+
+<p>It is also possible select a specific port number or to have ppp listen
+   to a local unix domain socket rather than to a TCP socket.  Refer to the
+   <tt>set socket</tt> command in manual page for further details.
+
+<p>Once a socket has been set up, the <tt>pppctl</tt> program may be used
+   in scripts that wish to manipulate the running program.
+
 <sect1><heading>Final system configuration</heading>
 
 <p>You now have PPP configured, but there are a few more things to
    do before it is ready to work. They all involve editing the
    <tt>/etc/rc.conf</tt> file (was <tt>/etc/sysconfig</tt>).
 
    Working from the top down in this file, make sure the ``hostname='' line
    is set, e.g.:
 
 <tscreen><verb>
    hostname=foo.bar.com
 </verb></tscreen>
 
+<p>If your ISP has supplied you with a static IP address and name, it's
+   probably best that you use this name as your host name.
+
 <p>Look for the network_interfaces variable.  If you want to configure
    your system to dial your ISP on demand, make sure the tun0 device is
    added to the list, otherwise remove it.
 
 <tscreen><verb>
    network_interfaces="lo0 tun0"
    ifconfig_tun0=
 </verb></tscreen>
 
    Note, the <tt>ifconfig_tun0</tt> variable should be empty, and
    a file called /etc/start_if.tun0 should be created.  This file
    should contain the line
 
 <tscreen><verb>
    ppp -auto mysystem
 </verb></tscreen>
 
    This script is executed at network configuration time, starting
-   your ppp daemon in automatic mode.
+   your ppp daemon in automatic mode.  If you have a LAN for which
+   this machine is a gateway, you may also wish to use the
+   <tt>-alias</tt> switch.  Refer to the manual page for further
+   details.
 
 <p>Set the router program to ``NO'' with the line
 
 <tscreen><verb>
    router_enable=NO            (/etc/rc.conf)
    router=NO                   (/etc/sysconfig)
 </verb></tscreen>
 
    It is important that the <tt>routed</tt> daemon is not started
    (the default) as <tt>routed</tt> tends to delete the default
    routing table entries created by ppp.
 
 <p>It is probably worth your while ensuring that the ``sendmail_flags'' line
    does not include the ``-q'' option, otherwise sendmail will attempt to do
    a network lookup every now and then, possibly causing your machine to dial
    out.  You may try:
 
 <tscreen><verb>
    sendmail_flags="-bd"
 </verb></tscreen>
 
    The upshot of this is that you must force sendmail to re-examine the
    mail queue whenever the ppp link is up by typing:
 
 <tscreen><verb>
    # /usr/sbin/sendmail -q
 </verb></tscreen>
 
-   If you don't like this, it is possible to set up a "dfilter" to block
-   SMTP traffic.  Refer to the sample files for further details.  You
-   can also use a script in the <tt>ppp.linkup</tt> file to execute this
-   command.
+<p>You may wish to use the <tt>!bg</tt> command in ppp.linkup to do this
+   automatically:
+
+<tscreen><verb>
+1     provider:
+2       delete ALL
+3       add 0 0 HISADDR
+4       !bg sendmail -bd -q30m
+</verb></tscreen>
+
+
+<p>If you don't like this, it is possible to set up a "dfilter" to block
+   SMTP traffic.  Refer to the sample files for further details.
+
+<p>All that is left is to reboot the machine.
 
-   All that is left is to reboot the machine.
+<p>After rebooting, you can now either type
 
-   You can now either type
 <tscreen><verb>
    # ppp
 </verb></tscreen>
 
    and then ``dial provider'' to start the PPP session, or, if you
    want ppp to establish sessions automatically when there is outbound
-   traffic (and you havn't created the start_if.tun0 script) , type
+   traffic (and you haven't created the start_if.tun0 script) , type
 
 <tscreen><verb>
    # ppp -auto provider
 </verb></tscreen>
 
 <sect1><heading>Summary</heading>
 
 <p>To recap, the following steps are necessary when setting up ppp
    for the first time:
 
 <p>Client side:
 
 <itemize>
    <item>Ensure that the tun device is built into your kernel.
    <item>Ensure that the tunX device file is available in the
          <tt>/dev</tt> directory.
-   <item>Create an entry in <tt>/etc/ppp.conf</tt>.  The
+   <item>Create an entry in <tt>/etc/ppp/ppp.conf</tt>.  The
          <tt>pmdemand</tt> example should suffice for most
          ISPs.
-   <item>Create an entry in <tt>/etc/ppp.linkup</tt>.
-   <item>Update your rc.conf (or sysconfig) file.
+   <item>If you have a dynamic IP address, create an entry in
+         <tt>/etc/ppp/ppp.linkup</tt>.
+   <item>Update your <tt>/etc/rc.conf</tt> (or <tt>sysconfig</tt>) file.
    <item>Create a start_if.tun0 script if you require demand
          dialing.
 </itemize>
 
 <p>Server side:
 <itemize>
    <item>Ensure that the tun device is built into your kernel.
    <item>Ensure that the tunX device file is available in the
          <tt>/dev</tt> directory.
    <item>Create an entry in /etc/passwd (using the vipw(8)
          program).
    <item>Create a profile in this users home directory that
          runs ``ppp -direct direct-server'' or similar.
-   <item>Create an entry in <tt>/etc/ppp.conf</tt>.  The
+   <item>Create an entry in <tt>/etc/ppp/ppp.conf</tt>.  The
          <tt>direct-server</tt> example should suffice.
-   <item>Create an entry in <tt>/etc/ppp.linkup</tt>.
-   <item>Update your rc.conf (or sysconfig) file.
+   <item>Create an entry in <tt>/etc/ppp/ppp.linkup</tt>.
+   <item>Update your <tt>/etc/rc.conf</tt> (or <tt>sysconfig</tt>) file.
 </itemize>
 
 <sect1><heading>Acknowledgments</heading>
 
 <p>Thanks to the following for their comments & suggestions:
 
 <p>&a.nik
 <p>&a.dirkvangulik
 <p>&a.pjc