path: root/handbook/userppp.sgml

<!-- $Id: userppp.sgml,v 1.30 1998-08-09 23:41:09 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
   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 user ppp as a ppp server.

<p>This document was 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 such as pppd.  Unless otherwise stated, all commands in this
  section should be executed as root.

  There are a large number of enhancements in version 2 of ppp.  You can
  discover what version you have by running ppp with no arguments and
  typing <tt>show version</tt> at the prompt.  It is a simple matter
  to upgrade to the latest version of ppp (under any version of FreeBSD)
  by downloading the latest archive via 
  <url url="http://www.Awfulhak.org/ppp.html" name="www.Awfulhak.org">.

<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><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 addresses of one or more nameservers.  Normally, you
            will be given two IP numbers.  You <bf>MUST</bf> have this
            information for ppp version 1.X unless you run your own
            nameserver.  From version 2 onwards, ppp supports nameserver
            address negotiation.  If your ISP also supports this, then
            using the command <tt>enable dns</tt> in your config file
            will tell ppp to set the nameservers up for you.
</itemize>

  The following information may have been supplied by your ISP, but
  is not strictly necessary:

<itemize>
   <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, we can make one up and your ISP's PPP server will
            tell us the correct value when we connect.
         <p>This IP number is referred to as <tt>HISADDR</tt> by ppp.

   <item><p>Your ISP's netmask.  If your ISP hasn't given you this
            information, you can safely use a netmask of 255.255.255.0.

   <item><p>If your ISP allocates you a static IP address and hostname
            then you can enter this information.  Otherwise, we simply
            let the peer assign whatever IP number it sees fit.
</itemize>

   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 (<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.
   <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=8010<POINTOPOINT,MULTICAST> mtu 1500
</verb></tscreen>

   which in this case shows four tunnel devices, two of which are
   currently configured and being used.  It should be noted that
   the RUNNING flag above indicates that the interface has been
   used as some point - it is not an error if your interface does
   not show up as RUNNING.

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

   The RUNNING flag may not yet be set, in which case you'll see:

<tscreen><verb>
   $ ifconfig tun0
   tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
   $ 
</verb></tscreen>

<sect1><heading>Name Resolution Configuration</heading>

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

<p>The resolver is a set of system calls that do the name mappings, but
   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 (in this order):

<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 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> 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 x.x.x.x
   nameserver y.y.y.y
   domain bar.com
</verb></tscreen>

   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.

<p>If you're running ppp version 2 or greater, the ``enable dns'' command
   will tell ppp to request that your ISP confirms the nameserver values.
   If your ISP supplies different addresses (or if there are no nameserver
   lines in <tt>/etc/resolv.conf</tt>), ppp will rewrite the file with the
   ISP-supplied values.

<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 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 for each PPP session).

<sect2><heading>PPP and Static IP addresses<label id="userppp:staticIP">
       </heading>

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

<tscreen><verb>
1     default:
2       set device /dev/cuaa0
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 "(0123) 456 7890"
7       set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp"
8       set timeout 300
9       set ifaddr x.x.x.x y.y.y.y 255.255.255.0 0.0.0.0
10      add default HISADDR
11      enable dns
</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.  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 ``:'' or ``|'' character as
               a separator.  The difference between these spearators is
               described in the ppp manual page.  To summarize, if you want
               to rotate through the numbers, 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 is of the same chat-like syntax as the dial
               string.  In this example, the string works for a service whose
               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.
	       When you write this script for the first time, you should
	       enable ``chat'' logging to ensure that the conversation is
               going as expected.
            <p>If you're using PAP or CHAP, there will be no login at this
               point, so your login string should 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
               300 seconds of inactivity.  If you never want to timeout,
               set this value to zero.

<tag/Line 9:/  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> mode.

<tag/Line 10:/ 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.

<tag/Line 11:/ This line tells ppp to ask your ISP to confirm that your
               nameserver addresses are correct.  If your ISP supports
               this facility, ppp can then update <tt>/etc/resolv.conf</tt>
               with the correct nameserver entries.
</descrip>

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

<p>Example configuration files can be found in the <tt>/etc/ppp</tt>
   directory.

<sect2><heading>PPP and Dynamic IP addresses<label id="userppp:dynamicIP">
       </heading>

<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 Static IP addresses">, with the following change:

<tscreen><verb>
9       set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
</verb></tscreen>

   Again, 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 9:/  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 always work.

               The last argument (<tt>0.0.0.0</tt>) 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> mode.
