Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 6 Dec 2006 21:14:30 GMT
From:      Niclas Zeising<niclas.zeising@gmail.com>
To:        freebsd-gnats-submit@FreeBSD.org
Subject:   docs/106425: [PATCH] add a HARDWARE-section to ata(4)
Message-ID:  <200612062114.kB6LEURu022466@www.freebsd.org>
Resent-Message-ID: <200612062150.kB6Lo4Df053177@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help

>Number:         106425
>Category:       docs
>Synopsis:       [PATCH] add a HARDWARE-section to ata(4)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Dec 06 21:50:03 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Niclas Zeising
>Release:        7-CURRENT
>Organization:
>Environment:
>Description:
The ata(4) manual page lacks a HARDWARE section which make the auto-generation of harware notes fail, or rather, no chip sets supported bu ata(4) shows up in the hardware notes.

There was a pr complaining about this last week, unfortunately I can't find it at the moment, so I'll file a new pr.
>How-To-Repeat:
man 4 ata
>Fix:
The attached patch tries to add a proper hardware section based on the chip sets already listed in ata(4). The list is rather long, and can maybe be tweaked so it becomes shorter. If you find a way to do so, feel free.

Patch attached with submission follows:

--- doc/en_US.ISO8859-1/books/handbook/security/chapter.sgml.orig	2006-11-12 11:13:08.000000000 +0100
+++ doc/en_US.ISO8859-1/books/handbook/security/chapter.sgml	2006-11-12 19:10:20.000000000 +0100
@@ -66,17 +66,20 @@
       </listitem>
 
       <listitem>
-	<para>How to configure IPsec and create a <acronym>VPN</acronym> between
-	&os;/&windows; machines.</para>
+	<para>How to configure IPsec and create a 
+	  <acronym role="Virual Private Network">VPN</acronym> between
+	  &os;/&windows; machines. </para>
       </listitem>
      
       <listitem>
-	<para>How to configure and use <application>OpenSSH</application>, &os;'s <acronym>SSH</acronym>
-	  implementation.</para>
+	<para>How to configure and use <application>OpenSSH</application>
+	  , &os;'s <acronym role="Secure Shell">SSH</acronym> implementation.
+	  </para>
       </listitem>
 
       <listitem>
-	<para>What file system <acronym>ACL</acronym>s are and how to use them.</para>
+	<para>What file system <acronym role="Access Control Lists">ACL</acronym>s
+	  are and how to use them.</para>
       </listitem>
 
       <listitem>
@@ -128,15 +131,14 @@
       inter-networked, security becomes an even bigger issue.</para>
 
     <para>System security also pertains to dealing with various forms of
-      attack, including attacks that attempt to crash, or otherwise make a
+      attacks, including attacks that attempt to crash, or otherwise make a
       system unusable, but do not attempt to compromise the
       <username>root</username> account (<quote>break root</quote>).
-      Security concerns
-      can be split up into several categories:</para>
+      Security concerns can be split up into several categories:</para>
 
     <orderedlist>
       <listitem>
-	<para>Denial of service attacks.</para>
+	<para>Denial of service (DoS) attacks.</para>
       </listitem>
 
       <listitem>
@@ -168,14 +170,14 @@
     <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
 
     <para>A denial of service attack is an action that deprives the
-      machine of needed resources.  Typically, DoS attacks are
-      brute-force mechanisms that attempt to crash or otherwise make a
+      machine of needed resources.  Typically, <acronym>DoS</acronym> attacks
+      are brute-force mechanisms that attempt to crash or otherwise make a
       machine unusable by overwhelming its servers or network stack.  Some
-      DoS attacks try to take advantage of bugs in the networking
-      stack to crash a machine with a single packet.  The latter can only
-      be fixed by applying a bug fix to the kernel.  Attacks on servers
-      can often be fixed by properly specifying options to limit the load
-      the servers incur on the system under adverse conditions.
+      <acronym>DoS</acronym> attacks try to take advantage of bugs in the
+      networking stack to crash a machine with a single packet.  The latter
+      can only be fixed by applying a bug fix to the kernel.  Attacks on
+      servers can often be fixed by properly specifying options to limit the
+      load the servers incur on the system under adverse conditions.
       Brute-force network attacks are harder to deal with.  A
       spoofed-packet attack, for example, is nearly impossible to stop,
       short of cutting your system off from the Internet.  It may not be
@@ -187,8 +189,8 @@
       <secondary>account compromises</secondary>
     </indexterm>
 
-    <para>A user account compromise is even more common than a DoS
-      attack.  Many sysadmins still run standard 
+    <para>A user account compromise is even more common than a
+      <acronym>DoS</acronym> attack.  Many sysadmins still run standard 
       <application>telnetd</application>, <application>rlogind</application>,
       <application>rshd</application>,
       and <application>ftpd</application> servers on their machines.
@@ -226,7 +228,7 @@
       a suid-root program that allows the attacker to break
       <username>root</username> once he has broken into a user's account.
       If an attacker has found a way to break <username>root</username>
-      on a machine, the attacker may not have a need
+      on a machine, the attacker may have the need
       to install a backdoor.  Many of the <username>root</username> holes
       found and closed to date involve a considerable amount of work
       by the attacker to cleanup after himself, so most attackers install
@@ -294,9 +296,8 @@
        <application>bold</application> text to refer to an
        application, and a <command>monospaced</command> font to refer
        to specific commands.  Protocols will use a normal font.  This
-       typographical distinction is useful for instances such as ssh,
-       since it is
-       a protocol as well as command.</para>
+       typographical distinction is useful for instances such as SSH,
+       since it is a protocol as well as command.</para>
     </note>
 
     <para>The sections that follow will cover the methods of securing your
@@ -348,8 +349,8 @@
 	<groupname>wheel</groupname> group are allowed to
 	<command>su</command> to <username>root</username>.
 	You should never give staff
-	members native <groupname>wheel</groupname> access by putting them in the
-	<groupname>wheel</groupname> group in their password entry.  Staff
+	members native <groupname>wheel</groupname> access by putting them in
+	the <groupname>wheel</groupname> group in their password entry.  Staff
 	accounts should be placed in a <groupname>staff</groupname> group, and
 	then added to the <groupname>wheel</groupname> group via the
 	<filename>/etc/group</filename> file.  Only those staff members
@@ -565,7 +566,7 @@
 	have sufficient control, then you may win out and be able to secure
 	the user accounts properly.  If not, you simply have to be more
 	vigilant in your monitoring of those accounts.  Use of
-	ssh and Kerberos for user accounts is
+	SSH and Kerberos for user accounts is
 	more problematic, due to the extra administration and technical
 	support required, but still a very good solution compared to a
 	encrypted password file.</para>
@@ -575,7 +576,7 @@
       <title>Securing the Password File</title>
 
       <para>The only sure fire way is to star out as many
-	passwords as you can and use ssh or
+	passwords as you can and use SSH or
 	Kerberos for access to those accounts.  Even though the encrypted
 	password file (<filename>/etc/spwd.db</filename>) can only be read
 	by <username>root</username>, it may be possible for an intruder
@@ -663,9 +664,9 @@
 	have to give the limited-access box significant access to the
 	other machines in the business, usually either by doing a
 	read-only NFS export of the other machines to the limited-access
-	box, or by setting up ssh key-pairs to
-	allow the limited-access box to ssh to
-	the other machines.  Except for its network traffic, NFS is the
+	box, or by setting up SSH key-pairs to
+	allow the limited-access box to use <application>ssh</application> to
+	access the other machines.  Except for its network traffic, NFS is the
 	least visible method &mdash; allowing you to monitor the
 	file systems on each client box virtually undetected.  If your
 	limited-access server is connected to the client boxes through a
@@ -674,8 +675,7 @@
 	hub, or through several layers of routing, the NFS method may be
 	too insecure (network-wise) and using
 	ssh may be the better choice even with
-	the audit-trail tracks that ssh
-	lays.</para>
+	the audit-trail tracks that SSH lays.</para>
 
       <para>Once you have given a limited-access box at least read access to the
 	client systems it is supposed to monitor, you must write scripts
@@ -694,13 +694,13 @@
 
       <para>When using ssh rather than NFS,
 	writing the security script is much more difficult.   You
-	essentially have to <command>scp</command> the scripts to the client 
+	essentially have to <command>scp</command> the scripts to the client
 	box in order to
 	run them, making them visible, and for safety you also need to
 	<command>scp</command> the binaries (such as find) that those
 	scripts use.  The <application>ssh</application> client on the
 	client box may already be compromised.  All in all, using
-	ssh may be necessary when running over
+	SSH may be necessary when running over
 	insecure links, but it is also a lot harder to deal with.</para>
 
       <para>A good security script will also check for changes to user and
@@ -753,8 +753,9 @@
       <title>Denial of Service Attacks</title>
       <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
 
