path: root/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml

<!--
     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml,v 1.29 2000/10/13 21:07:01 jim Exp $
-->

<chapter id="ppp-and-slip">
  <title>PPP and SLIP</title>

  <para><emphasis>Restructured, reorganized, and updated by &a.jim;,
    1 March 2000.</emphasis></para>

  <sect1>
    <title>Synopsis</title>

    <para>If you are connecting to the Internet via modem, or wish to
      provide dial-up connections to the Internet for others using FreeBSD,
      you have the option of using PPP or SLIP.</para>
      
    <para>This chapter covers three varieties of PPP;
      <emphasis>user</emphasis>, <emphasis>kernel</emphasis>, and
      <emphasis>PPPoE</emphasis> (PPP over Ethernet).  It also covers
      setting up a SLIP client and server.</para>

    <para>The first variety of PPP that will be covered is User PPP.  User
      PPP was introduced into FreeBSD in 2.0.5-RELEASE as an addition to
      the already existing kernel implementation of PPP.</para>

    <para>You may be wondering what the main difference is between User
      PPP and kernel PPP.  The answer is simple; user PPP does not run as
      a daemon, and can run as and when desired.  No PPP interface needs
      to be compiled into their kernel; it runs as a user process, and uses
      the tunnel device driver (<devicename>tun</devicename>) to get data
      into and out of the kernel.</para>

    <para>From here on out in this chapter, user ppp will simply be
      referred to as ppp unless a distinction needs to be made between it
      and 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 root.</para>
  </sect1>

  <sect1 id="userppp">
    <title>Using User PPP</title>

    <para><emphasis>Originally contributed by &a.brian;, with input
      from &a.nik;, &a.dirkvangulik;, and &a.pjc;.</emphasis></para>

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

      <sect3>
	<title>Assumptions</title>

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

	<itemizedlist>
	  <listitem>
	    <para>An account with an Internet Service Provider (ISP) which
	      you connect to using PPP.  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>

	  <listitem>
	    <para>Your login name and password.  This can be either a
	      regular UNIX-style login and password pair, or a PAP or CHAP
	      login and password pair.</para>
	  </listitem>

	  <listitem>
	    <para>The IP address(es) 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 tell
	      <application>ppp</application> to set the name servers for
	      you.</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.0</hostid>.</para>
	  </listitem>

	  <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 and make sure they provide it to you.</para>
      </sect3>
    
      <sect3>
	<title>Preparing the Kernel</title>

        <para>As previously mentioned, <application>ppp</application>
          uses the <devicename>tun</devicename> device, and whichever kernel
          you are using must have <devicename>tun</devicename> configured.
          The <devicename>tun</devicename> device is preconfigured
          for the default <filename>GENERIC</filename> kernel that ships
          with FreeBSD.  However, if you have installed a custom kernel,
          you must make sure your kernel is configured for ppp.</para>

	<para>To check, go to your kernel compile directory
	  (<filename>/sys/i386/conf</filename> or
	  <filename>/sys/pc98/conf</filename>) and examine your
	  configuration file.  It should have the following line somewhere
	  in it:</para>

	<programlisting>
pseudo-device	tun	1</programlisting>

	<para>If this line is not present, you will need to add it to the
	  configuration file and recompile your kernel.  The stock
	  <filename>GENERIC</filename> kernel has this included, so if you
	  have not installed a custom kernel or do not have a
	  <filename>/sys</filename> directory, you do not have to change
	  anything.  If you do need to recompile your kernel, please refer
	  to the <link linkend="kernelconfig">kernel configuration</link>
	  section for more information.</para>

	<para>You can check how many tunnel devices your current kernel
	  has by typing the following:</para>
	  
	<screen>&prompt.root; <userinput>ifconfig -a</userinput>
tun0: flags=8051&lt;UP,POINTOPOINT,RUNNING,MULTICAST&gt; mtu 1500
        inet 200.10.100.1 --&gt; 203.10.100.24 netmask 0xffffffff
tun1: flags=8050&lt;POINTOPOINT,RUNNING,MULTICAST&gt; mtu 576
tun2: flags=8051&lt;UP,POINTOPOINT,RUNNING,MULTICAST&gt; mtu 1500
        inet 203.10.100.1 --&gt; 203.10.100.20 netmask 0xffffffff
