<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="ppp-and-slip">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured, reorganized, and updated by </contrib>
	<!-- 1 Mar 2000 -->
      </author>
    </authorgroup>
  </chapterinfo>

  <title>PPP and SLIP</title>

  <sect1>
    <title>Synopsis</title>
    <indexterm id="ppp-ppp">
      <primary>PPP</primary>
    </indexterm>
    <indexterm id="ppp-slip">
      <primary>SLIP</primary>
    </indexterm>

    <para>FreeBSD has a number of ways to link one computer to
      another.  To establish a network or Internet connection through a
      dial-up modem, or to allow others to do so through you, requires
      the use of PPP or SLIP.  This chapter describes setting up
      these modem-based communication services in detail.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>How to setup User PPP.</para>
      </listitem>
      <listitem>
	<para>How to setup Kernel PPP.</para>
      </listitem>
      <listitem>
	<para>How to setup <acronym>PPPoE</acronym> (PPP over
	  Ethernet).</para>
      </listitem>
      <listitem>
	<para>How to setup <acronym>PPPoA</acronym> (PPP over
	  ATM).</para>
	</listitem>
      <listitem>
	<para>How to configure and setup a SLIP client and
	  server.</para>
      </listitem>
    </itemizedlist>

    <indexterm id="ppp-ppp-user">
      <primary>PPP</primary>
      <secondary>user PPP</secondary>
    </indexterm>      
    <indexterm id="ppp-ppp-kernel">
      <primary>PPP</primary>
      <secondary>kernel PPP</secondary>
    </indexterm>      
    <indexterm id="ppp-ppp-ethernet">
      <primary>PPP</primary>
      <secondary>over Ethernet</secondary>
    </indexterm>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Be familiar with basic network terminology.</para>
      </listitem>
      <listitem>
	<para>Understand the basics and purpose of a dialup connection
	  and PPP and/or SLIP.</para>
      </listitem>
    </itemizedlist>

    <para>You may be wondering what the main difference is between User
      PPP and kernel PPP.  The answer is simple; user PPP processes the
      inbound and outbound data in userland rather than in the kernel.
      This is expensive in terms of copying the data between the kernel
      and userland, but allows a far more feature-rich ppp implementation.
      User PPP uses the <devicename>tun</devicename> device to communicate
      with the outside world whereas kernel-ppp uses the
      <devicename>ppp</devicename> device.</para>

    <note>
      <para>Throughout in this chapter, user ppp will simply be
	referred to as ppp unless a distinction needs to be made between it
	and any other PPP software such as <command>pppd</command>.
	Unless otherwise stated, all of the commands explained in this
	section should be executed as <username>root</username>.</para>
    </note>
  </sect1>

  <sect1 id="userppp">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Tom</firstname>
          <surname>Rhodes</surname>
          <contrib>Updated and enhanced by </contrib>
        </author>
      </authorgroup>
      <authorgroup>
        <author>
          <firstname>Brian</firstname>
          <surname>Somers</surname>
	  <contrib>Originally contributed by </contrib>
        </author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Nik</firstname>
	  <surname>Clayton</surname>
	  <contrib>With input from </contrib>
        </author>
        <author>
	  <firstname>Dirk</firstname>
          <surname>Fr&ouml;mberg</surname>
        </author>
        <author>
          <firstname>Peter</firstname>
          <surname>Childs</surname>
        </author>
      </authorgroup>
    </sect1info>

    <title>Using User PPP</title>

    <sect2>
      <title>User PPP</title>

      <sect3>
	<title>Assumptions</title>

	<para>This document assumes you have the following:</para>

	<itemizedlist>
	  <indexterm id="ppp-isp">
	    <primary>ISP</primary>
	  </indexterm>
	  <indexterm id="ppp-ppp2">
	    <primary>PPP</primary>
	  </indexterm>
	  <listitem>
	    <para>An account with an Internet Service Provider (ISP) which
	      you connect to using PPP.</para>
	  </listitem>

	  <listitem>
	    <para>Further, you have a modem or
	      other device connected to your system and configured
	      correctly, which allows you to connect to your ISP.</para>
	  </listitem>

	  <listitem>
	    <para>The dial-up number(s) of your ISP.</para>
	  </listitem>

	  <indexterm id="ppp-pap">
	    <primary>PAP</primary>
	  </indexterm>
	  <indexterm id="ppp-chap">
	    <primary>CHAP</primary>
	  </indexterm>
	  <indexterm id="ppp-unix">
	    <primary>Unix</primary>
	  </indexterm>
	  <indexterm id="ppp-login">
	    <primary>login name</primary>
	  </indexterm>
	  <indexterm id="ppp-password">
	    <primary>password</primary>
	  </indexterm>
	  <listitem>
	    <para>Your login name and password. (Either a
	      regular Unix-style login and password pair, or a PAP or CHAP
	      login and password pair.)</para>
	  </listitem>

	  <indexterm id="ppp-nameserver">
	    <primary>nameserver</primary>
	  </indexterm>
	  <listitem>
	    <para>The IP address of one or more name servers.
	      Normally, you will be given two IP addresses by your ISP to
	      use for this.  If they have not given you at least one, then
	      you can use the <command>enable dns</command> command in
	      your <filename>ppp.conf</filename> file to have
	      <application>ppp</application> set the name servers for
	      you.  This feature depends on your ISPs PPP implementation
              supporting DNS negotiation.</para>
	  </listitem>
	</itemizedlist>

	<para>The following information may be supplied by your ISP, but
	  is not completely necessary:</para>

	<itemizedlist>
	  <listitem>
	    <para>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 <emphasis>default route</emphasis>.  If you do not have
	      this information, we can make one up and your ISP's PPP
	      server will tell us the correct value when we connect.</para>

	    <para>This IP number is referred to as
	      <literal>HISADDR</literal> by
	      <application>ppp</application>.</para>
	  </listitem>

	  <listitem>
	    <para>The netmask you should use.  If your ISP has not
	      provided you with one, you can safely use <hostid
	      role="netmask">255.255.255.255</hostid>.</para>
	  </listitem>

	  <indexterm id="ppp-statis-ip">
	    <primary>static IP address</primary>
	  </indexterm>
	  <listitem>
	    <para>If your ISP provides you with a static IP address and
	      hostname, you can enter it.  Otherwise, we simply let the
	      peer assign whatever IP address it sees fit.</para>
	  </listitem>
	</itemizedlist>
 
	<para>If you do not have any of the required information, contact
	  your ISP.</para>

	<note>
	  <para>Throughout this section, many of the examples showing
	    the contents of configuration files are numbered by line.
	    These numbers serve to aid in the presentation and
	    discussion only and are not meant to be placed in the actual
	    file.  Proper indentation with tab and space characters is
	    also important.</para>
	</note>

      </sect3>
    
      <sect3>
	<title>Preparing the Kernel</title>

        <para>As previously mentioned, <application>ppp</application>
          uses the <devicename>tun</devicename> device.  If this device
          has not been compiled into your kernel,
          <application>ppp</application> will load it on demand as a
          module.  The tunnel driver is dynamic, so any number of
          devices may be created (you are not limited by any kernel
          configuration values).</para>

	<note><para>It should be noted that the tunnel driver creates devices
	  on demand, so <command>ifconfig -a</command> will not necessarily
	  show any <devicename>tun</devicename> devices.</para></note>

      </sect3>

      <sect3>
	<title>Check the <devicename>tun</devicename> Device</title>

	<para>Under normal circumstances, most users will only use one
	  <devicename>tun</devicename> device
	  (<devicename>/dev/tun0</devicename>).  References to
	  <devicename>tun0</devicename> below may be changed to
	  <devicename>tunN</devicename> where <literal>N</literal>
	    is any unit number corresponding to your system.</para>

        <para>For FreeBSD installations that do not have DEVFS enabled,
          the existence of the <devicename>tun0</devicename> device should
          be verified (this is not necessary if DEVFS is enabled as device
          nodes will be created on demand).</para>

	<para>The easiest way to make sure that the
	  <devicename>tun0</devicename> device is configured correctly
	  is to remake the device.  To remake the device, do the
          following:</para>

	<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>sh MAKEDEV tun0</userinput></screen>

	<para>If you need 16 tunnel devices in your kernel, you will need
	  to create them.  This can be done by executing the following
	  commands:</para>

	<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>sh MAKEDEV tun15</userinput></screen>

        <sect4>
          <title>Check the Modem</title>
            <para>If you reconfigured your <filename>kernel</filename>
              then you should recall the <devicename>sio</devicename>
              device.  If your modem acts like a standard serial port
              then you most likely only need to make the serial device.
              You can do this by changing your directory to
              <filename>/dev</filename> and running the <filename>MAKEDEV</filename>
              script like above.  Now make the serial device with
<screen>&prompt.root; <userinput>sh MAKEDEV cuaa</userinput></screen>
              which will create the serial devices for your system.
              If your modem is on <devicename>sio1</devicename> or
              <acronym>COM2</acronym> if you are in dos, then your
              modem device would be <devicename>/dev/cuaa1</devicename>.
            </para>
          </sect4>
        </sect3>

      <sect3>
        <title>Manual Connections</title>
          <para>Connecting to the internet by manually controlling
            <command>ppp</command> is quick, easy, and a great way
            to debug a connection or just get information on how your
            <acronym>ISP</acronym> handles connections.  Lets start
            <application>PPP</application> from the command line,
            note that, in all of our examples we will use <emphasis>localhost</emphasis>
            as the hostname of the machine running <application>PPP</application>.
            You start <command>ppp</command> by just typing <command>ppp</command>:

<screen>&prompt.root; <userinput>ppp</userinput></screen>

        <para>We have now started <command>ppp</command></para>

<screen>ppp ON example&gt; set device <devicename>/dev/cuaa1</devicename></screen>

        <para>We set our modem device, in this case it is
          <devicename>cuaa1</devicename></para>

<screen>ppp ON example&gt; set speed 115200</screen>

        <para>Set the connection speed, in this case we
          are using 115,200 <acronym>kbps</acronym></para>

<screen>ppp ON example&gt; enable dns</screen>

        <para>Tell <command>ppp</command> to configure our
          resolver and add the nameserver lines to
          <filename>/etc/resolv.conf</filename>.  If we <command>ppp</command>
          cannot determine our hostname, we can set one manually later
        </para>

<screen>ppp ON example&gt; term</screen>

        <para>Switch to "terminal" mode so that we can manually
          control the modem</para>

<programlisting>
deflink: Entering terminal mode on <devicename>/dev/cuaa1</devicename>
type '~h' for help</programlisting>

<screen><userinput>at</userinput>
OK
<userinput>atdt<replaceable>123456789</replaceable></userinput></screen>

        <para>Use <command>at</command> to initialize the modem,
          then use <command>atdt</command> and the number for your
          <acronym>ISP</acronym> to begin the dial in process</para>

<screen>CONNECT</screen>

        <para>Confirmation of the connection, if we are going to have
          any connection problems, unrelated to hardware, here is where
          we will attempt to resolve them.</para>

<screen>ISP Login:<userinput>myusername</userinput></screen>

        <para>Here you are prompted for a username, return the
          prompt with the username that was provided by the
          <acronym>ISP</acronym></para>

<screen>ISP Pass:<userinput>mypassword</userinput></screen>

        <para>This time we are prompted for a password, just
          reply with the password that was provided by the
          <acronym>ISP</acronym>.  Just like when logging into
          FreeBSD, the password will not echo.</para>

<screen>Shell or PPP:<userinput>ppp</userinput></screen>

        <para>Depending on your <acronym>ISP</acronym> this prompt
          may never appear.  Here we are being asked if we wish to
          use a shell on the provider, or to start
          <command>ppp</command>.  In this example, we have chosen
          to use <command>ppp</command> as we want an internet
          connection.</para>

<screen>Ppp ON example&gt;</screen>

        <para>Notice that in this example the first <option>p</option>
          has been capitalized.  This shows that we have successfully
          connected to the <acronym>ISP</acronym>.</para>

