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.
This commit is contained in:
Dru Lavigne 2013-10-18 19:12:33 +00:00
parent 44a2e216de
commit 8cb1dee25b
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43002

View file

@ -36,14 +36,15 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>How to configure <acronym>PPP</acronym>.</para> <para>How to configure, use, and troubleshoot a
<acronym>PPP</acronym> connection.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>How to set up <acronym>PPP</acronym> over Ethernet <para>How to set up <acronym>PPP</acronym> over Ethernet
(<acronym>PPPoE</acronym>).</para> (<acronym>PPPoE</acronym>).</para>
</listitem> </listitem>
<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> (<acronym>PPPoA</acronym>).</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -106,7 +107,9 @@
<title>Configuring <acronym>PPP</acronym></title> <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> items are needed:</para>
<itemizedlist> <itemizedlist>
@ -130,35 +133,35 @@
</listitem> </listitem>
<listitem> <listitem>
<para>The <acronym>IP</acronym> address of one or more name <para>The <acronym>IP</acronym> address of one or more <acronym>DNS</acronym>
servers. Normally, an <acronym>ISP</acronym> provides these servers. Normally, the <acronym>ISP</acronym> provides these
addresses. If not, use <command>enable dns</command> in addresses. If it did not, &os; can be configured to use
<filename>ppp.conf</filename> and <acronym>DNS</acronym> negotiation.</para>
<application>ppp</application> will set the name servers.
This feature requires the <acronym>ISP</acronym> to
supporting DNS negotiation.</para>
</listitem> </listitem>
</itemizedlist> </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 <para>The following information may be supplied by the
<acronym>ISP</acronym>, but is not necessary:</para> <acronym>ISP</acronym>, but is not necessary:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>The <acronym>IP</acronym> address of the default <para>The <acronym>IP</acronym> address of the default
gateway. If this information is missing the gateway. If this information is unknown, the
<acronym>ISP</acronym>'s <acronym>PPP</acronym> server will <acronym>ISP</acronym> will automatically
provide the correct value during connection setup.</para> provide the correct value during connection setup. When
configuring <acronym>PPP</acronym> on &os;,
<para>This <acronym>IP</acronym> number is referred to as this address is referred to as
<literal>HISADDR</literal> by <literal>HISADDR</literal>.</para>
<application>ppp</application>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The subnet mask. If the <acronym>ISP</acronym> has not <para>The subnet mask. If the <acronym>ISP</acronym> has not
provided one, use <hostid provided one, <hostid
role="netmask">255.255.255.255</hostid>.</para> role="netmask">255.255.255.255</hostid> will be used in
the &man.ppp.8; configuration file.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -167,34 +170,32 @@
</indexterm> </indexterm>
<para>If the <acronym>ISP</acronym> has assigned a static <para>If the <acronym>ISP</acronym> has assigned a static
<acronym>IP</acronym> address and hostname, enter it. <acronym>IP</acronym> address and hostname, it should be
Otherwise, this information will be provided during input into the configuration file.
Otherwise, this information will be automatically provided during
connection setup.</para> connection setup.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>If any required information is missing, contact <para>The rest of this section demonstrates how to configure &os;
the <acronym>ISP</acronym>.</para> for common <acronym>PPP</acronym> connection
scenarios. The required configuration file is
<note> <filename>/etc/ppp/ppp.conf</filename> and additional files and
<para>Throughout this section, many of the examples showing the examples are available in <filename
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>
<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> class="directory">/usr/share/examples/ppp/</filename>.</para>
<para>A number of files are edited when configuring <note>
<command>ppp</command>. The edits <para>Throughout this section, many of the file examples
depend to some extent on whether the <acronym>ISP</acronym> display line numbers. These line
allocates <acronym>IP</acronym> addresses statically or numbers have been added to make it easier to follow the discussion
dynamically.</para> 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>
<sect2 id="userppp-staticIP"> <sect2 id="userppp-staticIP">
<title>PPP With Static <acronym>IP</acronym> Addresses</title> <title>PPP With Static <acronym>IP</acronym> Addresses</title>
@ -205,19 +206,13 @@
addresses</secondary> addresses</secondary>
</indexterm> </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 edit <filename>/etc/ppp/ppp.conf</filename> as described in
the example below.</para> 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: <programlisting>1 default:
2 set log Phase Chat LCP IPCP CCP tun command 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 4 set device /dev/cuau0
5 set speed 115200 5 set speed 115200
6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \ 6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
@ -229,18 +224,17 @@
12 set phone "(123) 456 7890" 12 set phone "(123) 456 7890"
13 set authname foo 13 set authname foo
14 set authkey bar 14 set authkey bar
15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp" 15 set timeout 300
16 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 set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.255 0.0.0.0 17 add default HISADDR</programlisting>
18 add default HISADDR</programlisting>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>Line 1:</term> <term>Line 1:</term>
<listitem> <listitem>
<para>Identifies the default entry. Commands in this <para>Identifies the <literal>default</literal> entry. Commands in this
entry are executed automatically when ppp is entry (lines 2 through 9) are executed automatically when <command>ppp</command> is
run.</para> run.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -249,14 +243,12 @@
<term>Line 2:</term> <term>Line 2:</term>
<listitem> <listitem>
<para>Enables logging parameters. When the <para>Enables verbose logging parameters for testing the connection. Once the
configuration is working satisfactorily, this line configuration is working satisfactorily, this line
should be reduced to saying:</para> should be reduced to:</para>
<programlisting>set log phase tun</programlisting> <programlisting>set log phase tun</programlisting>
<para>in order to avoid excessive log file
sizes.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -264,12 +256,9 @@
<term>Line 3:</term> <term>Line 3:</term>
<listitem> <listitem>
<para>Tells PPP how to identify itself to the peer. <para>Displays the version of &man.ppp.8; to the
PPP identifies itself to the peer if it has any <acronym>PPP</acronym> software running on the other side of the
trouble negotiating and setting up the link, connection.</para>
providing information that the peers administrator
may find useful when investigating such
problems.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -278,7 +267,7 @@
<listitem> <listitem>
<para>Identifies the device to which the modem is <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> <filename class="devicefile">/dev/cuau0</filename>
and and
<devicename>COM2</devicename> is <devicename>COM2</devicename> is
@ -291,26 +280,23 @@
<term>Line 5:</term> <term>Line 5:</term>
<listitem> <listitem>
<para>Sets the speed you want to connect at. If <para>Sets the connection speed. If
115200 does not work (it should with any reasonably <literal>115200</literal> does not work on an older modem,
new modem), try 38400 instead.</para> try <literal>38400</literal> instead.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>Line 6 &amp; 7:</term> <term>Lines 6 &amp; 7:</term>
<listitem> <listitem>
<para>The dial string. PPP uses an expect-send <para>The dial string written as an expect-send
syntax similar to the &man.chat.8; program. Refer syntax. Refer to &man.chat.8; for more information.</para>
to the manual page for information on the features
of this language.</para>
<para>Note that this command continues onto the next <para>Note that this command continues onto the next
line for readability. Any command in line for readability. Any command in
<filename>ppp.conf</filename> may do this if the <filename>ppp.conf</filename> may do this if the
last character on the line is a <literal>\</literal> last character on the line is <literal>\</literal>.</para>
character.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -318,9 +304,7 @@
<term>Line 8:</term> <term>Line 8:</term>
<listitem> <listitem>
<para>Sets the idle timeout for the link. 180 seconds <para>Sets the idle timeout for the link in seconds.</para>
is the default, so this line is purely
cosmetic.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -328,9 +312,9 @@
<term>Line 9:</term> <term>Line 9:</term>
<listitem> <listitem>
<para>Tells PPP to ask the peer to confirm the local <para>Instructs the peer to confirm the <acronym>DNS</acronym>
resolver settings. If you run a local name server, settings. If the local network is running its own <acronym>DNS</acronym> server,
this line should be commented out or removed.</para> this line should be commented out, by adding a <literal>#</literal> at the beginning of the line, or removed.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -339,7 +323,7 @@
<listitem> <listitem>
<para>A blank line for readability. Blank lines are <para>A blank line for readability. Blank lines are
ignored by PPP.</para> ignored by &man.ppp.8;.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -347,8 +331,8 @@
<term>Line 11:</term> <term>Line 11:</term>
<listitem> <listitem>
<para>Identifies an entry for a provider called <para>Identifies an entry called
<quote>provider</quote>. This could be changed <literal>provider</literal>. This could be changed
to the name of the <acronym>ISP</acronym> so that to the name of the <acronym>ISP</acronym> so that
<option>load <option>load
<replaceable>ISP</replaceable></option> can be <replaceable>ISP</replaceable></option> can be
@ -360,35 +344,24 @@
<term>Line 12:</term> <term>Line 12:</term>
<listitem> <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 Multiple phone numbers may be specified using the
colon (<literal>:</literal>) or pipe character colon (<literal>:</literal>) or pipe character
(<literal>|</literal>) as a separator. The (<literal>|</literal>) as a separator. To rotate
difference between the two separators is described
in &man.ppp.8;. To summarize, to rotate
through the numbers, use a colon. To through the numbers, use a colon. To
always attempt to dial the first number first and always attempt to dial the first number first and
only use the other numbers if the first number only use the other numbers if the first number
fails, use the pipe character. Always quote the fails, use the pipe character. Always enclose the
entire set of phone numbers as shown.</para> entire set of phone numbers between quotation
marks (<literal>"</literal>) to prevent dialing failures.</para>
<para>The phone number must be enclosed in quotation </listitem>
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>
<varlistentry> <varlistentry>
<term>Line 13 &amp; 14:</term> <term>Lines 13 &amp; 14:</term>
<listitem> <listitem>
<para>Identifies the user name and password. When <para>Use the user name and password for the <acronym>ISP</acronym>.</para>
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> </listitem>
</varlistentry> </varlistentry>
@ -396,55 +369,25 @@
<term>Line 15:</term> <term>Line 15:</term>
<listitem> <listitem>
<para>If <acronym>PAP</acronym> or <para>Sets the default idle
<acronym>CHAP</acronym> are used, there will be no timeout
login at this point, and this line should be in seconds for the connection. In this example, the
commented out or removed. See <xref connection will be closed automatically after 300
linkend="userppp-PAPnCHAP"/> for further seconds of inactivity. To prevent a timeout,
details.</para> set this value to zero.</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> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>Line 16:</term> <term>Line 16:</term>
<listitem> <listitem>
<para>Sets the default idle <para>Sets the interface addresses. The
timeout<indexterm><primary>timeout</primary></indexterm>
(in seconds) for the connection. Here, 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>
</listitem>
</varlistentry>
<varlistentry>
<term>Line 17:</term>
<listitem>
<para>Sets the interface addresses. The string
<replaceable>x.x.x.x</replaceable> should be <replaceable>x.x.x.x</replaceable> should be
replaced by the <acronym>IP</acronym> address that replaced by the static <acronym>IP</acronym> address that
the <acronym>ISP</acronym> has allocated. The the <acronym>ISP</acronym> has allocated and the
string <replaceable>y.y.y.y</replaceable> should be <replaceable>y.y.y.y</replaceable> should be
replaced by the <acronym>IP</acronym> address of the 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 provided a gateway address, use <hostid
role="netmask">10.0.0.2/0</hostid>. When using a role="netmask">10.0.0.2/0</hostid>. When using a
<quote>guessed</quote> address, create an entry in <quote>guessed</quote> address, create an entry in
@ -456,35 +399,26 @@ protocol: ppp</screen>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>Line 18:</term> <term>Line 17:</term>
<listitem> <listitem>
<para>Adds a default route to the gateway. The <para>Keep this line as-is as it adds a default route to the gateway. The
special word <literal>HISADDR</literal> is replaced <literal>HISADDR</literal> will automatically be replaced
with the gateway address specified on line 17. It with the gateway address specified on line 16. It
is important that this line appears after line 17, is important that this line appears after line 16.</para>
otherwise <literal>HISADDR</literal> will not yet
be initialized.</para>
<para>When <option>-auto</option> is not used, this <para>When <option>-auto</option> mode is not used to start the connection, this
line should be moved to the line should be moved to
<filename>ppp.linkup</filename> file.</para> <filename>ppp.linkup</filename>. Examples for this
</listitem> 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> </varlistentry>
</variablelist> </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>
<sect2 id="userppp-dynamicIP"> <sect2 id="userppp-dynamicIP">
@ -1618,19 +1552,19 @@ ppp_profile="name_of_service_provider"</programlisting>
</sect1> </sect1>
<sect1 id="pppoa"> <sect1 id="pppoa">
<title>Using <application>PPP</application> over ATM <title>Using <application>PPP</application> over <acronym>ATM</acronym>
(PPPoA)</title> (PPPoA)</title>
<indexterm> <indexterm>
<primary><acronym>PPP</acronym></primary> <primary><acronym>PPP</acronym></primary>
<secondary>over ATM</secondary> <secondary>over <acronym>ATM</acronym></secondary>
</indexterm> </indexterm>
<indexterm> <indexterm>
<primary>PPPoA</primary> <primary>PPPoA</primary>
</indexterm> </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> PPPoA is a popular choice among European DSL providers.</para>
<!-- <!--
This port is broken as of June, 2009 This port is broken as of June, 2009