-      <para>This section covers Denial of Service attacks.  A DoS attack
-	is typically a packet attack.  While there is not much you can do
+      <para>This section covers Denial of Service attacks.  A
+        <acronym role="Denial of Service">DoS</acronym> attack is typically
+	a packet attack.  While there is not much you can do
 	about modern spoofed packet attacks that saturate your network,
 	you can generally limit the damage by ensuring that the attacks
 	cannot take down your servers by:</para>
@@ -774,16 +775,16 @@
 	</listitem>
       </orderedlist>
 
-      <para>A common DoS attack scenario is attacking a forking server and
-	making it spawning so many child processes that the host system
-	eventually runs out of memory, file descriptors, etc. and then
-	grinds to a halt.  <application>inetd</application> 
-	(see &man.inetd.8;) has several
+      <para>A common <acronym>DoS</acronym> attack scenario is attacking a
+        forking server and making it spawning so many child processes that the
+	host system eventually runs out of memory, file descriptors, etc. and
+	then grinds to a halt.  The <application>inetd</application>
+	application (see &man.inetd.8;) has several
 	options to limit this sort of attack.  It should be noted that
 	while it is possible to prevent a machine from going down, it is
 	not generally possible to prevent a service from being disrupted
 	by the attack.  Read the <application>inetd</application> manual
-	page carefully and pay
+	page &man.inetd.8; carefully and pay
 	specific attention to the <option>-c</option>, <option>-C</option>,
 	and <option>-R</option> options.  Note that spoofed-IP attacks
 	will circumvent the <option>-C</option> option to 
@@ -822,8 +823,8 @@
       <para>It is a very good idea to protect internal services from
 	external access by firewalling them off at your border routers.
 	The idea here is to prevent saturation attacks from outside your
-	LAN, not so much to protect internal services from network-based
-	<username>root</username> compromise.
+	<acronym>LAN</acronym>, not so much to protect internal services from
+	network-based <username>root</username> compromise.
 	Always configure an exclusive firewall, i.e.,
 	<quote>firewall everything <emphasis>except</emphasis> ports A, B,
 	C, D, and M-Z</quote>.  This way you can firewall off all of your
@@ -840,7 +841,7 @@
 	without compromising your low ports.  Also take note that &os;
 	allows you to control the range of port numbers used for dynamic
 	binding, via the various <varname>net.inet.ip.portrange</varname>
-	<command>sysctl</command>'s (<command>sysctl -a | fgrep
+	<command>sysctl</command>s (<command>sysctl -a | fgrep
 	portrange</command>), which can also ease the complexity of your
 	firewall's configuration.  For example, you might use a normal
 	first/last range of 4000 to 5000, and a hiport range of 49152 to
@@ -848,9 +849,9 @@
 	(except for certain specific Internet-accessible ports, of
 	course).</para>
 
-      <para>Another common DoS attack is called a springboard attack
-	&mdash; to attack a server in a manner that causes the server to
-	generate responses which overloads the server, the local
+      <para>Another common <acronym>DoS</acronym> attack is called a 
+        springboard attack &mdash; to attack a server in a manner that causes
+	the server to generate responses which overloads the server, the local
 	network, or some other machine.  The most common attack of this
 	nature is the <emphasis>ICMP ping broadcast attack</emphasis>.
 	The attacker spoofs ping packets sent to your LAN's broadcast
@@ -862,13 +863,14 @@
 	trick on several dozen broadcast addresses over several dozen
 	different networks at once.  Broadcast attacks of over a hundred
 	and twenty megabits have been measured.  A second common
-	springboard attack is against the ICMP error reporting system.
-	By constructing packets that generate ICMP error responses, an
-	attacker can saturate a server's incoming network and cause the
-	server to saturate its outgoing network with ICMP responses.  This
-	type of attack can also crash the server by running it out of
-	memory, especially if the server cannot drain the ICMP responses
-	it generates fast enough.
+	springboard attack is against the
+	<acronym role="Internet Control Message Protocol">ICMP</acronym> error
+	reporting system. By constructing packets that generate
+	<acronym>ICMP</acronym> error responses, an attacker can saturate a
+	server's incoming network and cause the server to saturate its outgoing
+	network with ICMP responses. This type of attack can also crash the
+	server by running it out of memory, especially if the server cannot
+	drain the ICMP responses it generates fast enough.
 	Use the <application>sysctl</application>
 	variable <literal>net.inet.icmp.icmplim</literal> to limit these attacks.
 	The last major class of springboard
@@ -889,12 +891,12 @@
 	route cache.  Refer to the <varname>net.inet.ip.rtexpire</varname>,
 	<varname>rtminexpire</varname>, and <varname>rtmaxcache</varname>
 	<command>sysctl</command> parameters.  A spoofed packet attack
-	that uses a random source IP will cause the kernel to generate a
-	temporary cached route in the route table, viewable with
+	that uses a random source IP address will cause the kernel to generate
+	a temporary cached route in the route table, viewable with
 	<command>netstat -rna | fgrep W3</command>.  These routes
 	typically timeout in 1600 seconds or so.  If the kernel detects
 	that the cached route table has gotten too big it will dynamically
-	reduce the <varname>rtexpire</varname> but will never decrease it 
+	reduce the <varname>rtexpire</varname> but will never decrease it
 	to less than <varname>rtminexpire</varname>.  There are two 
 	problems:</para>
 	
@@ -925,17 +927,16 @@
       <indexterm><primary>KerberosIV</primary></indexterm>
 
       <para>There are a few issues with both Kerberos and
-	ssh that need to be addressed if
+	SSH that need to be addressed if
 	you intend to use them.  Kerberos 5 is an excellent
 	authentication protocol, but there are bugs in the kerberized
 	<application>telnet</application> and
 	<application>rlogin</application> applications that make them
 	unsuitable for dealing with binary streams.  Also, by default
 	Kerberos does not encrypt a session unless you use the
-	<option>-x</option> option.  <application>ssh</application>
-	encrypts everything by default.</para>
+	<option>-x</option> option.  SSH encrypts everything by default.</para>
 
-      <para>Ssh works quite well in every
+      <para>SSH works quite well in every
 	respect except that it forwards encryption keys by default.  What
 	this means is that if you have a secure workstation holding keys
 	that give you access to the rest of the system, and you
@@ -948,17 +949,16 @@
 	access to any other machine that your keys unlock.</para>
 
       <para>We recommend that you use ssh in
-	combination with Kerberos whenever possible for staff logins.
-	<application>Ssh</application> can be compiled with Kerberos
-	support.  This reduces your reliance on potentially exposed
-	ssh keys while at the same time
-	protecting passwords via Kerberos.  Ssh
-	keys should only be used for automated tasks from secure machines
+	combination with Kerberos whenever possible for staff logins.  The
+	<application>ssh</application> client and server can be compiled with
+	Kerberos support.  This reduces your reliance on potentially exposed
+	SSH keys while at the same time protecting passwords via Kerberos.
+	SSH keys should only be used for automated tasks from secure machines
 	(something that Kerberos is unsuited to do).  We also recommend that
 	you either turn off key-forwarding in the
-	ssh configuration, or that you make use
+	<application>ssh</application> configuration, or that you make use
 	of the <literal>from=IP/DOMAIN</literal> option that
-	ssh allows in its
+	<application>ssh</application> allows in its
 	<filename>authorized_keys</filename> file to make the key only
 	usable to entities logging in from specific machines.</para>
     </sect2>
@@ -1000,48 +1000,52 @@
       space of possible passwords.</para>
 
     <para>Unfortunately the only secure way to encrypt passwords when
-      &unix; came into being was based on DES, the Data Encryption
-      Standard.  This was not such a problem for users resident in
-      the US, but since the source code for DES could not be exported
-      outside the US, &os; had to find a way to both comply with 
+      &unix; came into being was based on
+      <acronym role="Data Encryption Standard">DES</acronym>, the Data
+      Encryption Standard.  This was not such a problem for users resident in
+      the US, but since the source code for <acronym>DES</acronym> could not be 
+      exported outside the US, &os; had to find a way to both comply with 
       US law and retain compatibility with all the other &unix;
-      variants that still used DES.</para>
+      variants that still used <acronym>DES</acronym>.</para>
 
     <para>The solution was to divide up the encryption libraries 
-      so that US users could install the DES libraries and use
-      DES but international users still had an encryption method
-      that could be exported abroad.  This is how &os; came to
-      use MD5 as its default encryption method.  MD5 is believed to
-      be more secure than DES, so installing DES is offered primarily
-      for compatibility reasons.</para>
+      so that US users could install the <acronym>DES</acronym> libraries and
+      use <acronym>DES</acronym> but international users still had an
+      encryption method that could be exported abroad.  This is how &os; came
+      to use <acronym role="Message Digest 5">MD5</acronym> as its default
+      encryption method.  <acronym>MD5</acronym> is believed to be more secure
+      than <acronym>DES</acronym>, so installing <acronym>DES</acronym> is
+      offered primarily for compatibility reasons.</para>
 
     <sect2>
       <title>Recognizing Your Crypt Mechanism</title>
 