<screen>PPp ON example&gt;</screen>

        <para>We have successfully authenticated with our
          <acronym>ISP</acronym> and are waiting for the
          assigned <acronym>IP</acronym> address.</para>

<screen>PPP ON example&gt;</screen>

        <para>We have made an agreement on an <acronym>IP</acronym>
          address and successfully completed our connection</para>

<screen>PPP ON example&gt;add default HISADDR</screen>

        <para>Here we add our default route, we need to do this
          before we can talk to the outside world as currently the
          only established connection is with the peer.  If this
          fails due to existing routes you can put a bang character
          <emphasis>!</emphasis> in front of the <option>add</option>.
          Alternatively, you can set this before making the actual connection
          and it will negotiate a new route accordingly.</para>

          <para>If everything went good we should now have an active
            connection to the internet, which could be thrown into
            the background using
            <keycombo action="simul"><keycap>CTRL</keycap> <keycap>z</keycap></keycombo>
            If you notice the <command>PPP</command> return to
            <command>ppp</command> then we have lost our connection.
            This is good to know because it shows our connection status.
            Capital P's show that we have a connection to the
            <acronym>ISP</acronym> and lowercase p's show that the
            connection has been lost for whatever reason.
            <command>ppp</command> only has these 2 states.
          </para>

          <sect4>
            <title>Troubleshooting Manual Connections</title>
              <para>Like everything else, once in awhile a problem or
                may occur.  <application>PPP</application> is no
                exemption to this theory.  If <command>ppp</command>
                would happen to stop responding there are some things
                we can try.</para>

              <para>If you have a direct line and cannot seem to make a
                connection, then turn hardware flow <acronym>CTS/RTS</acronym>
                to off with the <option>set ctsrts off</option>.  This is
                mainly the case if you are connected to some
                <application>PPP</application> capable terminal servers,
                where <application>PPP</application> hangs when it tries
                to write data to your communication link, so it would
                would be waiting for a <acronym>CTS</acronym>, or Clear
                To Send signal which may never come.  If you use this
                option however, you should also use the <option>set accmap</option>
                option, which may be required to defeat hardware dependent on
                passing certain characters from end to end, most of the time
                XON/XOFF.  See the &man.ppp.8; man page for more information
                on this option, and how it is used.</para>

              <para>If you have an older modem, you may need to use the
                <option>set parity even</option>.  Parity is set at none
                be default, but is used for error checking (with a large
                increase in traffic) on older modems and some
                <acronym>ISP</acronym>s.  You may need this option for
                the Compuserve ISP.</para>

              <para><application>PPP</application> may not return to the
                command mode, which is usually a negotiation error where
                the <acronym>ISP</acronym> is waiting for your side to start
                negotiating.  At this point, using the <command>~p</command>
                command will force ppp to start sending the configuration
                information.</para>

              <para>If you never obtain a login prompt, then most likely you
                you need to use <acronym>PAP</acronym> or <acronym>CHAP</acronym>
                authentication instead of the Unix-style in the example above.  To
                use <acronym>PAP</acronym> or <acronym>CHAP</acronym> just add the
                following options to <application>PPP</application> before going
                into terminal mode:</para>

<screen>ppp ON localhost&gt; <userinput>set authname <replaceable>myusername</replaceable></userinput></screen>

        <para>Where <replaceable>myusername</replaceable> should be replaced with
          the username that was assigned by the <acronym>ISP</acronym>.</para>

<screen>ppp ON localhost&gt; <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen>

        <para>Where <replaceable>mypassword</replaceable> should be replaced with
          the password that was assigned by the <acronym>ISP</acronym>.</para>

        <para>If you connect fine, but cannot seem to find any domain name, try to
          use &man.ping.8; with an <acronym>IP</acronym> address and see if you
          can get any return information.  If you experience 100 percent (100%)
          packet loss, then its most likely that you were not assigned a default
          route.  Double check that the option <option>add default HISADDR</option>
          was set during the connection.  If you can connect to a remote
          <acronym>IP</acronym> address then it is possible that a resolver address
          has not been added to the <filename>/etc/resolv.conf</filename>.  This
          file should look like:</para>

	  <programlisting>domain <replaceable>example.com</replaceable>
nameserver <replaceable>x.x.x.x</replaceable>
nameserver <replaceable>y.y.y.y</replaceable></programlisting>

        <para>Where <replaceable>x.x.x.x</replaceable> and
          <replaceable>y.y.y.y</replaceable> should be replaced with the
          <acronym>IP</acronym> address of your <acronym>ISP</acronym>'s DNS servers.
          This information may or may not have been provided when you signed up, but
          a quick call to your <acronym>ISP</acronym> should remedy that.</para>

              <para>You could also have &man.syslog.3; provide a logging function
                for your <application>PPP</application> connection.  Just add:</para>

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

              <para>to <filename>/etc/syslog.conf</filename>.  In most cases, this
                functionality already exists.</para>

        </sect4>
      </sect3>

      <sect3>
        <title>Automatic <application>PPP</application> Configuration</title>

	<indexterm><primary>PPP</primary><secondary>configuration</secondary></indexterm>
	<para>Both <command>ppp</command> and <command>pppd</command>
	  (the kernel level implementation of PPP) use the configuration
	  files located in the <filename>/etc/ppp</filename> directory.
          Examples for user ppp can be found in
          <filename>/usr/share/examples/ppp/</filename>.</para>

	<para>Configuring <command>ppp</command> 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
	  changes each time you connect to your ISP).</para>

	<sect4 id="userppp-staticIP">
	  <title>PPP and Static IP Addresses</title>

	  <indexterm><primary>PPP</primary><secondary>with static IP addresses</secondary></indexterm>
	  <para>You will need to edit the
	    <filename>/etc/ppp/ppp.conf</filename> configuration file.  It
            should look similar to the example below.</para>

	  <note>
	    <para>Lines that end in a <literal>:</literal> start in
	      the first column (beginning of the line)&mdash; all other
	      lines should be indented as shown using spaces or
	      tabs.  Most of the information you need to provide here
              was shown to us by doing the manual dial above.</para>
	  </note>

	  <programlisting>1     default:
2       set log Phase Chat LCP IPCP CCP tun command
3       ident user-ppp VERSION (built COMPILATIONDATE)
4       set device /dev/cuaa0
5       set speed 115200
6       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
7                 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
8       set timeout 180
9       enable dns
10
11    provider:
12      set phone "(123) 456 7890"
13      set authname foo
14      set authkey bar
15      set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
16      set timeout 300
17      set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.255 0.0.0.0
18      add default HISADDR</programlisting>

	  <variablelist>
	    <varlistentry>
	      <term>Line 1:</term>

	      <listitem>
		<para>Identifies the default entry.  Commands in this
		  entry are executed automatically when ppp is run.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 2:</term>

	      <listitem>
		<para>Enables logging parameters.  When the configuration
		  is working satisfactorily, this line should be reduced
                  to saying

	          <programlisting>set log phase tun</programlisting>

                  in order to avoid excessive log file sizes.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 3:</term>

	      <listitem>
		<para>Tells PPP how to identify itself to the peer.
                  PPP identifies itself to the peer if it has any trouble
                  negotiating and setting up the link, providing information
                  that the peers administrator may find useful when
                  investigating such problems.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 4:</term>

	      <listitem>
		<para>Identifies the device to which the modem is
		  connected.  <devicename>COM1</devicename> is
		  <devicename>/dev/cuaa0</devicename> and
		  <devicename>COM2</devicename> is
		  <devicename>/dev/cuaa1</devicename>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 5:</term>

	      <listitem>
		<para>Sets the speed you want to connect at.  If 115200
		  does not work (it should with any reasonably new modem),
		  try 38400 instead.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 6 & 7:</term>

	      <indexterm><primary>PPP</primary><secondary>user PPP</secondary></indexterm>
	      <listitem>
		<para>The dial string.  User PPP uses an expect-send
		  syntax similar to the &man.chat.8; program.  Refer to
		  the manual page for information on the features of this
		  language.</para>

		<para>Note that this command continues onto the next line
                   for readability.  Any command in
                   <filename>ppp.conf</filename> may do this if the last
                   character on the line is a ``\'' character.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 8:</term>

	      <listitem>
		<para>Sets the idle timeout for the link.  180 seconds
		  is the default, so this line is purely cosmetic.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 9:</term>

	      <listitem>
		<para>Tells PPP to ask the peer to confirm the local
		  resolver settings.  If you run a local name server, this
                  line should be commented out or removed.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 10:</term>

	      <listitem>
		<para>A blank line for readability.  Blank lines are ignored
		by PPP.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 11:</term>

	      <listitem>
		<para>Identifies an entry for a provider called
		  <quote>provider</quote>.  This could be changed
                    to the name of your <acronym>ISP</acronym> so
                    that later you can use the <option>load ISP</option>
                    to start the connection.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 12:</term>

	      <listitem>
		<para>Sets the phone number for this provider.  Multiple
		  phone numbers may be specified using the colon
		  (<literal>:</literal>) or pipe character
		  (<literal>|</literal>)as a separator.  The difference
		  between the two separators is described in &man.ppp.8;.
		  To summarize, if you want to rotate through the numbers,
		  use a colon.  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 pipe character.  Always
		  quote the entire set of phone numbers as shown.</para>
	    
	      <para>You must enclose the phone number in quotation marks
		(<literal>"</literal>) if there is any intention on using
		spaces in the phone number.  This can cause a simple, yet
		subtle error</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 13 & 14:</term>

	      <listitem>
		<para>Identifies the user name and password.  When connecting
                  using a Unix-style login prompt, these values are referred
                  to by the <command>set login</command> command using the \U
                  and \P variables.  When connecting using PAP or CHAP, these
                  values are used at authentication time.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 15:</term>

	      <listitem>
		<indexterm><primary>PAP</primary></indexterm>
		<indexterm><primary>CHAP</primary></indexterm>
		<para>If you are using PAP or CHAP, there will be no login
		  at this point, and this line should be commented out or
		  removed.  See <link linkend="userppp-PAPnCHAP">PAP and CHAP
		  authentication</link> for further details.</para>

                <para>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:</para>

		<screen>J. Random Provider
login: <replaceable>foo</replaceable>
password: <replaceable>bar</replaceable>
protocol: ppp</screen>

		<para>You will need to alter this script to suit your own
		  needs.  When you write this script for the first time,
		  you should ensure that you have enabled <quote>chat</quote>
                  logging so you can determine if the conversation is going
                  as expected.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 16:</term>

	      <indexterm><primary>timeout</primary></indexterm>
	      <listitem>
		<para>Sets the default idle 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 or use
                  the <option>-ddial</option> command line switch.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 17:</term>
	      <indexterm><primary>ISP</primary></indexterm>
	      <listitem>
		<para>Sets the interface addresses.  The string
		  <replaceable>x.x.x.x</replaceable> should be replaced by
		  the IP address that your provider has allocated to you.
		  The string <replaceable>y.y.y.y</replaceable> should be
		  replaced by the IP address that your ISP indicated for
		  their gateway (the machine to which you connect).  If
		  your ISP has not given you a gateway address, use <hostid
		  role="netmask">10.0.0.2/0</hostid>.  If you need to use
		  a <quote>guessed</quote> address, make sure that you
		  create an entry in
		  <filename>/etc/ppp/ppp.linkup</filename> as per the
		  instructions for <link linkend="userppp-dynamicIP">PPP
		  and Dynamic IP addresses</link>.  If this line is
		  omitted, <command>ppp</command> cannot run in
		  <option>-auto</option> mode.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 18:</term>

	      <listitem>
		<para>Adds a default route to your ISP's gateway.  The
		  special word <literal>HISADDR</literal> is replaced with
		  the gateway address specified on line 9.  It is
		  important that this line appears after line 9,
		  otherwise <literal>HISADDR</literal> will not yet be
		  initialized.</para>

		<para>If you do not wish to run ppp in <option>-auto</option>,
		  this line should be moved to the
                  <filename>ppp.linkup</filename> file.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>It is not necessary to add an entry to
	    <filename>ppp.linkup</filename> when you have a static IP
	    address and are running ppp in <option>-auto</option> mode 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.</para>

	  <para>Example configuration files can be found in the
	    <filename>/usr/share/examples/ppp/</filename> directory.</para>
	</sect4>

	<sect4 id="userppp-dynamicIP">
	  <title>PPP and Dynamic IP Addresses</title>
	  <indexterm><primary>PPP</primary><secondary>with dynamic IP addresses</secondary></indexterm>
	  <indexterm><primary>IPCP</primary></indexterm>
	  <para>If your service provider does not assign static IP
	    addresses, <command>ppp</command> can be configured to
	    negotiate the local and remote addresses.  This is done by
	    <quote>guessing</quote> an IP address and allowing
	    <command>ppp</command> to set it up correctly using the IP
	    Configuration Protocol (IPCP) after connecting.  The
	    <filename>ppp.conf</filename> configuration is the same as
	    <link linkend="userppp-staticIP">PPP and Static IP
	    Addresses</link>, with the following change:</para>

	  <programlisting>17      set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255</programlisting>

	  <para>Again, do not include the line number, it is just for
	    reference.  Indentation of at least one space is
	    required.</para>

	  <variablelist>
	    <varlistentry>
	      <term>Line 17:</term>

	      <listitem>
		<para>The number after the <literal>/</literal> 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.</para>

		<para>The last argument (<literal>0.0.0.0</literal>) tells
		  PPP to start negotiations using address <hostid
		  role="ipaddr">0.0.0.0</hostid> rather than <hostid
		  role="ipaddr">10.0.0.1</hostid> and is necessary for some
                  ISPs.  Do not use <literal>0.0.0.0</literal> as the first
                  argument to <command>set ifaddr</command> as it prevents
                  PPP from setting up an initial route in
                  <option>-auto</option> mode.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>If you are not running in <option>-auto</option> mode, you
	    will need to create an entry in
            <filename>/etc/ppp/ppp.linkup</filename>.
	    <filename>ppp.linkup</filename> is used after a connection has
	    been established.  At this point, <command>ppp</command> will
	    have assigned the interface addresses and it will now be
	    possible to add the routing table entries:</para>

	  <programlisting>1     provider:
2      add default HISADDR</programlisting>

	  <variablelist>
	    <varlistentry>
	      <term>Line 1:</term>

	      <listitem>
		<para>On establishing a connection, <command>ppp</command>
		  will look for an entry in <filename>ppp.linkup</filename>
		  according to the following rules: First, try to match
		  the same label as we used in
		  <filename>ppp.conf</filename>.  If that fails, look for
		  an entry for the IP address of our gateway.  This entry
		  is a four-octet IP style label.  If we still have not
		  found an entry, look for the <literal>MYADDR</literal>
		  entry.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 2:</term>

	      <listitem>
		<para>This line tells <command>ppp</command> to add a
		  default route that points to <literal>HISADDR</literal>.
		  <literal>HISADDR</literal> will be replaced with the IP
		  number of the gateway as negotiated by the IPCP.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>See the <literal>pmdemand</literal> entry in the files
	    <filename>/usr/share/examples/ppp/ppp.conf.sample</filename> and
	    <filename>/usr/share/examples/ppp/ppp.linkup.sample</filename> for a
	    detailed example.</para>
	</sect4>

	<sect4>
	  <title>Receiving Incoming Calls</title>
	  <indexterm><primary>PPP</primary><secondary>receiving
	  incoming calls</secondary></indexterm>
	  <para>When you configure <application>ppp</application> 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 LAN's
	    subnet, and use the command <command>enable proxy</command> in
	    your <filename>/etc/ppp/ppp.conf</filename> file.  You should
	    also confirm that the <filename>/etc/rc.conf</filename> file
	    contains the following:</para>

	  <programlisting>gateway_enable="YES"</programlisting>

	  <sect5>
	    <title>Which getty?</title>

	    <para><link linkend="dialup">Configuring FreeBSD for Dial-up
	      Services</link> provides a good description on enabling
	      dial-up services using &man.getty.8;.</para>

	    <para>An alternative to <command>getty</command> is <ulink
	      url="http://www.leo.org/~doering/mgetty/index.html">mgetty</ulink>,
	      a smarter version of <command>getty</command> designed with
	      dial-up lines in mind.</para>

	    <para>The advantages of using <command>mgetty</command> is
	      that it actively <emphasis>talks</emphasis> to modems,
	      meaning if port is turned off in
	      <filename>/etc/ttys</filename> then your modem will not answer
	      the phone.</para>

	    <para>Later versions of <command>mgetty</command> (from
	      0.99beta onwards) also support the automatic detection of
	      PPP streams, allowing your clients script-less access to
	      your server.</para>

	    <para>Refer to <link linkend="userppp-mgetty">Mgetty and
	      AutoPPP</link> for more information on
	      <command>mgetty</command>.</para>
	  </sect5>

	  <sect5>
	    <title><application>PPP</application> Permissions</title>

	    <para>The <command>ppp</command> command must normally be run
	      as the <username>root</username> user.  If however, you wish
	      to allow
	      <command>ppp</command> to run in server mode as a normal
	      user by executing <command>ppp</command> as described below,
	      that user must be given permission to run
	      <command>ppp</command> by adding them to the
	      <username>network</username> group in
	      <filename>/etc/group</filename>.</para>

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

	    <programlisting>allow users fred mary</programlisting>

	    <para>If this command is used in the <literal>default</literal>
	      section, it gives the specified users access to
	      everything.</para>
	  </sect5>

	  <sect5>
	    <title>PPP Shells for Dynamic-IP Users</title>
	    <indexterm><primary>PPP shells</primary></indexterm>

	    <para>Create a file called
	      <filename>/etc/ppp/ppp-shell</filename> containing the
	      following:</para>

	    <programlisting>#!/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</programlisting>

	    <para>This script should be executable.  Now make a symbolic
	      link called <filename>ppp-dialup</filename> to this script
	      using the following commands:</para>

	    <screen>&prompt.root; <userinput>ln -s ppp-shell /etc/ppp/ppp-dialup</userinput></screen>

	    <para>You should use this script as the
	      <emphasis>shell</emphasis> for all of your dialup users.
	      This is an example from <filename>/etc/password</filename>
	      for a dialup PPP user with username
	      <username>pchilds</username> (remember do not directly edit
	      the password file, use <command>vipw</command>).</para>

	    <programlisting>pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting>

	    <para>Create a <filename>/home/ppp</filename> directory that
	      is world readable containing the following 0 byte
	      files:</para>

	    <screen>-r--r--r--   1 root     wheel           0 May 27 02:23 .hushlogin
-r--r--r--   1 root     wheel           0 May 27 02:22 .rhosts</screen>

	    <para>which prevents <filename>/etc/motd</filename> from being
	      displayed.</para>
	  </sect5>

	  <sect5>
	    <title>PPP Shells for Static-IP Users</title>
	    <indexterm><primary>PPP shells</primary></indexterm>

	    <para>Create the <filename>ppp-shell</filename> file as above,
	      and for each account with statically assigned IPs create a
	      symbolic link to <filename>ppp-shell</filename>.</para>

	    <para>For example, if you have three dialup customers,
	      <username>fred</username>, <username>sam</username>, and
	      <username>mary</username>, that you route class C networks
	      for, you would type the following:</para>

	    <screen>&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred</userinput>
&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam</userinput>
&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary</userinput></screen>

	    <para>Each of these users dialup accounts should have their
	      shell set to the symbolic link created above (for example,
	      <username>mary</username>'s shell should be
	      <filename>/etc/ppp/ppp-mary</filename>).</para>
	  </sect5>

	  <sect5>
	    <title>Setting up ppp.conf for Dynamic-IP Users</title>
	  
	    <para>The <filename>/etc/ppp/ppp.conf</filename> file should
	      contain something along the lines of:</para>
	  
	    <programlisting>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</programlisting>

	    <note>
	      <para>The indenting is important.</para>
	    </note>

	    <para>The <literal>default:</literal> section is loaded for
	      each session.  For each dialup line enabled in
	      <filename>/etc/ttys</filename> create an entry similar to
	      the one for <literal>ttyd0:</literal> above.  Each line
	      should get a unique IP address from your pool of IP
	      addresses for dynamic users.</para>
	  </sect5>

	  <sect5>
	    <title>Setting up <filename>ppp.conf</filename> for Static-IP
	      Users</title>

	    <para>Along with the contents of the sample
	      <filename>/usr/share/examples/ppp/ppp.conf</filename> above you should add
	      a section for each of the statically assigned dialup users.
	      We will continue with our <username>fred</username>,
	      <username>sam</username>, and <username>mary</username>
	      example.</para>

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

	    <para>The file <filename>/etc/ppp/ppp.linkup</filename> should
	      also contain routing information for each static IP user if
	      required.  The line below  would add a route for the <hostid
	      role="ipaddr">203.14.101.0</hostid> class C via  the
	      client's ppp link.</para>

	    <programlisting>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</programlisting>
	  </sect5>
	</sect4>

	<sect4>
	  <title>More on <command>mgetty</command>, AutoPPP, and MS
	    Extensions</title>

	  <sect5 id="userppp-mgetty">
	    <title><command>mgetty</command> and AutoPPP</title>
	    <indexterm>
        <primary><command>mgetty</command></primary>
      </indexterm>
	    <indexterm><primary>AutoPPP</primary></indexterm>
	    <indexterm><primary>LCP</primary></indexterm>

	    <para>Configuring and compiling <command>mgetty</command> with
	      the <literal>AUTO_PPP</literal> option enabled allows
	      <command>mgetty</command> 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.</para>

	    <para>This section assumes the user has successfully
	      configured, compiled, and installed a version of
	      <command>mgetty</command> with the
	      <literal>AUTO_PPP</literal> option (v0.99beta or
	      later).</para>

	    <para>Make sure your
	      <filename>/usr/local/etc/mgetty+sendfax/login.config</filename>
	      file has the following in it:</para>

	    <programlisting>/AutoPPP/ -     -		      /etc/ppp/ppp-pap-dialup</programlisting>

	    <para>This will tell <command>mgetty</command> to run the
	      <filename>ppp-pap-dialup</filename> script for detected PPP
	      connections.</para>

	    <para>Create a file called
	      <filename>/etc/ppp/ppp-pap-dialup</filename> containing the
	      following (the file should be executable):</para>

	    <programlisting>#!/bin/sh
exec /usr/sbin/ppp -direct pap$IDENT</programlisting>

	    <para>For each dialup line enabled in
	      <filename>/etc/ttys</filename>, create a corresponding entry
	      in <filename>/etc/ppp/ppp.conf</filename>.  This will
	      happily co-exist with the definitions we created
	      above.</para>

	    <programlisting>pap:
  enable pap	      
  set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
  enable proxy</programlisting>

	    <para>Each user logging in with this method will need to have
	      a username/password in
	      <filename>/etc/ppp/ppp.secret</filename> file, or
	      alternatively add the following option to authenticate users
	      via PAP from <filename>/etc/password</filename> file.</para>

	    <programlisting>enable passwdauth</programlisting>

	    <para>If you wish to assign some users a static IP number, you
	      can specify the number as the third argument in
	      <filename>/etc/ppp/ppp.secret</filename>.  See
	      <filename>/usr/share/examples/ppp/ppp.secret.sample</filename> for
	      examples.</para>
	  </sect5>

	  <sect5>
	    <title>MS Extensions</title>
	    <indexterm><primary>DNS</primary></indexterm>    
	    <indexterm><primary>NetBIOS</primary></indexterm>
	    <indexterm><primary>PPP</primary><secondary>Microsoft extensions</secondary></indexterm>
	    <para>It is possible to configure PPP to supply DNS and
	      NetBIOS nameserver addresses on demand.</para>

	    <para>To enable these extensions with PPP version 1.x, the
	      following lines might be added to the relevant section of
	      <filename>/etc/ppp/ppp.conf</filename>.</para>

	    <programlisting>enable msext
set ns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5</programlisting>

	    <para>And for PPP version 2 and above:</para>

	    <programlisting>accept dns
set dns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5</programlisting>

	    <para>This will tell the clients the primary and secondary
	      name server addresses, and a NetBIOS nameserver host.</para>

	    <para>In version 2 and above, if the
	      <literal>set dns</literal> line is omitted, PPP will use the
	      values found in <filename>/etc/resolv.conf</filename>.</para>
	  </sect5>
	</sect4>

        <sect4 id="userppp-PAPnCHAP">
	  <title>PAP and CHAP Authentication</title>
	  <indexterm><primary>PAP</primary></indexterm>	    
	  <indexterm><primary>CHAP</primary></indexterm>	    
	  <para>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 <prompt>login:</prompt> prompt when you
	    connect, but will start talking PPP immediately.</para>

	  <para>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 is not much room for crackers to
	    <quote>eavesdrop</quote>.</para>

	  <para>Referring back to the <link linkend="userppp-staticIP">PPP
	    and Static IP addresses</link> or <link
	    linkend="userppp-dynamicIP">PPP and Dynamic IP addresses</link>
	    sections, the following alterations must be made:</para>

	  <programlisting>7       set login
&hellip;
12      set authname <replaceable>MyUserName</replaceable>
13      set authkey <replaceable>MyPassword</replaceable></programlisting>

	  <variablelist>
	    <varlistentry>
	      <term>Line 7:</term>

	      <listitem>
		<para>Your ISP will not normally require that you log into
		  the server if you are using PAP or CHAP.  You must
		  therefore disable your <quote>set login</quote>
		  string.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 12:</term>

	      <listitem>
		<para>This line specifies your PAP/CHAP user name.  You
		  will need to insert the correct value for
		  <replaceable>MyUserName</replaceable>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 13:</term>
	      <indexterm><primary>password</primary></indexterm>
	      <listitem>
		<para>This line specifies your PAP/CHAP password.  You
		  will need to insert the correct value for
		  <replaceable>MyPassword</replaceable>.  You may want to
		  add an additional line, such as:</para>
		    
		<programlisting>15      accept PAP</programlisting>

		<para>or</para>

		<programlisting>15      accept CHAP</programlisting>

		<para>to make it obvious that this is the intention, but
		  PAP and CHAP are both accepted by default.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</sect4>

	<sect4>
	  <title>Changing Your <command>ppp</command> Configuration on the
	    Fly</title>

	  <para>It is possible to talk to the <command>ppp</command>
	    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:</para>

	  <programlisting>set server /var/run/ppp-tun<replaceable>%d</replaceable> DiagnosticPassword 0177</programlisting>

	  <para>This will tell PPP to listen to the specified Unix-domain
	    socket, asking clients for the specified password before
	    allowing access.  The <literal>%d</literal> in the name is
	    replaced with the <devicename>tun</devicename> device number
	    that is in use.</para>

	  <para>Once a socket has been set up, the &man.pppctl.8; program
	    may be used in scripts that wish to manipulate the running
	    program.</para>
	</sect4>
      </sect3>

      <sect3 id="userppp-final">
	<title>Final System Configuration</title>
	<indexterm><primary>PPP</primary><secondary>configuration</secondary></indexterm>

	<para>You now have <command>ppp</command> configured, but there
	  are a few more things to do before it is ready to work.  They
	  all involve editing the <filename>/etc/rc.conf</filename>
	  file.</para>

	<para>Working from the top down in this file, make sure the
	  <literal>hostname=</literal> line is set, e.g.:</para>

	<programlisting>hostname="foo.example.com"</programlisting>

	<para>If your ISP has supplied you with a static IP address and
	  name, it is probably best that you use this name as your host
	  name.</para>

	<para>Look for the <literal>network_interfaces</literal> variable.
	  If you want to configure your system to dial your ISP on demand,
	  make sure the <devicename>tun0</devicename> device is added to
	  the list, otherwise remove it.</para>

	<programlisting>network_interfaces="lo0 tun0" ifconfig_tun0=</programlisting>

	<note>
	  <para>The <literal>ifconfig_tun0</literal> variable should be
	    empty, and a file called
	    <filename>/etc/start_if.tun0</filename> should be created.
	    This file should contain the line:</para>

	  <programlisting>ppp -auto mysystem</programlisting>

	  <para>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 <option>-alias</option> switch.  Refer to the manual page
	    for further details.</para>
	</note>

	<para>Set the router program to <literal>NO</literal> with
	  following line in your
	  <filename>/etc/rc.conf</filename>:</para>

	<programlisting>router_enable="NO"</programlisting>

	<indexterm>
    <primary><application>routed</application></primary>
  </indexterm>
	<para>It is important that the <command>routed</command> daemon is
	  not started (it is started by default), as
	  <command>routed</command> tends to delete the default routing
	  table entries created by <command>ppp</command>.</para>

	<para>It is probably worth your while ensuring that the
	  <literal>sendmail_flags</literal> line does not include the
	  <option>-q</option> option, otherwise
	  <command>sendmail</command> will attempt to do a network lookup
	  every now and then, possibly causing your machine to dial out.
	  You may try:</para>

	<programlisting>sendmail_flags="-bd"</programlisting>

	<indexterm>
    <primary><application>sendmail</application></primary>
  </indexterm>
	<para>The downside of this is that you must force
	  <command>sendmail</command> to re-examine the mail queue
	  whenever the ppp link is up by typing:</para>

	<screen>&prompt.root; <userinput>/usr/sbin/sendmail -q</userinput></screen>

	<para>You may wish to use the <command>!bg</command> command in
	  <filename>ppp.linkup</filename> to do this automatically:</para>

	<programlisting>1     provider:
2       delete ALL
3       add 0 0 HISADDR
4       !bg sendmail -bd -q30m</programlisting>

        <indexterm><primary>SMTP</primary></indexterm>
	<para>If you do not like this, it is possible to set up a
	  <quote>dfilter</quote> to block SMTP traffic.  Refer to the
	  sample files for further details.</para>

	<para>Now the only thing left to do is reboot the machine.</para>

	<para>All that is left is to reboot the machine.  After rebooting,
	  you can now either type:</para>

	<screen>&prompt.root; <userinput>ppp</userinput></screen>

	<para>and then <command>dial provider</command> to start the PPP
	  session, or, if you want <command>ppp</command> to establish
	  sessions automatically when there is outbound traffic (and
	  you have not created the <filename>start_if.tun0</filename>
	  script), type:</para>

	<screen>&prompt.root; <userinput>ppp -auto provider</userinput></screen>
      </sect3>

      <sect3>
	<title>Summary</title>

	<para>To recap, the following steps are necessary when setting up
	  ppp for the first time:</para>

	<para>Client side:</para>

	<procedure>
	  <step>
	    <para>Ensure that the <devicename>tun</devicename> device is
	      built into your kernel.</para>
	  </step>

	  <step>
	    <para>Ensure that the
	      <filename>tun<replaceable>X</replaceable></filename> device
	      file is available in the <filename>/dev</filename>
	      directory.</para>
	  </step>

	  <step>
	    <para>Create an entry in
	      <filename>/etc/ppp/ppp.conf</filename>.  The
	      <filename>pmdemand</filename> example should suffice for
	      most ISPs.</para>
	  </step>

	  <step>
	    <para>If you have a dynamic IP address, create an entry in
	      <filename>/etc/ppp/ppp.linkup</filename>.</para>
	  </step>

	  <step>
	    <para>Update your <filename>/etc/rc.conf</filename>
	      file.</para>
	  </step>

	  <step>
	    <para>Create a <filename>start_if.tun0</filename> script if
	      you require demand dialing.</para>
	  </step>
	</procedure>

	<para>Server side:</para>

	<procedure>
	  <step>
	    <para>Ensure that the <devicename>tun</devicename> device is
	      built into your kernel.</para>
	  </step>

	  <step>
	    <para>Ensure that the
	      <filename>tun<replaceable>X</replaceable></filename> device
	      file is available in the <filename>/dev</filename>
	      directory.</para>
	  </step>

	  <step>
	    <para>Create an entry in <filename>/etc/passwd</filename>
	      (using the &man.vipw.8; program).</para>
	  </step>

	  <step>
	    <para>Create a profile in this users home directory that runs
	      <command>ppp -direct direct-server</command> or
	      similar.</para>
	  </step>

	  <step>
	    <para>Create an entry in
	      <filename>/etc/ppp/ppp.conf</filename>.  The
	      <filename>direct-server</filename> example should
	      suffice.</para>
	  </step>

	  <step>
	    <para>Create an entry in
	      <filename>/etc/ppp/ppp.linkup</filename>.</para>
	  </step>

	  <step>
	    <para>Update your <filename>/etc/rc.conf</filename>
	      file.</para>
	  </step>
	</procedure>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="ppp">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Gennady B.</firstname>
          <surname>Sorokopud</surname>
          <contrib>Parts originally contributed by </contrib>
        </author>
        <author>
          <firstname>Robert</firstname>
          <surname>Huff</surname>
        </author>
      </authorgroup>
    </sect1info>

    <title>Using Kernel PPP</title>

    <sect2>
      <title>Setting up Kernel PPP</title>
      <indexterm><primary>PPP</primary><secondary>kernel PPP</secondary></indexterm>

      <para>Before you start setting up PPP on your machine make sure
	that <command>pppd</command> is located in
	<filename>/usr/sbin</filename> and the directory
	<filename>/etc/ppp</filename> exists.</para>

      <para><command>pppd</command> can work in two modes:</para>

      <orderedlist>
	<listitem>
	  <para>As a <quote>client</quote> &mdash; you want to connect your
	    machine to the outside world via a PPP serial connection or
	    modem line.</para>
	</listitem>

        <indexterm><primary>PPP</primary><secondary>server</secondary></indexterm>
	<listitem>
	  <para>as a <quote>server</quote> &mdash; your machine is located on
	    the network and used to connect other computers using
	    PPP.</para>
	</listitem>
      </orderedlist>

      <para>In both cases you will need to set up an options file
        (<filename>/etc/ppp/options</filename> or
	<filename>~/.ppprc</filename> if you have more than one user on
	your machine that uses PPP).</para>

      <para>You also will need some modem/serial software (preferably
        kermit) so you can dial and establish a connection with the
	remote host.</para>
    </sect2>

    <sect2>
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Trev</firstname>
	    <surname>Roydhouse</surname>
	    <contrib>Based on information provided by </contrib>
	    <!-- Trev.Roydhouse@f401.n711.z3.fidonet.org -->
	  </author>
	</authorgroup>
      </sect2info>
	    
      <title>Using <command>pppd</command> as a Client</title>
      <indexterm><primary>PPP</primary><secondary>client</secondary></indexterm>
      <indexterm><primary>Cisco</primary></indexterm>
      <para>The following <filename>/etc/ppp/options</filename> might be
        used to connect to a CISCO terminal server PPP line.</para>

      <programlisting>crtscts         # enable hardware flow control
modem           # modem control line
noipdefault     # remote PPP server must supply your IP address.
                # if the remote host doesn't send your IP during IPCP
                # negotiation , remove this option
passive         # wait for LCP packets
domain ppp.foo.com      # put your domain name here

:&lt;remote_ip&gt;    # put the IP of remote PPP host here
                # it will be used to route packets via PPP link
                # if you didn't specified the noipdefault option
                # change this line to &lt;local_ip&gt;:&lt;remote_ip&gt;

defaultroute    # put this if you want that PPP server will be your
                # default router</programlisting>

      <para>To connect:</para>

      <indexterm><primary>kermit</primary></indexterm>
      <indexterm><primary>modem</primary></indexterm>
      <procedure>
	<step>
	  <para>Dial to the remote host using kermit (or some other modem
	    program), and enter your user name and password (or whatever
	    is needed to enable PPP on the remote host).</para>
	</step>

	<step>
	  <para>Exit kermit (without hanging up the line).</para>
	</step>

	<step>
	  <para>Enter the following:</para>

	  <screen>&prompt.root; <userinput>/usr/src/usr.sbin/pppd.new/pppd <replaceable>/dev/tty01</replaceable> <replaceable>19200</replaceable></userinput></screen>

	  <para>Be sure to use the appropriate speed and device name.</para>
	</step>
      </procedure>

      <para>Now your computer is connected with PPP.  If the connection
	fails, you can add the <option>debug</option> option to the
	<filename>/etc/ppp/options</filename> file and check messages on
	the console to track the problem.</para>
	  
      <para>Following <filename>/etc/ppp/pppup</filename> script will make
	all 3 stages automatically:</para>

      <programlisting>#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing pppd, PID=' ${pid}
        kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing kermit, PID=' ${pid}
        kill -9 ${pid}
fi

ifconfig ppp0 down
ifconfig ppp0 delete

kermit -y /etc/ppp/kermit.dial
pppd /dev/tty01 19200</programlisting>

      <indexterm><primary>kermit</primary></indexterm>
      <para><filename>/etc/ppp/kermit.dial</filename> is a kermit script
	that dials and makes all necessary authorization on the remote
	host (an example of such a script is attached to the end of this
	document).</para>

      <para>Use the following <filename>/etc/ppp/pppdown</filename> script
        to disconnect the PPP line:</para>

      <programlisting>#!/bin/sh
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ X${pid} != "X" ] ; then
        echo 'killing pppd, PID=' ${pid}
        kill -TERM ${pid}
