svn commit: r43002 - head/en_US.ISO8859-1/books/handbook/ppp-and-slip
Dru Lavigne
dru at FreeBSD.org
Fri Oct 18 19:12:34 UTC 2013
Author: dru
Date: Fri Oct 18 19:12:33 2013
New Revision: 43002
URL: http://svnweb.freebsd.org/changeset/doc/43002
Log:
General tightening and cleanup of sections 26.1, 26.2, and 26.2.1.
- fix some acronyms along the way
The example in 26.2.1 should be changed to use callouts.
To be followed by a white space fix.
Modified:
head/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml Fri Oct 18 19:02:49 2013 (r43001)
+++ head/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml Fri Oct 18 19:12:33 2013 (r43002)
@@ -36,14 +36,15 @@
<itemizedlist>
<listitem>
- <para>How to configure <acronym>PPP</acronym>.</para>
+ <para>How to configure, use, and troubleshoot a
+ <acronym>PPP</acronym> connection.</para>
</listitem>
<listitem>
<para>How to set up <acronym>PPP</acronym> over Ethernet
(<acronym>PPPoE</acronym>).</para>
</listitem>
<listitem>
- <para>How to set up <acronym>PPP</acronym> over ATM
+ <para>How to set up <acronym>PPP</acronym> over <acronym>ATM</acronym>
(<acronym>PPPoA</acronym>).</para>
</listitem>
</itemizedlist>
@@ -106,7 +107,9 @@
<title>Configuring <acronym>PPP</acronym></title>
- <para>In order to configure <acronym>PPP</acronym>, the following
+ <para>&os; provides built-in support for managing dial-up
+ <acronym>PPP</acronym> connections using &man.ppp.8;. In order
+ to use a <acronym>PPP</acronym> connection, the following
items are needed:</para>
<itemizedlist>
@@ -130,35 +133,35 @@
</listitem>
<listitem>
- <para>The <acronym>IP</acronym> address of one or more name
- servers. Normally, an <acronym>ISP</acronym> provides these
- addresses. If not, use <command>enable dns</command> in
- <filename>ppp.conf</filename> and
- <application>ppp</application> will set the name servers.
- This feature requires the <acronym>ISP</acronym> to
- supporting DNS negotiation.</para>
+ <para>The <acronym>IP</acronym> address of one or more <acronym>DNS</acronym>
+ servers. Normally, the <acronym>ISP</acronym> provides these
+ addresses. If it did not, &os; can be configured to use
+ <acronym>DNS</acronym> negotiation.</para>
</listitem>
</itemizedlist>
+ <para>If any of the required information is missing, contact
+ the <acronym>ISP</acronym>.</para>
+
<para>The following information may be supplied by the
<acronym>ISP</acronym>, but is not necessary:</para>
<itemizedlist>
<listitem>
<para>The <acronym>IP</acronym> address of the default
- gateway. If this information is missing the
- <acronym>ISP</acronym>'s <acronym>PPP</acronym> server will
- provide the correct value during connection setup.</para>
-
- <para>This <acronym>IP</acronym> number is referred to as
- <literal>HISADDR</literal> by
- <application>ppp</application>.</para>
+ gateway. If this information is unknown, the
+ <acronym>ISP</acronym> will automatically
+ provide the correct value during connection setup. When
+ configuring <acronym>PPP</acronym> on &os;,
+ this address is referred to as
+ <literal>HISADDR</literal>.</para>
</listitem>
<listitem>
<para>The subnet mask. If the <acronym>ISP</acronym> has not
- provided one, use <hostid
- role="netmask">255.255.255.255</hostid>.</para>
+ provided one, <hostid
+ role="netmask">255.255.255.255</hostid> will be used in
+ the &man.ppp.8; configuration file.</para>
</listitem>
<listitem>
@@ -167,35 +170,33 @@
</indexterm>
<para>If the <acronym>ISP</acronym> has assigned a static
- <acronym>IP</acronym> address and hostname, enter it.
- Otherwise, this information will be provided during
+ <acronym>IP</acronym> address and hostname, it should be
+ input into the configuration file.
+ Otherwise, this information will be automatically provided during
connection setup.</para>
</listitem>
</itemizedlist>
- <para>If any required information is missing, contact
- the <acronym>ISP</acronym>.</para>
+ <para>The rest of this section demonstrates how to configure &os;
+ for common <acronym>PPP</acronym> connection
+ scenarios. The required configuration file is
+ <filename>/etc/ppp/ppp.conf</filename> and additional files and
+ examples are available in <filename
+ class="directory">/usr/share/examples/ppp/</filename>.</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>
+ <para>Throughout this section, many of the file examples
+ display line numbers. These line
+ numbers have been added to make it easier to follow the discussion
+ and are not meant to be placed in the actual file.</para>
+
+ <para>When editing a configuration file, proper
+ indentation is
+ important. Lines that end in a <literal>:</literal> start in the
+ first column (beginning of the line) while all other lines
+ should be indented as shown using spaces or tabs.</para>
</note>
- <para><command>ppp</command> uses the configuration files located
- in <filename class="directory">/etc/ppp</filename>. Examples
- can be found in <filename
- class="directory">/usr/share/examples/ppp/</filename>.</para>
-
- <para>A number of files are edited when configuring
- <command>ppp</command>. The edits
- depend to some extent on whether the <acronym>ISP</acronym>
- allocates <acronym>IP</acronym> addresses statically or
- dynamically.</para>
-
<sect2 id="userppp-staticIP">
<title>PPP With Static <acronym>IP</acronym> Addresses</title>
@@ -205,19 +206,13 @@
addresses</secondary>
</indexterm>
- <para>If the ISP has provided an address that does not change,
+ <para>If the <acronym>ISP</acronym>, also known as the peer, has provided an address that does not change,
edit <filename>/etc/ppp/ppp.conf</filename> as described in
the example below.</para>
- <note>
- <para>Lines that end in a <literal>:</literal> start in the
- first column (beginning of the line) while 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)
+3 ident user-ppp VERSION
4 set device /dev/cuau0
5 set speed 115200
6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
@@ -229,18 +224,17 @@
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>
+15 set timeout 300
+16 set ifaddr <replaceable>x.x.x.x</replaceable>/0 <replaceable>y.y.y.y</replaceable>/0 255.255.255.255 0.0.0.0
+17 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
+ <para>Identifies the <literal>default</literal> entry. Commands in this
+ entry (lines 2 through 9) are executed automatically when <command>ppp</command> is
run.</para>
</listitem>
</varlistentry>
@@ -249,14 +243,12 @@
<term>Line 2:</term>
<listitem>
- <para>Enables logging parameters. When the
+ <para>Enables verbose logging parameters for testing the connection. Once the
configuration is working satisfactorily, this line
- should be reduced to saying:</para>
+ should be reduced to:</para>
<programlisting>set log phase tun</programlisting>
- <para>in order to avoid excessive log file
- sizes.</para>
</listitem>
</varlistentry>
@@ -264,12 +256,9 @@
<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>
+ <para>Displays the version of &man.ppp.8; to the
+ <acronym>PPP</acronym> software running on the other side of the
+ connection.</para>
</listitem>
</varlistentry>
@@ -278,7 +267,7 @@
<listitem>
<para>Identifies the device to which the modem is
- connected. <devicename>COM1</devicename> is
+ connected, where <devicename>COM1</devicename> is
<filename class="devicefile">/dev/cuau0</filename>
and
<devicename>COM2</devicename> is
@@ -291,26 +280,23 @@
<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>
+ <para>Sets the connection speed. If
+ <literal>115200</literal> does not work on an older modem,
+ try <literal>38400</literal> instead.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Line 6 & 7:</term>
+ <term>Lines 6 & 7:</term>
<listitem>
- <para>The dial string. 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>The dial string written as an expect-send
+ syntax. Refer to &man.chat.8; for more information.</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>
+ last character on the line is <literal>\</literal>.</para>
</listitem>
</varlistentry>
@@ -318,9 +304,7 @@
<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>
+ <para>Sets the idle timeout for the link in seconds.</para>
</listitem>
</varlistentry>
@@ -328,9 +312,9 @@
<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>
+ <para>Instructs the peer to confirm the <acronym>DNS</acronym>
+ settings. If the local network is running its own <acronym>DNS</acronym> server,
+ this line should be commented out, by adding a <literal>#</literal> at the beginning of the line, or removed.</para>
</listitem>
</varlistentry>
@@ -339,7 +323,7 @@
<listitem>
<para>A blank line for readability. Blank lines are
- ignored by PPP.</para>
+ ignored by &man.ppp.8;.</para>
</listitem>
</varlistentry>
@@ -347,8 +331,8 @@
<term>Line 11:</term>
<listitem>
- <para>Identifies an entry for a provider called
- <quote>provider</quote>. This could be changed
+ <para>Identifies an entry called
+ <literal>provider</literal>. This could be changed
to the name of the <acronym>ISP</acronym> so that
<option>load
<replaceable>ISP</replaceable></option> can be
@@ -360,35 +344,24 @@
<term>Line 12:</term>
<listitem>
- <para>Sets the phone number for this provider.
+ <para>Use the phone number for the <acronym>ISP</acronym>.
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, to rotate
+ (<literal>|</literal>) as a separator. To rotate
through the numbers, use a colon. 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>The phone number must be enclosed 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>
+ fails, use the pipe character. Always enclose the
+ entire set of phone numbers between quotation
+ marks (<literal>"</literal>) to prevent dialing failures.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>Line 13 & 14:</term>
+ <term>Lines 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>
+ <para>Use the user name and password for the <acronym>ISP</acronym>.</para>
</listitem>
</varlistentry>
@@ -396,55 +369,25 @@
<term>Line 15:</term>
<listitem>
- <para>If <acronym>PAP</acronym> or
- <acronym>CHAP</acronym> are used, there will be no
- login at this point, and this line should be
- commented out or removed. See <xref
- linkend="userppp-PAPnCHAP"/> 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>Alter this script to suit your
- own needs. When writing this script for the first
- time, ensure that
- chat logging is enabled to help determine if
- the conversation is going as expected.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Line 16:</term>
-
- <listitem>
<para>Sets the default idle
- timeout<indexterm><primary>timeout</primary></indexterm>
- (in seconds) for the connection. Here, the
+ timeout
+ in seconds for the connection. In this example, the
connection will be closed automatically after 300
- seconds of inactivity. To prevent a timeout
- timeout, set this value to zero or use the
- <option>-ddial</option> command line switch.</para>
+ seconds of inactivity. To prevent a timeout,
+ set this value to zero.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Line 17:</term>
+ <term>Line 16:</term>
<listitem>
- <para>Sets the interface addresses. The string
+ <para>Sets the interface addresses. The
<replaceable>x.x.x.x</replaceable> should be
- replaced by the <acronym>IP</acronym> address that
- the <acronym>ISP</acronym> has allocated. The
- string <replaceable>y.y.y.y</replaceable> should be
+ replaced by the static <acronym>IP</acronym> address that
+ the <acronym>ISP</acronym> has allocated and the
+ <replaceable>y.y.y.y</replaceable> should be
replaced by the <acronym>IP</acronym> address of the
- gateway. If the <acronym>ISP</acronym> has not
+ default gateway. If the <acronym>ISP</acronym> has not
provided a gateway address, use <hostid
role="netmask">10.0.0.2/0</hostid>. When using a
<quote>guessed</quote> address, create an entry in
@@ -456,35 +399,26 @@ protocol: ppp</screen>
</varlistentry>
<varlistentry>
- <term>Line 18:</term>
+ <term>Line 17:</term>
<listitem>
- <para>Adds a default route to the 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>When <option>-auto</option> is not used, this
- line should be moved to the
- <filename>ppp.linkup</filename> file.</para>
- </listitem>
+ <para>Keep this line as-is as it adds a default route to the gateway. The
+ <literal>HISADDR</literal> will automatically be replaced
+ with the gateway address specified on line 16. It
+ is important that this line appears after line 16.</para>
+
+ <para>When <option>-auto</option> mode is not used to start the connection, this
+ line should be moved to
+ <filename>ppp.linkup</filename>. Examples for this
+ file can be found in <filename
+ class="directory">/usr/share/examples/ppp/</filename>.
+ However,
+ <filename>ppp.linkup</filename> is not needed when running &man.ppp.8; in
+ <option>-auto</option> mode as the routing table entries
+ are already correct.</para>
+ </listitem>
</varlistentry>
</variablelist>
-
- <para>It is not necessary to add an entry to
- <filename>ppp.linkup</filename> when using a static
- <acronym>IP</acronym> address and when running ppp in
- <option>-auto</option> mode as the routing table entries
- are already correct. However, an entry can be created 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>
</sect2>
<sect2 id="userppp-dynamicIP">
@@ -1618,19 +1552,19 @@ ppp_profile="name_of_service_provider"</
</sect1>
<sect1 id="pppoa">
- <title>Using <application>PPP</application> over ATM
+ <title>Using <application>PPP</application> over <acronym>ATM</acronym>
(PPPoA)</title>
<indexterm>
<primary><acronym>PPP</acronym></primary>
- <secondary>over ATM</secondary>
+ <secondary>over <acronym>ATM</acronym></secondary>
</indexterm>
<indexterm>
<primary>PPPoA</primary>
</indexterm>
- <para>The following describes how to set up PPP over ATM (PPPoA).
+ <para>The following describes how to set up PPP over <acronym>ATM</acronym> (PPPoA).
PPPoA is a popular choice among European DSL providers.</para>
<!--
This port is broken as of June, 2009
More information about the svn-doc-all
mailing list