Date: Fri, 18 Oct 2013 19:12:33 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43002 - head/en_US.ISO8859-1/books/handbook/ppp-and-slip Message-ID: <201310181912.r9IJCXVD052146@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310181912.r9IJCXVD052146>