tun3: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1500</screen>

	<note>
	  <para>In FreeBSD 4.0 and later releases, you will only see any
	    <devicename>tun</devicename> devices which have already been
	    used.  This means you might not see <emphasis>any</emphasis>
	    <devicename>tun</devicename> devices.  If this is the case, do
	    not worry; the device should be created dynamically when
	    <command>ppp</command> attempts to use it.</para>
	</note>

	<para>This case shows four tunnel devices, two of which are
	  currently configured and being used.  It should be noted that
	  the <literal>RUNNING</literal> flag above indicates that the
	  interface has been used at some point&mdash;it is not an error
	  if your interface does not show up as
	  <literal>RUNNING</literal>.</para>

	<para>If for some reason you have a kernel that does not have the
	  <devicename>tun</devicename> device in it and cannot recompile
	  the kernel, all is not lost.  You should be able to dynamically
	  load the code.  Please refer to the appropriate
	  &man.modload.8; and &man.lkm.4; man pages for further
	  details.</para>
      </sect3>

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

	<para>Under normal circumstances, most users will only require one
	  <devicename>tun</devicename> device
	  (<filename>/dev/tun0</filename>).  If you have specified more
	  than one on the <literal>pseudo-device</literal> line for
	  <devicename>tun</devicename> in your kernel configuration file,
	  then alter all references to <devicename>tun0</devicename> below
	  to reflect whichever device number you are using (e.g.,
	  <devicename>tun2</devicename>).</para>

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

	<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>./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>./MAKEDEV tun15</userinput></screen>

	<para>To confirm that the kernel is configured correctly, issue
	  the follow command and compare the results:</para>

	<screen>&prompt.root; <userinput>ifconfig tun0</userinput>
tun0: flags=8050&lt;POINTOPOINT,RUNNING,MULTICAST&gt; mut 1500</screen>

	<para>The <literal>RUNNING</literal> flag may not yet be set, in
	  which case you will see:</para>

	<screen>&prompt.root; <userinput>ifconfig tun0</userinput>
tun0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1500</screen>

	<para>Remember from earlier that you might not see the device if it
	  has not been used yet, as <devicename>tun</devicename> devices are
	  created on demand in FreeBSD 4.0 and later releases.</para>
      </sect3>

      <sect3>
	<title>Name Resolution Configuration</title>

	<para>The resolver is the part of the system that turns IP
	  addresses into hostnames and vice versa.  It can be configured
	  to look for maps that describe IP to hostname mappings in one of
	  two places.  The first is a file called
	  <filename>/etc/hosts</filename>.  Read &man.hosts.5; for more
	  information.  The second is the Internet Domain Name Service
	  (DNS), a distributed data base, the discussion of which is
	  beyond the scope of this document.</para>

	<para>The resolver is a set of system calls that do the name
	  mappings, but you have to tell them where to find their
	  information.  You do this by first editing the file
	  <filename>/etc/host.conf</filename>.  Do <emphasis>not</emphasis>
	  call this file <filename>/etc/hosts.conf</filename> (note the
	  extra <literal>s</literal>) as the results can be
	  confusing.</para>

	<sect4>
	  <title>Edit <filename>/etc/host.conf</filename></title>

	  <para>This file should contain the following two lines (in this
	    order):</para>

	  <programlisting>
hosts
bind</programlisting>

	  <para>These instruct the resolver to first look in the file
	    <filename>/etc/hosts</filename>, and then to consult the DNS
	    if the name was not found.</para>
	</sect4>
      
	<sect4>
	  <title>Edit <filename>/etc/hosts</filename></title>

	  <para>This file should contain the IP addresses and names of
	    machines on your network.  At a bare minimum it should contain
	    entries for the machine which will be running ppp.  Assuming
	    that your machine is called <hostid
	    role="fqdn">foo.bar.com</hostid> with the IP address <hostid
	    role="ipaddr">10.0.0.1</hostid>,
	    <filename>/etc/hosts</filename> should contain:</para>

	  <programlisting>
