From nobody@FreeBSD.ORG  Sun Jul 23 06:02:37 2000
Return-Path: <nobody@FreeBSD.ORG>
Received: by hub.freebsd.org (Postfix, from userid 32767)
	id 0037337BC20; Sun, 23 Jul 2000 06:02:36 -0700 (PDT)
Message-Id: <20000723130236.0037337BC20@hub.freebsd.org>
Date: Sun, 23 Jul 2000 06:02:36 -0700 (PDT)
From: george.russell@clara.net
Sender: nobody@FreeBSD.ORG
To: freebsd-gnats-submit@FreeBSD.org
Subject: Better user ppp documentation in man page than in handbook
X-Send-Pr-Version: www-1.0

>Number:         20121
>Category:       docs
>Synopsis:       Better user ppp documentation in man page than in handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    jim
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jul 23 06:10:01 PDT 2000
>Closed-Date:    Mon Apr 08 11:19:42 PDT 2002
>Last-Modified:  Mon Apr 08 11:19:42 PDT 2002
>Originator:     George Russell
>Release:        4.0 Release
>Organization:
>Environment:
>Description:
The user ppp setup information in the handbook, pedantic ppp primer,
is not up to date with the state of usr ppp, where as the user ppp man
page ( man 8 ppp) is. A link to the page, or incorporation of its content
would be very nice to people trying to setup ppp on FreeBSD, especially 4 and greater
the Connecting with your internet service provider section, which is aimed at
the 90% of users with a single modem connection to the net.
>How-To-Repeat:

>Fix:
Hmm.  Cut n paste would be nasty, a mention of man 8 ppp would be nice,
a merge would be best (imho) ;-)

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->jim 
Responsible-Changed-By: jim 
Responsible-Changed-When: Sun Jul 23 23:31:23 PDT 2000 
Responsible-Changed-Why:  
I'll take this.  I smell a ppp-handbook somewhere down the road :-) 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20121 

