Bug 20121
| Summary: | Better user ppp documentation in man page than in handbook | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | george.russell <george.russell> |
| Component: | Books & Articles | Assignee: | Jim Mock <jim> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
|
Description
george.russell
2000-07-23 14:10:01 UTC
Responsible Changed From-To: freebsd-doc->jim I'll take this. I smell a ppp-handbook somewhere down the road :-) This is a very large update to the user-ppp section of the handbook,
I want to do more, when the time comes. Things like cover the actual
RFC compliance, maybe some commands... But this is all in the future,
in the meantime, I think this patch will make it much easier for new
users to setup their ISP connection using ppp
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 Wed Feb 13 15:31:14 2002
+++ handbook/ppp-and-slip/chapter.sgml Thu Feb 14 01:22:35 2002
@@ -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>
@@ -271,7 +278,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 +293,214 @@
<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>
+ <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 likly 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>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>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>
-
- <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>
+ </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 +528,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 +659,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>
Kinda sorry Jim, I redid the patch, with more troubleshooting information, and a slight whitespace fix (which I did) along with more touching up... Then, in an unthinking manner due to late night work, I just submitted a regular pr for the patch and didn't notice until I got the gnats mail. In either case, with your permission, I would like to have the new patch committed, and both of the prs closed ;) Thanks --Tom Rhodes State Changed From-To: open->closed Jim and I worked on this togeather successfully closing this PR. |
