FreeBSD Bugzilla – Attachment 140023 Details for
Bug 186464
Online-Documentation for carp(4) is outdated
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
Remember
[x]
|
Forgot Password
Login:
[x]
[patch]
docs.carp_10x_v2.diff
docs.carp_10x_v2.diff (text/plain; charset=windows-1252), 23.22 KB, created by
Allan Jude
on 2014-02-13 05:05:22 UTC
(
hide
)
Description:
docs.carp_10x_v2.diff
Filename:
MIME Type:
Creator:
Allan Jude
Created:
2014-02-13 05:05:22 UTC
Size:
23.22 KB
patch
obsolete
>Index: head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml >=================================================================== >--- head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml (revision 43884) >+++ head/en_US.ISO8859-1/books/handbook/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,179 +5608,379 @@ > > <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 will usually 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 >+ high availability for one or more services. This example >+ configures failover support with 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 preferrably 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. 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, and the >+ failure would go completely unnoticed by the users. This >+ example has two different masters named >+ <systemitem>hosta.example.org</systemitem> and >+ <systemitem>hostb.example.org</systemitem>, with >+ a shared backup 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 <acronym>IP</acronym> address has a unique >+ identification number known as a Virtual Host Identification >+ (<acronym>VHID</acronym>). The <acronym>VHID</acronym> is >+ used to indicate which machines are to share a common address. >+ The <acronym>VHID</acronym> for each virtual >+ <acronym>IP</acronym> address must be unique across the >+ broadcast domain of the network interface.</para> >+ </sect2> > >- <programlisting>if_carp_load="YES"</programlisting> >+ <sect2 xml:id="carp-10x"> >+ <title>Using <acronym>CARP</acronym> on &os; 10 and >+ Later</title> > >- <para><acronym>CARP</acronym> functionality should now be >- available and may be tuned via several &man.sysctl.8; >- variables:</para> >+ <para>Enable support for <acronym>CARP</acronym> by loading the >+ <filename>carp.ko</filename> kernel module in >+ <filename>/boot/loader.conf</filename>:</para> > >- <informaltable frame="none" pgwide="1"> >- <tgroup cols="2"> >- <thead> >- <row> >- <entry>OID</entry> >- <entry>Description</entry> >- </row> >- </thead> >+ <programlisting>carp_load="YES"</programlisting> > >- <tbody> >- <row> >- <entry><varname>net.inet.carp.allow</varname></entry> >- <entry>Accept incoming <acronym>CARP</acronym> packets. >- Enabled by default.</entry> >- </row> >+ <para>The <acronym>CARP</acronym> can also be built into the >+ &os; kernel as described in <xref linkend="kernelconfig"/> >+ by enabling the option:</para> > >- <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> >+ <programlisting>device carp</programlisting> > >- <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> >+ <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.arpbalance</varname></entry> >- <entry>Balance local network traffic using >- <acronym>ARP</acronym>. Disabled by default.</entry> >- </row> >+ <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> > >- <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>On <systemitem>hostb.example.org</systemitem>:</para> > >- <para>The <acronym>CARP</acronym> devices themselves may be >- created using &man.ifconfig.8;:</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> > >- <screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen> >+ <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. The >+ <acronym>VHID</acronym> must also be unique for each virtual >+ <acronym>IP</acronym> address.</para> >+ </note> > >- <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> >+ <para>The third machine, >+ <systemitem>hostc.example.org</systemitem>, >+ needs to be prepared so that it can handle failover from >+ either of the previous host. 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. 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> > >- <sect2> >- <title>Using <acronym>CARP</acronym> for Server >- Availability</title> >+ <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>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>Having the 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> > >- <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 >+ <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:</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 with >+ <varname>preempt</varname>. When one of the physical >+ interfaces of the master fails, >+ <option>advskew</option> 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 >+ <acronym>CARP</acronym> <acronym>VHID</acronym>s are >+ logged. A value of 0 disables any logging. A value >+ of 1 enables logging state changes of >+ <acronym>CARP</acronym> <acronym>VHID</acronym>s. >+ Values above 1 enable logging of bad >+ <acronym>CARP</acronym> packets. The default value is >+ 1.</entry> >+ </row> >+ >+ <row> >+ <entry><varname>net.inet.carp.demotion</varname></entry> >+ <entry>This value shows the current level of >+ <acronym>CARP</acronym> demotion. The value is added >+ to the actual <option>advskew</option> sent in >+ announcements for all <acronym>VHID</acronym>s. >+ During normal system operation the demotion factor is >+ zero. Problematic conditions automatically 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 also be adjusted manually by >+ writing to this &man.sysctl.8; <acronym>OID</acronym>. >+ The signed value set via &man.sysctl.8; is added to >+ the current demotion factor. This allows the >+ behavior of <acronym>CARP</acronym> to be controlled >+ depending on external conditions, like 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 >+ <option>advskew</option> 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 >+ <option>advskew</option> value).</entry> >+ </row> >+ </tbody> >+ </tgroup> >+ </informaltable> >+ >+ <para>Other actions can be triggered from >+ <acronym>CARP</acronym> events by 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>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>The <acronym>CARP</acronym> can also be built into the >+ &os; kernel as described in <xref linkend="kernelconfig"/> >+ by enabling the option:</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> >+ <para>The third machine, >+ <systemitem>hostc.example.org</systemitem>, >+ needs to be prepared so that it can handle failover from >+ either of the previous host. This machine is configured >+ with two <acronym>CARP</acronym> devicess, one >+ to handle 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 the two <acronym>CARP</acronym> devicess 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>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:</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>
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
Attachments on
bug 186464
:
140022
| 140023