docs/160269: [patch] Handbook wireless section: sand off some rough edges
Warren Block
wblock at wonkity.com
Mon Aug 29 04:12:31 UTC 2011
On Mon, 29 Aug 2011, Garrett Cooper wrote:
> The following reply was made to PR docs/160269; it has been noted by GNATS.
>
> From: Garrett Cooper <yanegomi at gmail.com>
> >
> > <note>
> > - <para>If the <filename>/etc/rc.conf</filename> is set up
> > + <para>If <filename>/etc/rc.conf</filename> is set up
> > with the line <literal>ifconfig_wlan0="DHCP"</literal>
> > - then it is no need to run the
> > - <command>dhclient</command> command manually,
> > + then it is not necessary to run the
> > + <command>dhclient</command> command manually.
>
> This isn't entirely true. You can specify other options like
> "SYNCDHCP", "ssid <foo> DHCP", etc, and it will achieve what's
> described below. Manual execution of dhclient in general should be
> discouraged for most users.
Changes made; I also found "plumbs the keys" to make my brain hurt.
> > <para>EAP does not come with an encryption method, it was
> > decided to embed EAP inside an encrypted tunnel. Many
> > -types of EAP authentication methods have been designed,
> > -the most common methods are EAP-TLS, EAP-TTLS and
> > +types of EAP authentication methods have been designed.
> > +The most common methods are EAP-TLS, EAP-TTLS and
> > EAP-PEAP.</para>
>
> Maybe it should say something like "There are many EAP authentication
> methods: the most common ones are EAP-TLS, EAP-TTLS, and EAP-PEAP" ?
Done, but slightly differently. The preceding sentence also had
problems.
> > <para>EAP-TLS (EAP with Transport Layer Security) is a
> > @@ -1555,7 +1555,7 @@
> > 0<callout arearefs=3D"co-ttls-cacert">
> > <para>The <literal>ca_cert</literal> field indicates
> > the pathname of the CA certificate file. This file
> > -is needed to verify the server certificat.</para>
> > +is needed to verify the server certificate.</para>
> > </callout>
> >
> > <callout arearefs="co-ttls-pha2">
> > @@ -1599,10 +1599,10 @@
> >
> > <para>PEAP (Protected EAP) has been designed as an
> > alternative to EAP-TTLS. There are two types of PEAP
> > -methods, the most common one is PEAPv0/EAP-MSCHAPv2. In
> > +methods; the most common one is PEAPv0/EAP-MSCHAPv2. In
>
> That could be a colon instead.
The alternate type is never mentioned, so it's pointless to say that
there are two. Instead, let's just say PEAPv0/EAP-MSCHAPv2 is the most
common. This is actually an aside in the paragraph, so let's move it to
a <note> just before the paragraph.
> This sentence is extremely wordy.
Yes, and poorly organized. Better with the rewrite.
> The rest of the changes are good incremental improvements to the
> existing doc :).
Thanks! Second version of the patch attached, which I think addresses
both these and Mr. Kaduk's comments. Also removed one pointless
"simply".
-------------- next part --------------
--- en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml.orig 2011-08-28 17:57:28.000000000 -0600
+++ en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml 2011-08-28 22:07:24.000000000 -0600
@@ -1164,7 +1164,7 @@
authentication parameters, you will have to get an IP
address to communicate. Most of time you will obtain
your wireless IP address via DHCP. To achieve that,
- simply edit <filename>/etc/rc.conf</filename> and add
+ edit <filename>/etc/rc.conf</filename> and add
<literal>DHCP</literal> to the configuration for your
device as shown in various examples above:</para>
@@ -1225,7 +1225,7 @@
the 802.1X authentication protocol and uses one of several
ciphers instead of WEP for data integrity. The only
cipher required by WPA is TKIP (Temporary Key Integrity
- Protocol) which is a cipher that extends the basic RC4
+ Protocol). TKIP is a cipher that extends the basic RC4
cipher used by WEP by adding integrity checking, tamper
detection, and measures for responding to any detected
intrusions. TKIP is designed to work on legacy hardware
@@ -1243,7 +1243,7 @@
station and the access point using a pre-shared secret.
The former is commonly termed WPA Enterprise with the
latter known as WPA Personal. Since most people will not
- set up a RADIUS backend server for wireless network,
+ set up a RADIUS backend server for their wireless network,
WPA-PSK is by far the most commonly encountered
configuration for WPA.</para>
@@ -1258,7 +1258,7 @@
<sect5 id="network-wireless-wpa-wpa-psk">
<title>WPA-PSK</title>
- <para>WPA-PSK also known as WPA-Personal is based on a
+ <para>WPA-PSK, also known as WPA-Personal, is based on a
pre-shared key (PSK) generated from a given password and
that will be used as the master key in the wireless
network. This means every wireless user will share the
@@ -1289,7 +1289,7 @@
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>
- <para>Then, we can bring up the interface:</para>
+ <para>Then we can bring up the interface:</para>
<screen>&prompt.root; <userinput><filename>/etc/rc.d/netif</filename> start</userinput>
Starting wpa_supplicant.
@@ -1342,16 +1342,16 @@
wme burst roaming MANUAL</screen>
<note>
- <para>If the <filename>/etc/rc.conf</filename> is set up
- with the line <literal>ifconfig_wlan0="DHCP"</literal>
- then it is no need to run the
- <command>dhclient</command> command manually,
- <command>dhclient</command> will be launched after
- <command>wpa_supplicant</command> plumbs the
- keys.</para>
+ <para>If <filename>/etc/rc.conf</filename> has an
+ <literal>ifconfig_wlan0</literal> entry with the
+ <literal>DHCP</literal> string (like
+ <literal>ifconfig_wlan0="DHCP"</literal>),
+ <command>dhclient</command> will be launched
+ automatically after <command>wpa_supplicant</command>
+ associates with the access point.</para>
</note>
- <para>In the case where the use of DHCP is not possible,
+ <para>If DHCP is not possible or desired,
you can set a static IP address after
<command>wpa_supplicant</command> has authenticated the
station:</para>
@@ -1370,7 +1370,7 @@
wme burst roaming MANUAL</screen>
<para>When DHCP is not used, you also have to manually set
- up the default gateway and the nameserver:</para>
+ the default gateway and the nameserver:</para>
<screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput>
&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" >> /etc/resolv.conf</userinput></screen>
@@ -1380,17 +1380,17 @@
<title>WPA with EAP-TLS</title>
<para>The second way to use WPA is with an 802.1X backend
- authentication server, in this case WPA is called
- WPA-Enterprise to make difference with the less secure
- WPA-Personal with its pre-shared key. The
- authentication in WPA-Enterprise is based on EAP
- (Extensible Authentication Protocol).</para>
-
- <para>EAP does not come with an encryption method, it was
- decided to embed EAP inside an encrypted tunnel. Many
- types of EAP authentication methods have been designed,
- the most common methods are EAP-TLS, EAP-TTLS and
- EAP-PEAP.</para>
+ authentication server. In this case WPA is called
+ WPA-Enterprise to differentiate it from the less secure
+ WPA-Personal with its pre-shared key.
+ Authentication in WPA-Enterprise is based on the
+ Extensible Authentication Protocol (EAP).</para>
+
+ <para>EAP does not come with an encryption method.
+ Instead, it was decided to embed EAP inside an encrypted
+ tunnel. There are many EAP authentication methods, but
+ EAP-TLS, EAP-TTLS, and EAP-PEAP are the most
+ common.</para>
<para>EAP-TLS (EAP with Transport Layer Security) is a
very well-supported authentication protocol in the
@@ -1555,7 +1555,7 @@
<callout arearefs="co-ttls-cacert">
<para>The <literal>ca_cert</literal> field indicates
the pathname of the CA certificate file. This file
- is needed to verify the server certificat.</para>
+ is needed to verify the server certificate.</para>
</callout>
<callout arearefs="co-ttls-pha2">
@@ -1597,23 +1597,26 @@
<sect5 id="network-wireless-wpa-eap-peap">
<title>WPA with EAP-PEAP</title>
+ <note>
+ <para>PEAPv0/EAP-MSCHAPv2 is the most common PEAP method.
+ In the rest of this document, we will use the PEAP term
+ to refer to that method.</para>
+ </note>
+
<para>PEAP (Protected EAP) has been designed as an
- alternative to EAP-TTLS. There are two types of PEAP
- methods, the most common one is PEAPv0/EAP-MSCHAPv2. In
- the rest of this document, we will use the PEAP term to
- refer to that EAP method. PEAP is the most used EAP
- standard after EAP-TLS, in other words if you have a
- network with mixed OSes, PEAP should be the most
- supported standard after EAP-TLS.</para>
+ alternative to EAP-TTLS, and is the most used EAP
+ standard after EAP-TLS. In other words, if you have a
+ network with mixed OSes, PEAP should be the
+ most supported standard after EAP-TLS.</para>
<para>PEAP is similar to EAP-TTLS: it uses a server-side
certificate to authenticate clients by creating an
encrypted TLS tunnel between the client and the
authentication server, which protects the ensuing
- exchange of authentication information. In term of
- security the difference between EAP-TTLS and PEAP is
- that PEAP authentication broadcasts the username in
- clear, only the password is sent in the encrypted TLS
+ exchange of authentication information. In terms of
+ security, the difference between EAP-TTLS and PEAP is
+ that PEAP authentication broadcasts the username in the
+ clear, with only the password sent in the encrypted TLS
tunnel. EAP-TTLS will use the TLS tunnel for both
username and password.</para>
@@ -1658,10 +1661,10 @@
<callout arearefs="co-peap-pha1">
<para>This field contains the parameters for the
- first phase of the authentication (the TLS
+ first phase of authentication (the TLS
tunnel). According to the authentication server
used, you will have to specify a specific label
- for the authentication. Most of time, the label
+ for authentication. Most of the time, the label
will be <quote>client EAP encryption</quote> which
is set by using <literal>peaplabel=0</literal>.
More information can be found in the
@@ -1682,7 +1685,7 @@
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>
- <para>Then, we can bring up the interface:</para>
+ <para>Then we can bring up the interface:</para>
<screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
Starting wpa_supplicant.
@@ -1709,7 +1712,7 @@
<para>WEP (Wired Equivalent Privacy) is part of the original
802.11 standard. There is no authentication mechanism,
- only a weak form of access control, and it is easily to be
+ only a weak form of access control, and it is easily
cracked.</para>
<para>WEP can be set up with
@@ -1724,18 +1727,18 @@
<para>The <literal>weptxkey</literal> means which WEP
key will be used in the transmission. Here we used the
third key. This must match the setting in the access
- point. If you do not have any idea of what is the key
- used by the access point, you should try to use
+ point. If you do not have any idea of which key is
+ used by the access point, try
<literal>1</literal> (i.e., the first key) for this
value.</para>
</listitem>
<listitem>
- <para>The <literal>wepkey</literal> means setting the
- selected WEP key. It should in the format
- <replaceable>index:key</replaceable>, if the index is
- not given, key <literal>1</literal> is set. That is
- to say we need to set the index if we use keys other
+ <para>The <literal>wepkey</literal> selects one of the
+ WEP keys. It should be in the format
+ <replaceable>index:key</replaceable>. Key
+ <literal>1</literal> is used by default; the index
+ only needs to be set if we use a key other
than the first key.</para>
<note>
@@ -1746,7 +1749,7 @@
</listitem>
</itemizedlist>
- <para>You are encouraged to read &man.ifconfig.8; manual
+ <para>You are encouraged to read the &man.ifconfig.8; manual
page for further information.</para>
<para>The <command>wpa_supplicant</command> facility also
@@ -1777,7 +1780,7 @@
<para>IBSS mode, also called ad-hoc mode, is designed for point
to point connections. For example, to establish an ad-hoc
network between the machine <hostid>A</hostid> and the machine
- <hostid>B</hostid> we will just need to choose two IP addresses
+ <hostid>B</hostid>, we will just need to choose two IP addresses
and a SSID.</para>
<para>On the box <hostid>A</hostid>:</para>
@@ -1822,7 +1825,7 @@
protmode CTS wme burst</screen>
<para>Both <hostid>A</hostid> and <hostid>B</hostid> are now
- ready to exchange informations.</para>
+ ready to exchange information.</para>
</sect2>
<sect2 id="network-wireless-ap">
@@ -1839,19 +1842,19 @@
<para>Before configuring your &os; machine as an AP, the
kernel must be configured with the appropriate wireless
networking support for your wireless card. You also have to
- add the support for the security protocols you intend to
+ add support for the security protocols you intend to
use. For more details, see <xref
linkend="network-wireless-basic">.</para>
<note>
<para>The use of the NDIS driver wrapper and the &windows;
- drivers do not allow currently the AP operation. Only
+ drivers do not currently allow AP operation. Only
native &os; wireless drivers support AP mode.</para>
</note>
- <para>Once the wireless networking support is loaded, you can
+ <para>Once wireless networking support is loaded, you can
check if your wireless device supports the host-based access
- point mode (also know as hostap mode):</para>
+ point mode (also known as hostap mode):</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput>
@@ -1861,8 +1864,8 @@
<para>This output displays the card capabilities; the
<literal>HOSTAP</literal> word confirms this wireless card
can act as an Access Point. Various supported ciphers are
- also mentioned: WEP, TKIP, AES, etc., these informations
- are important to know what security protocols could be set
+ also mentioned: WEP, TKIP, AES, etc. This information
+ is important to know what security protocols can be used
on the Access Point.</para>
<para>The wireless device can only be put into hostap mode
@@ -1877,7 +1880,7 @@
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen>
- <para>Use again <command>ifconfig</command> to see the status
+ <para>Use <command>ifconfig</command> again to see the status
of the <devicename>wlan0</devicename> interface:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
@@ -2150,7 +2153,7 @@
<para>On &os;, it is possible to combine two or even more network
interfaces together in a <quote>failover</quote> fashion, that
is, to use the most preferred and available connection from a
- group of network interfaces, and have the operating system to
+ group of network interfaces, and have the operating system
switch automatically when the link state changes.</para>
<para>We will cover link aggregation and failover in <xref linkend="network-aggregation">
More information about the freebsd-doc
mailing list