fi

ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing kermit, PID=' ${pid}
        kill -9 ${pid}
fi

/sbin/ifconfig ppp0 down
/sbin/ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.hup
/etc/ppp/ppptest</programlisting>

      <para>Check to see if PPP is still running by executing
	<filename>/usr/etc/ppp/ppptest</filename>, which should look like
	this:</para>

      <programlisting>#!/bin/sh
pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'`
if [ X${pid} != "X" ] ; then
        echo 'pppd running: PID=' ${pid-NONE}
else
        echo 'No pppd running.'
fi
set -x
netstat -n -I ppp0
ifconfig ppp0</programlisting>

      <para>To hang up the modem, execute
	<filename>/etc/ppp/kermit.hup</filename>, which should
	contain:</para>

      <programlisting>set line /dev/tty01	; put your modem device here
set speed 19200
set file type binary
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none

pau 1
out +++
inp 5 OK
out ATH0\13
echo \13
exit</programlisting>

      <para>Here is an alternate method using <command>chat</command>
	instead of <command>kermit</command>.</para>

      <para>The following two files are sufficient to accomplish a 
	<command>pppd</command>	connection.</para>

      <para><filename>/etc/ppp/options</filename>:</para>

      <programlisting>/dev/cuaa1 115200

crtscts		# enable hardware flow control
modem		# modem control line
connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
noipdefault	# remote PPP serve must supply your IP address.
	        # if the remote host doesn't send your IP during
                # IPCP negotiation, remove this option
