<?xml version="1.0" encoding="iso-8859-1"?>
<!--
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 id="ppp-and-slip-synopsis">
<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 set up user PPP.</para>
</listitem>
<listitem>
<para>How to set up kernel PPP (&os; 7.X only).</para>
</listitem>
<listitem>
<para>How to set up <acronym>PPPoE</acronym> (PPP over
Ethernet).</para>
</listitem>
<listitem>
<para>How to set up <acronym>PPPoA</acronym> (PPP over
ATM).</para>
</listitem>
<listitem>
<para>How to configure and set up a SLIP client and
server (&os; 7.X only).</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 <application>ppp</application> unless a
distinction needs to be made between it and any other PPP
software such as <application>pppd</application>
(&os; 7.X only). Unless otherwise stated, all of the
commands explained in this chapter 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ömberg</surname>
</author>
<author>
<firstname>Peter</firstname>
<surname>Childs</surname>
</author>
</authorgroup>
</sect1info>
<title>Using User PPP</title>
<warning>
<para>As of &os; 8.0, device nodes for serial ports have been
renamed from
<filename>/dev/cuad<replaceable>N</replaceable></filename> to
<filename>/dev/cuau<replaceable>N</replaceable></filename> and
from
<filename>/dev/ttyd<replaceable>N</replaceable></filename> to
<filename>/dev/ttyu<replaceable>N</replaceable></filename>.
&os; 7.X users will have to adapt the following
documentation according to these changes.</para>
</warning>
<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>A modem or
other device connected to your system and properly
configured to allow you to connect to your ISP.</para>
</listitem>
<listitem>
<para>The dial-up number(s) of your ISP.</para>
</listitem>
<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>
<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>
<listitem>
<indexterm id="ppp-nameserver">
<primary>nameserver</primary>
</indexterm>
<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 <filename>ppp.conf</filename>
and <application>ppp</application> will 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>
<listitem>
<indexterm id="ppp-static-ip">
<primary>static IP address</primary>
</indexterm>
<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>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, &os; 7.X only)
use the configuration files located in the <filename
class="directory">/etc/ppp</filename> directory.
Examples for user ppp can be found in <filename
class="directory">/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)— all
other lines should be indented as shown using spaces
or tabs.</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/cuau0
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:</para>
<programlisting>set log phase tun</programlisting>
<para>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
<filename class="devicefile">/dev/cuau0</filename>
and
<devicename>COM2</devicename> is
<filename
class="devicefile">/dev/cuau1</filename>.</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>
<listitem>
<indexterm>
<primary>PPP</primary>
<secondary>user PPP</secondary>
</indexterm>
<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 <literal>\</literal>
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
<replaceable>ISP</replaceable></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>
<listitem>
<indexterm><primary>timeout</primary></indexterm>
<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>
<listitem>
<indexterm><primary>ISP</primary></indexterm>
<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 17. It
is important that this line appears after line 17,
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
class="directory">/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 0.0.0.0</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>
</sect4>
<sect4>
<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://mgetty.greenie.net/">mgetty</ulink> (from
<filename role="package">comms/mgetty+sendfax</filename>
port), 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>
</sect4>
<sect4>
<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 <groupname>network</groupname>
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>
</sect4>
<sect4>
<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/passwd</filename>
for a dialup PPP user with username
<username>pchilds</username> (remember do not directly
edit the password file, use &man.vipw.8;).</para>
<programlisting>pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting>
<para>Create a <filename
class="directory">/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>
</sect4>
<sect4>
<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 /24 CIDR
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>
</sect4>
<sect4>
<title>Setting Up <filename>ppp.conf</filename> 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
ttyu0:
set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
enable proxy
ttyu1:
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>ttyu0:</literal> above. Each
line should get a unique IP address from your pool of
IP addresses for dynamic users.</para>
</sect4>
<sect4>
<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/24</hostid>
network 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>
</sect4>
<sect4 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>By default the <filename
role="package">comms/mgetty+sendfax</filename> port
comes with the <literal>AUTO_PPP</literal> option enabled
allowing <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
compiled, and installed the <filename
role="package">comms/mgetty+sendfax</filename> port on
his system.</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 the <filename>/etc/passwd</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>
</sect4>
<sect4>
<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>
</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>13 set authname <replaceable>MyUserName</replaceable>
14 set authkey <replaceable>MyPassword</replaceable>
15 set login</programlisting>
<variablelist>
<varlistentry>
<term>Line 13:</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 14:</term>
<listitem>
<indexterm><primary>password</primary></indexterm>
<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>16 accept PAP</programlisting>
<para>or</para>
<programlisting>16 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>
<varlistentry>
<term>Line 15:</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>
</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-nat">
<title>Using PPP Network Address Translation
Capability</title>
<indexterm>
<primary>PPP</primary><secondary>NAT</secondary>
</indexterm>
<para>PPP has ability to use internal NAT without kernel
diverting capabilities. This functionality may be enabled
by the following line in
<filename>/etc/ppp/ppp.conf</filename>:</para>
<programlisting>nat enable yes</programlisting>
<para>Alternatively, PPP NAT may be enabled by command-line
option <literal>-nat</literal>. There is also
<filename>/etc/rc.conf</filename> knob named
<literal>ppp_nat</literal>, which is enabled by
default.</para>
<para>If you use this feature, you may also find useful
the following <filename>/etc/ppp/ppp.conf</filename> options
to enable incoming connections forwarding:</para>
<programlisting>nat port tcp 10.0.0.2:ftp ftp
nat port tcp 10.0.0.2:http http</programlisting>
<para>or do not trust the outside at all</para>
<programlisting>nat deny_incoming yes</programlisting>
</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>Make sure that the router program is set to
<literal>NO</literal> with the 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, as <command>routed</command> tends
to delete the default routing table entries created by
<command>ppp</command>.</para>
<para>It is probably a good idea to ensure 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>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
class="devicefile">tun<replaceable>N</replaceable></filename>
device file is available in the <filename
class="directory">/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
class="devicefile">tun<replaceable>N</replaceable></filename>
device file is available in the <filename
class="directory">/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>
<warning>
<para>This section applies and is valid only for
&os; 7.X.</para>
</warning>
<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 class="directory">/usr/sbin</filename> and the
directory <filename class="directory">/etc/ppp</filename>
exists.</para>
<para><command>pppd</command> can work in two modes:</para>
<orderedlist>
<listitem>
<para>As a <quote>client</quote> — you want to connect
your machine to the outside world via a PPP serial
connection or modem line.</para>
</listitem>
<listitem>
<indexterm>
<primary>PPP</primary>
<secondary>server</secondary>
</indexterm>
<para>As a <quote>server</quote> — your machine is
located on the network, and is 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 will also need some modem/serial software (preferably
<filename role="package">comms/kermit</filename>), 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 does not send your IP during IPCP
# negotiation, remove this option
passive # wait for LCP packets
domain ppp.foo.com # put your domain name here
:<replaceable>remote_ip</replaceable> # 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 <replaceable>local_ip</replaceable>:<replaceable>remote_ip</replaceable>
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
<application>Kermit</application> (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 <application>Kermit</application> (without
hanging up the line).</para>
</step>
<step>
<para>Enter the following:</para>
<screen>&prompt.root; <userinput>/usr/sbin/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 console messages to track the problem.</para>
<para>Following <filename>/etc/ppp/pppup</filename> script will
make all 3 stages automatic:</para>
<programlisting>#!/bin/sh
pgrep -l pppd
pid=`pgrep pppd`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
pgrep -l kermit
pid=`pgrep kermit`
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
<application>Kermit</application> 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=`pgrep pppd`
if [ X${pid} != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill -TERM ${pid}
fi
pgrep -l kermit
pid=`pgrep kermit`
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 <command>pppd</command> is still running
by executing <filename>/usr/etc/ppp/ppptest</filename>, which
should look like this:</para>
<programlisting>#!/bin/sh
pid=`pgrep pppd`
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/cuad1 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 <replaceable>your.domain</replaceable> # 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 <replaceable>local_ip</replaceable>:<replaceable>remote_ip</replaceable>
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<replaceable>phone.number</replaceable>
CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <replaceable>login-id</replaceable>
TIMEOUT 5 sword: <replaceable>password</replaceable></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 tell <application>pppd</application> to behave as a
server:</para>
<programlisting>#!/bin/sh
pgrep -l pppd
pid=`pgrep pppd`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
pgrep -l kermit
pid=`pgrep kermit`
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
pgrep -l pppd
pid=`pgrep pppd`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
pgrep -l kermit
pid=`pgrep kermit`
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 <application>Kermit</application> 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 mode
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="ppp-troubleshoot">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
<!-- 13 June 2003 -->
</sect1info>
<title>Troubleshooting <acronym>PPP</acronym> Connections</title>
<indexterm>
<primary>PPP</primary>
<secondary>troubleshooting</secondary>
</indexterm>
<warning>
<para>As of &os; 8.0, the &man.uart.4; driver replaces the
&man.sio.4; driver. Device nodes for serial ports have been
renamed from
<filename>/dev/cuad<replaceable>N</replaceable></filename> to
<filename>/dev/cuau<replaceable>N</replaceable></filename> and
from
<filename>/dev/ttyd<replaceable>N</replaceable></filename> to
<filename>/dev/ttyu<replaceable>N</replaceable></filename>.
&os; 7.X users will have to adapt the following
documentation according to these changes.</para>
</warning>
<para>This section covers a few issues which may arise when
using PPP over a modem connection. For instance, perhaps you
need to know exactly what prompts the system you are dialing
into will present. Some <acronym>ISP</acronym>s present the
<literal>ssword</literal> prompt, and others will present
<literal>password</literal>; if the <command>ppp</command>
script is not written accordingly, the login attempt will
fail. The most common way to debug <command>ppp</command>
connections is by connecting manually. The following
information will walk you through a manual connection step by
step.</para>
<sect2>
<title>Check the Device Nodes</title>
<para>When using a custom kernel, make sure to include the
following line in your kernel configuration file:</para>
<programlisting>device uart</programlisting>
<para>The <devicename>uart</devicename> device is already
included in the <literal>GENERIC</literal> kernel, so no
additional steps are necessary in this case. Just
check the <command>dmesg</command> output for the modem
device with:</para>
<screen>&prompt.root; <userinput>dmesg | grep uart</userinput></screen>
<para>You should get some pertinent output about the
<devicename>uart</devicename> devices. These are the COM
ports we need. If your modem acts like a standard serial
port then you should see it listed on
<devicename>uart1</devicename>, or
<devicename>COM2</devicename>. If so, you are not required
to rebuild the kernel. When matching up sio modem is on
<devicename>uart1</devicename> or
<devicename>COM2</devicename> if you are in DOS, then your
modem device would be <filename
class="devicefile">/dev/cuau1</filename>.</para>
</sect2>
<sect2>
<title>Connecting Manually</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> treats <command>ppp</command> client
connections. Lets start <application>PPP</application> from
the command line. Note that in all of our examples we will
use <emphasis>example</emphasis> as the hostname of the
machine running <application>PPP</application>. You start
<command>ppp</command> by just typing
<command>ppp</command>:</para>
<screen>&prompt.root; <userinput>ppp</userinput></screen>
<para>We have now started <command>ppp</command>.</para>
<screen>ppp ON example> <userinput>set device <filename class="devicefile">/dev/cuau1</filename></userinput></screen>
<para>We set our modem device, in this case it is
<devicename>cuau1</devicename>.</para>
<screen>ppp ON example> <userinput>set speed 115200</userinput></screen>
<para>Set the connection speed, in this case we
are using 115,200 <acronym>kbps</acronym>.</para>
<screen>ppp ON example> <userinput>enable dns</userinput></screen>
<para>Tell <command>ppp</command> to configure our
resolver and add the nameserver lines to
<filename>/etc/resolv.conf</filename>. If
<command>ppp</command> cannot determine our hostname, we can
set one manually later.</para>
<screen>ppp ON example> <userinput>term</userinput></screen>
<para>Switch to <quote>terminal</quote> mode so that we can
manually control the modem.</para>
<programlisting>deflink: Entering terminal mode on <filename class="devicefile">/dev/cuau1</filename>
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 logging into
&os;, 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></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></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></screen>
<para>We have made an agreement on an <acronym>IP</acronym>
address and successfully completed our connection.</para>
<screen>PPP ON example><userinput>add default HISADDR</userinput></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
<literal>!</literal> 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>
<sect3>
<title>Debugging</title>
<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 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; manual 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 <acronym>ISP</acronym>.</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
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 example> <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 example> <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 it is
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>
</sect3>
</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 PPP 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
<guimenu>System</guimenu> 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><ulink
url="http://renaud.waldura.com/doc/freebsd/pppoe/">Cheaper
Broadband with FreeBSD on DSL</ulink> by Renaud
Waldura.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="ppp-3com">
<title>PPPoE with a &tm.3com;
<trademark class="registered">HomeConnect</trademark> 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 immediately with the command:</para>
<screen>&prompt.root; <userinput>sysctl net.graph.nonstandard_pppoe=1</userinput></screen>
<para>Unfortunately, because this is a system-wide setting,
it is not possible to talk to a normal PPPoE client or server
and a &tm.3com; <trademark
class="registered">HomeConnect</trademark> 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.speedtouchdsl.com/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>
<para>Like many USB devices, the Alcatel &speedtouch; USB needs
to download firmware from the host computer to operate
properly. It is possible to automate this process in &os;
so that this transfer takes place whenever the device is
plugged into a USB port. The following information can be
added to the <filename>/etc/usbd.conf</filename> file to
enable this automatic firmware transfer. This file must be
edited as the <username>root</username> user.</para>
<programlisting>device "Alcatel SpeedTouch USB"
devname "ugen[0-9]+"
vendor 0x06b9
product 0x4061
attach "/usr/local/sbin/modem_run -f /usr/local/libdata/mgmt.o"</programlisting>
<para>To enable the USB daemon, <application>usbd</application>,
put the following the line into
<filename>/etc/rc.conf</filename>:</para>
<programlisting>usbd_enable="YES"</programlisting>
<para>It is also possible to set up
<application>ppp</application> to dial up at startup. To do
this add the following lines to
<filename>/etc/rc.conf</filename>. Again, for this procedure
you will need to be logged in as the <username>root</username>
user.</para>
<programlisting>ppp_enable="YES"
ppp_mode="ddial"
ppp_profile="adsl"</programlisting>
<para>For this to work correctly you will need to have used the
sample <filename>ppp.conf</filename> which is supplied with
the <filename role="package">net/pppoa</filename> port.</para>
</sect2>
<sect2>
<title>Using mpd</title>
<para>You can use <application>mpd</application> to connect to a
variety of services, in particular PPTP services. You can
find <application>mpd</application> in the Ports Collection,
<filename role="package">net/mpd</filename>. Many ADSL modems
require that a PPTP tunnel is created between the modem and
computer, one such modem is the Alcatel &speedtouch;
Home.</para>
<para>First you must install the port, and then you can
configure <application>mpd</application> to suit your
requirements and provider settings. The port places a set
of sample configuration files which are well documented in
<filename
class="directory"><replaceable>PREFIX</replaceable>/etc/mpd/</filename>.
Note here that <replaceable>PREFIX</replaceable> means the
directory into which your ports are installed, this defaults
to <filename class="directory">/usr/local/</filename>. A
complete guide to configure <application>mpd</application>
is available in HTML format once the port has been installed.
It is placed in <filename
class="directory"><replaceable>PREFIX</replaceable>/share/doc/mpd/</filename>.
Here is a sample configuration for connecting to an ADSL
service with <application>mpd</application>. The configuration
is spread over two files, first the
<filename>mpd.conf</filename>:</para>
<note>
<para>This example of the <filename>mpd.conf</filename> file
only works with <application>mpd</application> 4.x.</para>
</note>
<programlisting>default:
load adsl
adsl:
new -i ng0 adsl adsl
set bundle authname <replaceable>username</replaceable> <co
id="co-mpd-ex-user"/>
set bundle password <replaceable>password</replaceable> <co
id="co-mpd-ex-pass"/>
set bundle disable multilink
set link no pap acfcomp protocomp
set link disable chap
set link accept chap
set link keep-alive 30 10
set ipcp no vjcomp
set ipcp ranges 0.0.0.0/0 0.0.0.0/0
set iface route default
set iface disable on-demand
set iface enable proxy-arp
set iface idle 0
open</programlisting>
<calloutlist>
<callout arearefs="co-mpd-ex-user">
<para>The username used to authenticate with your ISP.</para>
</callout>
<callout arearefs="co-mpd-ex-pass">
<para>The password used to authenticate with your ISP.</para>
</callout>
</calloutlist>
<para>The <filename>mpd.links</filename> file contains information
about the link, or links, you wish to establish. An example
<filename>mpd.links</filename> to accompany the above example
is given beneath:</para>
<programlisting>adsl:
set link type pptp
set pptp mode active
set pptp enable originate outcall
set pptp self <replaceable>10.0.0.1</replaceable> <co
id="co-mpd-ex-self"/>
set pptp peer <replaceable>10.0.0.138</replaceable> <co
id="co-mpd-ex-peer"/></programlisting>
<calloutlist>
<callout arearefs="co-mpd-ex-self">
<para>The IP address of your &os; computer which you will be
using <application>mpd</application> from.</para>
</callout>
<callout arearefs="co-mpd-ex-peer">
<para>The IP address of your ADSL modem. For the Alcatel
&speedtouch; Home this address defaults to <hostid
role="ipaddr">10.0.0.138</hostid>.</para>
</callout>
</calloutlist>
<para>It is possible to initialize the connection easily by
issuing the following command as
<username>root</username>:</para>
<screen>&prompt.root; <userinput>mpd -b <replaceable>adsl</replaceable></userinput></screen>
<para>You can see the status of the connection with the following
command:</para>
<screen>&prompt.user; <userinput>ifconfig <replaceable>ng0</replaceable></userinput>
ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500
inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff</screen>
<para>Using <application>mpd</application> is the recommended
way to connect to an ADSL service with &os;.</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-pptp-ex-user"/>
set authkey <replaceable>password</replaceable> <co id="co-pptp-ex-pass"/>
set ifaddr 0 0
add default HISADDR</programlisting>
<calloutlist>
<callout arearefs="co-pptp-ex-user">
<para>The username of your account with the DSL
provider.</para>
</callout>
<callout arearefs="co-pptp-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 manual 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 router
documentation should tell you which address your device
uses. To open the tunnel and start a PPP session execute
the following command:</para>
<screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>adsl</replaceable></userinput></screen>
<tip>
<para>You may wish to add an ampersand (<quote>&</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<UP,POINTOPOINT,RUNNING,MULTICAST> 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
<command>pptp</command> 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>
<warning>
<para>This section applies and is valid only for
&os; 7.X.</para>
</warning>
<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 set up a symbolic link, such as
<filename class="devicefile">/dev/modem</filename>, to point
to the real device name, <filename
class="devicefile">/dev/cuad<replaceable>N</replaceable></filename>.
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 class="directory">/etc</filename> and
<filename>.kermrc</filename> files all over the system!</para>
<note>
<para><filename class="devicefile">/dev/cuad0</filename>
is <devicename>COM1</devicename>, <filename
class="devicefile">/dev/cuad1</filename> is
<devicename>COM2</devicename>, etc.</para>
</note>
<para>Make sure you have the following in your kernel
configuration file:</para>
<programlisting>device sl</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. Ours
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 <literal>files</literal> before
<literal>dns</literal> in the <literal>hosts:</literal>
section of your <filename>/etc/nsswitch.conf</filename>
file. Without these parameters 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="myname.my.domain"</programlisting>
<para>Your machine's full Internet hostname should be
placed here.</para>
</listitem>
<listitem>
<indexterm><primary>default
route</primary></indexterm>
<para>Designate the default router by changing the
line:</para>
<programlisting>defaultrouter="NO"</programlisting>
<para>to:</para>
<programlisting>defaultrouter="slip-gateway"</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
<application>Kermit</application>, 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 =>, 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 username and
password to fit yours. After doing so, you can just
type <command>slip</command> from the
<application>Kermit</application> 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 <application>Kermit</application> 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 <command>kermit</command> (by running
<command>fg</command> if you suspended it) and exit from
it (<keycap>q</keycap>).</para>
<para>The &man.slattach.8; 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.
(<command>ifconfig sl0</command> reports the same
thing.)</para>
<para>Some times, your modem might refuse to drop the carrier.
In that case, simply start <command>kermit</command> 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 on &a.net.name;
mailing list. 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<POINTOPOINT>
inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00</screen>
</listitem>
<listitem>
<para>If you get <errorname>no route to host</errorname>
messages from &man.ping.8;, there may be a problem
with your routing table. You can use the
<command>netstat -r</command> command to display the
current routes :</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) =>
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>The preceding examples are from a relatively busy
system. The numbers on your system will vary depending
on network activity.</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 start up 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
& 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 set up 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 <xref
linkend="dialup"/> for details on dialup services
configuration. You may also want to check the manual pages
or &man.sio.4; for information on the serial port device
driver and &man.ttys.5;, &man.gettytab.5;, &man.getty.8;,
& &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
<application>syslogd</application> daemon 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
<application>syslogd</application> is logging and where
it is logging to).</para>
</sect4>
</sect3>
<sect3>
<title>Kernel Configuration</title>
<indexterm>
<primary>kernel</primary>
<secondary>configuration</secondary>
</indexterm>
<indexterm>
<primary>SLIP</primary>
</indexterm>
<para>&os;'s default kernel (<filename>GENERIC</filename>)
comes with SLIP (&man.sl.4;) support; in case of a custom
kernel, you have to add the following line to your kernel
configuration file:</para>
<programlisting>device sl</programlisting>
<para>By default, your &os; machine will not forward packets.
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>. This will make sure that setting the
routing option will be persistent after a reboot.</para>
<para>To apply the settings immediately you can execute the
following command as <username>root</username>:</para>
<screen>&prompt.root; service routing start</screen>
<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 class="directory">/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 and 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 the file
<filename>/etc/nsswitch.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> — no header
compression</para>
</listitem>
<listitem>
<para><option>compress</option> — compress
headers</para>
</listitem>
<listitem>
<para><option>autocomp</option> — compress headers
if the remote end allows it</para>
</listitem>
<listitem>
<para><option>noicmp</option> — 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>
<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 need to configure a static route
to the SLIP subnet via your SLIP server on your nearest
IP router.</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 <quote>proxy ARP</quote>
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
$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 <Link>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> — 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 (i.e., <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 $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 (i.e., <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 have to add static routes to your closest default
router(s) to route your SLIP clients subnet via your SLIP
server.</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>
</sect3>
</sect2>
</sect1>
</chapter>