Date: Fri, 14 Feb 2014 02:26:26 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43918 - head/en_US.ISO8859-1/books/handbook/advanced-networking Message-ID: <201402140226.s1E2QQJn085360@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Fri Feb 14 02:26:26 2014 New Revision: 43918 URL: http://svnweb.freebsd.org/changeset/doc/43918 Log: Update the carp(4) section for 10.x and later. Allan Jude <freebsd@allanjude.com> supplied a great patch to fix this, and then spent a lot of time changing it to meet my numerous too-strict standards. PR: docs/186464 Submitted by: Rainer Duffner <rainer@ultra-secure.de> Reviewed by: glebius (earlier version) Modified: head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml Fri Feb 14 01:35:02 2014 (r43917) +++ head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml Fri Feb 14 02:26:26 2014 (r43918) @@ -5686,6 +5686,8 @@ route_hostD="192.168.173.4 hatm0 0 102 l <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> @@ -5698,182 +5700,235 @@ route_hostD="192.168.173.4 hatm0 0 102 l <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> - - <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> - - <programlisting>device carp</programlisting> - - <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> - - <programlisting>if_carp_load="YES"</programlisting> - - <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>The <acronym>CARP</acronym> devices themselves may be - created using &man.ifconfig.8;:</para> - - <screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen> - - <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> + same <acronym>IP</acronym> address and provide <emphasis>high availability</emphasis>. One or more hosts can fail, and the others will + take over for the failed system transparently. In addition to the shared <acronym>IP</acronym> address, hosts also have a + unique <acronym>IP</acronym> address for management and + configuration, as in the example provided here.</para> - <sect2> - <title>Using <acronym>CARP</acronym> for Server + <sect2 xml:id="carp-ha"> + <title>Using <acronym>CARP</acronym> for High Availability</title> - <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> - - <para>The two machines should be configured identically other - than their hostnames and <acronym>VHID</acronym>s. This - example calls these machines + <para><acronym>CARP</acronym> is often used to provide + high availability for one or more services. This example + configures failover support with three hosts, all with + unique <acronym>IP</acronym> addresses, but providing the same + web content. These machines are load balanced with a Round + Robin <acronym>DNS</acronym> configuration. The master and + backup machines are configured identically + except for their hostnames and management + <acronym>IP</acronym> addresses. These servers must have the same configuration and run + the same services. + When the failover occurs, requests to the + service on the shared <acronym>IP</acronym> address can only + be answered correctly if the backup server has access to the + same content. The backup 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 backup server will pick up the failed + master machine's <acronym>IP</acronym> address. Users will + not see a service failure at all.</para> + + <para>This + example has two different masters named <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 + <systemitem>hostb.example.org</systemitem>, with + a shared backup named + <systemitem>hostc.example.org</systemitem>.</para> + + <para>Each virtual <acronym>IP</acronym> address has a unique + identification number known as a Virtual Host Identification + (<acronym>VHID</acronym>). All of the machines that share an <acronym>IP</acronym> address have the same <acronym>VHID</acronym>. + The <acronym>VHID</acronym> for each virtual + <acronym>IP</acronym> address must be unique across the + broadcast domain of the network interface.</para> + </sect2> + + <sect2 xml:id="carp-10x"> + <title>Using <acronym>CARP</acronym> on &os; 10 and + Later</title> + + <para>Enable support for <acronym>CARP</acronym> by loading the + <filename>carp.ko</filename> kernel module in + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>carp_load="YES"</programlisting> + + <para>The <acronym>CARP</acronym> module can also be built into the + &os; kernel as described in <xref linkend="kernelconfig"/>:</para> + + <programlisting>device carp</programlisting> + + <para>The hostname, management + <acronym>IP</acronym> address, + <acronym>CARP</acronym> configuration, and the <acronym>IP</acronym> address + to be shared are all set by adding entries to + <filename>/etc/rc.conf</filename>. This example is for + <systemitem>hosta.example.org</systemitem>:</para> + + <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>On <systemitem>hostb.example.org</systemitem>:</para> + + <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> + + <note> + <para>The passwords specified with &man.ifconfig.8; + <option>pass</option> must be identical. + <acronym>CARP</acronym> will only listen to and accept + advertisements from machines with the correct password.</para> + </note> + + <para>The third machine, + <systemitem>hostc.example.org</systemitem>, + is prepared to handle failover from + either of the previous hosts. This machine is configured + with two <acronym>CARP</acronym> <acronym>VHID</acronym>s, one + to handle the virtual <acronym>IP</acronym> address of each + of the master hosts. <option>advskew</option>, the + <acronym>CARP</acronym> advertising skew, is set to + ensure that the backup host advertises later than the + master. <option>advskew</option> controls the order of precedence when there + are multiple backup servers. Set the configuration in + <filename>/etc/rc.conf</filename>:</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 two <acronym>CARP</acronym> + <acronym>VHID</acronym>s configured means that + <systemitem>hostc.example.org</systemitem> will notice if + either of the master servers becomes unavailable. If a master + fails to advertise before the backup server, the backup server + will pick up the shared <acronym>IP</acronym> address until + the master becomes available again.</para> + + <note> + <para>Preemption is disabled by default. If preemption has + been enabled, <systemitem>hostc.example.org</systemitem> + might not release the virtual <acronym>IP</acronym> address + back to the original master server. The administrator + can force the backup server to return the + <acronym>IP</acronym> address to the master with the + command:</para> + + <screen>&prompt.root; <command>ifconfig em0 vhid 1 state backup</command></screen> + </note> + + <para>At this point, either networking must be restarted or the + machine rebooted, then <acronym>CARP</acronym> is + enabled.</para> + + <para><acronym>CARP</acronym> functionality can be controlled + via several &man.sysctl.8; variables documented in the + &man.carp.4; manual pages. Other actions can be triggered + from <acronym>CARP</acronym> events by using + &man.devd.8;.</para> + </sect2> + + <sect2 xml:id="carp-9x"> + <title>Using <acronym>CARP</acronym> on &os; 9 and + Earlier</title> + + <para>Enable support for <acronym>CARP</acronym> by loading the + <filename>if_carp.ko</filename> kernel module in + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>if_carp_load="YES"</programlisting> + + <para><acronym>CARP</acronym> can also be built into the + &os; kernel as described in <xref linkend="kernelconfig"/>:</para> + + <programlisting>device carp</programlisting> + + <para>The <acronym>CARP</acronym> devices themselves may be + created using &man.ifconfig.8;:</para> + + <screen>&prompt.root; <command>ifconfig carp0 create</command></screen> + + <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> <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> + <para>On <systemitem>hostb.example.org</systemitem>:</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 - 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> + <para>The passwords specified with &man.ifconfig.8; + <option>pass</option> must be identical. + <acronym>CARP</acronym> will only listen to and accept + advertisements from machines with the correct password. The + <acronym>VHID</acronym> must also be unique for each virtual + <acronym>IP</acronym> address.</para> </note> <para>The third machine, - <systemitem>provider.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 host. - The appropriate <filename>/etc/rc.conf</filename> - configuration lines will be similar to the following:</para> + <systemitem>hostc.example.org</systemitem>, is + prepared to handle failover from either of the previous hosts. + This machine is configured with two + <acronym>CARP</acronym> devices, one to handle each of the virtual <acronym>IP</acronym> address of each of the master hosts. + Setting the <option>advskew</option> + controls the <acronym>CARP</acronym> advertising skew. The + skew ensuring that the backup hosts advertises later than the + master, and controls the order of precedence when there + are multiple backup servers. Set the configuration in + <filename>/etc/rc.conf</filename>:</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 up the <acronym>IP</acronym> address of either - machine, should it stop responding.</para> + <para>Having two <acronym>CARP</acronym> devices configured + means that <systemitem>hostc.example.org</systemitem> will + notice if either of the master servers becomes unavailable. + If a master fails to advertise before the backup server, the + backup server will pick up the shared <acronym>IP</acronym> + address until the master becomes available again.</para> <note> - <para>The default &os; kernel <emphasis>may</emphasis> have - preemption enabled. If so, - <systemitem>provider.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> + <para>Preemption is disabled in the GENERIC &os; kernel. + If Preemption has been enabled with a custom kernel, + <systemitem>hostc.example.org</systemitem> may not + release the <acronym>IP</acronym> address back to the + original content server. The administrator can force the backup + server to return the <acronym>IP</acronym> address to the + master with the command:</para> - <screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen> + <screen>&prompt.root; <command>ifconfig carp0 down && ifconfig carp0 up</command></screen> <para>This should be done on the <filename>carp</filename> interface which corresponds to the correct host.</para> </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>More information is available in &man.carp.4;.</para> + <para>At this point, either networking must be restarted or the + machine rebooted, then <acronym>CARP</acronym> is + enabled.</para> + + <para><acronym>CARP</acronym> functionality can be controlled + via several &man.sysctl.8; variables documented in the + &man.carp.4; manual pages. Other actions can be triggered + from <acronym>CARP</acronym> events by using + &man.devd.8;.</para> </sect2> </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402140226.s1E2QQJn085360>