passive         # wait for LCP packets
domain &lt;your.domain&gt;	# put your domain name here

:		# put the IP of remote PPP host here
	        # it will be used to route packets via PPP link
                # if you didn't specified the noipdefault option
                # change this line to &lt;local_ip&gt;:&lt;remote_ip&gt;

defaultroute	# put this if you want that PPP server will be
	        # your default router</programlisting>

      <para><filename>/etc/ppp/login.chat.script</filename>:</para>

      <note>
	<para>The following should go on a single line.</para>
      </note>

      <programlisting>ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT&lt;phone.number&gt;
  CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: &lt;login-id&gt;
  TIMEOUT 5 sword: &lt;password&gt;</programlisting>

      <para>Once these are installed and modified correctly, all you need
	to do is run <command>pppd</command>, like so:</para>

      <screen>&prompt.root; <userinput>pppd</userinput></screen>
    </sect2>

    <sect2>
      <title>Using <command>pppd</command> as a Server</title>

      <para><filename>/etc/ppp/options</filename> should contain something
	similar to the following:</para>

      <programlisting>crtscts                         # Hardware flow control
netmask 255.255.255.0           # netmask ( not required )
192.114.208.20:192.114.208.165  # ip's of local and remote hosts
                                # local ip must be different from one
                                # you assigned to the ethernet ( or other )
                                # interface on your machine.
                                # remote IP is ip address that will be 
                                # assigned to the remote machine
domain ppp.foo.com              # your domain
passive                         # wait for LCP
modem                           # modem line</programlisting>

      <para>The following <filename>/etc/ppp/pppserv</filename> script
	will enable tell <application>pppd</application> to behave as a
	server:</para>

      <programlisting>#!/bin/sh 
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing pppd, PID=' ${pid}
        kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing kermit, PID=' ${pid}
        kill -9 ${pid}
fi

# reset ppp interface
ifconfig ppp0 down
ifconfig ppp0 delete

# enable autoanswer mode
kermit -y /etc/ppp/kermit.ans

# run ppp
pppd /dev/tty01 19200</programlisting>

      <para>Use this <filename>/etc/ppp/pppservdown</filename> script to
	stop the server:</para>

      <programlisting>#!/bin/sh 
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing pppd, PID=' ${pid}
        kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
        echo 'killing kermit, PID=' ${pid}
        kill -9 ${pid}
fi
ifconfig ppp0 down
ifconfig ppp0 delete

kermit -y /etc/ppp/kermit.noans</programlisting>

      <para>The following kermit script
	(<filename>/etc/ppp/kermit.ans</filename>) will enable/disable
	autoanswer mode on your modem.  It should look like this:</para>

      <programlisting>set line /dev/tty01
set speed 19200
set file type binary
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none

pau 1
out +++
inp 5 OK
out ATH0\13
inp 5 OK
echo \13
out ATS0=1\13   ; change this to out ATS0=0\13 if you want to disable
                ; autoanswer mod
inp 5 OK
echo \13
exit</programlisting>

      <para>A script named <filename>/etc/ppp/kermit.dial</filename> is
	used for dialing and authenticating on the remote host.  You will
	need to customize it for your needs.  Put your login and password
	in this script; you will also need to change the input statement
	depending on responses from your modem and remote host.</para>

      <programlisting>;
; put the com line attached to the modem here:
;
set line /dev/tty01
;
; put the modem speed here:
;
set speed 19200
set file type binary            ; full 8 bit file xfer
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
set modem hayes
set dial hangup off
set carrier auto                ; Then SET CARRIER if necessary,
set dial display on             ; Then SET DIAL if necessary,
set input echo on
set input timeout proceed
set input case ignore
def \%x 0                       ; login prompt counter
goto slhup

:slcmd                          ; put the modem in command mode
echo Put the modem in command mode.
clear                           ; Clear unread characters from input buffer
pause 1
output +++                      ; hayes escape sequence
input 1 OK\13\10                ; wait for OK
if success goto slhup
output \13
pause 1
output at\13
input 1 OK\13\10
if fail goto slcmd              ; if modem doesn't answer OK, try again

:slhup                          ; hang up the phone
clear                           ; Clear unread characters from input buffer
pause 1
echo Hanging up the phone.
output ath0\13                  ; hayes command for on hook
input 2 OK\13\10
if fail goto slcmd              ; if no OK answer, put modem in command mode

:sldial                         ; dial the number
pause 1
echo Dialing.
output atdt9,550311\13\10               ; put phone number here
assign \%x 0                    ; zero the time counter

:look
clear                           ; Clear unread characters from input buffer
increment \%x                   ; Count the seconds
input 1 {CONNECT }
if success goto sllogin
reinput 1 {NO CARRIER\13\10}
if success goto sldial
reinput 1 {NO DIALTONE\13\10}
if success goto slnodial
reinput 1 {\255}
if success goto slhup
reinput 1 {\127}
if success goto slhup
if < \%x 60 goto look
else goto slhup

:sllogin                        ; login
assign \%x 0                    ; zero the time counter
pause 1
echo Looking for login prompt.

:slloop
increment \%x                   ; Count the seconds
clear                           ; Clear unread characters from input buffer
output \13
;
; put your expected login prompt here:
;
input 1 {Username: }
if success goto sluid
reinput 1 {\255}
if success goto slhup
reinput 1 {\127}
if success goto slhup
if < \%x 10 goto slloop         ; try 10 times to get a login prompt
else goto slhup                 ; hang up and start again if 10 failures

:sluid
;
; put your userid here:
;
output ppp-login\13
input 1 {Password: }
;
; put your password here:
;
output ppp-password\13
input 1 {Entering SLIP mode.}
echo
quit

:slnodial
echo \7No dialtone.  Check the telephone line!\7
exit 1