</descrip>

<p>If you are running version 1.X of ppp, 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>
1     provider:
2       delete ALL
3       add default HISADDR
</verb></tscreen>

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

<p>Version 2 of ppp introduces ``sticky routes''.  Any <tt>add</tt> or
   <tt>delete</tt> lines that contain <tt>MYADDR</tt> or <tt>HISADDR</tt>
   will be remembered, and any time the actual values of <tt>MYADDR</tt>
   or <tt>HISADDR</tt> change, the routes will be re-applied.  This
   removes the necessity of repeating these lines in <tt>ppp.linkup</tt>.

<sect2><heading>Receiving incoming calls with PPP</heading>

<p>This section describes setting up ppp in a server role.

<p>When you configure <tt>ppp</tt> to receive incoming calls on a
   machine connected to a LAN, you must decide if you wish to forward
   packets to the LAN.  If you do, you should allocate the peer an IP
   number from your LANs subnet, and use the command

<tscreen><verb>
    enable proxy
</verb></tscreen>

   in your <tt>ppp.conf</tt> file.  You should also confirm that the
   <tt>/etc/rc.conf</tt> file (this file used to be called
   <tt>/etc/sysconfig</tt>) contains the following:

<tscreen><verb>
    gateway_enable=YES
</verb></tscreen>

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

<p>You will also need to give them access to one or more sections of the
   configuration file using the <tt>allow</tt> command:

<tscreen><verb>
    allow users fred mary
</verb></tscreen>

   If this command is used in the default section, it gives the specified
   users access to everything.

<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 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<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
   exec /usr/sbin/ppp -direct pap
</verb></tscreen>   

<p>Now create a single configuration entry in <tt>/etc/ppp/ppp.conf</tt>
   that will work for all of your incoming calls:
 
<tscreen><verb>
   pap:
    enable pap
    set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
    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>If you wish to assign some users a static IP number, you can specify
   the number as the third argument in <tt>/etc/ppp/ppp.secret</tt>.  See
   <tt>/etc/ppp/ppp.secret.sample</tt> for examples.

<sect4><heading>MS extentions</heading>

<p>It is possible to configure ppp to supply DNS and NetBIOS nameserver
   addresses on demand.

<p>To enable these extensions with ppp version 1.X, the following lines
   might be added to the relevant section of <tt>/etc/ppp/ppp.conf</tt>:

<tscreen><verb>
    enable msext
    set ns 203.14.100.1 203.14.100.2
    set nbns 203.14.100.5
</verb></tscreen>  

   or for ppp version 2 and above:

<tscreen><verb>
    accept dns
    set dns 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.

<p>In version 2 and above, if the ``set dns'' line is omited, ppp will
   use the values found in <tt>/etc/resolv.conf</tt>.

<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 crackers
   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
.....
12      set authname MyUserName
13      set authkey MyPassword
</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 12:/ This line specifies your PAP/CHAP user name.  You will need
               to insert the correct value for <tt>MyUserName</tt>.
<tag/Line 13:/ This line specifies your PAP/CHAP password.  You will need
               to insert the correct value for <tt>MyPassword</tt>.
               You may want to add an additional line
<tscreen><verb>
15      accept PAP
</verb></tscreen>
               or
<tscreen><verb>
15      accept CHAP
</verb></tscreen>
               to make it obvious that this is the intention, but PAP
               and CHAP are both accepted by default.
</descrip>

<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 diagnostic port has been
   set up.  To do this, add the following line to your configuration:

<tscreen><verb>
        set server /var/run/ppp-tun%d DiagnosticPassword 0177
</verb></tscreen>

   This will tell ppp to listen to the specified unix-domain socket,
   asking clients for the specified password before allowing access.
   The %d in the name is replaced with the tun device number that is
   in use.

<p>Once a socket has been set up, the <tt>pppctl(8)</tt> program may be used
   in scripts that wish to manipulate the running program.

<sect1><heading>Final system configuration<label id="userppp:final">
       </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.  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
   (it's started by 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>

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

<p>After rebooting, 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 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/ppp.conf</tt>.  The
         <tt>pmdemand</tt> example should suffice for most
         ISPs.
   <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/ppp.conf</tt>.  The
         <tt>direct-server</tt> example should suffice.
   <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>This section of the handbook was last updated on Monday Aug 10, 1998
   by &a.brian

<p>Thanks to the following for their input, comments & suggestions:

<p>&a.nik
<p>&a.dirkvangulik
<p>&a.pjc