From: Tom Rhodes <darklogik@pittgoth.com>
To: FreeBSD-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/20121: [patch] ppp section
Date: Thu, 14 Feb 2002 01:47:41 -0500 (EST)

 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&gt; set device <devicename>/dev/cuaa1</devicename></screen>
 +
 +        <para>We set our modem device, in this case it is
 +          <devicename>cuaa1</devicename></para>
 +
 +<screen>ppp ON example&gt; set speed 115200</screen>
 +
 +        <para>Set the connection speed, in this case we
 +          are using 115,200 <acronym>kbps</acronym></para>
 +
 +<screen>ppp ON example&gt; enable dns</screen>
 +
 +        <para>Tell <command>ppp</command> to configure our
 +          resolver and add the nameserver lines to
 +          <filename>/etc/resolv.conf</filename>.  If we <command>ppp</command>
 +          cannot determine our hostname, we can set one manually later
 +        </para>
 +
 +<screen>ppp ON example&gt; term</screen>
 +
 +        <para>Switch to "terminal" mode so that we can manually
 +          control the modem</para>
 +
 +<programlisting>
 +deflink: Entering terminal mode on <devicename>/dev/cuaa1</devicename>
 +type '~h' for help</programlisting>
 +
 +<screen><userinput>at</userinput>
 +OK
 +<userinput>atdt<replaceable>123456789</replaceable></userinput></screen>
 +
 +        <para>Use <command>at</command> to initialize the modem,
 +          then use <command>atdt</command> and the number for your
 +          <acronym>ISP</acronym> to begin the dial in process</para>
 +
 +<screen>CONNECT</screen>
 +
 +        <para>Confirmation of the connection, if we are going to have
 +          any connection problems, unrelated to hardware, here is where
 +          we will attempt to resolve them.</para>
 +
 +<screen>ISP Login:<userinput>myusername</userinput></screen>
 +
 +        <para>Here you are prompted for a username, return the
 +          prompt with the username that was provided by the
 +          <acronym>ISP</acronym></para>
 +
 +<screen>ISP Pass:<userinput>mypassword</userinput></screen>
 +
 +        <para>This time we are prompted for a password, just
 +          reply with the password that was provided by the
 +          <acronym>ISP</acronym>.  Just like when logging into
 +          FreeBSD, the password will not echo.</para>
 +
 +<screen>Shell or PPP:<userinput>ppp</userinput></screen>
 +
 +        <para>Depending on your <acronym>ISP</acronym> this prompt
 +          may never appear.  Here we are being asked if we wish to
 +          use a shell on the provider, or to start
 +          <command>ppp</command>.  In this example, we have chosen
 +          to use <command>ppp</command> as we want an internet
 +          connection.</para>
 +
 +<screen>Ppp ON example&gt;</screen>
 +
 +        <para>Notice that in this example the first <option>p</option>
 +          has been capitalized.  This shows that we have successfully
 +          connected to the <acronym>ISP</acronym>.</para>
 +
 +<screen>PPp ON example&gt;</screen>
 +
 +        <para>We have successfully authenticated with our
 +          <acronym>ISP</acronym> and are waiting for the
 +          assigned <acronym>IP</acronym> address.</para>
 +
 +<screen>PPP ON example&gt;</screen>
 +
 +        <para>We have made an agreement on an <acronym>IP</acronym>
 +          address and successfully completed our connection</para>
 +
 +<screen>PPP ON example&gt;add default HISADDR</screen>
 +
 +        <para>Here we add our default route, we need to do this
 +          before we can talk to the outside world as currently the
 +          only established connection is with the peer.  If this
 +          fails due to existing routes you can put a bang character
 +          <emphasis>!</emphasis> in front of the <option>add</option>.
 +          Alternatively, you can set this before making the actual connection
 +          and it will negotiate a new route accordingly.</para>
 +
 +          <para>If everything went good we should now have an active
 +            connection to the internet, which could be thrown into
 +            the background using
 +            <keycombo action="simul"><keycap>CTRL</keycap> <keycap>z</keycap></keycombo>
 +            If you notice the <command>PPP</command> return to
 +            <command>ppp</command> then we have lost our connection.
 +            This is good to know because it shows our connection status.
 +            Capital P's show that we have a connection to the
 +            <acronym>ISP</acronym> and lowercase p's show that the
 +            connection has been lost for whatever reason.
 +            <command>ppp</command> only has these 2 states.
 +          </para>
 +
 +          <sect4>
 +            <title>Troubleshooting Manual Connections</title>
 +              <para>Like everything else, once in awhile a problem or
 +                may occur.  <application>PPP</application> is no
 +                exemption to this theory.  If <command>ppp</command>
 +                would happen to stop responding there are some things
 +                we can try.</para>
 +
 +              <para>If you have a direct line and cannot seem to make a
 +                connection, then turn hardware flow <acronym>CTS/RTS</acronym>
 +                to off with the <option>set ctsrts off</option>.  This is
 +                mainly the case if you are connected to some
 +                <application>PPP</application> capable terminal servers,
 +                where <application>PPP</application> hangs when it tries
 +                to write data to your communication link, so it would
 +                would be waiting for a <acronym>CTS</acronym>, or Clear
 +                To Send signal which may never come.  If you use this
 +                option however, you should also use the <option>set accmap</option>
 +                option, which may be required to defeat hardware dependent on
 +                passing certain characters from end to end, most of the time
 +                XON/XOFF.  See the &man.ppp.8; man page for more information
 +                on this option, and how it is used.</para>
 +
 +              <para>If you have an older modem, you may need to use the
 +                <option>set parity even</option>.  Parity is set at none
 +                be default, but is used for error checking (with a large
 +                increase in traffic) on older modems and some
 +                <acronym>ISP</acronym>s.  You may need this option for
 +                the Compuserve ISP.</para>
 +
 +              <para><application>PPP</application> may not return to the
 +                command mode, which is usually a negotiation error where
 +                the <acronym>ISP</acronym> is waiting for your side to start
 +                negotiating.  At this point, using the <command>~p</command>
 +                command will force ppp to start sending the configuration
 +                information.</para>
 +
 +              <para>If you never obtain a login prompt, then most 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&gt; <userinput>set authname <replaceable>myusername</replaceable></userinput></screen>
 +
 +        <para>Where <replaceable>myusername</replaceable> should be replaced with
 +          the username that was assigned by the <acronym>ISP</acronym>.</para>
 +
 +<screen>ppp ON localhost&gt; <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen>
 +
 +        <para>Where <replaceable>mypassword</replaceable> should be replaced with
 +          the password that was assigned by the <acronym>ISP</acronym>.</para>
 +
 +              <para>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)&mdash; 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>
  

From: Tom Rhodes <darklogik@pittgoth.com>
To: freebsd-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/20121: [patch] did a new patch...
Date: Tue, 19 Feb 2002 01:54:50 -0500

 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 
State-Changed-By: trhodes 
State-Changed-When: Mon Apr 8 11:19:00 PDT 2002 
State-Changed-Why:  
Jim and I worked on this togeather successfully closing this PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20121 
>Unformatted:
