From owner-p4-projects@FreeBSD.ORG  Tue Jul  8 12:55:35 2008
Return-Path: <owner-p4-projects@FreeBSD.ORG>
Delivered-To: p4-projects@freebsd.org
Received: by hub.freebsd.org (Postfix, from userid 32767)
	id C4A9B106567E; Tue,  8 Jul 2008 12:55:34 +0000 (UTC)
Delivered-To: perforce@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 87D4D106567B
	for <perforce@freebsd.org>; Tue,  8 Jul 2008 12:55:34 +0000 (UTC)
	(envelope-from remko@freebsd.org)
Received: from repoman.freebsd.org (repoman.freebsd.org
	[IPv6:2001:4f8:fff6::29])
	by mx1.freebsd.org (Postfix) with ESMTP id 73A768FC1A
	for <perforce@freebsd.org>; Tue,  8 Jul 2008 12:55:34 +0000 (UTC)
	(envelope-from remko@freebsd.org)
Received: from repoman.freebsd.org (localhost [127.0.0.1])
	by repoman.freebsd.org (8.14.1/8.14.1) with ESMTP id m68CtYNc048190
	for <perforce@freebsd.org>; Tue, 8 Jul 2008 12:55:34 GMT
	(envelope-from remko@freebsd.org)
Received: (from perforce@localhost)
	by repoman.freebsd.org (8.14.2/8.14.1/Submit) id m68CtYKQ048188
	for perforce@freebsd.org; Tue, 8 Jul 2008 12:55:34 GMT
	(envelope-from remko@freebsd.org)
Date: Tue, 8 Jul 2008 12:55:34 GMT
Message-Id: <200807081255.m68CtYKQ048188@repoman.freebsd.org>
X-Authentication-Warning: repoman.freebsd.org: perforce set sender to
	remko@freebsd.org using -f
From: Remko Lodder <remko@FreeBSD.org>
To: Perforce Change Reviews <perforce@freebsd.org>
Cc: 
Subject: PERFORCE change 144880 for review
X-BeenThere: p4-projects@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: p4 projects tree changes <p4-projects.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/p4-projects>,
	<mailto:p4-projects-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/p4-projects>
List-Post: <mailto:p4-projects@freebsd.org>
List-Help: <mailto:p4-projects-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/p4-projects>,
	<mailto:p4-projects-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Jul 2008 12:55:35 -0000

http://perforce.freebsd.org/chv.cgi?CH=144880

Change 144880 by remko@remko_nakur on 2008/07/08 12:54:50

	IFC

Affected files ...

.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml#3 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/portbuild/article.sgml#3 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/faq/book.sgml#3 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/security/chapter.sgml#2 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml#3 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/share/sgml/authors.ent#3 integrate
.. //depot/projects/docproj_nl/share/pgpkeys/nwhitehorn.key#1 branch
.. //depot/projects/docproj_nl/share/pgpkeys/pgpkeys-developers.sgml#3 integrate
.. //depot/projects/docproj_nl/share/pgpkeys/pgpkeys.ent#3 integrate
.. //depot/projects/docproj_nl/www/en/developers.sgml#2 integrate
.. //depot/projects/docproj_nl/www/en/gnome/docs/develfaq.sgml#2 integrate
.. //depot/projects/docproj_nl/www/en/gnome/docs/halfaq.sgml#2 integrate
.. //depot/projects/docproj_nl/www/en/gnome/index.xsl#2 integrate
.. //depot/projects/docproj_nl/www/share/sgml/events.xml#2 integrate
.. //depot/projects/docproj_nl/www/share/sgml/news.xml#2 integrate
.. //depot/projects/docproj_nl/www/share/sgml/press.xml#2 integrate
.. //depot/projects/docproj_nl/www/share/sgml/templates.events.xsl#2 integrate

Differences ...

==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml#3 (text+ko) ====

@@ -1,4 +1,4 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml,v 1.232 2008/06/23 11:42:41 erik Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml,v 1.234 2008/07/08 05:40:34 sson Exp $ -->
 <!--
 	NOTE TO NEW COMMITTERS: Core and committers lists are sorted in
 	alphabetical order by last name. Please keep in mind that fact while
@@ -1266,6 +1266,10 @@
     </listitem>
 
     <listitem>
+      <para>&a.sson;</para>
+    </listitem>
+
+    <listitem>
       <para>&a.ssouhlal;</para>
     </listitem>
 
@@ -1430,6 +1434,10 @@
     </listitem>
 
     <listitem>
+      <para>&a.nwhitehorn;</para>
+    </listitem>
+
+    <listitem>
       <para>&a.miwi;</para>
     </listitem>
 

==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/portbuild/article.sgml#3 (text+ko) ====

@@ -11,7 +11,7 @@
       <corpauthor>The &os; Ports Management Team</corpauthor>
     </authorgroup>
 
-    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/portbuild/article.sgml,v 1.28 2008/06/11 12:15:30 pav Exp $</pubdate>
+    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/portbuild/article.sgml,v 1.29 2008/07/04 13:03:22 pav Exp $</pubdate>
 
     <copyright>
       <year>2003</year>
@@ -1067,4 +1067,70 @@
       should also be committed  to
       <filename>/usr/ports/CHANGES</filename>.</para>
   </sect1>
+
+  <sect1 id="disk-failure">
+    <title>Procedures for dealing with disk failures</title>
+
+    <para>When a machine has a disk failure (e.g. panics due to read errors,
+      etc), then we should do the following steps:</para>
+
+    <itemizedlist>
+      <listitem><para>Note the time and failure mode (e.g. paste in the
+	relevant console output) in
+	<filename>/var/portbuild/<replaceable>${arch}</replaceable>/reboots</filename></para></listitem>
+
+      <listitem><para>For i386 gohan clients, scrub the disk by touching
+	<filename>/SCRUB</filename> in the nfsroot (e.g.
+	<filename>/a/nfs/8.dir1/SCRUB</filename>) and rebooting.  This will
+	<command>dd if=/dev/zero of=/dev/ad0</command> and force the drive to
+	remap any bad sectors it finds, if it has enough spares left.  This is
+	a temporary measure to extend the lifetime of a drive that is on the
+	way out.</para>
+
+	<note><para>For the i386 blade systems another signal of a failing
+	  disk seems to be that the blade will completely hang and be
+	  unresponsive to either console break, or even NMI.</para></note>
+
+	<para>For other build systems that don't newfs their disk at boot (e.g.
+	  amd64 systems) this step has to be skipped.</para></listitem>
+
+      <listitem><para>If the problem recurs, then the disk is probably toast.
+	Take the machine out of <filename>mlist</filename> and (for ata disks)
+	run <command>smartctl</command> on the drive:</para>
+
+	<screen>smartctl -t long /dev/ad0</screen>
+
+	<para>It will take about 1/2 hour:</para>
+
+	<screen>gohan51# smartctl -t long /dev/ad0
+smartctl version 5.38 [i386-portbld-freebsd8.0] Copyright (C) 2002-8
+Bruce Allen
+Home page is http://smartmontools.sourceforge.net/
+
+=== START OF OFFLINE IMMEDIATE AND SELF-TEST SECTION ===
+Sending command: "Execute SMART Extended self-test routine immediately in off-line mode".
+Drive command "Execute SMART Extended self-test routine immediately in off-line mode" successful.
+Testing has begun.
+Please wait 31 minutes for test to complete.
+Test will complete after Fri Jul  4 03:59:56 2008
+
+Use smartctl -X to abort test.</screen>
+
+	<para>Then <command>smartctl -a /dev/ad0</command> shows the status
+	  after it finishes:</para>
+
+	<screen># SMART Self-test log structure revision number 1
+# Num  Test_Description    Status                  Remaining 
+LifeTime(hours)  LBA_of_first_error
+#   1  Extended offline    Completed: read failure       80%     15252    319286</screen>
+
+	<para>It will also display other data including a log of previous drive
+	  errors.  It is possible for the drive to show previous DMA errors
+	  without failing the self-test though (because of sector
+	  remapping).</para></listitem>
+    </itemizedlist>
+
+    <para>When a disk has failed, please inform &a.kris; so he can try to get it
+      replaced.</para>
+  </sect1>
 </article>

==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/faq/book.sgml#3 (text+ko) ====

@@ -10,7 +10,7 @@
 
     <corpauthor>The FreeBSD Documentation Project</corpauthor>
 
-    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/books/faq/book.sgml,v 1.1004 2008/06/21 12:24:43 pgj Exp $</pubdate>
+    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/books/faq/book.sgml,v 1.1065 2008/07/06 09:19:23 pgj Exp $</pubdate>
 
     <copyright>
       <year>1995</year>
@@ -7638,6 +7638,15 @@
             set to <literal>YES</literal> in
             <filename>/etc/rc.conf</filename>.</para>
 
+	  <note>
+	    <para>In recent &os; releases, the &man.mrouted.8;
+	      multicast routing daemon, the &man.map-mbone.8; and
+	      &man.mrinfo.8; utilities have been removed from the base
+	      system.  These programs are now available in the &os;
+	      Ports Collection as <filename
+		role="package">net/mrouted</filename>.</para>
+	  </note>
+
           <para>MBONE tools are available in their own ports category,
             <ulink
             url="http://www.FreeBSD.org/ports/mbone.html">mbone</ulink>.
@@ -8449,7 +8458,7 @@
 
           <para>There is a setting on most modems for determining how
             tolerant it should be to temporary losses of carrier.  On a
-            USR &sportster; for example, this is measured by the S10
+            &usrobotics;&nbsp;&sportster; for example, this is measured by the <literal>S10</literal>
             register in tenths of a second.  To make your modem more
             forgiving, you could add the following send-expect sequence
             to your dial string:</para>
@@ -8516,12 +8525,12 @@
 
         <answer>
           <para>There is very little you can do about this.  Most ISPs
-            will refuse to help if you are not running a Microsoft OS.
+            will refuse to help if you are not running a &microsoft; OS.
             You can <literal>enable lqr</literal> in your
             <filename>ppp.conf</filename> file, allowing &man.ppp.8; to detect
             the remote failure and hang up, but this detection is
             relatively slow and therefore not that useful.  You may want to
-            avoid telling your ISP that you are running user-PPP...</para>
+            avoid telling your ISP that you are running user-PPP.</para>
 
           <para>First, try disabling all local compression by adding the
             following to your configuration:</para>
@@ -8534,20 +8543,20 @@
             determine which setting makes the difference through trial
             and error.  This will provide good ammunition when you contact
             your ISP (although it may make it apparent that you are not
-            running a Microsoft product).</para>
+            running a &microsoft; product).</para>
 
           <para>Before contacting your ISP, enable async logging
             locally and wait until the connection hangs again.  This
             may use up quite a bit of disk space.  The last data read
-            from the port may be of interest.  It is usually ascii
-            data, and may even describe the problem (<quote>Memory
-            fault, core dumped</quote>?).</para>
+            from the port may be of interest.  It is usually ASCII
+            data, and may even describe the problem (<errorname>Memory
+            fault</errorname>, <errorname>Core dumped</errorname>).</para>
 
           <para>If your ISP is helpful, they should be able to enable
             logging on their end, then when the next link drop occurs,
             they may be able to tell you why their side is having a
             problem.  Feel free to send the details to &a.brian;, or
-            even to ask your ISP to contact me directly.</para>
+            even to ask your ISP to contact him directly.</para>
         </answer>
       </qandaentry>
 
@@ -8556,20 +8565,36 @@
           <para>&man.ppp.8; has hung.  What can I do?</para>
         </question>
 
-        <answer>
-          <para>Your best bet here is to rebuild &man.ppp.8; by adding
-            <literal>CFLAGS+=-g</literal> and
-            <literal>STRIP=</literal> to the end of the Makefile, then
-            doing a <command>make clean &amp;&amp; make &amp;&amp;
-            make install</command>.  When &man.ppp.8; hangs, find the
-            &man.ppp.8; process id with <command>ps ajxww | fgrep
-            ppp</command> and run <command>gdb ppp
-            <replaceable>PID</replaceable></command>.  From the <command>gdb</command>
-            prompt, you can then use <command>bt</command> to get a
-            stack trace.</para>
+	<answer>
+	  <para>Your best bet here is to rebuild &man.ppp.8; with
+	    debugging information, and then use &man.gdb.1; to grab a stack
+	    trace from the <application>ppp</application> process that is
+	    stuck.  To rebuild the <application>ppp</application> utility with
+	    debugging information, you can type:</para>
+
+	   <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/ppp</userinput>
+&prompt.root; <userinput>env DEBUG_FLAGS='-g' make clean</userinput>
+&prompt.root; <userinput>env DEBUG_FLAGS='-g' make install</userinput></screen>
+
+	  <para>Then you should restart <application>ppp</application>
+	    and wait until it hangs again.  When the debug build of
+	    <application>ppp</application> hangs, start
+	    <application>gdb</application> on the stuck process by
+	    typing:</para>
+
+	  <screen>&prompt.root; <userinput>gdb ppp `pgrep ppp`</userinput></screen>
+
+	  <para>At the <application>gdb</application> prompt, you can
+	    use the <command>bt</command> or <command>where</command>
+	    commands to get a stack trace.  Save the output of your
+	    <application>gdb</application> session, and
+	    <quote>detach</quote> from the running process by the
+	    <command>quit</command> command of
+	    <application>gdb</application>.</para>
 
-          <para>Send the results to &a.brian;.</para>
-        </answer>
+	  <para>Finally, send the log of your
+	    <application>gdb</application> session to &a.brian;.</para>
+	</answer>
       </qandaentry>
 
       <qandaentry>
@@ -8605,7 +8630,7 @@
 
         <answer>
           <para>Occasionally, just after connecting, you may see messages
-            in the log that say <quote>magic is the same</quote>.
+            in the log that say <errorname>Magic is same</errorname>.
             Sometimes, these messages are harmless, and sometimes one side
             or the other exits.  Most PPP implementations cannot survive
             this problem, and even if the link seems to come up, you will see
@@ -8614,9 +8639,9 @@
             connection.</para>
 
           <para>This normally happens on server machines with slow
-            disks that are spawning a getty on the port, and executing
-            &man.ppp.8; from a login script or program after login.  I
-            have also heard reports of it happening consistently when
+            disks that are spawning a &man.getty.8; on the port, and executing
+            &man.ppp.8; from a login script or program after login.  There
+            were reports of it happening consistently when
             using slirp.  The reason is that in the time taken between
             &man.getty.8; exiting and &man.ppp.8; starting, the
             client-side &man.ppp.8; starts sending Line Control
@@ -8644,7 +8669,7 @@
             from the server.</para>
 
           <para>This can be avoided by allowing the peer to start
-            negotiating with the following line in your ppp.conf
+            negotiating with the following line in your <filename>ppp.conf</filename>
             file:</para>
 
           <programlisting>set openmode passive</programlisting>
@@ -8716,26 +8741,26 @@
             getting nowhere and gives up.</para>
 
           <para>The best way to avoid this is to configure one side to be
-            <literal>passive</literal> - that is, make one side
+            <literal>passive</literal> &mdash; that is, make one side
             wait for the other to start negotiating.  This can be done
-            with the</para>
+            with the following command:</para>
 
           <programlisting>set openmode passive</programlisting>
 
-          <para>command.  Care should be taken with this option.  You
-            should also use the</para>
+          <para>Care should be taken with this option.  You
+            should also use the this command to limit the amount
+            of time that &man.ppp.8; waits for the peer to begin
+            negotations:</para>
 
-          <programlisting>set stopped N</programlisting>
+          <programlisting>set stopped <replaceable>N</replaceable></programlisting>
 
-          <para>command to limit the amount of time that
-            &man.ppp.8; waits for the peer to begin
-            negotiations.  Alternatively, the</para>
+          <para>Alternatively, the following command (where
+            <replaceable>N</replaceable> is the number of seconds
+            to wait before starting negotiations) can be used:</para>
 
-          <programlisting>set openmode active N</programlisting>
+          <programlisting>set openmode active <replaceable>N</replaceable></programlisting>
 
-          <para>command (where <replaceable>N</replaceable> is the
-            number of seconds to wait before starting negotiations) can be
-            used.  Check the manual page for details.</para>
+          <para>Check the manual page for details.</para>
         </answer>
       </qandaentry>
 
@@ -8749,7 +8774,7 @@
           <para>When you execute the <command>shell</command> or
             <command>!</command> command, &man.ppp.8; executes a
             shell (or if you have passed any arguments,
-            &man.ppp.8; will execute those arguments). Ppp will
+            &man.ppp.8; will execute those arguments).  The <application>ppp</application> program will
             wait for the command to complete before continuing. If you
             attempt to use the PPP link while running the command, the link
             will appear to have frozen. This is because
@@ -8783,7 +8808,7 @@
 
       <qandaentry>
         <question id="ppp-auto-noreasondial">
-          <para>Why does &man.ppp.8; dial for no reason in -auto mode?</para>
+          <para>Why does &man.ppp.8; dial for no reason in <option>-auto</option> mode?</para>
         </question><answer>
 
           <para>If &man.ppp.8; is dialing unexpectedly, you must
