The following reply was made to PR docs/186464; it has been noted by GNATS.
From: Allan Jude <free...@allanjude.com>
To: bug-follo...@freebsd.org
Cc:
Subject: Re: docs/186464: Online-Documentation for carp(4) is outdated
Date: Wed, 12 Feb 2014 18:03:38 -0500
This is a multi-part message in MIME format.
--------------020801060300060708020404
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Attached is a diff to bring the carp(4) section of the handbook up to date.
It pulls the conceptual stuff out into a section before the
instructions, and provides separate instructions for 9.x and prior, and
10.x and later.
Also adds some of the newer markup, like <systemitem class="ipaddress">
--
Allan Jude
--------------020801060300060708020404
Content-Type: text/plain; charset=windows-1252;
name="docs.carp_10x.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="docs.carp_10x.diff"
Index: advanced-networking/chapter.xml
===================================================================
--- advanced-networking/chapter.xml (revision 43884)
+++ advanced-networking/chapter.xml (working copy)
@@ -5589,15 +5589,16 @@
</sect1>
<sect1 xml:id="carp">
- <info><title>Common Address Redundancy Protocol
- (<acronym>CARP</acronym>)</title>
+ <info>
+ <title>Common Address Redundancy Protocol
+ (<acronym>CARP</acronym>)</title>
+
<authorgroup>
<author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed
by </contrib></author>
+
<author><personname><firstname>Allan</firstname><surname>Jude</surname></personname><contrib>Updated
by </contrib></author>
</authorgroup>
</info>
-
-
<indexterm>
<primary><acronym>CARP</acronym></primary>
</indexterm>
@@ -5607,135 +5608,280 @@
<para>The Common Address Redundancy Protocol
(<acronym>CARP</acronym>) allows multiple hosts to share the
- same <acronym>IP</acronym> address. In some configurations,
- this may be used for availability or load balancing. Hosts
- may use separate <acronym>IP</acronym> addresses, as in the
- example provided here.</para>
+ same <acronym>IP</acronym> address(es) and can be used to
+ achieve high availability. Hosts should also have a unique
+ <acronym>IP</acronym> address for management and configuration,
+ as in the example provided here.</para>
- <para>To enable support for <acronym>CARP</acronym>, the &os;
- kernel can be rebuilt as described in <xref linkend="kernelconfig"/>
with the following option:</para>
+ <sect2 xml:id="carp-ha">
+ <title>Using <acronym>CARP</acronym> for High
+ Availability</title>
- <programlisting>device carp</programlisting>
+ <para>One use of <acronym>CARP</acronym> is to provide server
+ high availability for one or more services. This example
+ configures failover support for three hosts, all with
+ unique <acronym>IP</acronym> addresses and providing the same
+ web content. These machines are load balanced with a Round
+ Robin <acronym>DNS</acronym> configuration. The master and
+ backup machines should be configured identically other than
+ their hostnames and management <acronym>IP</acronym>
+ addresses. These servers need to run the same services, such
+ as the web server, with the same configuration so that when
+ the failover happens, requests to that service will be
+ answered correctly and with the same content. The failover
+ machine has two additional <acronym>CARP</acronym> interfaces,
+ one for each of the master content server's
+ <acronym>IP</acronym> addresses. When a failure occurs, the
+ failover server will pick up the failed machine's
+ <acronym>IP</acronym> address. This means that the failure
+ should go completely unnoticed by the user. This example has
+ two different masters named
+ <systemitem>hosta.example.org</systemitem> and
+ <systemitem>hostb.example.org</systemitem> respectively, with
+ a shared slave named
+ <systemitem>hostc.example.org</systemitem>.</para>
- <para>Alternatively, the <filename>if_carp.ko</filename> module
- can be loaded at boot time. Add the following line to
- <filename>/boot/loader.conf</filename>:</para>
+ <para>Each virtual address has a unique
+ identification number known as a Virtual Host IDentification
+ (<acronym>VHID</acronym>) which is used to distinguish the
+ virtual address across the various failover machines that
+ share the address on the network.</para>
- <programlisting>if_carp_load="YES"</programlisting>
+ </sect2>
- <para><acronym>CARP</acronym> functionality should now be
- available and may be tuned via several &man.sysctl.8;
- variables:</para>
+ <sect2 xml:id="carp-10x">
+ <title>Using <acronym>CARP</acronym> on &os; 10 and
+ Later</title>
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>OID</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <para>To enable support for <acronym>CARP</acronym>, load the
+ <filename>carp.ko</filename> kernel module by adding the
+ following line to
+ <filename>/boot/loader.conf</filename>:</para>
- <tbody>
- <row>
- <entry><varname>net.inet.carp.allow</varname></entry>
- <entry>Accept incoming <acronym>CARP</acronym> packets.
- Enabled by default.</entry>
- </row>
+ <programlisting>carp_load="YES"</programlisting>
- <row>
- <entry><varname>net.inet.carp.preempt</varname></entry>
- <entry>This option downs all of the
- <acronym>CARP</acronym> interfaces on the host when one
- goes down. Disabled by default.</entry>
- </row>
+ <para>Alternatively, the &os; kernel can be rebuilt as
+ described in <xref linkend="kernelconfig"/> with the following
+ option:</para>
- <row>
- <entry><varname>net.inet.carp.log</varname></entry>
- <entry>A value of <literal>0</literal> disables any
- logging. A value of <literal>1</literal> enables
- logging of bad <acronym>CARP</acronym> packets. Values
- greater than <literal>1</literal> enable logging of
- state changes for the <acronym>CARP</acronym>
- interfaces. The default value is
- <literal>1</literal>.</entry>
- </row>
+ <programlisting>device carp</programlisting>
- <row>
- <entry><varname>net.inet.carp.arpbalance</varname></entry>
- <entry>Balance local network traffic using
- <acronym>ARP</acronym>. Disabled by default.</entry>
- </row>
+ <para>Set the hostname, configure the management
+ <acronym>IP</acronym> address, then configure
+ <acronym>CARP</acronym> and the <acronym>IP</acronym> address
+ to be shared by adding the required lines to
+ <filename>/etc/rc.conf</filename>. Here are example lines for
+ <systemitem>hosta.example.org</systemitem>:</para>
- <row>
- <entry><varname>net.inet.carp.suppress_preempt</varname></entry>
- <entry>A read-only variable showing the status of
- preemption suppression. Preemption can be suppressed
- if the link on an interface is down. A value of
- <literal>0</literal> means that preemption is not
- suppressed. Every problem increments this
- variable.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <programlisting>hostname="hosta.example.org"
+ifconfig_em0="inet <systemitem class="ipaddress">192.168.1.3</systemitem>
netmask 255.255.255.0"
+ifconfig_em0_alias0="vhid 1 pass testpass alias <systemitem
class="ipaddress">192.168.1.50</systemitem>/32"</programlisting>
- <para>The <acronym>CARP</acronym> devices themselves may be
- created using &man.ifconfig.8;:</para>
+ <para>On <systemitem>hostb.example.org</systemitem>, use the
+ following lines:</para>
- <screen>&prompt.root; <userinput>ifconfig carp0
create</userinput></screen>
+ <programlisting>hostname="hostb.example.org"
+ifconfig_em0="inet <systemitem class="ipaddress">192.168.1.4</systemitem>
netmask 255.255.255.0"
+ifconfig_em0_alias0="vhid 2 pass testpass alias <systemitem
class="ipaddress">192.168.1.51</systemitem>/32"</programlisting>
- <para>In a real environment, each interface has a unique
- identification number known as a Virtual Host IDentification
- (<acronym>VHID</acronym>) which is used to distinguish the
- host on the network.</para>
+ <note>
+ <para>It is very important that the passwords, specified by
+ <option>pass</option> with &man.ifconfig.8;, are
+ identical. The <filename>carp</filename> devices will
+ only listen to and accept advertisements from machines
+ with the correct password. The <acronym>VHID</acronym>
+ must also be unique for each machine.</para>
+ </note>
- <sect2>
- <title>Using <acronym>CARP</acronym> for Server
- Availability</title>
+ <para>The third machine,
+ <systemitem>hostc.example.org</systemitem>,
+ should be prepared so that it may handle failover from either
+ of the previous host. This machine will be configured with
+ two <acronym>CARP</acronym> <acronym>VHID</acronym>s, one to
+ handle each host. The additional <literal>advskew</literal>
+ parameter controls the <acronym>CARP</acronym> advertising
+ skew. By making this host advertise later, it will become a
+ backup, rather than the master. The appropriate
+ <filename>/etc/rc.conf</filename> configuration lines will be
+ similar to the following:</para>
- <para>One use of <acronym>CARP</acronym> is to provide server
- availability. This example configures failover support for
- three hosts, all with unique <acronym>IP</acronym>
- addresses and providing the same web content. These machines
- act in conjunction with a Round Robin
- <acronym>DNS</acronym> configuration. The failover machine
- has two additional <acronym>CARP</acronym> interfaces, one
- for each of the content server's
- <acronym>IP</acronym> addresses. When a
- failure occurs, the failover server will pick up the failed
- machine's <acronym>IP</acronym> address.
- This means that the failure should go completely unnoticed
- by the user. The failover server requires identical content
- and services as the other content servers it is expected to
- pick up load for.</para>
+ <programlisting>hostname="hostc.example.org"
+ifconfig_em0="inet <systemitem class="ipaddress">192.168.1.5</systemitem>
netmask 255.255.255.0"
+ifconfig_em0_alias0="vhid 1 advskew 100 pass testpass alias <systemitem
class="ipaddress">192.168.1.50</systemitem>/32"
+ifconfig_em0_alias1="vhid 2 advskew 100 pass testpass alias <systemitem
class="ipaddress">192.168.1.51</systemitem>/32"</programlisting>
+ <para>Having the two <acronym>CARP</acronym>
+ <acronym>VHID</acronym>s will allow
+ <systemitem>hostc.example.org</systemitem> to notice and
+ pick up the shared <acronym>IP</acronym> address of either
+ machine, should it become unavailable.</para>
+
+ <note>
+ <para>The default &os; kernel has
+ preemption disabled. If it is enabled,
+ <systemitem>hostc.example.org</systemitem> may not
+ relinquish the <acronym>IP</acronym> address back to the
+ original master server. In this case, an administrator may
+ have to manually force the <acronym>IP</acronym> back to the
+ master. The following command should be issued on
+ <systemitem>hostc.example.org</systemitem>:</para>
+
+ <screen>&prompt.root; <userinput>ifconfig em0 vhid 1 state
backup</userinput></screen>
+
+ </note>
+
+ <para>At this point, <acronym>CARP</acronym> should be enabled
+ and available for testing. For testing, either networking
+ has to be restarted or the machines rebooted.</para>
+
+ <para><acronym>CARP</acronym> functionality should now be
+ available and may be tuned via several &man.sysctl.8;
+ variables:</para>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>OID</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>net.inet.carp.allow</varname></entry>
+ <entry>Accept incoming <acronym>CARP</acronym> packets.
+ Enabled by default.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.preempt</varname></entry>
+ <entry>Allow virtual hosts to preempt each other. For
+ firewalls and routers with multiple interfaces, it is
+ desirable to failover all of the addresses running
+ carp together, when one of the physical interfaces
+ goes down. This is achieved by the use of the preempt
+ option. When one of the physical interfaces of the
+ master fails, advskew is demoted to a configured value
+ on all its <acronym>CARP</acronym>
+ <acronym>VHID</acronym>s. Due to the preempt option,
+ the backup host would start announcing itself, and
+ thus preempt the master host on both interfaces
+ instead of just the failed one. Disabled by
+ default.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.log</varname></entry>
+ <entry>Determines what events relating to carp vhids are
+ logged. A value of 0 disables any logging. A value
+ of 1 enables logging state changes of carp vhids.
+ Values above 1 enable logging of bad carp packets.
+ The default value is 1.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.demotion</varname></entry>
+ <entry>This value shows current level of
+ <acronym>CARP</acronym> demotion. The value is added
+ to the actual advskew sent in announcements for all
+ <acronym>VHID</acronym>s. During normal system
+ operation the demotion factor is zero. However,
+ problematic conditions raise this level: when
+ <acronym>CARP</acronym> experiences a problem with
+ sending announcements, when an interface running a
+ <acronym>VHID</acronym> goes down, or while the
+ &man.pfsync.4; interface is not synchronized. The
+ demotion factor can be adjusted by writing to this
+ &man.sysctl.8; oid. The signed value supplied to the
+ &man.sysctl.8; command is added to current demotion
+ factor. This allows the behaviour of
+ <acronym>CARP</acronym> to be controlled depending on
+ external conditions, for example on the status of some
+ daemon utility.</entry>
+ </row>
+
+ <row>
+
<entry><varname>net.inet.carp.ifdown_demotion_factor</varname></entry>
+ <entry>This value is added to
+ <varname>net.inet.carp.demotion</varname> when an
+ interface running a <acronym>VHID</acronym> goes down.
+ The default value is 240 (the maximum advskew
+ value).</entry>
+ </row>
+
+ <row>
+
<entry><varname>net.inet.carp.senderr_demotion_factor</varname></entry>
+ <entry>This value is added to
+ <varname>net.inet.carp.demotion</varname> when
+ <acronym>CARP</acronym> experiences errors sending its
+ announcements. The default value is 240 (the maximum
+ advskew value).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>It is also possible to trigger other actions based on
+ <acronym>CARP</acronym> events using &man.devd.8;. More
+ information is available in &man.carp.4;.</para>
+
+ </sect2>
+
+ <sect2 xml:id="carp-9x">
+ <title>Using <acronym>CARP</acronym> on &os; 9 and
+ Earlier</title>
+
+ <para>To enable support for <acronym>CARP</acronym>, load the
+ <filename>if_carp.ko</filename> kernel module by adding the
+ following line to
+ <filename>/boot/loader.conf</filename>:</para>
+
+ <programlisting>if_carp_load="YES"</programlisting>
+
+ <para>Alternatively, the &os; kernel can be rebuilt as
+ described in <xref linkend="kernelconfig"/> with the following
+ option:</para>
+
+ <programlisting>device carp</programlisting>
+
+ <para>The <acronym>CARP</acronym> devices themselves may be
+ created using &man.ifconfig.8;:</para>
+
+ <screen>&prompt.root; <userinput>ifconfig carp0
create</userinput></screen>
+
+ <para>Each virtual address has a unique
+ identification number known as a Virtual Host IDentification
+ (<acronym>VHID</acronym>) which is used to distinguish the
+ virtual address across the various failover machines that
+ share the address on the network.</para>
+
<para>The two machines should be configured identically other
- than their hostnames and <acronym>VHID</acronym>s. This
- example calls these machines
- <systemitem>hosta.example.org</systemitem> and
- <systemitem>hostb.example.org</systemitem> respectively. First, the
- required lines for a <acronym>CARP</acronym> configuration
- have to be added to <filename>/etc/rc.conf</filename>. Here
- are the lines for
+ than their hostnames, unique <acronym>IP</acronym> addresses
+ and <acronym>VHID</acronym>s. This example calls these
+ machines <systemitem>hosta.example.org</systemitem> and
+ <systemitem>hostb.example.org</systemitem> respectively.
+ First, the required lines for a <acronym>CARP</acronym>
+ configuration have to be added to
+ <filename>/etc/rc.conf</filename>. Here are example lines for
<systemitem>hosta.example.org</systemitem>:</para>
<programlisting>hostname="hosta.example.org"
-ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0"
+ifconfig_fxp0="inet <systemitem class="ipaddress">192.168.1.3</systemitem>
netmask 255.255.255.0"
cloned_interfaces="carp0"
-ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24"</programlisting>
+ifconfig_carp0="vhid 1 pass testpass <systemitem
class="ipaddress">192.168.1.50</systemitem>/24"</programlisting>
<para>On <systemitem>hostb.example.org</systemitem>, use the following
lines:</para>
<programlisting>hostname="hostb.example.org"
-ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0"
+ifconfig_fxp0="inet <systemitem class="ipaddress">192.168.1.4</systemitem>
netmask 255.255.255.0"
cloned_interfaces="carp0"
-ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting>
+ifconfig_carp0="vhid 2 pass testpass <systemitem
class="ipaddress">192.168.1.51</systemitem>/24"</programlisting>
<note>
<para>It is very important that the passwords, specified by
- the <option>pass</option> option to &man.ifconfig.8;, are
+ <option>pass</option> with &man.ifconfig.8;, are
identical. The <filename>carp</filename> devices will
only listen to and accept advertisements from machines
with the correct password. The <acronym>VHID</acronym>
@@ -5742,7 +5888,7 @@
must also be unique for each machine.</para>
</note>
- <para>The third machine, <systemitem>provider.example.org</systemitem>,
+ <para>The third machine, <systemitem>hostc.example.org</systemitem>,
should be prepared so that it may handle failover from either
host. This machine will require two
<filename>carp</filename> devices, one to handle each
@@ -5749,26 +5895,26 @@
host. The appropriate <filename>/etc/rc.conf</filename>
configuration lines will be similar to the following:</para>
- <programlisting>hostname="provider.example.org"
-ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0"
+ <programlisting>hostname="hostc.example.org"
+ifconfig_fxp0="inet <systemitem class="ipaddress">192.168.1.5</systemitem>
netmask 255.255.255.0"
cloned_interfaces="carp0 carp1"
-ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24"
-ifconfig_carp1="vhid 2 advskew 100 pass testpass
192.168.1.51/24"</programlisting>
+ifconfig_carp0="vhid 1 advskew 100 pass testpass <systemitem
class="ipaddress">192.168.1.50</systemitem>/24"
+ifconfig_carp1="vhid 2 advskew 100 pass testpass <systemitem
class="ipaddress">192.168.1.51</systemitem>/24"</programlisting>
<para>Having the two <filename>carp</filename> devices will
- allow <systemitem>provider.example.org</systemitem> to notice and pick
+ allow <systemitem>hostc.example.org</systemitem> to notice and pick
up the <acronym>IP</acronym> address of either machine, should
- it stop responding.</para>
+ it become unavailable.</para>
<note>
<para>The default &os; kernel <emphasis>may</emphasis> have
preemption enabled. If so,
- <systemitem>provider.example.org</systemitem> may not relinquish the
+ <systemitem>hostc.example.org</systemitem> may not relinquish the
<acronym>IP</acronym> address back to the original content
server. In this case, an administrator may have to manually
force the <acronym>IP</acronym> back to the master. The
following command should be issued on
- <systemitem>provider.example.org</systemitem>:</para>
+ <systemitem>hostc.example.org</systemitem>:</para>
<screen>&prompt.root; <userinput>ifconfig carp0 down &&
ifconfig carp0 up</userinput></screen>
@@ -5780,6 +5926,63 @@
and available for testing. For testing, either networking
has to be restarted or the machines rebooted.</para>
+ <para><acronym>CARP</acronym> functionality should now be
+ available and may be tuned via several &man.sysctl.8;
+ variables:</para>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>OID</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>net.inet.carp.allow</varname></entry>
+ <entry>Accept incoming <acronym>CARP</acronym> packets.
+ Enabled by default.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.preempt</varname></entry>
+ <entry>This option downs all of the
+ <acronym>CARP</acronym> interfaces on the host when one
+ goes down. Disabled by default.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.log</varname></entry>
+ <entry>A value of <literal>0</literal> disables any
+ logging. A value of <literal>1</literal> enables
+ logging of bad <acronym>CARP</acronym> packets. Values
+ greater than <literal>1</literal> enable logging of
+ state changes for the <acronym>CARP</acronym>
+ interfaces. The default value is
+ <literal>1</literal>.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.arpbalance</varname></entry>
+ <entry>Balance local network traffic using
+ <acronym>ARP</acronym>. Disabled by default.</entry>
+ </row>
+
+ <row>
+ <entry><varname>net.inet.carp.suppress_preempt</varname></entry>
+ <entry>A read-only variable showing the status of
+ preemption suppression. Preemption can be suppressed
+ if the link on an interface is down. A value of
+ <literal>0</literal> means that preemption is not
+ suppressed. Every problem increments this
+ variable.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
<para>More information is available in &man.carp.4;.</para>
</sect2>
</sect1>
--------------020801060300060708020404--
_______________________________________________
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"