127.0.0.1	localhost.bar.com	localhost
127.0.0.1	localhost.bar.com.
10.0.0.1	foo.bar.com		foo
10.0.0.1	foo.bar.com.</programlisting>

	  <para>The first two lines define the alias
	    <hostid>localhost</hostid> as a synonym for the current
	    machine.  Regardless of your own IP address, the IP address
	    for this line should always be <hostid
	    role="ipaddr">127.0.0.1</hostid>.  The second two lines map
	    the name <hostid role="fqdn">foo.bar.com</hostid> (and the
	    shorthand <hostid>foo</hostid>) to the IP address <hostid
	    role="ipaddr">10.0.0.1</hostid>.</para>

	  <para>If your provider allocates you a static IP address and
	    name, use them in place of the <hostid
	    role="ipaddr">10.0.0.1</hostid> entry.</para>
	</sect4>

	<sect4>
	  <title>Edit <filename>/etc/resolv.conf</filename></title>

	  <para>The <filename>/etc/resolv.conf</filename> file tells the
	    resolver how to behave.  If you are running your own DNS, you
	    may leave this file empty.  Normally, you will need to enter
	    the following line(s):</para>

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

	  <para>The <hostid
	    role="ipaddr"><replaceable>x.x.x.x</replaceable></hostid> and 
	    <hostid role="ipaddr"><replaceable>y.y.y.y</replaceable></hostid>
	    addresses are those given to you by your ISP.  Add as many
	    <literal>nameserver</literal> lines as your ISP provides.  The
	    <literal>domain</literal> line defaults to your hostname's
	    domain, and is probably unnecessary.  Refer to the
	    &man.resolv.conf.5; manual page for details of other possible
	    entries in this file.</para>

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

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

	<para>Both <command>ppp</command> and <command>pppd</command>
	  (the kernel level implementation of PPP) use the configuration
	  files located in the <filename>/usr/share/examples/ppp</filename> directory.
	  The sample configuration files provided are a good reference,
	  so do not delete them.</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>

	  <para>You will need to create a configuration file called
	    <filename>/etc/ppp/ppp.conf</filename>.  It should look
	    similar to the example below.</para>

	  <note>
	    <para>Lines that end in a <literal>:</literal> start in the
	      first column, all other lines should be indented as shown
	      using spaces or tabs.</para>
	  </note>

	  <programlisting>
1     default:
2       set device /dev/cuaa0
3       set speed 115200
4       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT"
5     provider:
6       set phone "(123) 456 7890"
7       set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp"
8       set timeout 300
9       set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.0 0.0.0.0
10      add default HISADDR	  
11      enable dns</programlisting>

	  <para>Do not include the line numbers, they are just for
	    reference in this discussion.</para>

	  <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>Identifies the device to which the modem is
		  connected.  <devicename>COM1</devicename> is
		  <filename>/dev/cuaa0</filename> and
		  <devicename>COM2</devicename> is
		  <filename>/dev/cuaa1</filename>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 3:</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 4:</term>

	      <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>
	      </listitem>
	    </varlistentry>

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

	      <listitem>
		<para>Identifies an entry for a provider called
		  <quote>provider</quote>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 6:</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>
	      </listitem>
	    </varlistentry>

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

	      <listitem>
		<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 enable <quote>chat</quote> logging to ensure
		  that the conversation is going as expected.</para>

		<para>If you are using PAP or CHAP, there will be no login
		  at this point, so your login string can be left blank.
		  See <link linkend="userppp-PAPnCHAP">PAP and CHAP
		  authentication</link> for further details.</para>
	      </listitem>
	    </varlistentry>

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

	      <listitem>
		<para>Sets the default timeout (in seconds) for the
		  connection.  Here, the connection will be closed
		  automatically after 300 seconds of inactivity.  If you
		  never want to timeout, set this value to zero.</para>
	      </listitem>
	    </varlistentry>

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

	      <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 hasn't 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> or <option>-dynamic</option>
		  mode.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 10:</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>
	      </listitem>
	    </varlistentry>

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

	      <listitem>
		<para>This line tells PPP to ask your ISP to confirm that
		  your nameserver addresses are correct.  If your ISP
		  supports this facility, PPP can then update
		  <filename>/etc/resolv.conf</filename> with the correct
		  nameserver entries.</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 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>

	  <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>
9      set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0</programlisting>

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

	  <variablelist>
	    <varlistentry>
	      <term>Line 9:</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 negotiate using address <hostid
		  role="ipaddr">0.0.0.0</hostid> rather than <hostid
		  role="ipaddr">10.0.0.1</hostid>.  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 running version 1.x of PPP, you will also 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
	    know what IP addresses should <emphasis>really</emphasis> be
	    used.  The following entry will delete the existing bogus
	    routes, and create correct ones:</para>

	  <programlisting>
