From owner-freebsd-doc@FreeBSD.ORG Wed Feb 12 23:10:02 2014 Return-Path: Delivered-To: freebsd-doc@smarthost.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 4DB1E79A for ; Wed, 12 Feb 2014 23:10:02 +0000 (UTC) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 3687B18AC for ; Wed, 12 Feb 2014 23:10:02 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.7/8.14.7) with ESMTP id s1CNA1lm000966 for ; Wed, 12 Feb 2014 23:10:01 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.8/8.14.8/Submit) id s1CNA1vN000965; Wed, 12 Feb 2014 23:10:01 GMT (envelope-from gnats) Date: Wed, 12 Feb 2014 23:10:01 GMT Message-Id: <201402122310.s1CNA1vN000965@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org Cc: From: Allan Jude Subject: Re: docs/186464: Online-Documentation for carp(4) is outdated X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list Reply-To: Allan Jude List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Feb 2014 23:10:02 -0000 The following reply was made to PR docs/186464; it has been noted by GNATS. From: Allan Jude To: bug-followup@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 -- 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 @@ - Common Address Redundancy Protocol - (<acronym>CARP</acronym>) + + Common Address Redundancy Protocol + (<acronym>CARP</acronym>) + TomRhodesContributed by + AllanJudeUpdated by - - CARP @@ -5607,135 +5608,280 @@ The Common Address Redundancy Protocol (CARP) allows multiple hosts to share the - same IP address. In some configurations, - this may be used for availability or load balancing. Hosts - may use separate IP addresses, as in the - example provided here. + same IP address(es) and can be used to + achieve high availability. Hosts should also have a unique + IP address for management and configuration, + as in the example provided here. - To enable support for CARP, the &os; - kernel can be rebuilt as described in with the following option: + + Using <acronym>CARP</acronym> for High + Availability - device carp + One use of CARP is to provide server + high availability for one or more services. This example + configures failover support for three hosts, all with + unique IP addresses and providing the same + web content. These machines are load balanced with a Round + Robin DNS configuration. The master and + backup machines should be configured identically other than + their hostnames and management IP + 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 CARP interfaces, + one for each of the master content server's + IP addresses. When a failure occurs, the + failover server will pick up the failed machine's + IP address. This means that the failure + should go completely unnoticed by the user. This example has + two different masters named + hosta.example.org and + hostb.example.org respectively, with + a shared slave named + hostc.example.org. - Alternatively, the if_carp.ko module - can be loaded at boot time. Add the following line to - /boot/loader.conf: + Each virtual address has a unique + identification number known as a Virtual Host IDentification + (VHID) which is used to distinguish the + virtual address across the various failover machines that + share the address on the network. - if_carp_load="YES" + - CARP functionality should now be - available and may be tuned via several &man.sysctl.8; - variables: + + Using <acronym>CARP</acronym> on &os; 10 and + Later - - - - - OID - Description - - + To enable support for CARP, load the + carp.ko kernel module by adding the + following line to + /boot/loader.conf: - - - net.inet.carp.allow - Accept incoming CARP packets. - Enabled by default. - + carp_load="YES" - - net.inet.carp.preempt - This option downs all of the - CARP interfaces on the host when one - goes down. Disabled by default. - + Alternatively, the &os; kernel can be rebuilt as + described in with the following + option: - - net.inet.carp.log - A value of 0 disables any - logging. A value of 1 enables - logging of bad CARP packets. Values - greater than 1 enable logging of - state changes for the CARP - interfaces. The default value is - 1. - + device carp - - net.inet.carp.arpbalance - Balance local network traffic using - ARP. Disabled by default. - + Set the hostname, configure the management + IP address, then configure + CARP and the IP address + to be shared by adding the required lines to + /etc/rc.conf. Here are example lines for + hosta.example.org: - - net.inet.carp.suppress_preempt - 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 - 0 means that preemption is not - suppressed. Every problem increments this - variable. - - - - + hostname="hosta.example.org" +ifconfig_em0="inet 192.168.1.3 netmask 255.255.255.0" +ifconfig_em0_alias0="vhid 1 pass testpass alias 192.168.1.50/32" - The CARP devices themselves may be - created using &man.ifconfig.8;: + On hostb.example.org, use the + following lines: - &prompt.root; ifconfig carp0 create + hostname="hostb.example.org" +ifconfig_em0="inet 192.168.1.4 netmask 255.255.255.0" +ifconfig_em0_alias0="vhid 2 pass testpass alias 192.168.1.51/32" - In a real environment, each interface has a unique - identification number known as a Virtual Host IDentification - (VHID) which is used to distinguish the - host on the network. + + It is very important that the passwords, specified by + with &man.ifconfig.8;, are + identical. The carp devices will + only listen to and accept advertisements from machines + with the correct password. The VHID + must also be unique for each machine. + - - Using <acronym>CARP</acronym> for Server - Availability + The third machine, + hostc.example.org, + should be prepared so that it may handle failover from either + of the previous host. This machine will be configured with + two CARP VHIDs, one to + handle each host. The additional advskew + parameter controls the CARP advertising + skew. By making this host advertise later, it will become a + backup, rather than the master. The appropriate + /etc/rc.conf configuration lines will be + similar to the following: - One use of CARP is to provide server - availability. This example configures failover support for - three hosts, all with unique IP - addresses and providing the same web content. These machines - act in conjunction with a Round Robin - DNS configuration. The failover machine - has two additional CARP interfaces, one - for each of the content server's - IP addresses. When a - failure occurs, the failover server will pick up the failed - machine's IP 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. + hostname="hostc.example.org" +ifconfig_em0="inet 192.168.1.5 netmask 255.255.255.0" +ifconfig_em0_alias0="vhid 1 advskew 100 pass testpass alias 192.168.1.50/32" +ifconfig_em0_alias1="vhid 2 advskew 100 pass testpass alias 192.168.1.51/32" + Having the two CARP + VHIDs will allow + hostc.example.org to notice and + pick up the shared IP address of either + machine, should it become unavailable. + + + The default &os; kernel has + preemption disabled. If it is enabled, + hostc.example.org may not + relinquish the IP address back to the + original master server. In this case, an administrator may + have to manually force the IP back to the + master. The following command should be issued on + hostc.example.org: + + &prompt.root; ifconfig em0 vhid 1 state backup + + + + At this point, CARP should be enabled + and available for testing. For testing, either networking + has to be restarted or the machines rebooted. + + CARP functionality should now be + available and may be tuned via several &man.sysctl.8; + variables: + + + + + + OID + Description + + + + + + net.inet.carp.allow + Accept incoming CARP packets. + Enabled by default. + + + + net.inet.carp.preempt + 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 CARP + VHIDs. 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. + + + + net.inet.carp.log + 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. + + + + net.inet.carp.demotion + This value shows current level of + CARP demotion. The value is added + to the actual advskew sent in announcements for all + VHIDs. During normal system + operation the demotion factor is zero. However, + problematic conditions raise this level: when + CARP experiences a problem with + sending announcements, when an interface running a + VHID 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 + CARP to be controlled depending on + external conditions, for example on the status of some + daemon utility. + + + + net.inet.carp.ifdown_demotion_factor + This value is added to + net.inet.carp.demotion when an + interface running a VHID goes down. + The default value is 240 (the maximum advskew + value). + + + + net.inet.carp.senderr_demotion_factor + This value is added to + net.inet.carp.demotion when + CARP experiences errors sending its + announcements. The default value is 240 (the maximum + advskew value). + + + + + + It is also possible to trigger other actions based on + CARP events using &man.devd.8;. More + information is available in &man.carp.4;. + + + + + Using <acronym>CARP</acronym> on &os; 9 and + Earlier + + To enable support for CARP, load the + if_carp.ko kernel module by adding the + following line to + /boot/loader.conf: + + if_carp_load="YES" + + Alternatively, the &os; kernel can be rebuilt as + described in with the following + option: + + device carp + + The CARP devices themselves may be + created using &man.ifconfig.8;: + + &prompt.root; ifconfig carp0 create + + Each virtual address has a unique + identification number known as a Virtual Host IDentification + (VHID) which is used to distinguish the + virtual address across the various failover machines that + share the address on the network. + The two machines should be configured identically other - than their hostnames and VHIDs. This - example calls these machines - hosta.example.org and - hostb.example.org respectively. First, the - required lines for a CARP configuration - have to be added to /etc/rc.conf. Here - are the lines for + than their hostnames, unique IP addresses + and VHIDs. This example calls these + machines hosta.example.org and + hostb.example.org respectively. + First, the required lines for a CARP + configuration have to be added to + /etc/rc.conf. Here are example lines for hosta.example.org: hostname="hosta.example.org" -ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0" +ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0" cloned_interfaces="carp0" -ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24" +ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24" On hostb.example.org, use the following lines: hostname="hostb.example.org" -ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0" +ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0" cloned_interfaces="carp0" -ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24" +ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24" It is very important that the passwords, specified by - the option to &man.ifconfig.8;, are + with &man.ifconfig.8;, are identical. The carp devices will only listen to and accept advertisements from machines with the correct password. The VHID @@ -5742,7 +5888,7 @@ must also be unique for each machine. - The third machine, provider.example.org, + The third machine, hostc.example.org, should be prepared so that it may handle failover from either host. This machine will require two carp devices, one to handle each @@ -5749,26 +5895,26 @@ host. The appropriate /etc/rc.conf configuration lines will be similar to the following: - hostname="provider.example.org" -ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0" + hostname="hostc.example.org" +ifconfig_fxp0="inet 192.168.1.5 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" +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" Having the two carp devices will - allow provider.example.org to notice and pick + allow hostc.example.org to notice and pick up the IP address of either machine, should - it stop responding. + it become unavailable. The default &os; kernel may have preemption enabled. If so, - provider.example.org may not relinquish the + hostc.example.org may not relinquish the IP address back to the original content server. In this case, an administrator may have to manually force the IP back to the master. The following command should be issued on - provider.example.org: + hostc.example.org: &prompt.root; ifconfig carp0 down && ifconfig carp0 up @@ -5780,6 +5926,63 @@ and available for testing. For testing, either networking has to be restarted or the machines rebooted. + CARP functionality should now be + available and may be tuned via several &man.sysctl.8; + variables: + + + + + + OID + Description + + + + + + net.inet.carp.allow + Accept incoming CARP packets. + Enabled by default. + + + + net.inet.carp.preempt + This option downs all of the + CARP interfaces on the host when one + goes down. Disabled by default. + + + + net.inet.carp.log + A value of 0 disables any + logging. A value of 1 enables + logging of bad CARP packets. Values + greater than 1 enable logging of + state changes for the CARP + interfaces. The default value is + 1. + + + + net.inet.carp.arpbalance + Balance local network traffic using + ARP. Disabled by default. + + + + net.inet.carp.suppress_preempt + 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 + 0 means that preemption is not + suppressed. Every problem increments this + variable. + + + + + More information is available in &man.carp.4;. --------------020801060300060708020404--