@@ -8811,7 +8836,7 @@
 set dfilter 3 permit 0/0 0/0</programlisting>
 
           <para>This is not always suitable, as it will effectively
-            break your demand-dial capabilities - most programs will
+            break your demand-dial capabilities &mdash; most programs will
             need a DNS lookup before doing any other network related
             things.</para>
 
@@ -8833,7 +8858,7 @@
             queue is run (usually, sendmail is invoked with
             <option>-bd -q30m</option>, telling it to run the queue
             every 30 minutes) or until a <command>sendmail
-            -q</command> is done (perhaps from your ppp.linkup
+            <option>-q</option></command> is done (perhaps from your <filename>ppp.linkup</filename>
             file).</para>
         </answer>
       </qandaentry>
@@ -8878,7 +8903,7 @@
 
           <para>If you wish to see your connect speed and are using PAP
             or CHAP (and therefore do not have anything to
-            <quote>chat</quote> after the CONNECT in the dial script - no
+            <quote>chat</quote> after the CONNECT in the dial script &mdash; no
             <literal>set login</literal> script), you must make sure that
             you instruct &man.ppp.8; to <quote>expect</quote> the whole CONNECT
             line, something like this:</para>
@@ -8899,7 +8924,7 @@
             in my chat script?</para>
         </question><answer>
 
-          <para>Ppp parses each line in your config files so that it can
+          <para>The <application>ppp</application> utility parses each line in your config files so that it can
             interpret strings such as
             <literal>set phone "123 456 789"</literal> correctly and
             realize that the number is actually only
@@ -8920,19 +8945,19 @@
 
           <programlisting>set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK"</programlisting>
 
-          <para>resulting in the following sequence:</para>
+          <para>It will result in the following sequence:</para>
 
           <programlisting>ATZ
 OK
 AT\X
 OK</programlisting>
 
-          <para>or</para>
+          <para>Or:</para>
 
           <programlisting>set phone 1234567
 set dial "\"\" ATZ OK ATDT\\T"</programlisting>
 
-          <para>resulting in the following sequence:</para>
+          <para>It will result in the following sequence:</para>
 
           <programlisting>ATZ
 OK
@@ -8943,30 +8968,26 @@
 
       <qandaentry>
         <question id="ppp-segfault-nocore">
-          <para>Why does &man.ppp.8; get a seg-fault, but I see no
+          <para>Why does &man.ppp.8; get a <errorname>Segmentation fault</errorname>, but I see no
             <filename>ppp.core</filename> file?</para>
         </question>
 
         <answer>
-          <para>Ppp (or any other program for that matter) should
+          <para>The <application>ppp</application> utility (or any other program for that matter) should
             never dump core.  Because &man.ppp.8; runs with an
-            effective user id of 0, the operating system will not
-            write &man.ppp.8;'s core image to disk before terminating
+            effective user&nbsp;ID of <literal>0</literal>, the operating system will not
+            write core image of &man.ppp.8; to disk before terminating
             it.  If, however &man.ppp.8; is actually terminating due
             to a segmentation violation or some other signal that
             normally causes core to be dumped,
             <emphasis>and</emphasis> you are sure you are using the
             latest version (see the start of this section), then you
-            should do the following:</para>
+            should install the system sources and do the following:</para>
 
-          <screen>&prompt.user; <userinput>tar xfz ppp-*.src.tar.gz</userinput>
-&prompt.user; <userinput>cd ppp*/ppp</userinput>
-&prompt.user; <userinput>echo STRIP= &gt;&gt;Makefile</userinput>
-&prompt.user; <userinput>echo CFLAGS+=-g &gt;&gt;Makefile</userinput>
-&prompt.user; <userinput>make clean all</userinput>
-&prompt.user; <userinput>su</userinput>
-&prompt.root; <userinput>make install</userinput>
-&prompt.root; <userinput>chmod 555 /usr/sbin/ppp</userinput></screen>
+          <screen>&prompt.root;  <userinput><command>cd</command> <filename role="directory">/usr/src/usr.sbin/ppp</filename></userinput>
+&prompt.root; <userinput><command>echo</command> <makevar>STRIP</makevar>= &gt;&gt; <filename>/etc/make.conf</filename></userinput>
+&prompt.root; <userinput><command>echo</command> <makevar>CFLAGS</makevar>+=<option>-g</option> &gt;&gt; <filename>/etc/make.conf</filename></userinput>
+&prompt.root; <userinput><command>make</command> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen>
 
           <para>You will now have a debuggable version of &man.ppp.8;
             installed.  You will have to be <username>root</username>
@@ -8994,28 +9015,28 @@
             question, making it possible to diagnose the problem.</para>
 
           <para>If you are familiar with &man.gdb.1;, you may wish to find out some
-            other bits and pieces such as what actually caused the dump and
-            the addresses &amp; values of the relevant variables.</para>
+            other bits and pieces such as what actually caused the dump or
+            the addresses and values of the relevant variables.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-autodialprocess-noconnect">
-          <para>Why does the process that forces a dial in auto mode never
+          <para>Why does the process that forces a dial in <option>-auto</option> mode never
             connect?</para>
         </question>
 
         <answer>
           <para>This was a known problem with
             &man.ppp.8; set up to negotiate a
-            dynamic local IP number with the peer in auto mode.  It is
-            fixed in the latest version - search the manual page for
+            dynamic local IP number with the peer in <option>-auto</option> mode.  It has
+            been fixed a long time ago &mdash; search the manual page for
             <literal>iface</literal>.</para>
 
           <para>The problem was that when that initial program calls
-            &man.connect.2;, the IP number of the tun interface is assigned
+            &man.connect.2;, the IP number of the &man.tun.4; interface is assigned
             to the socket endpoint. The kernel creates the first outgoing
-            packet and writes it to the tun device.
+            packet and writes it to the &man.tun.4; device.
             &man.ppp.8; then reads the packet and
             establishes a connection. If, as a result of
             &man.ppp.8;'s dynamic IP assignment, the
@@ -9027,19 +9048,19 @@
 
           <para>There are several theoretical ways to approach this
             problem. It would be nicest if the peer would re-assign the
-            same IP number if possible <literal>:-)</literal>
+            same IP number if possible.
             The current version of &man.ppp.8; does
             this, but most other implementations do not.</para>
 
           <para>The easiest method from our side would be to never