-      <para>Currently the library supports DES, MD5 and Blowfish hash
-	functions.  By default &os; uses MD5 to encrypt
+      <para>Currently the library supports <acronym>DES</acronym>,
+      <acronym>MD5</acronym> and Blowfish hash
+	functions.  By default &os; uses <acronym>MD5</acronym> to encrypt
 	passwords.</para>
 
       <para>It is pretty easy to identify which encryption method 
 	&os; is set up to use.  Examining the encrypted passwords in
 	the <filename>/etc/master.passwd</filename> file is one way.
-	Passwords encrypted with the MD5 hash are longer than those
-	encrypted with the DES hash and also begin with the characters
-	<literal>&dollar;1&dollar;</literal>.  Passwords starting with
-	<literal>&dollar;2a&dollar;</literal> are encrypted with the
-	Blowfish hash function.  DES password strings do not
-	have any particular identifying characteristics, but they are
-	shorter than MD5 passwords, and are coded in a 64-character
-	alphabet which does not include the <literal>&dollar;</literal>
-	character, so a relatively short string which does not begin with
-	a dollar sign is very likely a DES password.</para>
+	Passwords encrypted with the <acronym>MD5</acronym> hash are longer
+	than those encrypted with the <acronym>DES</acronym> hash and also
+	begin with the characters <literal>&dollar;1&dollar;</literal>.  
+	Passwords starting with <literal>&dollar;2a&dollar;</literal> are
+	encrypted with the Blowfish hash function.  <acronym>DES</acronym>
+	password strings do not have any particular identifying characteristics,
+	but they are shorter than <acronym>MD5</acronym> passwords, and are
+	coded in a 64-character alphabet which does not include the
+	<literal>&dollar;</literal> character, so a relatively short string
+	which does not begin with a dollar sign is very likely a
+	<acronym>DES</acronym> password.</para>
 
       <para>The password format used for new passwords is controlled
 	by the <literal>passwd_format</literal> login capability in
 	<filename>/etc/login.conf</filename>, which takes values of
 	<literal>des</literal>, <literal>md5</literal> or
 	<literal>blf</literal>.  See the &man.login.conf.5; manual page
-	for more information about login capabilities.</para>
+	for more information on login capabilities.</para>
 
     </sect2>
   </sect1>
@@ -1054,16 +1058,17 @@
       <secondary>one-time passwords</secondary>
     </indexterm>
 
-    <para>By default, &os; includes support for OPIE (One-time Passwords
-      In Everything), which uses the MD5 hash by default.</para>
+    <para>By default, &os; includes support for
+      <acronym role="One-Time Passwords In Everything">OPIE</acronym>
+      (One-time Passwords In Everything), which uses the
+      <acronym>MD5</acronym> hash by default.</para>
 
     <para>There are three different sorts of passwords which we will discuss
       below.  The first is your usual &unix; style or
       Kerberos password; we will call this a <quote>&unix; password</quote>.
-      The second sort is the one-time password which is generated by the OPIE
-      &man.opiekey.1; program and accepted by the
-      &man.opiepasswd.1; program
-      and the login prompt; we will
+      The second sort is the one-time password which is generated by the 
+      <acronym>OPIE</acronym> &man.opiekey.1; program and accepted by the
+      &man.opiepasswd.1; program and the login prompt; we will
       call this a <quote>one-time password</quote>.  The final sort of
       password is the secret password which you give to the
       <command>opiekey</command> program (and
@@ -1075,32 +1080,33 @@
 
     <para>The secret password does not have anything to do with your &unix;
       password; they can be the same but this is not recommended.
-      OPIE secret passwords are not limited to 8 characters like old
-      &unix; passwords<footnote><para>Under &os; the standard login
+      <acronym>OPIE</acronym> secret passwords are not limited to 8 characters
+      like old &unix; passwords<footnote><para>Under &os; the standard login
       password may be up to 128 characters in length.</para></footnote>,
       they can be as long as you like.  Passwords of six or
       seven word long phrases are fairly common.  For the most part, the
-      OPIE system operates completely independently of the &unix;
-      password system.</para>
+      <acronym>OPIE</acronym> system operates completely independently of the
+      &unix; password system.</para>
 
     <para>Besides the password, there are two other pieces of data that
-      are important to OPIE.  One is what is known as the
+      are important to <acronym>OPIE</acronym>.  One is what is known as the
       <quote>seed</quote> or <quote>key</quote>, consisting of two letters
       and five digits.  The other is what is called the <quote>iteration
-      count</quote>, a number between 1 and 100.  OPIE creates the
-      one-time password by concatenating the seed and the secret password,
-      then applying the MD5 hash as many times as specified by the
-      iteration count and turning the result into six short English words.
-      These six English words are your one-time password.  The
-      authentication system (primarily PAM) keeps
-      track of the last one-time password used, and the user is
+      count</quote>, a number between 1 and 100.  <acronym>OPIE</acronym> 
+      creates the one-time password by concatenating the seed and the secret 
+      password, then applying the <acronym>MD5</acronym> hash as many times as
+      specified by the iteration count and turning the result into six short 
+      English words. These six English words are your one-time password.  The
+      authentication system (primarily 
+      <acronym role="Pluggable Authentication Modules">PAM</acronym>)
+      keeps track of the last one-time password used, and the user is
       authenticated if the hash of the user-provided password is equal to
       the previous password.  Because a one-way hash is used it is
       impossible to generate future one-time passwords if a successfully
       used password is captured; the iteration count is decremented after
       each successful login to keep the user and the login program in
-      sync.  When the iteration count gets down to 1, OPIE must be
-      reinitialized.</para>
+      sync.  When the iteration count gets down to 1, <acronym>OPIE</acronym>
+      must be reinitialized.</para>
 
     <para>There are a few programs involved in each system
       which we will discuss below.  The
@@ -1108,7 +1114,7 @@
       count, a seed, and a secret password, and generates a one-time
       password or a consecutive list of one-time passwords.  The
       <command>opiepasswd</command>
-      program is used to initialize OPIE,
+      program is used to initialize <acronym>OPIE</acronym>,
       and to change passwords, iteration counts, or seeds; it
       takes either a secret passphrase, or an iteration count,
       seed, and a one-time password.  The
@@ -1133,8 +1139,8 @@
 
     <sect2>
       <title>Secure Connection Initialization</title>
-      <para>To initialize OPIE for the first time, execute the
-        <command>opiepasswd</command> command:</para>
+      <para>To initialize <acronym>OPIE</acronym> for the first time, execute
+        the <command>opiepasswd</command> command:</para>
 
       <screen>&prompt.user; <userinput>opiepasswd -c</userinput>
 [grimreaper] ~ $ opiepasswd -f -c
@@ -1210,7 +1216,7 @@
     <sect2>
       <title>Generating a Single One-time Password</title>
 
-      <para>Once you have initialized OPIE and login, you will be 
+      <para>Once you have initialized OPIE and login, you will be
 	presented with a prompt like this:</para>
 
 <screen>&prompt.user; <userinput>telnet example.com</userinput>
@@ -1224,8 +1230,8 @@
 otp-md5 498 gr4269 ext
 Password: </screen>
 
-      <para>As a side note, the OPIE prompts have a useful feature
-	(not shown here): if you press <keycap>Return</keycap>
+      <para>As a side note, the <acronym>OPIE</acronym> prompts have a useful
+        feature (not shown here): if you press <keycap>Return</keycap>
 	at the password prompt, the
 	prompter will turn echo on, so you can see what you are
 	typing.  This can be extremely useful if you are attempting to
@@ -1290,8 +1296,8 @@
     <sect2>
       <title>Restricting Use of &unix; Passwords</title>
 
-      <para>OPIE can restrict the use of &unix; passwords based on the IP
-	address of a login session.  The relevant file
+      <para><acronym>OPIE</acronym> can restrict the use of &unix; passwords
+        based on the IP address of a login session.  The relevant file
 	is <filename>/etc/opieaccess</filename>, which is present by default.
 	Please check &man.opieaccess.5;
 	for more information on this file and which security considerations
@@ -1327,7 +1333,8 @@
     <title>TCP Wrappers</title>
 
     <para>Anyone familiar with &man.inetd.8; has probably heard
-      of <acronym>TCP</acronym> Wrappers at some point.  But few
+      of <acronym role="Transport Control Protocol">TCP</acronym>
+      Wrappers at some point.  But few
       individuals seem to fully comprehend its usefulness in a
       network environment.  It seems that everyone wants to
       install a firewall to handle network connections.  While a
@@ -1591,8 +1598,9 @@
         during the era of restrictive export controls on cryptographic
         code from the USA.</para>
 
-      <para>Alternatively, the MIT implementation of Kerberos is
-        available from the Ports Collection as
+      <para>Alternatively, the 
+        <acronym role="Massachusetts Insitute of Technology">MIT</acronym>
+	implementation of Kerberos is available from the Ports Collection as
         <filename role="package">security/krb5</filename>.</para>
     </sect2>
 
@@ -1889,7 +1897,7 @@
 Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
 
       <para>Now try changing the password using &man.passwd.1; to
-	check if the <application>kpasswd</application> daemon can get 
+	check if the <application>kpasswd</application> daemon can get
 	authorization to the Kerberos database:</para>
 
       <screen>&prompt.user; <userinput>passwd</userinput>
@@ -2133,7 +2141,7 @@
 	programs that implement the program
 	(<application>Kerberos</application> telnet, for example).  The
 	current version of the protocol is version 5, described in
-	<acronym>RFC</acronym>&nbsp;1510.</para>
+	<acronym role="Request For Comments">RFC</acronym>&nbsp;1510.</para>
 
       <para>Several free implementations of this protocol are available,
 	covering a wide range of operating systems.  The Massachusetts
@@ -2168,7 +2176,8 @@
 	<secondary>Key Distribution Center</secondary>
       </indexterm>
 
-      <para>The Key Distribution Center (<acronym>KDC</acronym>) is the
+      <para>The Key Distribution Center 
+        <acronym role="Key Distribution Center">KDC</acronym>) is the
 	centralized authentication service that
 	<application>Kerberos</application> provides &mdash; it is the
 	computer that issues <application>Kerberos</application> tickets.
@@ -2580,8 +2589,9 @@
 	      immediately upon running <command>kinit</command> &mdash;
 	      even before you type your password!  The explanation is
 	      that the <application>Kerberos</application> server freely
-	      transmits a <acronym>TGT</acronym> (Ticket Granting
-	      Ticket) to any unauthorized request;  however, every
+	      transmits a
+	      <acronym role="Ticket Granting Ticket">TGT</acronym> (Ticket
+	      Granting Ticket) to any unauthorized request;  however, every
 	      <acronym>TGT</acronym> is encrypted in a key derived from
 	      the user's password.  Therefore, when a user types their
 	      password it is not being sent to the <acronym>KDC</acronym>,
@@ -2726,7 +2736,7 @@
 	</sect3>
 
 	<sect3>
-	  <title>The KDC is a single point of failure</title>
+	  <title>The <acronym>KDC</acronym> is a single point of failure</title>
 
 	  <para>By design, the <acronym>KDC</acronym> must be as secure as
 	    the master password database is contained on it.  The
@@ -2783,7 +2793,8 @@
 	  <listitem>
 	  <para><ulink
 	    url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html">;
-	    The <application>Kerberos</application> FAQ</ulink></para>
+	    The <application>Kerberos</application> <acronym>FAQ</acronym>
+	    </ulink></para>
 	</listitem>
 
 	<listitem>
@@ -2792,9 +2803,10 @@
 	</listitem>
 
 	<listitem>
-	  <para><ulink url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC 1510,
-	    The <application>Kerberos</application> Network Authentication Service
-	    (V5)</ulink></para>
+	  <para><ulink
+	  url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">;
+	    <acronym>RFC</acronym> 1510, The <application>Kerberos</application>
+	    Network Authentication Service (V5)</ulink></para>
 	</listitem>
 
 	<listitem>
@@ -2850,9 +2862,12 @@
     </note>
 
     <para>The version of <application>OpenSSL</application> included
-      in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3),
-      Transport Layer Security v1 (TLSv1) network security protocols
-      and can be used as a general cryptographic library.</para>
+      in &os; supports Secure Sockets Layer v2/v3 (
+      <acronym role="Secure Sockets Layer">SSL</acronym>v2/
+      <acronym>SSL</acronym>v3), Transport Layer Security v1 
+      (<acronym role="Transport Layer Security">TLS</acronym>v1) network 
+      security protocols and can be used as a general cryptographic library.
+      </para>
 
     <note>
       <para>While <application>OpenSSL</application> supports the
@@ -2869,8 +2884,9 @@
       that the credentials of the company or individual are valid
       and not fraudulent.  If the certificate in question has
       not been verified by one of the several <quote>Certificate Authorities</quote>,
-      or <acronym>CA</acronym>s, a warning is usually produced.  A
-      Certificate Authority is a company, such as <ulink url="http://www.verisign.com">VeriSign</ulink>, which will
+      or <acronym role="Certificate Authorities">CA</acronym>s, a warning is
+      usually produced.  A Certificate Authority is a company, such as
+      <ulink url="http://www.verisign.com">VeriSign</ulink>, which will
       sign certificates in order to validate credentials of individuals
       or companies.  This process has a cost associated with it and
       is definitely not a requirement for using certificates; however,
@@ -2961,9 +2977,9 @@
 
       <para>So what can these files do?  A good use would be to
 	encrypt connections to the <application>Sendmail</application>
-	<acronym>MTA</acronym>.  This would dissolve the use of clear
-	text authentication for users who send mail via the local
-	<acronym>MTA</acronym>.</para>
+	<acronym role="Mail Transport Agent">MTA</acronym>.  This would
+	dissolve the use of clear text authentication for users who send
+	mail via the local <acronym>MTA</acronym>.</para>
 
       <note>
 	<para>This is not the best use in the world as some
@@ -3047,7 +3063,8 @@
     </indexterm>
 
     <title>VPN over IPsec</title>
-    <para>Creating a VPN between two networks, separated by the
+    <para>Creating a <acronym role="Virtual Private Network">VPN</acronym>
+      between two networks, separated by the
       Internet, using FreeBSD gateways.</para>
  
     <sect2>
@@ -3067,30 +3084,33 @@
       <title>Understanding IPsec</title>
 
       <para>This section will guide you through the process of setting
-	up IPsec, and to use it in an environment which consists of
+	up <acronym role="IP Security">IPsec</acronym>, and to use it in an
+	environment which consists of
 	FreeBSD and <application>&microsoft.windows; 2000/XP</application>
 	machines, to make them communicate securely.  In order to set up
-	IPsec, it is necessary that you are familiar with the concepts
-	of building a custom kernel (see
+	<acronym>IPsec</acronym>, it is necessary that you are familiar with
+	the concepts of building a custom kernel (see
 	<xref linkend="kernelconfig">).</para>
     
       <para><emphasis>IPsec</emphasis> is a protocol which sits on top
-	of the Internet Protocol (IP) layer.  It allows two or more
-	hosts to communicate in a secure manner (hence the name).  The
-	FreeBSD IPsec <quote>network stack</quote> is based on the
-	<ulink url="http://www.kame.net/">KAME</ulink>; implementation,
-	which has support for both protocol families, IPv4 and
-	IPv6.</para>
+	of the Internet Protocol 
+	(<acronym role="Internet Protocol"IP</acronym>) layer.  It allows two
+	or more hosts to communicate in a secure manner (hence the name).  The
+	FreeBSD <acronym>IPsec</acronym> <quote>network stack</quote> is based
+	on the <ulink url="http://www.kame.net/">KAME</ulink>; implementation,
+	which has support for both protocol families, IPv4 and IPv6.</para>
 
       <note>
         <para>FreeBSD contains a <quote>hardware
-        accelerated</quote> IPsec stack, known as <quote>Fast
-        IPsec</quote>, that was obtained from OpenBSD.  It employs
+        accelerated</quote> <acroonym>IPsec</acronym> stack, known as
+	<quote>Fast IPsec</quote>, that was obtained from OpenBSD.  It employs
         cryptographic hardware (whenever possible) via the
-        &man.crypto.4; subsystem to optimize the performance of IPsec.
+        &man.crypto.4; subsystem to optimize the performance of
+	<acronym>IPsec.</acronym>
         This subsystem is new, and does not support all the features
-        that are available in the KAME version of IPsec.  However, in
-        order to enable hardware-accelerated IPsec, the following
+        that are available in the KAME version of <acronym>IPsec</acronym>.
+	However, in order to enable hardware-accelerated
+	<acronym>IPsec</acronym>, the following
         kernel option has to be added to your kernel configuration
         file:</para>
 
@@ -3105,8 +3125,8 @@
 
         <para> Note, that it is not currently possible to use the
 	  <quote>Fast IPsec</quote> subsystem in lieu of the KAME
-	  implementation of IPsec.  Consult the &man.fast.ipsec.4;
-	  manual page for more information.</para>
+	  implementation of <acronym>IPsec</acronym>.  Consult the
+	  &man.fast.ipsec.4; manual page for more information.</para>
       </note>
 
       <note>
@@ -3130,23 +3150,25 @@
 	<secondary>AH</secondary>
       </indexterm>
 
-      <para>IPsec consists of two sub-protocols:</para>
+      <para><acronym>IPsec</acronym> consists of two sub-protocols:</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>Encapsulated Security Payload
-	      (ESP)</emphasis>, protects the IP packet data from third
-	    party interference, by encrypting the contents using
+	    (<acronym role="Encapsulated Security Payload">ESP</acronym>)
+	    </emphasis>, protects the <acronym>IP</acronym> packet data from
+	    third party interference, by encrypting the contents using
 	    symmetric cryptography algorithms (like Blowfish,
-	    3DES).</para>
+	    <acronym>3DES</acronym>).</para>
         </listitem>
         <listitem>
-          <para><emphasis>Authentication Header (AH)</emphasis>,
-	    protects the IP packet header from third party interference
-	    and spoofing, by computing a cryptographic checksum and
-	    hashing the IP packet header fields with a secure hashing
-	    function.  This is then followed by an additional header
-	    that contains the hash, to allow the information in the
+          <para><emphasis>Authentication Header
+	    (<acronym role="Authentication Header">AH</acronym>)</emphasis>,
+	    protects the <acronym>IP</acronym> packet header from third party
+	    interference and spoofing, by computing a cryptographic checksum
+	    and hashing the <acronym>IP</acronym> packet header fields with a
+	    secure hashing function.  This is then followed by an additional
+	    header that contains the hash, to allow the information in the
 	    packet to be authenticated.</para>
         </listitem>
       </itemizedlist>
@@ -3164,18 +3186,19 @@
 	<see>VPN</see>
       </indexterm>
 
-      <para>IPsec can either be used to directly encrypt the traffic
-	between two hosts (known as <emphasis>Transport
-	  Mode</emphasis>); or to build <quote>virtual tunnels</quote>
+      <para><acronym>IPsec</acronym> can either be used to directly encrypt
+        the traffic between two hosts (known as <emphasis>Transport
+	Mode</emphasis>); or to build <quote>virtual tunnels</quote>
 	between two subnets, which could be used for secure
 	communication between two corporate networks (known as
 	<emphasis>Tunnel Mode</emphasis>).  The latter is more commonly
-	known as a <emphasis>Virtual Private Network (VPN)</emphasis>.
-	The &man.ipsec.4; manual page should be consulted for detailed
-	information on the IPsec subsystem in FreeBSD.</para>
+	known as a <emphasis>Virtual Private Network (<acronym>VPN</acronym>)
+	</emphasis>. The &man.ipsec.4; manual page should be consulted for
+	detailed information on the <acronym>IPsec</acronym> subsystem in
+	&os;.</para>
       
-      <para>To add IPsec support to your kernel, add the following
-	options to your kernel configuration file:</para>
+      <para>To add <acronym>IPsec</acronym> support to your kernel, add the
+        following options to your kernel configuration file:</para>
 
       <indexterm>
 	<primary>kernel options</primary>
@@ -3208,11 +3231,12 @@
     <sect2>
       <title>The Problem</title>
  
-      <para>There is no standard for what constitutes a VPN.  VPNs can
-	be implemented using a number of different technologies, each of
+      <para>There is no standard for what constitutes a <acronym>VPN</acronym>.
+        <acronym>VPN</acronym>s can be implemented using a number of different
+	technologies, each of
 	which have their own strengths and weaknesses.  This section
 	presents a scenario, and the strategies used for implementing a
-	VPN for this scenario.</para>
+	<acronym>VPN</acronym> for this scenario.</para>
     </sect2>
     
     <sect2> 
@@ -3231,33 +3255,36 @@
           <para>You have at least two sites</para>
         </listitem>
         <listitem>
-          <para>Both sites are using IP internally</para>
+          <para>Both sites are using <acronym>IP</acronym> internally</para>
         </listitem>
         <listitem>
           <para>Both sites are connected to the Internet, through a
             gateway that is running FreeBSD.</para>
         </listitem>
         <listitem>
-          <para>The gateway on each network has at least one public IP
-            address.</para>
+          <para>The gateway on each network has at least one public 
+	    <acronym>IP</acronym>address.</para>
         </listitem>
         <listitem>
           <para>The internal addresses of the two networks can be
-            public or private IP addresses, it does not matter.  You can
-            be running NAT on the gateway machine if necessary.</para>
+            public or private <acronym>IP</acronym> addresses, it does not
+	    matter.  You can be running 
+	    <acronym role="Network Address Translation">NAT</acronym> on the
+	    gateway machine if necessary.</para>
         </listitem>
         <listitem>
-          <para>The internal IP addresses of the two networks
-            <emphasis>do not collide</emphasis>.  While I expect it is
-            theoretically possible to use a combination of VPN
-            technology and NAT to get this to work, I expect it to be a
+          <para>The internal <acronym>IP</acronym> addresses of the two
+	    networks <emphasis>do not collide</emphasis>.  While I expect it
+	    is theoretically possible to use a combination of
+	    <acronym>VPN</acronym> technology and <acronym>NAT</acronym>
+	    to get this to work, I expect it to be a
             configuration nightmare.</para>
         </listitem>
       </itemizedlist>
       
       <para>If you find that you are trying to connect two networks,
-        both of which, internally, use the same private IP address range
-        (e.g. both of them use <hostid
+        both of which, internally, use the same private <acronym>IP</acronym>
+	address range (e.g. both of them use <hostid
         role="ipaddr">192.168.1.x</hostid>), then one of the networks will
         have to be renumbered.</para>
  
@@ -3293,14 +3320,16 @@
 	</textobject>
       </mediaobject>
  
-      <para>Notice the two public IP addresses.  I will use the letters to
+      <para>Notice the two public <acronym>IP</acronym> addresses.  I will use
+        the letters to
         refer to them in the rest of this article.  Anywhere you see those
         letters in this article, replace them with your own public IP
         addresses.  Note also that internally, the two gateway
-        machines have .1 IP addresses, and that the two networks have
-        different private IP addresses (<hostid
-        role="ipaddr">192.168.1.x</hostid> and <hostid
-        role="ipaddr">192.168.2.x</hostid> respectively).  All the
+        machines have <hostid role="ipaddr">.1</hostid> <acronym>IP</acronym>
+	addresses, and that the two networks have different private
+	<acronym>IP</acronym> addresses  
+	(<hostid role="ipaddr">192.168.1.x</hostid> and 
+	<hostid role="ipaddr">192.168.2.x</hostid> respectively).  All the
         machines on the private networks have been configured to use the
         <hostid role="ipaddr">.1</hostid> machine as their default
         gateway.</para>
@@ -3323,8 +3352,8 @@
       <para>And the whole thing has to be secure.  This means that
         traffic between the two networks has to be encrypted.</para>
  
-      <para>Creating a VPN between these two networks is a multi-step
-        process.  The stages are as follows:</para>
+      <para>Creating a <acronym>VPN</acronym> between these two networks is a
+        multi-step process.  The stages are as follows:</para>
  
       <orderedlist>
         <listitem>
@@ -3343,7 +3372,7 @@
         <listitem>
           <para>Configure additional software on the FreeBSD gateways,
             to allow &windows; machines to see one another across the
-            VPN.</para>
+            <acronym>VPN</acronym>.</para>
         </listitem>
       </orderedlist>
 
@@ -3400,9 +3429,9 @@
         the public IP addresses, and two for the private IP
         addresses.</para>
  
-      <para>Support for the gif device must be compiled in to the
-        &os; kernel on both machines.  You can do this by adding the
-        line:</para>
+      <para>Support for the <devicename>gif</devicename> device must be
+        compiled in to the &os; kernel on both machines.  You can do this by
+	adding the line:</para>
  
       <programlisting>device gif</programlisting>
  
@@ -3410,8 +3439,9 @@
         then compile, install, and reboot as normal.</para>
  
       <para>Configuring the tunnel is a two step process.  First the
-        tunnel must be told what the outside (or public) IP addresses
-        are, using &man.ifconfig.8;.  Then the private IP addresses must be
+        tunnel must be told what the outside (or public) <acronym>IP</acronym>
+	addresses are, using &man.ifconfig.8;.  Then the private 
+	<acronym>IP</acronym> addresses must be
         configured using &man.ifconfig.8;.</para>
  
       <para>On the gateway machine on network #1 you would run the
@@ -3423,7 +3453,8 @@
       </screen>
 
       <para>On the other gateway machine you run the same commands,
-        but with the order of the IP addresses reversed.</para>
+        but with the order of the <acronym>IP</acronym> addresses reversed.
+	</para>
 
       <screen>&prompt.root; <userinput>ifconfig <replaceable>gif0</replaceable> create</userinput>
 &prompt.root; <userinput>ifconfig <replaceable>gif0</replaceable> tunnel <replaceable>W.X.Y.Z</replaceable> <replaceable>A.B.C.D</replaceable></userinput>
@@ -3471,15 +3502,16 @@
         shortly.</para>
  
       <para>It is likely that you are running a firewall on both
-        machines.  This will need to be circumvented for your VPN
-        traffic.  You might want to allow all traffic between both
-        networks, or you might want to include firewall rules that
-        protect both ends of the VPN from one another.</para>
+        machines.  This will need to be circumvented for your 
+	<acronym>VPN</acronym> traffic.  You might want to allow all traffic
+	between both networks, or you might want to include firewall rules
+	that protect both ends of the <acronym>VPN</acronym> from one
+	another.</para>
  
       <para>It greatly simplifies testing if you configure the
-        firewall to allow all traffic through the VPN.  You can always
-        tighten things up later.  If you are using &man.ipfw.8; on the
-        gateway machines then a command like</para>
+        firewall to allow all traffic through the <acronym>VPN</acronym>.
+	You can always tighten things up later.  If you are using &man.ipfw.8;
+	on the gateway machines then a command like</para>
 
       <programlisting>ipfw add 1 allow ip from any to any via gif0</programlisting>
  
@@ -3487,9 +3519,10 @@
         VPN, without affecting your other firewall rules.  Obviously
         you will need to run this command on both gateway hosts.</para>
  
-      <para>This is sufficient to allow each gateway machine to ping
-        the other.  On <hostid role="ipaddr">192.168.1.1</hostid>, you
-        should be able to run</para>
+      <para>This is sufficient to allow each gateway machine to
+        <command>ping</command> the other.  On
+	<hostid role="ipaddr">192.168.1.1</hostid>, you should be able to run
+	</para>
  
       <programlisting>ping 192.168.2.1</programlisting>
  
@@ -3497,7 +3530,7 @@
         thing on the other gateway machine.</para>
  
       <para>However, you will not be able to reach internal machines
-        on either network yet.  This is because of the routing --
+        on either network yet.  This is because of the routing &mdash;
         although the gateway machines know how to reach one another,
         they do not know how to reach the network behind each one.</para>
  
@@ -3516,12 +3549,12 @@
         <hostid role="ipaddr">192.168.1.x</hostid> addresses
         instead.</para>
  
-      <para>IP traffic from hosts on one network will now be able to
-        reach hosts on the other network.</para>
+      <para><acronym>IP</acronym> traffic from hosts on one network will now
+        be able to reach hosts on the other network.</para>
  
-      <para>That has now created two thirds of a VPN between the two
-        networks, in as much as it is <quote>virtual</quote> and it is a
-        <quote>network</quote>.  It is not private yet.  You can test
+      <para>That has now created two thirds of a <acronym>VPN</acronym> between
+        the two networks, in as much as it is <quote>virtual</quote> and it is
+	a <quote>network</quote>.  It is not private yet.  You can test
         this using &man.ping.8; and &man.tcpdump.1;.  Log in to the
         gateway host and run</para>
  
@@ -3542,10 +3575,10 @@
 16:10:26.029112 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
       </programlisting>
  
-      <para>As you can see, the ICMP messages are going back and forth
-        unencrypted.  If you had used the <option>-s</option> parameter to
-        &man.tcpdump.1; to grab more bytes of data from the packets you
-        would see more information.</para>
+      <para>As you can see, the <acronym>ICMP</acronym> messages are going
+        back and forth unencrypted.  If you had used the <option>-s</option>
+	parameter to &man.tcpdump.1; to grab more bytes of data from the
+	packets you would see more information.</para>
  
       <para>Obviously this is unacceptable.  The next section will
         discuss securing the link between the two networks so that it
@@ -3586,7 +3619,8 @@
     <sect3>
       <title>Step 2: Securing the link</title>
  
-      <para>To secure the link we will be using IPsec.  IPsec provides
+      <para>To secure the link we will be using <acronym>IPsec</acronym>.
+        <acronym>IPsec</acronym> provides
         a mechanism for two hosts to agree on an encryption key, and to
         then use this key in order to encrypt data between the two
         hosts.</para>
@@ -3603,10 +3637,10 @@
         <listitem>
           <para>There must be a mechanism for specifying which traffic
             should be encrypted.  Obviously, you do not want to encrypt
-            all your outgoing traffic -- you only want to encrypt the
-            traffic that is part of the VPN.  The rules that you put in
-            place to determine what traffic will be encrypted are called
-            <quote>security policies</quote>.</para>
+            all your outgoing traffic &mdash; you only want to encrypt the
+            traffic that is part of the <acronym>VPN</acronym>.  The rules
+	    that you put in place to determine what traffic will be encrypted
+	    are called <quote>security policies</quote>.</para>
          </listitem>
        </orderedlist>
  
@@ -3614,7 +3648,8 @@
          maintained by the kernel, and can be modified by userland
          programs.  However, before you can do this you must configure the
          kernel to support IPsec and the Encapsulated Security Payload
-         (ESP) protocol.  This is done by configuring a kernel with:</para>
+         (<acronym>ESP</acronym>) protocol.  This is done by configuring a
+	 kernel with:</para>
  
        <indexterm>
 	 <primary>kernel options</primary>
@@ -3637,7 +3672,9 @@
          associations.  You can configure them by hand between two hosts,
          which entails choosing the encryption algorithm, encryption keys,
          and so forth, or you can use daemons that implement the Internet
-         Key Exchange protocol (IKE) to do this for you.</para>
+         Key Exchange protocol 
+	 (<acronym role="Internet Key Exchange">IKE</acronym>) to do this
+	 for you.</para>
  
        <para>I recommend the latter.  Apart from anything else, it is
          easier to set up.</para>
@@ -3662,26 +3699,28 @@
        <para>There are a number of choices for daemons to manage
          security associations with FreeBSD.  This article will describe
          how to use one of these, racoon&nbsp;&mdash; which is available from
-	 <filename role="package">security/ipsec-tools</filename> in the &os; Ports
-	 collection.</para>
+	 <filename role="package">security/ipsec-tools</filename> in the &os;
+	 Ports Collection.</para>
  
        <indexterm>
 	 <primary>racoon</primary>
        </indexterm>
 
-       <para>The <application>racoon</application> software must be run on both gateway hosts.  On each host it
-         is configured with the IP address of the other end of the VPN,
-         and a secret key (which you choose, and must be the same on both
-         gateways).</para>
+       <para>The <application>racoon</application> software must be run on 
+         both gateway hosts.  On each host it is configured with the 
+	 <acronym>IP</acronym> address of the other end of the
+	 <acronym>VPN</acronym>, and a secret key (which you choose, and
+	 must be the same on both gateways).</para>
  
        <para>The two daemons then contact one another, confirm that they
          are who they say they are (by using the secret key that you
          configured).  The daemons then generate a new secret key, and use
-         this to encrypt the traffic over the VPN.  They periodically
+         this to encrypt the traffic over the <acronym>VPN</acronym>.  They
+	 periodically
          change this secret, so that even if an attacker were to crack one
          of the keys (which is as theoretically close to unfeasible as it
-         gets) it will not do them much good -- by the time they have cracked
-         the key the two daemons have chosen another one.</para>
+         gets) it will not do them much good &mdash; by the time they have
+	 cracked the key the two daemons have chosen another one.</para>
  
        <para>The configuration file for racoon is stored in
          <filename>${PREFIX}/etc/racoon</filename>.  You should find a
@@ -3691,9 +3730,10 @@
          key</quote>.</para>
  
        <para>The default racoon configuration expects to find this in
-         the file <filename>${PREFIX}/etc/racoon/psk.txt</filename>.  It is important to note
-         that the pre-shared key is <emphasis>not</emphasis> the key that will be used to
-         encrypt your traffic across the VPN link, it is simply a token
+         the file <filename>${PREFIX}/etc/racoon/psk.txt</filename>.  It is
+	 important to note that the pre-shared key is <emphasis>not</emphasis>
+	 the key that will be used to encrypt your traffic across the 
+	 <acronym>VPN</acronym> link, it is simply a token
          that allows the key management daemons to trust one another.</para>
 
        <para><filename>psk.txt</filename> contains a line for each
@@ -3705,23 +3745,28 @@
  
        <programlisting>W.X.Y.Z            secret</programlisting>
  
-       <para>That is, the <emphasis>public</emphasis> IP address of the remote end,
-         whitespace, and a text string that provides the secret.
-         Obviously, you should not use <quote>secret</quote> as your key -- the normal
+       <para>That is, the <emphasis>public</emphasis> <acronym>IP</acronym>
+         address of the remote end, whitespace, and a text string that
+	 provides the secret. Obviously, you should not use 
+	 <quote>secret</quote> as your key &mdash; the normal
          rules for choosing a password apply.</para>
  
        <para>On gateway host #2 the line would look like this</para>
  
        <programlisting>A.B.C.D            secret</programlisting>
  
-       <para>That is, the public IP address of the remote end, and the
+       <para>That is, the public <acronym>IP</acronym> address of the remote
+         end, and the
          same secret key.  <filename>psk.txt</filename> must be mode
          <literal>0600</literal> (i.e., only read/write to
          <username>root</username>) before racoon will run.</para>
  
        <para>You must run racoon on both gateway machines.  You will
-         also need to add some firewall rules to allow the IKE traffic,
-         which is carried over UDP to the ISAKMP (Internet Security Association
+         also need to add some firewall rules to allow the
+	 <acronym>IKE</acronym> traffic,
+         which is carried over <acronym>UDP</acronym> to the 
+	 <acronym role="Internet Security Association Key Management
+Protocol">ISAKMP</acronym> (Internet Security Association
          Key Management Protocol) port.  Again, this should be fairly early in
          your firewall ruleset.</para>
  
@@ -3732,7 +3777,7 @@
        <para>Once racoon is running you can try pinging one gateway host
          from the other.  The connection is still not encrypted, but
          racoon will then set up the security associations between the two
-         hosts -- this might take a moment, and you may see this as a
+         hosts &mdash; this might take a moment, and you may see this as a
          short delay before the ping commands start responding.</para>
  
        <para>Once the security association has been set up you can
@@ -3750,12 +3795,14 @@
          link.</para>
  
        <para>Each IP packet that you send out has a header that contains
-         data about the packet.  The header includes the IP addresses of
-         both the source and destination.  As we already know, private IP
+         data about the packet.  The header includes the
+	 <acronym>IP</acronym> addresses of both the source and destination.
+	 As we already know, private <acronym>IP</acronym>
          addresses, such as the <hostid role="ipaddr">192.168.x.y</hostid>
          range are not supposed to appear on the public Internet.
          Instead, they must first be encapsulated inside another packet.
-         This packet must have the public source and destination IP
+         This packet must have the public source and destination
+	 <acronym>IP</acronym>
          addresses substituted for the private addresses.</para>
  
        <para>So if your outgoing packet started looking like this:</para>
@@ -3805,11 +3852,13 @@
  
        <para>This encapsulation is carried out by the
          <devicename>gif</devicename> device.  As
-         you can see, the packet now has real IP addresses on the outside,
+         you can see, the packet now has real <acronym>IP<acronym> addresses
+	 on the outside,
          and our original packet has been wrapped up as data inside the
          packet that will be put out on the Internet.</para>
  
-       <para>Obviously, we want all traffic between the VPNs to be
+       <para>Obviously, we want all traffic between the
+         <acronym>VPN</acronym>s to be
          encrypted.  You might try putting this in to words, as:</para>
 
        <para><quote>If a packet leaves from <hostid
@@ -3848,9 +3897,9 @@
          filename that contains configuration instructions.</para>
  
        <para>The configuration on gateway host #1 (which has the public
-         IP address <hostid role="ipaddr">A.B.C.D</hostid>) to force all
-         outbound traffic to <hostid role="ipaddr">W.X.Y.Z</hostid> to be
-         encrypted is:</para>
+         <acronym>IP</acronym> address <hostid role="ipaddr">A.B.C.D</hostid>)
+         to force all outbound traffic to <hostid role="ipaddr">W.X.Y.Z</hostid>
+	 to be encrypted is:</para>
  
        <programlisting>
 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
@@ -3865,7 +3914,8 @@
          to add a rule to the secure policy database.  The rest of this
          line specifies which packets will match this policy.  <hostid
          role="ipaddr">A.B.C.D/32</hostid> and <hostid
-         role="ipaddr">W.X.Y.Z/32</hostid> are the IP addresses and
+         role="ipaddr">W.X.Y.Z/32</hostid> are the <acronym>IP</acronym>
+	 addresses and
          netmasks that identify the network or hosts that this policy will
          apply to.  In this case, we want it to apply to traffic between
          these two hosts.  <option>ipencap</option> tells the kernel that
@@ -3893,15 +3943,16 @@
          <option>out</option> in this case, and the necessary reversal of
          the IP addresses.</para>
  
-       <para>The other gateway host (which has the public IP address
-         <hostid role="ipaddr">W.X.Y.Z</hostid>) will need similar rules.</para>
+       <para>The other gateway host (which has the public
+         <acronym>IP</acronym> address <hostid role="ipaddr">W.X.Y.Z</hostid>)
+         will need similar rules.</para>
  
        <programlisting>spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;</programlisting>
  
-       <para>Finally, you need to add firewall rules to allow ESP and
-        IPENCAP packets back and forth.  These rules will need to be
-        added to both hosts.</para>
+       <para>Finally, you need to add firewall rules to allow 
+         <acronym>ESP</acronym> and <acronym>IPENCAP</acronym> packets back
+	 and forth.  These rules will need to be added to both hosts.</para>
  
        <programlisting>ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
@@ -3944,7 +3995,8 @@
 	  </textobject>
 	</mediaobject>
 
-       <para>When they are received by the far end of the VPN they will
+       <para>When they are received by the far end of the
+         <acronym>VPN</acronym> they will
          first be decrypted (using the security associations that have
          been negotiated by racoon).  Then they will enter the
          <devicename>gif</devicename> interface, which will unwrap
@@ -3966,12 +4018,13 @@
  
        <programlisting>XXX tcpdump output</programlisting>
  
-       <para>Now, as you can see, &man.tcpdump.1; shows the ESP packets.  If
+       <para>Now, as you can see, &man.tcpdump.1; shows the
+         <acronym>ESP</acronym> packets.  If
          you try to examine them with the <option>-s</option> option you will see
          (apparently) gibberish, because of the encryption.</para>
  
-      <para>Congratulations.  You have just set up a VPN between two
-        remote sites.</para>
+      <para>Congratulations.  You have just set up a <acronym>VPN</acronym>
+        between two remote sites.</para>
  
       <itemizedlist>
         <title>Summary</title>
@@ -3986,7 +4039,8 @@
           <para>Install <filename
             role="package">security/ipsec-tools</filename>.  Edit
             <filename>${PREFIX}/etc/racoon/psk.txt</filename> on both
-            gateway hosts, adding an entry for the remote host's IP
+            gateway hosts, adding an entry for the remote host's
+	    <acronym>IP</acronym>
             address and a secret key that they both know.  Make sure
             this file is mode 0600.</para>
         </listitem>
@@ -4020,7 +4074,8 @@
 </programlisting>
         </listitem>
         <listitem>
-          <para>Add firewall rules to allow IKE, ESP, and IPENCAP
+          <para>Add firewall rules to allow <acronym>IKE</acronym>,
+	    <acronym>ESP</acronym>, and <acronym>IPENCAP</acronym>
             traffic to both hosts:</para>
  
           <programlisting>
@@ -4034,10 +4089,11 @@
         </listitem>
       </itemizedlist>
 
-      <para>The previous two steps should suffice to get the VPN up and
+      <para>The previous two steps should suffice to get the
+       <acronym>VPN</acronym> up and
         running.  Machines on each network will be able to refer to one
-        another using IP addresses, and all traffic across the link will
-        be automatically and securely encrypted.</para>
+        another using <acronym>IP</acornym> addresses, and all traffic across
+	the link will be automatically and securely encrypted.</para>
     </sect3> 
     </sect2> 
   </sect1>
@@ -4065,14 +4121,16 @@
       access remote machines securely.  It can be used as a direct
       replacement for <command>rlogin</command>,
       <command>rsh</command>, <command>rcp</command>, and
-      <command>telnet</command>.  Additionally, TCP/IP
-      connections can be tunneled/forwarded securely through SSH.
+      <command>telnet</command>.  Additionally, <acronym>TCP/IP</acronym>
+      connections can be tunneled/forwarded securely through <acronym
+      role="Secure Shell">SSH</acronym>.
       <application>OpenSSH</application> encrypts all traffic to effectively eliminate eavesdropping,
       connection hijacking, and other network-level attacks.</para>
 
-    <para><application>OpenSSH</application> is maintained by the OpenBSD project, and is based
+    <para><application>OpenSSH</application> is maintained by the OpenBSD
+      project, and is based
       upon SSH v1.2.12 with all the recent bug fixes and updates.  It
-      is compatible with both SSH protocols 1 and 2.</para>
+      is compatible with both <acronym>SSH</acronym> protocols 1 and 2.</para>
 
     <sect2>
       <title>Advantages of Using OpenSSH</title>
@@ -4124,12 +4182,13 @@
 
       <para>The login will continue just as it would have if a session was
         created using <command>rlogin</command> or
-        <command>telnet</command>.  SSH utilizes a key fingerprint
-        system for verifying the authenticity of the server when the 
-        client connects.  The user is prompted to enter
+        <command>telnet</command>.  <acronym>SSH</acronym> utilizes a key
+	fingerprint system for verifying the authenticity of the server when
+	the  client connects.  The user is prompted to enter
 	<literal>yes</literal> only when
         connecting for the first time.  Future attempts to login are all
-        verified against the saved fingerprint key.  The SSH client
+        verified against the saved fingerprint key.  The
+	<acronym>SSH</acronym> client
         will alert you if the saved fingerprint differs from the
         received fingerprint on future login attempts.  The fingerprints
         are saved in <filename>~/.ssh/known_hosts</filename>, or
@@ -4137,7 +4196,8 @@
 	fingerprints.</para>
 
       <para>By default, recent versions of the
-        <application>OpenSSH</application> servers only accept SSH v2
+        <application>OpenSSH</application> servers only accept
+	<acronym>SSH</acronym>v2
         connections.  The client will use version 2 if possible and
         will fall back to version 1.  The client can also be forced to
         use one or the other by passing it the <option>-1</option> or
@@ -4170,8 +4230,8 @@
       <para>The arguments passed to &man.scp.1; are similar
 	to &man.cp.1;, with the file or files in the first
 	argument, and the destination in the second.  Since the file is
-	fetched over the network, through SSH, one or more of the file
-	arguments takes on the form
+	fetched over the network, through <acronym>SSH</acronym>, one or
+	more of the file arguments takes on the form
 	<option>user@host:&lt;path_to_remote_file&gt;</option>.</para>
 
     </sect2>
@@ -4201,7 +4261,8 @@
       <title>ssh-keygen</title>
 
       <para>Instead of using passwords, &man.ssh-keygen.1; can
-        be used to generate DSA or RSA keys to authenticate a user:</para>
+        be used to generate <acronym>DSA</acronym> or <acronym>RSA</acronym>
+	keys to authenticate a user:</para>
 
       <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput>
 Generating public/private dsa key pair.
@@ -4223,12 +4284,12 @@
         <filename>~/.ssh/id_rsa.pub</filename>, respectively for DSA and
         RSA key types.  The public key must be placed in
         <filename>~/.ssh/authorized_keys</filename> of the remote
-        machine in order for the setup to work.  Similarly, RSA version
-        1 public keys should be placed in
+        machine in order for the setup to work.  Similarly,
+	<acronym>RSA</acronym> version 1 public keys should be placed in
         <filename>~/.ssh/authorized_keys</filename>.</para>
 
       <para>This will allow connection to the remote machine based upon
-        SSH keys instead of passwords.</para>
+        <acronym>SSH</acronym> keys instead of passwords.</para>
 
       <para>If a passphrase is used in &man.ssh-keygen.1;, the user
         will be prompted for a password each time in order to use the
@@ -4246,7 +4307,7 @@
       <title>ssh-agent and ssh-add</title>
 
       <para>The &man.ssh-agent.1; and &man.ssh-add.1; utilities provide
-        methods for <application>SSH</application> keys to be loaded
+        methods for <application>ssh</application> keys to be loaded
         into memory for use, without needing to type the passphrase
         each time.</para>
 
@@ -4283,7 +4344,7 @@
         launch <application>XFCE</application>, every time X11 starts.
         Then once that is done and X11 has been restarted so that the
         changes can take effect, simply run &man.ssh-add.1; to load
-        all of your SSH keys.</para>
+        all of your <acronym>SSH</acronym> keys.</para>
     </sect2>
 
     <sect2 id="security-ssh-tunneling">
@@ -4312,7 +4373,7 @@
 	  <listitem>
 	    <para>Forces <command>ssh</command> to use version 2 of
 	      the protocol. (Do not use if you are working with older
-	      SSH servers)</para>
+	      <acronym>SSH</acronym> servers)</para>
 	  </listitem>
 	</varlistentry>
 
@@ -4349,29 +4410,33 @@
 	  <term><option>user@foo.example.com</option></term>
 
 	  <listitem>
-	    <para>The remote SSH server.</para>
+	    <para>The remote <acronym>SSH</acronym> server.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
 
-      <para>An SSH tunnel works by creating a listen socket on
-	<hostid>localhost</hostid> on the specified port.
+      <para>A <acronym>SSH</acronym> tunnel works by creating a listen socket
+        om <hostid>localhost</hostid> on the specified port.
 	It then forwards any connection received
-	on the local host/port via the SSH connection to the specified
-	remote host and port.</para>
+	on the local host/port via the <acronym>SSH</acronym> connection to
+	the specified remote host and port.</para>
 
       <para>In the example, port <replaceable>5023</replaceable> on
 	<hostid>localhost</hostid> is being forwarded to port
 	<replaceable>23</replaceable> on <hostid>localhost</hostid>
-	of the remote machine.  Since <replaceable>23</replaceable> is <application>telnet</application>,
-	this would create a secure <application>telnet</application> session through an SSH tunnel.</para>
-
-      <para>This can be used to wrap any number of insecure TCP
-        protocols such as SMTP, POP3, FTP, etc.</para>
+	of the remote machine.  Since <replaceable>23</replaceable> is 
+	<application>telnet</application>,
+	this would create a secure <application>telnet</application> session
+	through an <acronym>SSH</acronym> tunnel.</para>
+
+      <para>This can be used to wrap any number of insecure
+        <acronym>TCP</acronym> protocols such as <acronym>SMTP</acronym>,
+	<acronym>POP3</acronym>, <acronym>FTP</acronym>, etc.</para>
 
       <example>
-	<title>Using SSH to Create a Secure Tunnel for SMTP</title>
+	<title>Using <acronym>SSH</acronym> to Create a Secure Tunnel for
+	  <acronym>SMTP</acronym></title>
 
         <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
 user@mailserver.example.com's password: <userinput>*****</userinput>
@@ -4383,52 +4448,55 @@
 
         <para>This can be used in conjunction with an
           &man.ssh-keygen.1; and additional user accounts to create a
-          more seamless/hassle-free SSH tunneling environment.  Keys
-          can be used in place of typing a password, and the tunnels
-          can be run as a separate user.</para>
+          more seamless/hassle-free <acronym>SSH</acronym> tunneling
+	  environment.  Keys can be used in place of typing a password, an
+	  the tunnels can be run as a separate user.</para>
       </example>
 
       <sect3>
-	<title>Practical SSH Tunneling Examples</title>
+	<title>Practical <acronym>SSH</acronym> Tunneling Examples</title>
 
 	<sect4>
-	  <title>Secure Access of a POP3 Server</title>
+	  <title>Secure Access of a <acronym>POP3</acronym> Server</title>
 
-	  <para>At work, there is an SSH server that accepts
+	  <para>At work, there is an <acronym>SSH</acronym> server that accepts
 	    connections from the outside.  On the same office network
-	    resides a mail server running a POP3 server.  The network,
+	    resides a mail server running a <acronym>POP3</acronym> server.
+	    The network,
 	    or network path between your home and office may or may not
 	    be completely trustable.  Because of this, you need to check
 	    your e-mail in a secure manner.  The solution is to create
-	    an SSH connection to your office's SSH server, and tunnel
+	    an <command>ssh</command> connection to your office's
+	    <acronym>SSH</acronym> server, and tunnel
 	    through to the mail server.</para>
 
 	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
 user@ssh-server.example.com's password: <userinput>******</userinput></screen>
 
 	  <para>When the tunnel is up and running, you can point your
-	    mail client to send POP3 requests to <hostid>localhost</hostid>
+	    mail client to send <acronym>POP3</acronym> requests to
+	    <hostid>localhost</hostid>
 	    port 2110.  A connection here will be forwarded securely across
 	    the tunnel to <hostid>mail.example.com</hostid>.</para>
 	</sect4>
 
 	<sect4>
-	  <title>Bypassing a Draconian Firewall</title>
+	  <title>Bypassing a draconian Firewall</title>
 
 	  <para>Some network administrators impose extremely draconian
 	    firewall rules, filtering not only incoming connections,
 	    but outgoing connections.  You may be only given access
-	    to contact remote machines on ports 22 and 80 for SSH
-	    and web surfing.</para>
+	    to contact remote machines on ports 22 and 80 for
+	    <acronym>SSH</acronym> and web surfing.</para>
 
 	  <para>You may wish to access another (perhaps non-work
 	    related) service, such as an Ogg Vorbis server to stream
 	    music.  If this Ogg Vorbis server is streaming on some other
 	    port than 22 or 80, you will not be able to access it.</para>
 
-	  <para>The solution is to create an SSH connection to a machine
-	    outside of your network's firewall, and use it to tunnel to
-	    the Ogg Vorbis server.</para>
+	  <para>The solution is to create an <acronym>SSH</acronym> connection
+	    to a machine outside of your network's firewall, and use it to
+	    tunnel to the Ogg Vorbis server.</para>
 
 	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput>
 user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen>
@@ -4501,7 +4569,7 @@
 
     <para>In conjunction with file system enhancements like snapshots, FreeBSD 5.0
       and later offers the security of File System Access Control Lists
-      (<acronym>ACLs</acronym>).</para>
+      (<acronym role="Access Control Lists">ACLs</acronym>).</para>
 
     <para>Access Control Lists extend the standard &unix;
       permission model in a highly compatible (&posix;.1e) way.  This feature

>Release-Note:
>Audit-Trail:
>Unformatted:



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200612062114.kB6LEURu022466>