Attachment 140022 Details for Bug 186464 – docs.carp_10x.diff

[patch] docs.carp_10x.diff

docs.carp_10x.diff (text/plain; charset=windows-1252), 21.36 KB, created by Allan Jude on 2014-02-12 23:03:38 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Allan Jude

Created: 2014-02-12 23:03:38 UTC

Size: 21.36 KB

patch

obsolete

>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 &amp;&amp; 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>

Actions: View | Diff

Attachments on bug 186464: 140022 | 140023