1     provider:
2      delete ALL
3      add 0 0 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 delete all
		  of the existing routes for the acquired
		  <devicename>tun</devicename> interface (except the
		  direct route entry).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>Line 3:</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 in the IPCP.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>See the pmdemand 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>

	  <para>Version 2 of PPP introduces <quote>sticky routes</quote>.
	    Any <literal>add</literal> or <literal>delete</literal> lines
	    that contain <literal>MYADDR</literal> or
	    <literal>HISADDR</literal> will be remembered, and any time
	    the actual values of <literal>MYADDR</literal> or
	    <literal>HISADDR</literal> change, the routes will be
	    reapplied.  This removes the necessity of repeating these
	    lines in <filename>ppp.linkup</filename>.</para>
	</sect4>

	<sect4>
	  <title>Receiving Incoming Calls</title>

	  <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="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 getty.</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 user id 0.  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>

	    <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 don't 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>

	    <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 (i.e.,
	      <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>
	    
	    <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>
	    
	    <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>

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

	  <para>As always, do not include the line numbers, they are just
	    for reference in this discussion.  Indentation of at least one
	    space is required.</para>

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

	      <listitem>
		<para>Your ISP will not normally require that you log into
		  the server if you're 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>

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

	<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.bar.com"</programlisting>

	<para>If your ISP has supplied you with a static IP address and
	  name, it's probably best that you use this name as your host
	  name.</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>

	<para>It is important that the <command>routed</command> daemon is
	  not started (it is started by default), as it
	  <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>

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

	<para>If you don't 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">
    <title>Using Kernel PPP</title>

    <para><emphasis>Parts originally contributed by &a.gena; and
      &a.rhuff;.</emphasis></para>

    <sect2>
      <title>Setting up Kernel PPP</title>

      <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>, i.e., you want to connect your
	    machine to the outside world via a PPP serial connection or
	    modem line.</para>
	</listitem>

	<listitem>
	  <para>as a <quote>server</quote>, i.e. 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>
      <title>Using <command>pppd</command> as a client</title>

      <para>I used the following <filename>/etc/ppp/options</filename> to
	connect to 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>
      
      <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>

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

      <para>This sample is based primarily on information provided by:
	Trev Roydhouse &lt;Trev.Roydhouse@f401.n711.z3.fidonet.org&gt;
	and used with permission.</para>
    </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">
    <title>Using PPP over Ethernet (PPPoE)</title>

    <para><emphasis>Contributed by &a.jim;  (from <ulink
      url="http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html">node.to</ulink>) 10 Jan 2000.</emphasis></para>

    <para>The following describes how to set up PPP over Ethernet, a.k.a,
      PPPoE.</para>

    <sect2>
      <title>Prerequisites</title>

      <para>There are a few requirements that your system will need to meet
        in order for PPPoE to function properly.  They are:</para>

      <itemizedlist>
        <listitem>
          <para>Kernel source for FreeBSD 3.4 or later</para>
        </listitem>

        <listitem>
          <para><application>ppp</application> from FreeBSD 3.4 or later</para>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Kernel Configuration</title>

      <para>You will need to set the following options in your kernel
        configuration file and then <link linkend="kernelconfig">compile a new
        kernel</link>.</para>

      <itemizedlist>
        <listitem>
          <para>options NETGRAPH</para>
        </listitem>
      </itemizedlist>

      <para>Optionally, you can add</para>

      <itemizedlist>
        <listitem>
          <para>options NETGRAPH_PPPOE</para>
        </listitem>
        <listitem>
          <para>options NETGRAPH_SOCKET</para>
        </listitem>
      </itemizedlist>

      <para>
        although if this functionality is not available at runtime,
        <application>ppp</application> will load the relevant modules
        on demand
      </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: # or name_of_service_provider
  set device PPPoE:xl1 # replace xl1 with your ethernet device
  set mru 1492
  set mtu 1492
  set authname YOURLOGINNAME
  set authkey YOURPASSWORD
  set log Phase tun command # you can add more detailed logging if you wish
  set dial
  set login
  set ifaddr 10.0.0.1/0 10.0.0.2/0
  add default HISADDR
  nat enable yes # if you want to enable nat for your local net

papchap:
  set authname YOURLOGINNAME
  set authkey YOURPASSWORD</programlisting>

      <para>
        Care should be taken when running <ulink
	  url="../FAQ/ppp.html#PPPoEwithNAT">PPPoE with the
          <option>-nat</option> option</ulink>.
      </para>

    </sect2>

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

      <para>As root, 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"
ppp_profile="default" # or your provider</programlisting>
    </sect2>
  </sect1>

  <sect1 id="slip">
    <title>Using SLIP</title>

    <para><emphasis>Originally contributed by &a.asami; and
      &a.ghelmer;, with input from &a.wilko; and
      &a.piero;.</emphasis></para>

    <sect2 id="slipc">
      <title>Setting up a SLIP Client</title>

      <para>The following is one way to set up a FreeBSD machine for SLIP
	on a static host network.  For dynamic hostname assignments (i.e.,
	your address changes each time you dial up), you probably need to
	do something much fancier.</para>

      <para>First, determine which serial port your modem is connected to.
	I have a symbolic link to <filename>/dev/modem</filename> from
	<filename>/dev/cuaa1</filename>, and only use the modem name in
	my configuration files.  It can become quite cumbersome when you
	need to fix a bunch of files in <filename>/etc</filename> and
	<filename>.kermrc</filename>'s 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          silvia.HIP.Berkeley.EDU silvia.HIP silvia
136.152.64.1            inr-3.Berkeley.EDU inr-3 slip-gateway
128.32.136.9            ns1.Berkeley.edu ns1
128.32.136.12           ns2.Berkeley.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>You should give it your full Internet
		  hostname.</para>
	      </listitem>

	      <listitem>
		<para>Add sl0 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>

	      <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 HIP.Berkeley.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12</programlisting>

	    <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 root and toor (and any other
	      accounts that do not have a password).  Use passwd or
	      &man.vipw.8;, do not edit the
	      <filename>/etc/passwd</filename> or
	      <filename>/etc/master.passwd</filename> files!</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>

	<procedure>
	  <step>
	    <para>Dial up, type <command>slip</command> at the prompt,
	      enter your machine name and password.  The things you need
	      to enter depends on your environment.  I use kermit, with 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 get
	      connected.</para>

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

	  <step>
	    <para>Leave the kermit there (you can suspend it by
	      <command>z</command>) and as root, 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 slattach.</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 slattach.  Keep in mind you must be
	  <username>root</username> to do the above.  Then go back to
	  kermit (<command>fg</command> if you suspended it) and exit from
	  it (<command>q</command>).</para>

	<para>The slattach man 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
	      slattach (I have no idea why this can be fatal, but adding
	      this flag solved the problem for at least one
	      person).</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.  I 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.  Mine looks like:</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.Berkeley.EDU UG          8   224515  sl0 -      -
localhost.Berkel localhost.Berkeley UH          5    42127  lo0 -       0.438
inr-3.Berkeley.E silvia.HIP.Berkele UH          1        0  sl0 -      -
silvia.HIP.Berke localhost.Berkeley UGH        34 47641234  lo0 -       0.438
(root node)</screen>

	    <para>This is after transferring a bunch of files, your
	      numbers should be smaller).</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>

    <sect2 id="slips">
      <title>Setting up a SLIP Server</title>

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

	<para>This document 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>

	<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="http://www.FreeBSD.org/">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 (except it would be all on one
	    line):</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 goes
	    into <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 which
	    files <command>syslogd</command> is logging).</para>

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

      <sect3>
	<title>Kernel Configuration</title>

	<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 in
	  <command>netstat -i</command>'s output 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 kernels do not come configured
	  to forward packets (ie, 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]),
	  so 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>

	<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 <link linkend="kernelconfig">Configuring the
	  FreeBSD Kernel</link> 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 I believe 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>

	  <para>Note that <command>sliplogin</command> under early releases
	    of FreeBSD 2 ignored the options that FreeBSD 1.x recognized,
	    so the options <option>normal</option>,
	    <option>compress</option>, <option>autocomp</option>, and
	    <option>noicmp</option> had no effect until support was added
	    in FreeBSD 2.2 (unless your <filename>slip.login</filename>
	    script included code to make use of the flags).</para>

	  <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 document 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
	    <link linkend="slips-prereqs">slips-prereqs</link> section
	    and/or consult your IP network manager.</para>

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

	  <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
	    <command>ifconfig</command>'s 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 a another IP node on the Ethernet asks to
	    speak to the SLIP client's IP address.</para>

	  <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 (ie, <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 for after you create it (ie, <command>chmod 755
	    /etc/sliphome/slip.logout</command>).</para>
	</sect4>
      </sect3>

      <sect3>
	<title>Routing Considerations</title>

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

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

	  <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>; I believe 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>

	  <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>When you get <command>gated</command> built and installed
	    and create a configuration file for it, you will need to run
	    <command>gated</command> in place of <command>routed</command>
	    on your FreeBSD system; change the
	    <filename>routed/gated</filename> startup parameters in
	    <filename>/etc/netstart</filename> as appropriate for your
	    system.  Please see the manual page for
	    <command>gated</command> for information on
	    <command>gated</command>'s 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:
-->