Date: Tue, 19 Feb 2002 01:30:24 -0500 (EST) From: Tom Rhodes <darklogik@pittgoth.com> To: FreeBSD-gnats-submit@freebsd.org Subject: docs/35105: [PATCH] handbook User-ppp chapter Message-ID: <200202190630.g1J6UOL17025@pittgoth.com>
next in thread | raw e-mail | index | archive | help
>Number: 35105
>Category: docs
>Synopsis: [PATCH] handbook User-ppp chapter
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Feb 18 22:30:01 PST 2002
>Closed-Date:
>Last-Modified:
>Originator:
>Release: FreeBSD 4.5 i386
>Organization:
>Environment:
System: FreeBSD localhost 4.5
>Description:
Many times over has it mentioned in the past that
the PPP chapter either lacks content, needs more information,
is difficult to work with, or some other problem... In the
pr database, we have a pr requesting a merge of ppp(8)
and the handbook PPP chapter.
>How-To-Repeat:
Read the handbook
>Fix:
A patch is here for all to review, and someone to commit.
Only in handbook: imagelib
diff -ru handbook.old/ppp-and-slip/chapter.sgml handbook/ppp-and-slip/chapter.sgml
--- handbook.old/ppp-and-slip/chapter.sgml Mon Feb 18 23:57:54 2002
+++ handbook/ppp-and-slip/chapter.sgml Tue Feb 19 01:11:17 2002
@@ -73,10 +73,10 @@
<itemizedlist>
<listitem>
- <para>be familiar with basic network terminology.</para>
+ <para>Be familiar with basic network terminology.</para>
</listitem>
<listitem>
- <para>understand the basics and purpose of a dialup connection
+ <para>Understand the basics and purpose of a dialup connection
and PPP and/or SLIP.</para>
</listitem>
</itemizedlist>
@@ -103,6 +103,13 @@
<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>
@@ -186,8 +193,8 @@
Normally, you will be given two IP addresses by your ISP to
use for this. If they have not given you at least one, then
you can use the <command>enable dns</command> command in
- your <filename>ppp.conf</filename> file to tell
- <application>ppp</application> to set the name servers for
+ your <filename>ppp.conf</filename> file to have
+ <application>ppp</application> set the name servers for
you. This feature depends on your ISPs PPP implementation
supporting DNS negotiation.</para>
</listitem>
@@ -228,7 +235,6 @@
<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.
@@ -271,7 +277,7 @@
the existence of the <devicename>tun0</devicename> device should
be verified (this is not necessary if DEVFS is enabled as device
nodes will be created on demand).</para>
-
+
<para>The easiest way to make sure that the
<devicename>tun0</devicename> device is configured correctly
is to remake the device. To remake the device, do the
@@ -286,137 +292,232 @@
<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>sh MAKEDEV tun15</userinput></screen>
- </sect3>
- <sect3>
- <title>Name Resolution Configuration</title>
+ <sect4>
+ <title>Check the Modem</title>
+ <para>If you reconfigured your <filename>kernel</filename>
+ then you should recall the <devicename>sio</devicename>
+ device. If your modem acts like a standard serial port
+ then you most likely only need to make the serial device.
+ You can do this by changing your directory to
+ <filename>/dev</filename> and running the <filename>MAKEDEV</filename>
+ script like above. Now make the serial device with
+<screen>&prompt.root; <userinput>sh MAKEDEV cuaa</userinput></screen>
+ which will create the serial devices for your system.
+ If your modem is on <devicename>sio1</devicename> or
+ <acronym>COM2</acronym> if you are in dos, then your
+ modem device would be <devicename>/dev/cuaa1</devicename>.
+ </para>
+ </sect4>
+ </sect3>
- <indexterm id="ppp-resolver">
- <primary>resolver</primary>
- </indexterm>
- <indexterm id="ppp-hostname">
- <primary><command>hostname</command></primary>
- </indexterm>
- <indexterm id="ppp-hosts">
- <primary><filename>hosts</filename></primary>
- </indexterm>
- <para>The resolver is the part of the system that looks up IP
- addresses into hostnames and vice versa. It can be configured
- to look for maps that describe IP to hostname mappings in one of
- two places. The first is a file called
- <filename>/etc/hosts</filename>. Read &man.hosts.5; for more
- information. The second is the Internet Domain Name Service
- (DNS), a distributed data base. For more information on DNS
- and DNS services, refer to <xref linkend="dns">.</para>
-
- <para>The resolver is a set of system calls that perform the name
- mappings, but you have to tell it where to find the
- information. For versions of FreeBSD prior to 5.0. This is done by
- editing the file <filename>/etc/host.conf</filename>.
- FreeBSD 5.0 uses the <filename>/etc/nsswitch.conf</filename> file.</para>
-
- <sect4>
- <title>Edit <filename>/etc/host.conf</filename></title>
-
- <para>For versions of FreeBSD prior to 5.0, this file should
- contain the following two lines (in this order):</para>
-
- <programlisting>hosts
-bind</programlisting>
-
- <para>This instructs the resolver to first look in the file
- <filename>/etc/hosts</filename>, and to then consult the DNS
- if the name was not found.</para>
- </sect4>
-
- <sect4>
- <title>Edit <filename>/etc/nsswitch.conf</filename></title>
-
- <para>For FreeBSD version 5.0 or above, this file should
- contain at least the following line:</para>
-
- <programlisting>hosts: files, dns</programlisting>
-
- <para>This instructs the resolver to first look in the file
- <filename>/etc/hosts</filename>, and to then consult DNS
- if the name was not found.</para>
- </sect4>
-
- <sect4>
- <title>Edit <filename>/etc/hosts</filename></title>
-
- <para>This file may contain the IP addresses and names of
- machines on your local network. At a bare minimum it should
- contain
- entries for the machine which will be running ppp. Assuming
- that your machine is called <hostid
- role="fqdn">foo.example.com</hostid> with the IP address <hostid
- role="ipaddr">10.0.0.1</hostid>,
- <filename>/etc/hosts</filename> should contain:</para>
-
- <programlisting>127.0.0.1 localhost.example.com localhost
-::1 localhost.example.com localhost
-10.0.0.1 foo.example.com foo</programlisting>
-
- <para>The first two lines define the alias
- <hostid>localhost</hostid> as a synonym for the current
- machine. Regardless of your own IP address, the IP addresses
- for these lines should always be <hostid
- role="ipaddr">127.0.0.1</hostid> and <hostid
- role="ipaddr">::1</hostid>. The last line maps
- the name <hostid role="fqdn">foo.example.com</hostid> (and the
- shorthand <hostid>foo</hostid>) to the IP address <hostid
- role="ipaddr">10.0.0.1</hostid>.</para>
-
- <note>
- <para><hostid role="ipaddr">127.0.0.1</hostid> and
- <hostid>localhost</hostid> are known as loopback
- addresses, which loopback to the local machine.</para>
- </note>
-
- <para>If your provider allocates you a static IP address and
- name, and you are not using that as your host name, add this
- to the <filename>/etc/hosts</filename> too.</para>
- </sect4>
-
- <sect4>
- <title>Edit <filename>/etc/resolv.conf</filename></title>
-
- <para>The <filename>/etc/resolv.conf</filename> file tells the
- resolver how to behave. Normally, you will need to enter
- the following line(s):</para>
+ <sect3>
+ <title>Manual Connections</title>
+ <para>Connecting to the internet by manually controlling
+ <command>ppp</command> is quick, easy, and a great way
+ to debug a connection or just get information on how your
+ <acronym>ISP</acronym> handles connections. Lets start
+ <application>PPP</application> from the command line,
+ note that, in all of our examples we will use <emphasis>localhost</emphasis>
+ as the hostname of the machine running <application>PPP</application>.
+ You start <command>ppp</command> by just typing <command>ppp</command>:
+
+<screen>&prompt.root; <userinput>ppp</userinput></screen>
+
+ <para>We have now started <command>ppp</command></para>
+
+<screen>ppp ON example> set device <devicename>/dev/cuaa1</devicename></screen>
+
+ <para>We set our modem device, in this case it is
+ <devicename>cuaa1</devicename></para>
+
+<screen>ppp ON example> set speed 115200</screen>
+
+ <para>Set the connection speed, in this case we
+ are using 115,200 <acronym>kbps</acronym></para>
+
+<screen>ppp ON example> enable dns</screen>
+
+ <para>Tell <command>ppp</command> to configure our
+ resolver and add the nameserver lines to
+ <filename>/etc/resolv.conf</filename>. If we <command>ppp</command>
+ cannot determine our hostname, we can set one manually later
+ </para>
+
+<screen>ppp ON example> term</screen>
+
+ <para>Switch to "terminal" mode so that we can manually
+ control the modem</para>
+
+<programlisting>
+deflink: Entering terminal mode on <devicename>/dev/cuaa1</devicename>
+type '~h' for help</programlisting>
+
+<screen><userinput>at</userinput>
+OK
+<userinput>atdt<replaceable>123456789</replaceable></userinput></screen>
+
+ <para>Use <command>at</command> to initialize the modem,
+ then use <command>atdt</command> and the number for your
+ <acronym>ISP</acronym> to begin the dial in process</para>
+
+<screen>CONNECT</screen>
+
+ <para>Confirmation of the connection, if we are going to have
+ any connection problems, unrelated to hardware, here is where
+ we will attempt to resolve them.</para>
+
+<screen>ISP Login:<userinput>myusername</userinput></screen>
+
+ <para>Here you are prompted for a username, return the
+ prompt with the username that was provided by the
+ <acronym>ISP</acronym></para>
+
+<screen>ISP Pass:<userinput>mypassword</userinput></screen>
+
+ <para>This time we are prompted for a password, just
+ reply with the password that was provided by the
+ <acronym>ISP</acronym>. Just like when logging into
+ FreeBSD, the password will not echo.</para>
+
+<screen>Shell or PPP:<userinput>ppp</userinput></screen>
+
+ <para>Depending on your <acronym>ISP</acronym> this prompt
+ may never appear. Here we are being asked if we wish to
+ use a shell on the provider, or to start
+ <command>ppp</command>. In this example, we have chosen
+ to use <command>ppp</command> as we want an internet
+ connection.</para>
+
+<screen>Ppp ON example></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>add default HISADDR</screen>
+
+ <para>Here we add our default route, we need to do this
+ before we can talk to the outside world as currently the
+ only established connection is with the peer. If this
+ fails due to existing routes you can put a bang character
+ <emphasis>!</emphasis> in front of the <option>add</option>.
+ Alternatively, you can set this before making the actual connection
+ and it will negotiate a new route accordingly.</para>
+
+ <para>If everything went good we should now have an active
+ connection to the internet, which could be thrown into
+ the background using
+ <keycombo action="simul"><keycap>CTRL</keycap> <keycap>z</keycap></keycombo>
+ If you notice the <command>PPP</command> return to
+ <command>ppp</command> then we have lost our connection.
+ This is good to know because it shows our connection status.
+ Capital P's show that we have a connection to the
+ <acronym>ISP</acronym> and lowercase p's show that the
+ connection has been lost for whatever reason.
+ <command>ppp</command> only has these 2 states.
+ </para>
+
+ <sect4>
+ <title>Troubleshooting Manual Connections</title>
+ <para>Like everything else, once in awhile a problem or
+ may occur. <application>PPP</application> is no
+ exemption to this theory. If <command>ppp</command>
+ would happen to stop responding there are some things
+ we can try.</para>
+
+ <para>If you have a direct line and cannot seem to make a
+ connection, then turn hardware flow <acronym>CTS/RTS</acronym>
+ to off with the <option>set ctsrts off</option>. This is
+ mainly the case if you are connected to some
+ <application>PPP</application> capable terminal servers,
+ where <application>PPP</application> hangs when it tries
+ to write data to your communication link, so it would
+ would be waiting for a <acronym>CTS</acronym>, or Clear
+ To Send signal which may never come. If you use this
+ option however, you should also use the <option>set accmap</option>
+ option, which may be required to defeat hardware dependent on
+ passing certain characters from end to end, most of the time
+ XON/XOFF. See the &man.ppp.8; man page for more information
+ on this option, and how it is used.</para>
+
+ <para>If you have an older modem, you may need to use the
+ <option>set parity even</option>. Parity is set at none
+ be default, but is used for error checking (with a large
+ increase in traffic) on older modems and some
+ <acronym>ISP</acronym>s. You may need this option for
+ the Compuserve ISP.</para>
+
+ <para><application>PPP</application> may not return to the
+ command mode, which is usually a negotiation error where
+ the <acronym>ISP</acronym> is waiting for your side to start
+ negotiating. At this point, using the <command>~p</command>
+ command will force ppp to start sending the configuration
+ information.</para>
+
+ <para>If you never obtain a login prompt, then most likely you
+ you need to use <acronym>PAP</acronym> or <acronym>CHAP</acronym>
+ authentication instead of the Unix-style in the example above. To
+ use <acronym>PAP</acronym> or <acronym>CHAP</acronym> just add the
+ following options to <application>PPP</application> before going
+ into terminal mode:</para>
+
+<screen>ppp ON localhost> <userinput>set authname <replaceable>myusername</replaceable></userinput></screen>
+
+ <para>Where <replaceable>myusername</replaceable> should be replaced with
+ the username that was assigned by the <acronym>ISP</acronym>.</para>
+
+<screen>ppp ON localhost> <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen>
+
+ <para>Where <replaceable>mypassword</replaceable> should be replaced with
+ the password that was assigned by the <acronym>ISP</acronym>.</para>
+
+ <para>If you connect fine, but cannot seem to find any domain name, try to
+ use &man.ping.8; with an <acronym>IP</acronym> address and see if you
+ can get any return information. If you experience 100 percent (100%)
+ packet loss, then its most likely that you were not assigned a default
+ route. Double check that the option <option>add default HISADDR</option>
+ was set during the connection. If you can connect to a remote
+ <acronym>IP</acronym> address then it is possible that a resolver address
+ has not been added to the <filename>/etc/resolv.conf</filename>. This
+ file should look like:</para>
<programlisting>domain <replaceable>example.com</replaceable>
nameserver <replaceable>x.x.x.x</replaceable>
nameserver <replaceable>y.y.y.y</replaceable></programlisting>
- <para>The <hostid
- role="ipaddr"><replaceable>x.x.x.x</replaceable></hostid> and
- <hostid role="ipaddr"><replaceable>y.y.y.y</replaceable></hostid>
- addresses are those given to you by your ISP. Add as many
- <literal>nameserver</literal> lines as your ISP provides. The
- <literal>domain</literal> line is set to your hosts
- domain name. Refer to the &man.resolv.conf.5; manual page for
- details of other possible entries in this file.</para>
-
- <para>If you are running a local name server, replace the
- above nameserver lines with:</para>
-
- <programlisting>nameserver <replaceable>0.0.0.0</replaceable></programlisting>
-
- <indexterm><primary>PPP</primary></indexterm>
- <indexterm><primary>ISP</primary></indexterm>
- <para>The <command>enable dns</command> command (entered in the
- <filename>/etc/ppp/ppp.conf</filename> file - see below) will
- tell PPP to request that your ISP confirms the nameserver values.
- If your ISP supplies different addresses (or if there are no
- nameserver lines in <filename>/etc/resolv.conf</filename>), PPP
- will rewrite the file with the ISP-supplied values.</para>
- </sect4>
+ <para>Where <replaceable>x.x.x.x</replaceable> and
+ <replaceable>y.y.y.y</replaceable> should be replaced with the
+ <acronym>IP</acronym> address of your <acronym>ISP</acronym>'s DNS servers.
+ This information may or may not have been provided when you signed up, but
+ a quick call to your <acronym>ISP</acronym> should remedy that.</para>
+
+ <para>You could also have &man.syslog.3; provide a logging function
+ for your <application>PPP</application> connection. Just add:</para>
+
+ <programlisting>
+ !ppp
+ *.* /var/log/ppp.log</programlisting>
+
+ <para>to <filename>/etc/syslog.conf</filename>. In most cases, this
+ functionality already exists.</para>
+
+ </sect4>
</sect3>
<sect3>
- <title><application>PPP</application> Configuration</title>
+ <title>Automatic <application>PPP</application> Configuration</title>
<indexterm><primary>PPP</primary><secondary>configuration</secondary></indexterm>
<para>Both <command>ppp</command> and <command>pppd</command>
@@ -444,7 +545,8 @@
<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>
+ tabs. Most of the information you need to provide here
+ was shown to us by doing the manual dial above.</para>
</note>
<programlisting>1 default:
@@ -574,7 +676,10 @@
<listitem>
<para>Identifies an entry for a provider called
- <quote>provider</quote>.</para>
+ <quote>provider</quote>. This could be changed
+ to the name of your <acronym>ISP</acronym> so
+ that later you can use the <option>load ISP</option>
+ to start the connection.</para>
</listitem>
</varlistentry>
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200202190630.g1J6UOL17025>