; local variables:
; mode: csh
; comment-start: "; "
; comment-start-skip: "; "
; end:</programlisting>
    </sect2>
  </sect1>

  <sect1 id="pppoe">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Jim</firstname>
          <surname>Mock</surname>
          <contrib>Contributed (from http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by </contrib>
	</author>
      </authorgroup>
      <!-- 10 Jan 2000 -->
    </sect1info>

    <title>Using <application>PPP</application> over Ethernet (PPPoE)</title>
    <indexterm><primary>PPP</primary><secondary>over Ethernet</secondary></indexterm>
    <indexterm>
      <primary>PPPoE</primary>
      <see>PPP, over Ethernet</see>
    </indexterm>

    <para>This section describes how to set up PPP over Ethernet
      (<acronym>PPPoE</acronym>).</para>

    <sect2>
      <title>Configuring the kernel</title>

      <para>No kernel configuration is necessary for PPPoE any longer.  If
	the necessary netgraph support is not built into the kernel, it will
        be dynamically loaded by <application>ppp</application>.</para>
    </sect2>

    <sect2>
      <title>Setting up <filename>ppp.conf</filename></title>

      <para>Here is an example of a working
        <filename>ppp.conf</filename>:</para>

      <programlisting>default:
  set log Phase tun command # you can add more detailed logging if you wish
  set ifaddr 10.0.0.1/0 10.0.0.2/0

name_of_service_provider:
  set device PPPoE:<replaceable>xl1</replaceable> # replace xl1 with your ethernet device
  set authname YOURLOGINNAME
  set authkey YOURPASSWORD
  set dial
  set login
  add default HISADDR</programlisting>

    </sect2>

    <sect2>
      <title>Running <application>PPP</application></title>

      <para>As <username>root</username>, you can run:</para>

      <screen>&prompt.root; <userinput>ppp -ddial name_of_service_provider</userinput></screen>

    </sect2>

    <sect2>
      <title>Starting <application>PPP</application> at Boot</title>

      <para>Add the following to your <filename>/etc/rc.conf</filename>
        file:</para>

      <programlisting>ppp_enable="YES"
ppp_mode="ddial"
ppp_nat="YES"	# if you want to enable nat for your local network, otherwise NO
ppp_profile="name_of_service_provider"</programlisting>
    </sect2>

    <sect2>
      <title>Using a PPPoE Service tag</title>

      <para>Sometimes it will be necessary to use a service tag to establish
	your connection.  Service tags are used to distinguish between
	different PPPoE servers attached to a given network.</para>

      <para>You should have been given any required service tag information
	in the documentation provided by your ISP.  If you cannot locate
	it there, ask your ISP's tech support personnel.</para>

      <para>As a last resort, you could try the method suggested by the
	<ulink url="http://www.roaringpenguin.com/pppoe/">Roaring Penguin
	PPPoE</ulink> program which can be found in the <link
	linkend="ports">ports collection</link>.  Bear in mind however,
	this may de-program your modem and render it useless, so
	think twice before doing it.  Simply install the program shipped
	with the modem by your provider.  Then, access the
	<literal>System</literal> menu from the program.  The name of your
	profile should be listed there.  It is usually
	<emphasis>ISP</emphasis>.</para>

      <para>The profile name (service tag) will be used in the PPPoE
	configuration entry in <filename>ppp.conf</filename> as the provider
	part of the <command>set device</command> command (see the &man.ppp.8;
	manual page for full details).  It should look like this:</para>

      <programlisting>set device PPPoE:<replaceable>xl1</replaceable>:<replaceable>ISP</replaceable></programlisting>

      <para>Do not forget to change <replaceable>xl1</replaceable>
	to the proper device for your Ethernet card.</para>
      <para>Do not forget to change <replaceable>ISP</replaceable>
	to the profile you have just found above.</para>

      <para>For additional information, see:</para>

      <itemizedlist>
	<listitem>
	  <para><citetitle>Cheaper Broadband with FreeBSD on
	    DSL</citetitle> by Renaud Waldura in <ulink
	    url="http://www.daemonnews.org/200101/pppoe.html">Daemon
	    News</ulink>.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="ppp-3com">

      <title>PPPoE with a 3Com HomeConnect ADSL Modem Dual Link</title>

      <para>This modem does not follow <ulink
	url="http://www.faqs.org/rfcs/rfc2516.html">RFC 2516</ulink>
	(<emphasis>A Method for transmitting PPP over Ethernet
	(PPPoE)</emphasis>, written by L. Mamakos, K. Lidl, J. Evarts,
	D. Carrel, D. Simone, and R. Wheeler).  Instead, different packet
	type codes have been used for the Ethernet frames.  Please complain
	to <ulink url="http://www.3com.com/">3Com</ulink> if you think it
	should comply with the PPPoE specification.</para>

      <para>In order to make FreeBSD capable of communicating with this
	device, a sysctl must be set.  This can be done automatically at
	boot time by updating <filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>net.graph.nonstandard_pppoe=1</programlisting>

      <para>or can be done for immediate effect with the command
	<command>sysctl -w net.graph.nonstandard_pppoe=1</command>.</para>

      <para>Unfortunately, because this is a system-wide setting, it is
	not possible to talk to a normal PPPoE client or server and a
	3Com HomeConnect ADSL Modem at the same time.</para>

    </sect2>
  </sect1>

  <sect1 id="pppoa">
    <title>Using <application>PPP</application> over ATM (PPPoA)</title>
    <indexterm><primary>PPP</primary><secondary>over ATM</secondary></indexterm>
    <indexterm>
      <primary>PPPoA</primary>
      <see>PPP, over ATM</see>
    </indexterm>

    <para>The following describes how to set up PPP over ATM (PPPoA).
      PPPoA is a popular choice among European DSL providers.</para>

    <sect2>
      <title>Using PPPoA with the Alcatel Speedtouch USB</title>

      <para>PPPoA support for this device is supplied as a port in FreeBSD
	because the firmware is distributed under <ulink
	  URL="http://www.alcatel.com/consumer/dsl/disclaimer_lx.htm">Alcatel's
	license agreement</ulink> and can not be redistributed freely with the
	base system of FreeBSD.</para>

      <para>To install the software, simply use the <link
	  linkend="ports">ports collection</link>. Install the
	<filename role="package">net/pppoa</filename> port and follow the
	instructions provided with it.</para>
    </sect2>

    <sect2>
      <title>Using pptpclient</title>
	  
      <para>It is also possible to use FreeBSD to connect to other PPPoA
	services using
	<filename role="package">net/pptpclient</filename>.</para>
	  
      <para>To use <filename role="package">net/pptpclient</filename> to
	connect to a DSL service, install the port or package and edit your
	<filename>/etc/ppp/ppp.conf</filename>. You will need to be
	<username>root</username> to perform both of these operations. An
	example section of <filename>ppp.conf</filename> is given
	below. For further information on <filename>ppp.conf</filename>
	options consult the <application>ppp</application> manual page,
	&man.ppp.8;.</para>

      <programlisting>adsl:
 set log phase chat lcp ipcp ccp tun command
 set timeout 0
 enable dns
 set authname <replaceable>username</replaceable> <co id="co-ex-user">
 set authkey <replaceable>password</replaceable> <co id="co-ex-pass">
 set ifaddr 0 0
 add default HISADDR</programlisting>

   <calloutlist>
     <callout arearefs="co-ex-user">
	   <para>The username of your account with the DSL provider.</para>
	 </callout>
	 <callout arearefs="co-ex-pass">
	   <para>The password for your account.</para>
	 </callout>
   </calloutlist>

   <warning>
     <para>Because you must put your account's password in the
	 <filename>ppp.conf</filename> file in plain text form you should
	 make sure than nobody can read the contents of this file. The
	 following series of commands will make sure the file is only
	 readable by the <username>root</username> account. Refer to the
	 manuals pages for &man.chmod.1; and &man.chown.8; for further
	 information.</para>
	 <screen>&prompt.root; <userinput>chown root:wheel /etc/ppp/ppp.conf</userinput>
&prompt.root; <userinput>chmod 600 /etc/ppp/ppp.conf</userinput></screen>
   </warning>

      <para>This will open a tunnel for a PPP session to your DSL router.
	Ethernet DSL modems have a preconfigured LAN IP address which you
	connect to. In the case of the Alcatel Speedtouch Home this address is
	<hostid role="ipaddr">10.0.0.138</hostid>. Your routers documentation
	should tell you which address your device uses. To open the tunnel and
	start a <application>ppp</application> session execute the following
	command.</para>

      <screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>isp</replaceable></userinput></screen>

      <tip>
	<para>You may wish to add an ampersand (<quote>&amp;</quote>) to the
	  end of the previous command because <application>pptp</application>
	  will not return your prompt to you otherwise.</para>
      </tip>
	  
      <para>A <devicename>tun</devicename> virtual tunnel device will be
	created for interaction between the <application>pptp</application>
	and <application>ppp</application> processes. Once you have been
	returned to your prompt, or the <application>pptp</application>
	process has confirmed a connection you can examine the tunnel like
	so.</para>

      <screen>&prompt.user; <userinput>ifconfig <replaceable>tun0</replaceable></userinput>
tun0: flags=8051&lt;UP,POINTOPOINT,RUNNING,MULTICAST&gt; mtu 1500
        inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 
        Opened by PID 918</screen>

      <para>If you are unable to connect, check the configuration of
	your router, which is usually accessible via
	<application>telnet</application> or with a web browser. If you still
	cannot connect you should examine the output of the
	<application>pptp</application> command and the contents of the
	<application>ppp</application> log file,
	<filename>/var/log/ppp.log</filename> for clues.</para>
    </sect2>
  </sect1>

  <sect1 id="slip">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Satoshi</firstname>
	  <surname>Asami</surname>
	  <contrib>Originally contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Guy</firstname>
	  <surname>Helmer</surname>
	  <contrib>With input from </contrib>
	</author>
	<author>
	  <firstname>Piero</firstname>
          <surname>Serini</surname>
	</author>
      </authorgroup>
    </sect1info>

    <title>Using SLIP</title>
    <indexterm><primary>SLIP</primary></indexterm>

    <sect2 id="slipc">
      <title>Setting up a SLIP Client</title>
      <indexterm><primary>SLIP</primary><secondary>client</secondary></indexterm>
      <para>The following is one way to set up a FreeBSD machine for SLIP
	on a static host network.  For dynamic hostname assignments (your
	address changes each time you dial up), you probably need to
	have a more complex setup.</para>

      <para>First, determine which serial port your modem is connected to.
	Many people setup a symbolic link, such as
	<devicename>/dev/modem</devicename>, to point to the real device name,
	<devicename>/dev/cuaaN</devicename>.  This allows you to
	abstract the actual device name should you ever need to move
	the modem to a different port.  It can become quite cumbersome when you
	need to fix a bunch of files in <filename>/etc</filename> and
	<filename>.kermrc</filename> files all over the system!</para>

      <note>
	<para><filename>/dev/cuaa0</filename> is
	  <devicename>COM1</devicename>, <filename>cuaa1</filename> is
	  <devicename>COM2</devicename>, etc.</para>
      </note>

      <para>Make sure you have the following in your kernel configuration
	file:</para>
      
      <programlisting>pseudo-device   sl      1</programlisting>

      <para>It is included in the <filename>GENERIC</filename> kernel, so
	this should not be a problem unless you have deleted it.</para>

      <sect3>
	<title>Things You Have to Do Only Once</title>

	<procedure>
	  <step>
	    <para>Add your home machine, the gateway and nameservers to
	      your <filename>/etc/hosts</filename> file.  Mine looks like
	      this:</para>

	    <programlisting>127.0.0.1               localhost loghost
136.152.64.181          water.CS.Example.EDU water.CS water
136.152.64.1            inr-3.CS.Example.EDU inr-3 slip-gateway
128.32.136.9            ns1.Example.EDU ns1
128.32.136.12           ns2.Example.EDU ns2</programlisting>
	  </step>

	  <step>
	    <para>Make sure you have <option>hosts</option> before
	      <option>bind</option> in your
	      <filename>/etc/host.conf</filename>.  Otherwise, funny
	      things may happen.</para>
	  </step>

	  <step>
	    <para>Edit the <filename>/etc/rc.conf</filename> file.</para>

	    <orderedlist>
	      <listitem>
		<para>Set your hostname by editing the line that
		  says:</para>
	      
		<programlisting>hostname=<quote>myname.my.domain</quote></programlisting>

		<para>Your machine's full Internet hostname should be
		  placed here.</para>
	      </listitem>

	      <listitem>
		<para>Add <devicename>sl0</devicename> to the list of
		  network interfaces by changing the line that
		  says:</para>

		<programlisting>network_interfaces="lo0"</programlisting>

		<para>to:</para>

		<programlisting>network_interfaces=<quote>lo0 sl0</quote></programlisting>
	      </listitem>

	      <listitem>
		<para>Set the startup flags of sl0 by adding a
		  line:</para>

		<programlisting>ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"</programlisting>
	      </listitem>

	      <indexterm><primary>default route</primary></indexterm>
	      <listitem>
		<para>Designate the default router by changing the
		  line:</para>

		<programlisting>defaultrouter=<quote>NO</quote></programlisting>

		<para>to:</para>

		<programlisting>defaultrouter=<quote>slip-gateway</quote></programlisting>
	      </listitem>
	    </orderedlist>
	  </step>

	  <step>
	    <para>Make a file <filename>/etc/resolv.conf</filename> which
	      contains:</para>

	    <programlisting>domain CS.Example.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12</programlisting>

	    <indexterm><primary>nameserver</primary></indexterm>
	    <indexterm><primary>domain name</primary></indexterm>
	    <para>As you can see, these set up the nameserver hosts.  Of
	      course, the actual domain names and addresses depend on your
	      environment.</para>
	  </step>

	  <step>
	    <para>Set the password for <username>root</username> and 
	      <username>toor</username> (and any other
	      accounts that do not have a password).</para>
	  </step>

	  <step>
	    <para>Reboot your machine and make sure it comes up with the
	      correct hostname.</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
	<title>Making a SLIP Connection</title>
	<indexterm><primary>SLIP</primary><secondary>connecting with</secondary></indexterm>
	<procedure>
	  <step>
	    <para>Dial up, type <command>slip</command> at the prompt,
	      enter your machine name and password.  What is required to
	      be entered depends on your environment.  If you use
	      kermit, you can try a script like this:</para>

	    <programlisting># kermit setup
set modem hayes
set line /dev/modem
set speed 115200
set parity none
set flow rts/cts
set terminal bytesize 8
set file type binary
# The next macro will dial up and login
define slip dial 643-9600, input 10 =&gt;, if failure stop, -
output slip\x0d, input 10 Username:, if failure stop, -
output silvia\x0d, input 10 Password:, if failure stop, -
output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>

	    <para>Of course, you have to change the hostname and password
	      to fit yours.  After doing so, you can just type
	      <command>slip</command> from the kermit prompt to
	      connect.</para>

	    <note>
	      <para>Leaving your password in plain text anywhere in the
	        filesystem is generally a <emphasis>bad</emphasis> idea.
		Do it at your own risk.</para>
	    </note>
	  </step>

	  <step>
	    <para>Leave the kermit there (you can suspend it by
	      <keycombo>
		<keycap>Ctrl</keycap>
		<keycap>z</keycap>
	      </keycombo>) and as <username>root</username>, type:</para>

	    <screen>&prompt.root; <userinput>slattach -h -c -s 115200 /dev/modem</userinput></screen>

	    <para>If you are able to <command>ping</command> hosts on the
	      other side of the router, you are connected!  If it does not
	      work, you might want to try <option>-a</option> instead of
	      <option>-c</option> as an argument to 
              <command>slattach</command>.</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
	<title>How to Shutdown the Connection</title>

	<para>Do the following:</para>

	<screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen>

	<para>to kill <command>slattach</command>.  Keep in mind you must be
	  <username>root</username> to do the above.  Then go back to
	  kermit (by running <command>fg</command> if you suspended it) and
	  exit from
	  it (<command>q</command>).</para>

	<para>The <command>slattach</command> manual page says you have 
	  to use <command>ifconfig sl0 down</command> 
          to mark the interface down, but this does not
	  seem to make any difference for me.
	  (<command>ifconfig sl0</command> reports the same thing.)</para>

	<para>Some times, your modem might refuse to drop the carrier
	  (mine often does).  In that case, simply start kermit and quit
	  it again. It usually goes out on the second try.</para>
      </sect3>

      <sect3>
	<title>Troubleshooting</title>

	<para>If it does not work, feel free to ask me.  The things that
	  people tripped over so far:</para>

	<itemizedlist>
	  <listitem>
	    <para>Not using <option>-c</option> or <option>-a</option> in
	      <command>slattach</command> (This should not be fatal,
	      but some users have reported that this solves their
	      problems.)</para>
	  </listitem>

	  <listitem>
	    <para>Using <option>s10</option> instead of
	      <option>sl0</option> (might be hard to see the difference on
	      some fonts).</para>
	  </listitem>

	  <listitem>
	    <para>Try <command>ifconfig sl0</command> to see your
	      interface status.  For example, you might get:</para>

	    <screen>&prompt.root; <userinput>ifconfig sl0</userinput>
sl0: flags=10&lt;POINTOPOINT&gt;
        inet 136.152.64.181 --&gt; 136.152.64.1 netmask ffffff00</screen>
	  </listitem>

	  <listitem>
	    <para>Also, <command>netstat -r</command> will give the
	      routing table, in case you get the <quote>no route to
	      host</quote> messages from ping.  An example shown here:</para>

	    <screen>&prompt.root; <userinput>netstat -r</userinput>
Routing tables
Destination      Gateway            Flags     Refs     Use  IfaceMTU    Rtt    Netmasks:

(root node)
(root node)

Route Tree for Protocol Family inet:
(root node) =&gt;
default          inr-3.Example.EDU  UG          8   224515  sl0 -      -
localhost.Exampl localhost.Example. UH          5    42127  lo0 -       0.438
inr-3.Example.ED water.CS.Example.E UH          1        0  sl0 -      -
water.CS.Example localhost.Example. UGH        34 47641234  lo0 -       0.438
(root node)</screen>

	    <para>This is after the link has been up for a while, the numbers
	      on your system will vary.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>

    <sect2 id="slips">
      <title>Setting up a SLIP Server</title>
      <indexterm><primary>SLIP</primary><secondary>server</secondary></indexterm>

      <para>This document provides suggestions for setting up SLIP Server
	services on a FreeBSD system, which typically means configuring
	your system to automatically startup connections upon login for
	remote SLIP clients.</para>

      <!-- Disclaimer is not necessarily relevant
      <para> The author has written this document based
	on his experience; however, as your system and needs may be
	different, this document may not answer all of your questions, and
	the author cannot be responsible if you damage your system or lose
	data due to attempting to follow the suggestions here.</para>
      -->

      <sect3 id="slips-prereqs">
	<title>Prerequisites</title>
	<indexterm><primary>TCP/IP networking</primary></indexterm>
	<para>This section is very technical in nature, so background
	  knowledge is required.  It is assumed that you are familiar with
	  the TCP/IP network protocol, and in particular, network and node
	  addressing, network address masks, subnetting, routing, and
	  routing protocols, such as RIP.  Configuring SLIP services on a
	  dial-up server requires a knowledge of these concepts, and if
	  you are not familiar with them, please read a copy of either
	  Craig Hunt's <emphasis>TCP/IP Network Administration</emphasis>
	  published by O'Reilly &amp; Associates, Inc. (ISBN Number
	  0-937175-82-X), or Douglas Comer's books on the TCP/IP
	  protocol.</para>

	<indexterm><primary>modem</primary></indexterm>
	<para>It is further assumed that you have already setup your
	  modem(s) and configured the appropriate system files to allow
	  logins through your modems.  If you have not prepared your
	  system for this yet, please see the tutorial for configuring
	  dialup services; if you have a World-Wide Web browser available,
	  browse the list of tutorials at <ulink
	  url="../../../../index.html">http://www.FreeBSD.org/</ulink>.
	  You may also want to check the manual pages for &man.sio.4; for
	  information on the serial port device driver and &man.ttys.5;,
	  &man.gettytab.5;, &man.getty.8;, &amp; &man.init.8; for
	  information relevant to configuring the system to accept logins
	  on modems, and perhaps &man.stty.1; for information on setting
	  serial port parameters (such as <literal>clocal</literal> for
	  directly-connected serial interfaces).</para>
      </sect3>

      <sect3>
	<title>Quick Overview</title>

	<para>In its typical configuration, using FreeBSD as a SLIP server
	  works as follows:  a SLIP user dials up your FreeBSD SLIP Server
	  system and logs in with a special SLIP login ID that uses
	  <filename>/usr/sbin/sliplogin</filename> as the special user's
	  shell.  The <command>sliplogin</command> program browses the
	  file <filename>/etc/sliphome/slip.hosts</filename> to find a
	  matching line for the special user, and if it finds a match,
	  connects the serial line to an available SLIP interface and then
	  runs the shell script
	  <filename>/etc/sliphome/slip.login</filename> to configure the
	  SLIP interface.</para>

        <sect4>
	  <title>An Example of a SLIP Server Login</title>

	  <para>For example, if a SLIP user ID were
	    <username>Shelmerg</username>, <username>Shelmerg</username>'s
	    entry in <filename>/etc/master.passwd</filename> would look
	    something like this:</para>

	  <programlisting>Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin</programlisting>

	  <para>When <username>Shelmerg</username> logs in,
	    <command>sliplogin</command> will search
	    <filename>/etc/sliphome/slip.hosts</filename> for a line that
	    had a matching user ID; for example, there may be a line in
	    <filename>/etc/sliphome/slip.hosts</filename> that
	    reads:</para>

	  <programlisting>Shelmerg        dc-slip sl-helmer       0xfffffc00		  autocomp</programlisting>

	  <para><command>sliplogin</command> will find that matching line,
	    hook the serial line into the next available SLIP interface,
	    and then execute <filename>/etc/sliphome/slip.login</filename>
	    like this:</para>

	  <programlisting>/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting>

	  <para>If all goes well,
	    <filename>/etc/sliphome/slip.login</filename> will issue an
	    <command>ifconfig</command> for the SLIP interface to which
	    <command>sliplogin</command> attached itself (slip interface
	    0, in the above example, which was the first parameter in the
	    list given to <filename>slip.login</filename>) to set the
	    local IP address (<hostid>dc-slip</hostid>), remote IP address
	    (<hostid>sl-helmer</hostid>), network mask for the SLIP
	    interface (<hostid role="netmask">0xfffffc00</hostid>), and
	    any additional flags (<literal>autocomp</literal>).  If
	    something goes wrong, <command>sliplogin</command> usually
	    logs good informational messages via the
	    <literal>daemon</literal> syslog facility, which usually logs
	    to <filename>/var/log/messages</filename> (see the manual
	    pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps
	    check <filename>/etc/syslog.conf</filename> to see to what
	    <command>syslogd</command> is logging and where it is
	    logging to.</para>

	  <para>OK, enough of the examples &mdash; let us dive into
	    setting up the system.</para>
	</sect4>
      </sect3>

      <sect3>
	<title>Kernel Configuration</title>
	<indexterm><primary>kernel</primary><secondary>configuration</secondary></indexterm>
	<para>FreeBSD's default kernels usually come with two SLIP
	  interfaces defined (<devicename>sl0</devicename> and
	  <devicename>sl1</devicename>); you can use <command>netstat
	  -i</command> to see whether these interfaces are defined in your
	  kernel.</para>

	<para>Sample output from <command>netstat -i</command>:</para>

	<screen>Name  Mtu   Network     Address            Ipkts Ierrs    Opkts Oerrs  Coll
ed0   1500  &lt;Link&gt;0.0.c0.2c.5f.4a         291311     0   174209     0   133
ed0   1500  138.247.224 ivory             291311     0   174209     0   133
lo0   65535 &lt;Link&gt;                            79     0       79     0     0
lo0   65535 loop        localhost             79     0       79     0     0
sl0*  296   &lt;Link&gt;                             0     0        0     0     0
sl1*  296   &lt;Link&gt;                             0     0        0     0     0</screen>

	<para>The <devicename>sl0</devicename> and
	  <devicename>sl1</devicename> interfaces shown from
	  <command>netstat -i</command> indicate that there are
	  two SLIP interfaces built into the kernel.  (The asterisks after
	  the <literal>sl0</literal> and <literal>sl1</literal> indicate
	  that the interfaces are <quote>down</quote>.)</para>

	<para>However, FreeBSD's default kernel does not come configured
	  to forward packets (by default, your FreeBSD machine will not act
	  as a
	  router) due to Internet RFC requirements for Internet hosts (see
	  RFCs 1009 [Requirements for Internet Gateways], 1122
	  [Requirements for Internet Hosts &mdash; Communication Layers],
	  and perhaps 1127 [A Perspective on the Host Requirements RFCs]).
	  If you want your FreeBSD SLIP Server to act as a router, you
	  will have to edit the <filename>/etc/rc.conf</filename> file and
	  change the setting of the <literal>gateway_enable</literal> variable to
	  <option>YES</option>.</para>
 
	<para>You will then need to reboot for the new settings to take
	  effect.</para>

	<para>You will notice that near the end of the default kernel
	  configuration file (<filename>/sys/i386/conf/GENERIC</filename>)
	  is a line that reads:</para>

	<programlisting>pseudo-device sl 2</programlisting>

	<indexterm><primary>SLIP</primary></indexterm>
	<para>This is the line that defines the number of SLIP devices
	  available in the kernel; the number at the end of the line is
	  the maximum number of SLIP connections that may be operating
	  simultaneously.</para>

	<para>Please refer to <xref linkend="kernelconfig"> on
	  Configuring the FreeBSD Kernel for help in
	  reconfiguring your kernel.</para>
      </sect3>

      <sect3>
	<title>Sliplogin Configuration</title>

	<para>As mentioned earlier, there are three files in the
	  <filename>/etc/sliphome</filename> directory that are part of
	  the configuration for <filename>/usr/sbin/sliplogin</filename>
	  (see &man.sliplogin.8; for the actual manual page for
	  <command>sliplogin</command>): <filename>slip.hosts</filename>,
	  which defines the SLIP users &amp; their associated IP
	  addresses; <filename>slip.login</filename>, which usually just
	  configures the SLIP interface; and (optionally)
	  <filename>slip.logout</filename>, which undoes
	  <filename>slip.login</filename>'s effects when the serial
	  connection is terminated.</para>

        <sect4>
	  <title><filename>slip.hosts</filename> Configuration</title>

	  <para><filename>/etc/sliphome/slip.hosts</filename> contains
	    lines which have at least four items separated by
	    whitespace:</para>

	  <itemizedlist>
	    <listitem>
	      <para>SLIP user's login ID</para>
	    </listitem>

	    <listitem>
	      <para>Local address (local to the SLIP server) of the SLIP
		link</para>
	    </listitem>

	    <listitem>
	      <para>Remote address of the SLIP link</para>
	    </listitem>

	    <listitem>
	      <para>Network mask</para>
	    </listitem>
	  </itemizedlist>

	  <para>The local and remote addresses may be host names (resolved
	    to IP addresses by <filename>/etc/hosts</filename> or by the
	    domain name service, depending on your specifications in
	    <filename>/etc/host.conf</filename>), and the
	    network mask may be a name that can be resolved by a lookup
	    into <filename>/etc/networks</filename>.  On a sample system,
	    <filename>/etc/sliphome/slip.hosts</filename> looks like
	    this:</para>

	  <programlisting>#
# login local-addr      remote-addr     mask            opt1    opt2 
#                                               (normal,compress,noicmp)
#
Shelmerg  dc-slip       sl-helmerg      0xfffffc00      autocomp</programlisting>

	  <para>At the end of the line is one or more of the
	    options.</para>

	  <itemizedlist>
	    <listitem>
	      <para><option>normal</option> &mdash; no header
		compression</para>
	    </listitem>

	    <listitem>
	      <para><option>compress</option> &mdash; compress
		headers</para>
	    </listitem>

	    <listitem>
	      <para><option>autocomp</option> &mdash; compress headers if
		the remote end allows it</para>
	    </listitem>

	    <listitem>
	      <para><option>noicmp</option> &mdash; disable ICMP packets
		(so any <quote>ping</quote> packets will be dropped instead
		of using up your bandwidth)</para>
	    </listitem>
	  </itemizedlist>

  	  <indexterm><primary>SLIP</primary></indexterm>
  	  <indexterm><primary>TCP/IP networking</primary></indexterm>
	  <para>Your choice of local and remote addresses for your SLIP
	    links depends on whether you are going to dedicate a TCP/IP
	    subnet or if you are going to use <quote>proxy ARP</quote> on
	    your SLIP server (it is not <quote>true</quote> proxy ARP, but
	    that is the terminology used in this section to describe it).
	    If you are not sure which method to select or how to assign IP
	    addresses, please refer to the TCP/IP books referenced in
	    the SLIP Prerequisites (<xref linkend="slips-prereqs">)
	    and/or consult your IP network manager.</para>

  	  <indexterm>
        <primary><command>gated</command></primary>
      </indexterm>
	  <para>If you are going to use a separate subnet for your SLIP
	    clients, you will need to allocate the subnet number out of
	    your assigned IP network number and assign each of your SLIP
	    client's IP numbers out of that subnet.  Then, you will
	    probably either need to configure a static route to the SLIP
	    subnet via your SLIP server on your nearest IP router, or
	    install <command>gated</command> on your FreeBSD SLIP server
	    and configure it to talk the appropriate routing protocols to
	    your other routers to inform them about your SLIP server's
	    route to the SLIP subnet.</para>

  	  <indexterm><primary>Ethernet</primary></indexterm>
	  <para>Otherwise, if you will use the <quote>proxy ARP</quote>
	    method, you will need to assign your SLIP client's IP
	    addresses out of your SLIP server's Ethernet subnet, and you
	    will also need to adjust your
	    <filename>/etc/sliphome/slip.login</filename> and
	    <filename>/etc/sliphome/slip.logout</filename> scripts to use
	    &man.arp.8; to manage the proxy-ARP entries in the SLIP
	    server's ARP table.</para>
	</sect4>

	<sect4>
	  <title><filename>slip.login</filename> Configuration</title>

	  <para>The typical <filename>/etc/sliphome/slip.login</filename>
	    file looks like this:</para>

	  <programlisting>#!/bin/sh -
#
#       @(#)slip.login  5.1 (Berkeley) 7/1/90

#
# generic login file for a slip line.  sliplogin invokes this with
# the parameters:
#      1        2         3        4          5         6     7-n
#   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 inet $4 $5 netmask $6</programlisting>

	  <para>This <filename>slip.login</filename> file merely runs
	    <command>ifconfig</command> for the appropriate SLIP interface
	    with the local and remote addresses and network mask of the
	    SLIP interface.</para>

	  <para>If you have decided to use the <quote>proxy ARP</quote>
	    method (instead of using a separate subnet for your SLIP
	    clients), your <filename>/etc/sliphome/slip.login</filename>
	    file will need to look something like this:</para>

	  <programlisting>#!/bin/sh -
#
#       @(#)slip.login  5.1 (Berkeley) 7/1/90

#
# generic login file for a slip line.  sliplogin invokes this with
# the parameters:
#      1        2         3        4          5         6     7-n
#   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 inet $4 $5 netmask $6 
# Answer ARP requests for the SLIP client with our Ethernet addr
/usr/sbin/arp -s $5 00:11:22:33:44:55 pub</programlisting>

	  <para>The additional line in this
	    <filename>slip.login</filename>, <command>arp -s
	    &#36;5 00:11:22:33:44:55 pub</command>, creates an ARP entry
	    in the SLIP server's ARP table.  This ARP entry causes the
	    SLIP server to respond with the SLIP server's Ethernet MAC
	    address whenever another IP node on the Ethernet asks to
	    speak to the SLIP client's IP address.</para>

  	  <indexterm><primary>Ethernet</primary><secondary>MAC address</secondary></indexterm>
	  <para>When using the example above, be sure to replace the
	    Ethernet MAC address (<hostid
	    role="mac">00:11:22:33:44:55</hostid>) with the MAC address of
	    your system's Ethernet card, or your <quote>proxy ARP</quote>
	    will definitely not work!  You can discover your SLIP server's
	    Ethernet MAC address by looking at the results of running
	    <command>netstat -i</command>; the second line of the output
	    should look something like:</para>

	  <screen>ed0   1500  &lt;Link&gt;0.2.c1.28.5f.4a         191923	0   129457     0   116</screen>

	  <para>This indicates that this particular system's Ethernet MAC
	    address is <hostid role="mac">00:02:c1:28:5f:4a</hostid>
	    &mdash; the periods in the Ethernet MAC address given by
	    <command>netstat -i</command> must be changed to colons and
	    leading zeros should be added to each single-digit hexadecimal
	    number to convert the address into the form that &man.arp.8;
	    desires; see the manual page on &man.arp.8; for complete
	    information on usage.</para>

	  <note>
	    <para>When you create
	      <filename>/etc/sliphome/slip.login</filename> and
	      <filename>/etc/sliphome/slip.logout</filename>, the
	      <quote>execute</quote> bit (<command>chmod 755
	      /etc/sliphome/slip.login /etc/sliphome/slip.logout</command>)
	      must be set, or <command>sliplogin</command> will be unable
	      to execute it.</para>
	  </note>
	</sect4>

	<sect4>
	  <title><filename>slip.logout</filename> Configuration</title>

	  <para><filename>/etc/sliphome/slip.logout</filename> is not
	    strictly needed (unless you are implementing <quote>proxy
	    ARP</quote>), but if you decide to create it, this is an
	    example of a basic
	    <filename>slip.logout</filename> script:</para>

	  <programlisting>#!/bin/sh -
#
#       slip.logout

#
# logout file for a slip line.  sliplogin invokes this with
# the parameters:
#      1        2         3        4          5         6     7-n
#   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 down</programlisting>

	  <para>If you are using <quote>proxy ARP</quote>, you will want to
	    have <filename>/etc/sliphome/slip.logout</filename> remove the
	    ARP entry for the SLIP client:</para>

	  <programlisting>#!/bin/sh -
#
#       @(#)slip.logout

#
# logout file for a slip line.  sliplogin invokes this with
# the parameters:
#      1        2         3        4          5         6     7-n
#   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 down
# Quit answering ARP requests for the SLIP client
/usr/sbin/arp -d $5</programlisting>

	  <para>The <command>arp -d &#36;5</command> removes the ARP entry
	    that the <quote>proxy ARP</quote>
	    <filename>slip.login</filename> added when the SLIP client
	    logged in.</para>

	  <para>It bears repeating: make sure
	    <filename>/etc/sliphome/slip.logout</filename> has the execute
	    bit set after you create it (ie, <command>chmod 755
	    /etc/sliphome/slip.logout</command>).</para>
	</sect4>
      </sect3>

      <sect3>
	<title>Routing Considerations</title>
	<indexterm>
    <primary>SLIP</primary>
    <secondary>routing</secondary>
  </indexterm>
	<para>If you are not using the <quote>proxy ARP</quote> method for
	  routing packets between your SLIP clients and the rest of your
	  network (and perhaps the Internet), you will probably either
	  have to add static routes to your closest default router(s) to
	  route your SLIP client subnet via your SLIP server, or you will
	  probably need to install and configure <command>gated</command>
	  on your FreeBSD SLIP server so that it will tell your routers
	  via appropriate routing protocols about your SLIP subnet.</para>

	<sect4>
	  <title>Static Routes</title>
	  <indexterm><primary>static routes</primary></indexterm>
	  <para>Adding static routes to your nearest default routers can
	    be troublesome (or impossible if you do not have authority to
	    do so...).  If you have a multiple-router network in your
	    organization, some routers, such as those made by Cisco and Proteon, may
	    not only need to be configured with the static route to the
	    SLIP subnet, but also need to be told which static routes to
	    tell other routers about, so some expertise and
	    troubleshooting/tweaking may be necessary to get
	    static-route-based routing to work.</para>
	</sect4>

	<sect4>
	  <title>Running <command>gated</command></title>
	  <indexterm>
      <primary><application>gated</application></primary>
    </indexterm>
	  <para>An alternative to the headaches of static routes is to
	    install <command>gated</command> on your FreeBSD SLIP server
	    and configure it to use the appropriate routing protocols
	    (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP
	    subnet.  You can use <command>gated</command> from the <link
	    linkend="ports">ports collection</link> or retrieve and build
	    it yourself from <ulink
	    url="ftp://ftp.gated.merit.edu/research.and.development/gated/">the
	    GateD anonymous FTP site</ulink>; the current version
	    as of this writing is
	    <filename>gated-R3_5Alpha_8.tar.Z</filename>, which includes
	    support for FreeBSD <quote>out-of-the-box</quote>.  Complete
	    information and documentation on <command>gated</command> is
	    available on the Web starting at <ulink
	    url="http://www.gated.merit.edu/">the Merit GateD
	    Consortium</ulink>.  Compile and install it, and then write a
	    <filename>/etc/gated.conf</filename> file to configure your
	    gated; here is a sample, similar to what the author used on a
	    FreeBSD SLIP server:</para>

	  <programlisting>#
# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5
# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface
#
#
# tracing options
#
traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ;

rip yes {
  interface sl noripout noripin ;
  interface ed ripin ripout version 1 ;
  traceoptions route ;
} ;

#
# Turn on a bunch of tracing info for the interface to the kernel:
kernel {
  traceoptions remnants request routes info interface ;
} ;

#
# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP
#

export proto rip interface ed {
  proto direct {
      <replaceable>xxx.xxx.yy</replaceable> mask 255.255.252.0 metric 1; # SLIP connections
  } ;
} ;

#
# Accept routes from RIP via ed Ethernet interfaces
	      
import proto rip interface ed {
  all ;
} ;</programlisting>

          <indexterm><primary>RIP</primary></indexterm>
	  <para>The above sample <filename>gated.conf</filename> file
	    broadcasts routing information regarding the SLIP subnet
	    <replaceable>xxx.xxx.yy</replaceable> via RIP onto the
	    Ethernet; if you are using a different Ethernet driver than
	    the <devicename>ed</devicename> driver, you will need to
	    change the references to the <devicename>ed</devicename>
	    interface appropriately.  This sample file also sets up
	    tracing to <filename>/var/tmp/gated.output</filename> for
	    debugging <command>gated</command>'s activity; you can
	    certainly turn off the tracing options if
	    <command>gated</command> works OK for you.  You will need to
	    change the <replaceable>xxx.xxx.yy</replaceable>'s into the
	    network address of your own SLIP subnet (be sure to change the
	    net mask in the <literal>proto direct</literal> clause as
	    well).</para>

	  <para>Once you have installed and configured
	    <command>gated</command> on your system, you will need to
	    tell the FreeBSD startup scripts to run
	    <command>gated</command> in place of
	    <command>routed</command>.  The easiest way to accomplish
	    this is to set the <varname>router</varname> and
	    <varname>router_flags</varname> variables in
	    <filename>/etc/rc.conf</filename>.  Please see the manual
	    page for <command>gated</command> for information on
	    command-line parameters.</para>
        </sect4>
      </sect3>
    </sect2>
  </sect1>
</chapter>

<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
