--------------------------------------------
On Sun, 7/26/15, Hiroki Sato <h...@freebsd.org> wrote:
Subject: Re: Documentation shortcoming
To: d...@freebsd.org, dru.lavi...@att.net
Cc: freebsd-doc@FreeBSD.org, rues...@kdo.de
Date: Sunday, July 26, 2015, 4:01 PM
Dru Lavigne <dru.lavi...@att.net>
wrote
in <1437908470.22608.yahoomailba...@web184901.mail.gq1.yahoo.com>:
dr> Apparently, this is only required for link local
addresses, which
dr> should be clarified in the Handbook. Can someone with
more IPv6-clue
dr> suggest a clearer wording so that both cases are
understood?
> I have a patch including this kind of clarification and other updates
> (attached). Can you review this?
Thank you for updating this content! I've attached a slightly modified patch,
mostly small grammar tuning.
Cheers,
Dru
Index: chapter.xml
===================================================================
--- chapter.xml (revision 47098)
+++ chapter.xml (working copy)
@@ -4439,10 +4439,10 @@
<term>Anycast</term>
<listitem>
<para>These addresses are syntactically indistinguishable
- from unicast addresses but they address a group of
- interfaces. The packet destined for an anycast address
- will arrive at the nearest router interface. Anycast
- addresses are only used by routers.</para>
+ from unicast addresses, except that they address any of
+ the interfaces belonging to the address. The packet
+ destined for an anycast address will be received by one
+ of the interfaces.</para>
</listitem>
</varlistentry>
@@ -4450,13 +4450,8 @@
<term>Multicast</term>
<listitem>
<para>These addresses identify a group of interfaces. A
- packet destined for a multicast address will arrive at
- all interfaces belonging to the multicast group. The
- <acronym>IPv4</acronym> broadcast address, usually
- <systemitem
- class="ipaddress">xxx.xxx.xxx.255</systemitem>, is
- expressed by multicast addresses in
- <acronym>IPv6</acronym>.</para>
+ packet destined for a multicast address will be received by
+ all interfaces belonging to the multicast group.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -4484,7 +4479,7 @@
which in turn is equivalent to
<systemitem>2002::a00:1</systemitem>.</para>
- <para>To view a &os; system's <acronym>IPv6 </acronym> address,
+ <para>To view a &os; system's <acronym>IPv6</acronym> address,
use &man.ifconfig.8;:</para>
<screen>&prompt.root; <userinput>ifconfig</userinput></screen>
@@ -4538,16 +4533,8 @@
</row>
<row>
- <entry><systemitem>::00:xx:xx:xx:xx</systemitem></entry>
+ <entry><systemitem>::ffff:<replaceable>xx:xx:xx:xx</replaceable></systemitem></entry>
<entry>96 bits</entry>
- <entry>embedded <acronym>IPv4</acronym></entry>
- <entry>The lower 32 bits are the compatible
- <acronym>IPv4</acronym> address.</entry>
- </row>
-
- <row>
- <entry><systemitem>::ff:xx:xx:xx:xx</systemitem></entry>
- <entry>96 bits</entry>
<entry><acronym>IPv4</acronym> mapped
<acronym>IPv6</acronym> address</entry>
<entry>The lower 32 bits are the <acronym>IPv4</acronym>
@@ -4556,11 +4543,15 @@
</row>
<row>
- <entry><systemitem>fe80::/10</systemitem></entry>
+ <entry><systemitem>fe80::%<replaceable>rl0</replaceable>/10</systemitem></entry>
<entry>10 bits</entry>
<entry>link-local</entry>
<entry>Equivalent to 169.254.0.0/16 in
- <acronym>IPv4</acronym>.</entry>
+ <acronym>IPv4</acronym>. An address with a link-local
+ scope always needs a zone id because it is unique only
+ on a link. The zone id is an interface name, for
+ example <literal>%rl0</literal>, or an interface index
+ number.</entry>
</row>
<row>
@@ -4580,7 +4571,7 @@
</row>
<row>
- <entry><systemitem>2000::-3fff:: </systemitem></entry>
+ <entry><systemitem>2000::-3fff::</systemitem></entry>
<entry>3 bits</entry>
<entry>global unicast</entry>
<entry>All global unicast addresses are assigned from
@@ -4597,21 +4588,23 @@
</sect2>
<sect2>
- <title>Configuring <acronym>IPv6</acronym></title>
+ <title>Configuring <acronym>IPv6</acronym> Host</title>
<para>To configure a &os; system as an <acronym>IPv6</acronym>
- client, add these two lines to
+ host, add these two lines to
<filename>rc.conf</filename>:</para>
- <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 accept_rtadv"
-rtsold_enable="YES"</programlisting>
+ <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 accept_rtadv"</programlisting>
- <para>The first line enables the specified interface to receive
- router solicitation messages. The second line enables the
- router solicitation daemon, &man.rtsol.8;.</para>
+ <para>This line enables the specified interface to receive
+ Router Advertisement messages. These messages are distributed
+ by routers on the same link to provide information such as the
+ subnet prefix, default routers, <acronym>MTU</acronym>,
+ recursive <acronym>DNS</acronym> server list, and so
+ on.</para>
- <para>For &os; 8.<replaceable>x</replaceable>, add a third
- line:</para>
+ <para>For &os; 8.<replaceable>x</replaceable>, add the
+ following line:</para>
<programlisting>ipv6_enable="YES"</programlisting>
@@ -4619,16 +4612,25 @@
<acronym>IPv6</acronym> address, add an entry to specify the
static address and associated prefix length:</para>
- <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 <replaceable>2001:db8:4672:6565:2026:5043:2d42:5344</replaceable> prefixlen <replaceable>64</replaceable>"</programlisting>
+ <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 <replaceable>2001:db8:4672:6565:2026:5043:2d42:5344</replaceable>/<replaceable>64</replaceable>"</programlisting>
<para>On a &os; 8.<replaceable>x</replaceable> system, that
line uses this format instead:</para>
- <programlisting>ipv6_ifconfig_<replaceable>rl0</replaceable>="<replaceable>2001:db8:4672:6565:2026:5043:2d42:5344</replaceable>"</programlisting>
+ <programlisting>ipv6_ifconfig_<replaceable>rl0</replaceable>="<replaceable>2001:db8:4672:6565:2026:5043:2d42:5344</replaceable> prefixlen <replaceable>64</replaceable>"</programlisting>
- <para>To assign a default router, specify its address:</para>
+ <para>To manually assign a default router, specify its address.
+ Note that this information is also provided via Router
+ Advertisement messages and the specified address will not be
+ overridden.</para>
<programlisting>ipv6_defaultrouter="<replaceable>2001:db8:4672:6565::1</replaceable>"</programlisting>
+
+ <para>This can be an link-local address because an IPv6-capable
+ interface always has one. In that case, an address must be
+ associated with a zone id:</para>
+
+ <programlisting>ipv6_defaultrouter="<replaceable>fe80::1%rl0</replaceable>"</programlisting>
</sect2>
<sect2>
@@ -4672,8 +4674,14 @@
the generic tunneling interface
<filename><replaceable>gif0</replaceable></filename>:</para>
- <programlisting>gif_interfaces="gif<replaceable>0</replaceable>"</programlisting>
+ <programlisting>cloned_interfaces="gif<replaceable>0</replaceable>"</programlisting>
+ <note>
+ <para><varname>gif_interfaces</varname> and
+ <varname>gif_ifconfig</varname> used in earlier releases are
+ now obsolete.</para>
+ </note>
+
<para>Next, configure that interface with the
<acronym>IPv4</acronym> addresses of the local and remote
endpoints. Replace <replaceable>MY_IPv4_ADDR</replaceable>
@@ -4680,7 +4688,7 @@
and <replaceable>REMOTE_IPv4_ADDR</replaceable> with the
actual <acronym>IPv4</acronym> addresses:</para>
- <programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>
+ <programlisting>ifconfig_gif0="inet tunnel <replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>
<para>To apply the <acronym>IPv6</acronym> address that has been
assigned for use as the <acronym>IPv6</acronym> tunnel
@@ -4688,7 +4696,7 @@
<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>
with the assigned address:</para>
- <programlisting>ifconfig_gif0_ipv6="inet6 <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
+ <programlisting>ifconfig_gif0_ipv6="inet6 tunnel <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
<para>For &os; 8.<replaceable>x</replaceable>, that line
should instead use this format:</para>
@@ -4711,38 +4719,76 @@
</sect2>
<sect2>
- <title>Router Advertisement and Host Auto Configuration</title>
+ <title><acronym>IPv6</acronym> Router Configuration</title>
<para>This section demonstrates how to setup &man.rtadvd.8; to
- advertise the <acronym>IPv6</acronym> default route.</para>
+ distribute Router Advertisement messages.</para>
<para>To enable &man.rtadvd.8;, add the following to
<filename>/etc/rc.conf</filename>:</para>
- <programlisting>rtadvd_enable="YES"</programlisting>
+ <programlisting>ipv6_gateway_enable="YES"
+rtadvd_enable="YES"</programlisting>
- <para>It is important to specify the interface on which to
- do <acronym>IPv6</acronym> router solicitation. For example,
- to tell &man.rtadvd.8; to use
- <filename>rl0</filename>:</para>
+ <para>It is important to specify the interface on which to send
+ <acronym>IPv6</acronym> Router Advertisement messages. For
+ example, to tell &man.rtadvd.8; to use
+ <systemitem>rl0</systemitem>:</para>
<programlisting>rtadvd_interfaces="rl0"</programlisting>
- <para>Next, create the configuration file,
- <filename>/etc/rtadvd.conf</filename> as seen in this
+ <para>A valid global <acronym>IPv6</acronym> prefix must be
+ configured on the <systemitem>rl0</systemitem>
+ interface.</para>
+
+ <programlisting>ifconfig_rl0_ipv6="inet6 <replaceable>2001:db8:1::1/64</replaceable>"</programlisting>
+
+ <para>And on every <acronym>IPv6</acronym> router, a
+ subnet-router anycast address should be configured as an
+ alias. It is the same address and prefix length as the global
+ <acronym>IPv6</acronym> prefix with an additional keyword
+ <literal>anycast</literal>.</para>
+
+ <programlisting>ifconfig_rl0_ipv6_alias0="inet6 <replaceable>2001:db8:1::/64</replaceable> anycast"</programlisting>
+
+ <para>Note that &man.rtadvd.8; normally does not require a
+ configuration file, <filename>/etc/rtadvd.conf</filename>.</para>
+
+ <para>For example, information about available recursive
+ <acronym>DNS</acronym> servers and/or the search list for a
+ non-fully-qualified domain name can be distributed with a
+ Router Advertisement message. To enable this, create
+ <filename>/etc/rtadvd.conf</filename>, as seen in this
example:</para>
<programlisting>rl0:\
- :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting>
+ :rdnss="<replaceable>2001:db8:ffff::10,2001:db8:ffff::2:43</replaceable>":\
+ :dnssl="<replaceable>example.com</replaceable>":</programlisting>
- <para>Replace <filename>rl0</filename> with the interface
- to be used and <systemitem>2001:471:1f11:246::</systemitem>
- with the prefix of the allocation.</para>
+ <para>More details can be found in &man.rtadvd.conf.5;.</para>
- <para>For a dedicated <systemitem
- class="netmask">/64</systemitem> subnet, nothing else needs
- to be changed. Otherwise, change the
- <literal>prefixlen#</literal> to the correct value.</para>
+ <para><acronym>IPv6</acronym> host nodes on the same link will
+ receive Router Advertisement messages from this router and
+ configure a global <acronym>IPv6</acronym> address and the
+ <acronym>IPv6</acronym> default route. The receipt of these
+ messages is disabled by default. The following line in
+ <filename>/etc/rc.conf</filename> on an
+ <acronym>IPv6</acronym> host enables these messages on
+ the <systemitem>rl0</systemitem> interface:</para>
+
+ <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 accept_rtadv"</programlisting>
+
+ <para>If Router Advertisement messages contain lists of
+ recursive <acronym>DNS</acronym> servers and/or search lists
+ for non-fully-qualified domain names, an
+ <acronym>IPv6</acronym> host has to enable the &man.rtsold.8;
+ daemon by adding the following line to
+ <filename>/etc/rc.conf</filename>:</para>
+
+ <programlisting>rtsold_enable="YES"</programlisting>
+
+ <para>This daemon handles updating
+ <filename>/etc/resolv.conf</filename>.</para>
</sect2>
<sect2>
_______________________________________________
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
