From owner-svn-doc-all@FreeBSD.ORG Fri Feb 14 02:26:26 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id A7CB58A2; Fri, 14 Feb 2014 02:26:26 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (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 919141E36; Fri, 14 Feb 2014 02:26:26 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1E2QQiY085361; Fri, 14 Feb 2014 02:26:26 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1E2QQJn085360; Fri, 14 Feb 2014 02:26:26 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402140226.s1E2QQJn085360@svn.freebsd.org> From: Warren Block Date: Fri, 14 Feb 2014 02:26:26 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 14 Feb 2014 02:26:26 -0000 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 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 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 TomRhodesContributed by + AllanJudeUpdated + by @@ -5698,182 +5700,235 @@ route_hostD="192.168.173.4 hatm0 0 102 l 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. - - To enable support for CARP, the &os; - kernel can be rebuilt as described in with the following option: - - device carp - - Alternatively, the if_carp.ko module - can be loaded at boot time. Add the following line to - /boot/loader.conf: - - if_carp_load="YES" - - 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. - - - - - - The CARP devices themselves may be - created using &man.ifconfig.8;: - - &prompt.root; ifconfig carp0 create - - 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. + same IP address and provide high availability. One or more hosts can fail, and the others will + take over for the failed system transparently. In addition to the shared IP address, hosts also have a + unique IP address for management and + configuration, as in the example provided here. - - Using <acronym>CARP</acronym> for Server + <sect2 xml:id="carp-ha"> + <title>Using <acronym>CARP</acronym> for High Availability - 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. - - The two machines should be configured identically other - than their hostnames and VHIDs. This - example calls these machines + CARP is often used to provide + high availability for one or more services. This example + configures failover support with three hosts, all with + unique IP addresses, but providing the same + web content. These machines are load balanced with a Round + Robin DNS configuration. The master and + backup machines are configured identically + except for their hostnames and management + IP addresses. These servers must have the same configuration and run + the same services. + When the failover occurs, requests to the + service on the shared IP address can only + be answered correctly if the backup server has access to the + same content. The backup machine has two additional + CARP interfaces, one for each of the + master content server's IP addresses. When + a failure occurs, the backup server will pick up the failed + master machine's IP address. Users will + not see a service failure at all. + + This + example has two different masters named 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 + hostb.example.org, with + a shared backup named + hostc.example.org. + + Each virtual IP address has a unique + identification number known as a Virtual Host Identification + (VHID). All of the machines that share an IP address have the same VHID. + The VHID for each virtual + IP address must be unique across the + broadcast domain of the network interface. + + + + Using <acronym>CARP</acronym> on &os; 10 and + Later + + Enable support for CARP by loading the + carp.ko kernel module in + /boot/loader.conf: + + carp_load="YES" + + The CARP module can also be built into the + &os; kernel as described in : + + device carp + + The hostname, management + IP address, + CARP configuration, and the IP address + to be shared are all set by adding entries to + /etc/rc.conf. This example is for + hosta.example.org: + + 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" + + On hostb.example.org: + + 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" + + + The passwords specified with &man.ifconfig.8; + must be identical. + CARP will only listen to and accept + advertisements from machines with the correct password. + + + The third machine, + hostc.example.org, + is prepared to handle failover from + either of the previous hosts. This machine is configured + with two CARP VHIDs, one + to handle the virtual IP address of each + of the master hosts. , the + CARP advertising skew, is set to + ensure that the backup host advertises later than the + master. controls the order of precedence when there + are multiple backup servers. Set the configuration in + /etc/rc.conf: + + 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 two CARP + VHIDs configured means that + hostc.example.org 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 IP address until + the master becomes available again. + + + Preemption is disabled by default. If preemption has + been enabled, hostc.example.org + might not release the virtual IP address + back to the original master server. The administrator + can force the backup server to return the + IP address to the master with the + command: + + &prompt.root; ifconfig em0 vhid 1 state backup + + + At this point, either networking must be restarted or the + machine rebooted, then CARP is + enabled. + + CARP functionality can be controlled + via several &man.sysctl.8; variables documented in the + &man.carp.4; manual pages. Other actions can be triggered + from CARP events by using + &man.devd.8;. + + + + Using <acronym>CARP</acronym> on &os; 9 and + Earlier + + Enable support for CARP by loading the + if_carp.ko kernel module in + /boot/loader.conf: + + if_carp_load="YES" + + CARP can also be built into the + &os; kernel as described in : + + device carp + + The CARP devices themselves may be + created using &man.ifconfig.8;: + + &prompt.root; ifconfig carp0 create + + 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: 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: + On hostb.example.org: 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 - 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. + The passwords specified with &man.ifconfig.8; + must be identical. + CARP will only listen to and accept + advertisements from machines with the correct password. The + VHID must also be unique for each virtual + IP address. The third machine, - provider.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 host. - The appropriate /etc/rc.conf - configuration lines will be similar to the following: + hostc.example.org, is + prepared to handle failover from either of the previous hosts. + This machine is configured with two + CARP devices, one to handle each of the virtual IP address of each of the master hosts. + Setting the + controls the CARP 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 + /etc/rc.conf: - 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 up the IP address of either - machine, should it stop responding. + Having two CARP devices configured + means that hostc.example.org 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 IP + address until the master becomes available again. - The default &os; kernel may have - preemption enabled. If so, - provider.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: + Preemption is disabled in the GENERIC &os; kernel. + If Preemption has been enabled with a custom kernel, + hostc.example.org may not + release the IP address back to the + original content server. The administrator can force the backup + server to return the IP address to the + master with the command: - &prompt.root; ifconfig carp0 down && ifconfig carp0 up + &prompt.root; ifconfig carp0 down && ifconfig carp0 up This should be done on the carp interface which corresponds to the correct host. - At this point, CARP should be enabled - and available for testing. For testing, either networking - has to be restarted or the machines rebooted. - - More information is available in &man.carp.4;. + At this point, either networking must be restarted or the + machine rebooted, then CARP is + enabled. + + CARP functionality can be controlled + via several &man.sysctl.8; variables documented in the + &man.carp.4; manual pages. Other actions can be triggered + from CARP events by using + &man.devd.8;.