-            change the tun interface IP number, but instead to change
+            change the &man.tun.4; interface IP number, but instead to change
             all outgoing packets so that the source IP number is
             changed from the interface IP to the negotiated IP on the
             fly. This is essentially what the
             <literal>iface-alias</literal> option in the latest
             version of &man.ppp.8; is doing (with the help of
             &man.libalias.3; and &man.ppp.8;'s <option>-nat</option>
-            switch) - it is maintaining all previous interface
+            switch) &mdash; it is maintaining all previous interface
             addresses and NATing them to the last negotiated
             address.</para>
 
@@ -9048,16 +9069,16 @@
             from one IP to another.  &man.ppp.8; would
             use this call to modify the sockets of all existing programs
             when a new IP number is negotiated. The same system call could
-            be used by dhcp clients when they are forced to re-bind() their
+            be used by <acronym>DHCP</acronym> clients when they are forced to call the <function>bind()</function> function for their
             sockets.</para>
 
           <para>Yet another possibility is to allow an interface to be
             brought up without an IP number. Outgoing packets would be
-            given an IP number of 255.255.255.255 up until the first
-            SIOCAIFADDR ioctl is done. This would result in fully binding
+            given an IP number of <hostid role="ipaddr">255.255.255.255</hostid> up until the first
+            <literal>SIOCAIFADDR</literal> &man.ioctl.2; is done.  This would result in fully binding
             the socket. It would be up to &man.ppp.8;
             to change the source IP number, but only if it is set to
-            255.255.255.255, and only the IP number and IP checksum would
+            <hostid role="ipaddr">255.255.255.255</hostid>, and only the IP number and IP checksum would
             need to change. This, however is a bit of a hack as the kernel
             would be sending bad packets to an improperly configured
             interface, on the assumption that some other mechanism is
@@ -9067,11 +9088,11 @@
 
       <qandaentry>
         <question id="ppp-nat-games">
-          <para>Why do most games not work with the -nat switch?</para>
+          <para>Why do most games not work with the <option>-nat</option> switch?</para>
         </question>
 
         <answer>
-          <para>The reason games and the like do not work when libalias
+          <para>The reason games and the like do not work when &man.libalias.3;
             is in use is that the machine on the outside will try to open a
             connection or send (unsolicited) UDP packets to the machine on
             the inside. The NAT software does not know that it should send
@@ -9079,8 +9100,8 @@
 
           <para>To make things work, make sure that the only thing
             running is the software that you are having problems with, then
-            either run tcpdump on the tun interface of the gateway or
-            enable &man.ppp.8; tcp/ip logging (<literal>set log +tcp/ip</literal>)
+            either run &man.tcpdump.1; on the &man.tun.4; interface of the gateway or
+            enable &man.ppp.8; TCP/IP logging (<literal>set log +tcp/ip</literal>)
             on the gateway.</para>
 
           <para>When you start the offending software, you should see
@@ -9105,7 +9126,7 @@
           <para>You will not be able to use the software on other machines
             without changing the above command, and running the software
             on two internal machines at the same time is out of the question
-            - after all, the outside world is seeing your entire internal
+            &mdash; after all, the outside world is seeing your entire internal
             network as being just a single machine.</para>
 
           <para>If the port numbers are not consistent, there are three
@@ -9113,9 +9134,9 @@
 
           <orderedlist>
             <listitem>
-              <para>Submit support in libalias. Examples of
+              <para>Submit support in &man.libalias.3;.  Examples of
                 <quote>special cases</quote> can be found in
-                <filename>/usr/src/lib/libalias/alias_*.c</filename>
+                <filename>/usr/src/sys/netinet/libalias/alias_*.c</filename>
                 (<filename>alias_ftp.c</filename> is a good
                 prototype). This usually involves reading certain
                 recognised outgoing packets, identifying the
@@ -9131,8 +9152,8 @@
             </listitem>
 
             <listitem>
-              <para>Use a proxy.  The application may support socks5
-                for example, or (as in the <quote>cvsup</quote> case)
+              <para>Use a proxy.  The application may support <literal>socks5</literal>
+                for example, or (as in the <command>cvsup</command> case)
                 may have a <quote>passive</quote> option that avoids
                 ever requesting that the peer open connections back to
                 the local machine.</para>
@@ -9166,9 +9187,9 @@
                 :65000 65000</literal></para>
 
               <para>Manually change the port number within the game to
-                65000. If you have got a number of machines that you wish
+                <literal>65000</literal>. If you have got a number of machines that you wish
                 to play on assign a unique port number for each (i.e.
-                65001, 65002, etc) and add a <literal>nat port</literal>
+                <literal>65001</literal>, <literal>65002</literal>, etc) and add a <literal>nat port</literal>
                 line for each one.</para>
             </listitem>
 
@@ -9253,7 +9274,7 @@
 
           <para>If your link freezes as soon as you have connected and you
             see a large number of FCS errors, this may be because your link
-            is not 8 bit clean. Make sure your modem is not using software
+            is not 8-bit clean. Make sure your modem is not using software
             flow control (XON/XOFF). If your datalink
             <emphasis>must</emphasis> use software flow control, use the
             command <literal>set accmap 0x000a0000</literal> to tell
@@ -9267,9 +9288,9 @@
             determine if the incoming data is actually a login or
             shell prompt. If you have a shell prompt at the remote
             end, it is possible to terminate &man.ppp.8; without
-            dropping the line by using the <literal>close
-            lcp</literal> command (a following <literal>term</literal>
-            command will reconnect you to the shell on the remote
+            dropping the line by using the <command>close
+            lcp</command> command (a following <command>term</command>
+            command) will reconnect you to the shell on the remote
             machine.</para>
 
           <para>If nothing in your log file indicates why the link might
@@ -9280,7 +9301,7 @@
 
       <qandaentry id=PPPoEwithNAT>
         <question id="macos-win98-pppoe-freeze">
-          <para>Why do &macos; and &windows; 98 connections freeze when
+          <para>Why do &macos; and &windows;&nbsp;98 connections freeze when
             running PPPoE on the gateway?</para>
         </question>
 
@@ -9291,33 +9312,32 @@
             solution:</para>
 
           <para>This is due to what is called a <quote>Black Hole</quote>
-            router.  &macos; and &windows; 98 (and maybe other Microsoft OSs)
+            router.  &macos; and &windows;&nbsp;98 (and maybe other &microsoft; OSs)
             send TCP packets with a requested segment size too big to fit
-            into a PPPoE frame (MTU is 1500 by default for Ethernet)
+            into a PPPoE frame (MTU is <literal>1500</literal> by default for Ethernet)
             <emphasis>and</emphasis> have the <quote>do not
             fragment</quote> bit set (default of TCP) and the Telco router
             is not sending ICMP <quote>must fragment</quote> back to the
-            www site you are trying to load.  (Alternatively, the router is
-            sending the ICMP packet correctly, but the firewall at the www
+            WWW site you are trying to load.  (Alternatively, the router is
+            sending the ICMP packet correctly, but the firewall at the WWW
             site is dropping it.)  When the www server is sending
             you frames that do not fit into the PPPoE pipe the Telco router
             drops them on the floor and your page does not load (some
             pages/graphics do as they are smaller than a MSS.) This seems
-            to be the default of most Telco PPPoE configurations (if only
-            they knew how to program a router... sigh...)</para>
+            to be the default of most Telco PPPoE configurations.</para>
 
-          <para>One fix is to use regedit on your 95/98 boxes to add the
-            following registry entry...</para>
+          <para>One fix is to use <application>regedit</application> on your 95/98 system to add the
+            following registry entry:</para>
 
           <programlisting>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU</programlisting>
 
           <para>It should be a string with a value
-            <quote>1436</quote>, as some ADSL routers are reported to
+            <literal>1436</literal>, as some ADSL routers are reported to
             be unable to deal with packets larger than this.  This
             registry key has been changed to
             <literal>Tcpip\Parameters\Interfaces\<replaceable>ID for
-            adapter</replaceable>\MTU</literal> in &windows; 2000 and
-            becomes a DWORD.</para>
+            adapter</replaceable>\MTU</literal> in &windows;&nbsp;2000 and
+            becomes a <literal>DWORD</literal>.</para>
 
           <para>Refer to the Microsoft Knowledge Base documents <ulink
             url="http://support.microsoft.com/support/kb/articles/Q158/4/74.asp">Q158474
@@ -9327,38 +9347,34 @@
             </ulink> for more information on changing &windows; MTU to
             work with a NAT router.</para>
 
-          <para>Another regedit possibility under &windows; 2000 is to
+          <para>Another regedit possibility under &windows;&nbsp;2000 to
             set the
             <literal>Tcpip\Parameters\Interfaces\<replaceable>ID for
-            adapter</replaceable>\EnablePMTUBHDetect</literal> DWORD
-            to 1 as mentioned in the Microsoft document 120642
+            adapter</replaceable>\EnablePMTUBHDetect</literal> <literal>DWORD</literal>
+            to <literal>1</literal> as mentioned in the Microsoft document 120642
             mentioned above.</para>
 
           <para>Unfortunately, &macos; does not provide an interface for
-            changing TCP/IP settings. However, there is commercial software
-            available, such as OTAdvancedTuner (OT for OpenTransport, the
-            &macos; TCP/IP stack) by <ulink
-            url="http://www.softworks.com/">Sustainable Softworks</ulink>,
+            changing TCP/IP settings. However, there many commercial software
+            available
             that will allow users to customize TCP/IP settings. &macos; NAT
-            users should select <literal>ip_interface_MTU</literal> from
-            the drop-down menu, enter <literal>1450</literal> instead of
-            <literal>1500</literal> in the box, click the box next to
-            <literal>Save as Auto Configure</literal>, and click
-            <literal>Make Active</literal>.</para>
+            users should search for their MTU settings and
+            enter <literal>1450</literal> instead of
+            <literal>1500</literal>.</para>
 
-          <para>The latest version of &man.ppp.8;
-            (2.3 or greater) has an <command>enable tcpmssfixup</command>
+          <para>The &man.ppp.8;
+            has an <command>enable tcpmssfixup</command>
             command that will automatically adjust the MSS to an appropriate
             value.  This facility is enabled by default.  If you are stuck
             with an older version of &man.ppp.8;, you
-            may want to look at the <application>tcpmssd</application>
+            may want to look at the <filename role="port">net/tcpmssd</filename>
             port.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="desperation">
-          <para>None of this helps - I am desperate!  What can I do?</para>
+          <para>None of this helps &mdash; I am desperate!  What can I do?</para>
         </question>
 
         <answer>
@@ -9393,29 +9409,28 @@
           <para>As the FreeBSD kernel boots, it will probe for the serial
             ports in your system for which the kernel was configured.
             You can either watch your system closely for the messages it
-            prints or run the command</para>
+            prints or run this command after your system is up and
+            running:</para>
 
-          <screen>&prompt.user; <userinput>dmesg | grep sio</userinput></screen>
+          <screen>&prompt.user; <userinput>dmesg | grep -E "^sio[0-9]"</userinput></screen>
 
-          <para>after your system is up and running.</para>
-
           <para>Here is some example output from the above command:</para>
 
-          <programlisting>sio0 at 0x3f8-0x3ff irq 4 on isa
+          <programlisting>sio0: <16550A-compatible COM port> port 0x3f8-0x3ff irq 4 flags 0x10 on acpi0
 sio0: type 16550A
-sio1 at 0x2f8-0x2ff irq 3 on isa
+sio1: <16550A-compatible COM port> port 0x2f8-0x2ff irq 3 on acpi0
 sio1: type 16550A</programlisting>
 
-          <para>This shows two serial ports.  The first is on irq 4, is
+          <para>This shows two serial ports.  The first is on IRQ&nbsp;4, is
             using port address <literal>0x3f8</literal>, and has a
             16550A-type UART chip.  The second uses the same kind of chip
-            but is on irq 3 and is at port address <literal>0x2f8</literal>.
+            but is on IRQ&nbsp;3 and is at port address <literal>0x2f8</literal>.
             Internal modem cards are treated just like serial ports &mdash; except
             that they always have a modem <quote>attached</quote> to the
             port.</para>
 
           <para>The <filename>GENERIC</filename> kernel includes support
-            for two serial ports using the same irq and port address
+            for two serial ports using the same IRQ and port address
             settings in the above example.  If these settings are not
             right for your system, or if you have added modem cards or have
             more serial ports than your kernel is configured for, just
@@ -9444,7 +9459,7 @@
         <answer>
           <para>The third serial port, <devicename>sio2</devicename>
             (see &man.sio.4;, known as <devicename>COM3</devicename> in DOS), is on
-            <devicename>/dev/cuaa2</devicename> for dial-out devices,
+            <devicename>/dev/cuad2</devicename> for dial-out devices,
             and on <devicename>/dev/ttyd2</devicename> for dial-in
             devices.  What is the difference between these two classes
             of devices?</para>
@@ -9455,10 +9470,10 @@
             <devicename>/dev/ttyd<replaceable>X</replaceable></devicename>
             in blocking mode, a process will wait for the
             corresponding
-            <devicename>cuaa<replaceable>X</replaceable></devicename>
+            <devicename>cuad<replaceable>X</replaceable></devicename>
             device to become inactive, and then wait for the carrier
             detect line to go active.  When you open the
-            <devicename>cuaa<replaceable>X</replaceable></devicename>
+            <devicename>cuad<replaceable>X</replaceable></devicename>
             device, it makes sure the serial port is not already in
             use by the
             <devicename>ttyd<replaceable>X</replaceable></devicename>
@@ -9466,7 +9481,7 @@
             it from the
             <devicename>ttyd<replaceable>X</replaceable></devicename>
             device. Also, the
-            <devicename>cuaa<replaceable>X</replaceable></devicename>
+            <devicename>cuad<replaceable>X</replaceable></devicename>
             device does not care about carrier detect. With this
             scheme and an auto-answer modem, you can have remote users
             log in and you can still dial out with the same modem and
@@ -9482,27 +9497,37 @@
 
         <answer>
           <para>Again, the section on kernel configuration provides
-            information about configuring your kernel. For a multiport
+            information about configuring your kernel.  For a multiport
             serial card, place an &man.sio.4; line for each serial
-            port on the card in the kernel configuration file. But
-            place the irq and vector specifiers on only one of the
-            entries. All of the ports on the card should share one
-            irq.  For consistency, use the last serial port to specify
-            the irq.  Also, specify the
-            <literal>COM_MULTIPORT</literal> option.</para>
+            port on the card in the &man.device.hints.5; file.  But
+            place the IRQ specifiers on only one of the
+            entries.  All of the ports on the card should share one
+            IRQ.  For consistency, use the last serial port to specify
+            the IRQ.  Also, specify the following
+            option in the kernel
+            configuration file:</para>
+
+          <programlisting>options COM_MULTIPORT</programlisting>
 
-          <para>The following example is for an AST 4-port serial card on
-            irq 7:</para>
+          <para>The following <filename>/boot/device.hints</filename> example is for an AST 4-port serial card on
+            IRQ&nbsp;12:</para>
 
-          <programlisting>options "COM_MULTIPORT"
-device sio4 at isa? port 0x2a0 tty flags 0x781
-device sio5 at isa? port 0x2a8 tty flags 0x781
-device sio6 at isa? port 0x2b0 tty flags 0x781
-device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr</programlisting>
+          <programlisting>hint.sio.4.at="isa"
+hint.sio.4.port="0x2a0"
+hint.sio.4.flags="0x701"
+hint.sio.5.at="isa"
+hint.sio.5.port="0x2a8"
+hint.sio.5.flags="0x701"
+hint.sio.6.at="isa"
+hint.sio.6.port="0x2b0"
+hint.sio.6.flags="0x701"
+hint.sio.7.at="isa"
+hint.sio.7.port="0x2b8"
+hint.sio.7.flags="0x701"
+hint.sio.7.irq="12"</programlisting>
 
-          <para>The flags indicate that the master port has minor number 7
-            (<literal>0x700</literal>), diagnostics enabled during probe
-            (<literal>0x080</literal>), and all the ports share an irq
+          <para>The flags indicate that the master port has minor number <literal>7</literal>
+            (<literal>0x700</literal>), and all the ports share an IRQ
             (<literal>0x001</literal>).</para>
         </answer>
       </qandaentry>
@@ -9510,11 +9535,11 @@
       <qandaentry>
         <question id="multiport-serial-share-irq">
           <para>Can FreeBSD handle multiport serial cards sharing
-            irqs?</para>
+            IRQs?</para>
         </question>
 
         <answer>
-          <para>Not yet. You will have to use a different irq for each
+          <para>Not yet. You will have to use a different IRQ for each
             card.</para>
 
         </answer>
@@ -9527,51 +9552,9 @@
         </question>
 
         <answer>
-          <para>The
-            <devicename>ttyd<replaceable>X</replaceable></devicename>
-            (or
-            <devicename>cuaa<replaceable>X</replaceable></devicename>)
-            device is the regular device you will want to open for
-            your applications.  When a process opens the device, it
-            will have a default set of terminal I/O settings. You can
-            see these settings with the command</para>
-
-          <screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen>
-
-          <para>When you change the settings to this device, the settings
-            are in effect until the device is closed.  When it is reopened,
-            it goes back to the default set.  To make changes to the
-            default set, you can open and adjust the settings of the
-            <quote>initial state</quote> device. For example, to turn on
-            <acronym>CLOCAL</acronym> mode, 8 bits, and
-            <acronym>XON/XOFF</acronym> flow control by default for
-            ttyd5, do:</para>
-
-          <screen>&prompt.root; <userinput>stty -f /dev/ttyid5 clocal cs8 ixon ixoff</userinput></screen>
-
-          <para>A good place to do this is in
-            <filename>/etc/rc.serial</filename>. Now, an application
-            will have these settings by default when it opens
-            <filename>ttyd5</filename>.  It can still change these
-            settings to its liking, though.</para>
-
-          <para>You can also prevent certain settings from being
-            changed by an application by making adjustments to the
-            <quote>lock state</quote> device.  For example, to lock
-            the speed of <devicename>ttyd5</devicename> to 57600 bps,
-            do</para>
-
-          <screen>&prompt.root; <userinput>stty -f /dev/ttyld5 57600</userinput></screen>
-
-          <para>Now, an application that opens
-            <devicename>ttyd5</devicename> and tries to change the
-            speed of the port will be stuck with 57600 bps.</para>
-
-          <para>Naturally, you should make the initial state and lock
-            state devices writable only by
-            <username>root</username>. The &man.MAKEDEV.8; script does
-            <emphasis>NOT</emphasis> do this when it creates the
-            device entries.</para>
+	  <para>See the <ulink
+	      url="&url.books.handbook;/serial.html#SERIAL-HW-CONFIG">Serial Communications</ulink>
+	    section in the &os; Handbook.</para>
         </answer>
       </qandaentry>
 
@@ -9581,79 +9564,9 @@
         </question>
 
         <answer>
-          <para>So you want to become an Internet service provider, eh?
-            First, you will need one or more modems that can auto-answer.
-            Your modem will need to assert carrier-detect when it detects a
-            carrier and not assert it all the time. It will need to hang up
-            the phone and reset itself when the data terminal ready
-            (<acronym>DTR</acronym>) line goes from on to off. It should
-            probably use <filename>RTS/CTS</filename> flow control or no
-            local flow control at all. Finally, it must use a constant
-            speed between the computer and itself, but (to be nice to your
-            callers) it should negotiate a speed between itself and the
-            remote modem.</para>
-
-          <para>For many Hayes command-set--compatible modems, this
-            command will make these settings and store them in
-            nonvolatile memory:</para>
-
-          <programlisting>AT &amp;C1 &amp;D3 &amp;K3 &amp;Q6 S0=1 &amp;W</programlisting>
-
-          <para>See the section <link linkend="direct-at">on sending AT
-            commands</link> below for information on how to make these
-            settings without resorting to an &ms-dos; terminal program.</para>
-
-          <para>Next, make an entry in <filename>/etc/ttys</filename>
-            (see &man.ttys.5;) for the modem.  This file lists all the
-            ports on which the operating system will await logins.
-            Add a line that looks something like this:</para>
-
-          <programlisting>ttyd1 "/usr/libexec/getty std.57600" dialup on insecure</programlisting>
-
-          <para>This line indicates that the second serial port
-            (<devicename>/dev/ttyd1</devicename>) has a modem
-            connected running at 57600 bps and no parity
-            (<literal>std.57600</literal>, which comes from the file
-            <filename>/etc/gettytab</filename>, see &man.gettytab.5;).
-            The terminal type for this port is
-            <literal>dialup</literal>.  The port is
-            <literal>on</literal> and is
-            <literal>insecure</literal> &mdash; meaning
-            <username>root</username> logins on the port are not
-            allowed. For dialin ports like this one, use the
-            <devicename>ttyd<replaceable>X</replaceable></devicename>
-            entry.</para>
-
-          <para>It is common practice to use <literal>dialup</literal>
-            as the terminal type. Many users set up in their
-            <filename>.profile</filename> or
-            <filename>.login</filename> files a prompt for the actual
-            terminal type if the starting type is dialup. The example
-            shows the port as insecure. To become
-            <username>root</username> on this port, you have to login
-            as a regular user, then &man.su.1; to become
-            <username>root</username>. If you use
-            <literal>secure</literal> then <username>root</username>
-            can login in directly.</para>
-
-          <para>After making modifications to
-            <filename>/etc/ttys</filename>, you need to send a hangup
-            or <acronym>HUP</acronym> signal to the &man.init.8;
-            process:</para>
-
-          <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
-
-          <para>This forces the &man.init.8; process to reread
-            <filename>/etc/ttys</filename>.  The init process will
-            then start getty processes on all <literal>on</literal>
-            ports.  You can find out if logins are available for your
-            port by typing</para>
-
-          <screen>&prompt.user; <userinput>ps -ax | grep '[t]tyd1'</userinput></screen>
-
-          <para>You should see something like:</para>
-
-          <programlisting>747 ??  I      0:00.04 /usr/libexec/getty std.57600 ttyd1</programlisting>
+	  <para>Please read the section about <ulink

>>> TRUNCATED FOR MAIL (1000 lines) <<<