From 4b4c9adb80f11da18a259f2a3b99e0a3b877c3bd Mon Sep 17 00:00:00 2001 From: glebius Date: Wed, 23 Feb 2005 08:29:50 +0000 Subject: Manpage for CARP from .Ox, with minor modifications. Obtained from: OpenBSD --- share/man/man4/Makefile | 1 + share/man/man4/carp.4 | 214 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 share/man/man4/carp.4 (limited to 'share/man') diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 6857509..d75844b 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -35,6 +35,7 @@ MAN= aac.4 \ bridge.4 \ bt.4 \ cardbus.4 \ + carp.4 \ ccd.4 \ cd.4 \ ch.4 \ diff --git a/share/man/man4/carp.4 b/share/man/man4/carp.4 new file mode 100644 index 0000000..16ebfea --- /dev/null +++ b/share/man/man4/carp.4 @@ -0,0 +1,214 @@ +.\" $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $ +.\" +.\" Copyright (c) 2003, Ryan McBride. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 23, 2005 +.Dt CARP 4 +.Os +.Sh NAME +.Nm carp +.Nd Common Address Redundancy Protocol +.Sh SYNOPSIS +.Cd "device carp" +.Sh DESCRIPTION +The +.Nm +interface is a pseudo-device which implements and controls the +CARP protocol. +.Nm +allows multiple hosts on the same local network to share a set of IP addresses. +Its primary purpose is to ensure that these +addresses are always available, but in some configurations +.Nm +can also provide load balancing functionality. +.Pp +A +.Nm +interface can be created at runtime using the +.Ic ifconfig carp Ns Ar N Ic create +command or by setting up configuration in +.Pa /etc/rc.conf +file. +.Pp +To use +.Nm , +the administrator needs to configure at minimum a common virtual host ID and +virtual host IP address on each machine which is to take part in the virtual +group. +Additional parameters can also be set on a per-interface basis: +.Cm advbase +and +.Cm advskew , +which are used to control how frequently the host sends advertisements when it +is the master for a virtual host, and +.Cm pass +which is used to authenticate carp advertisements. +Finally +.Cm carpdev +is used to specify which interface the +.Nm +device attaches to. +If unspecified, the kernel attempts to set carpdev by looking for +another interface with the same subnet. +These configurations can be done using +.Xr ifconfig 8 , +or through the +.Dv SIOCSVH +ioctl. +.Pp +Additionally, there are a number of global parameters which can be set using +.Xr sysctl 8 : +.Bl -tag -width net.inet.carp.arpbalance +.It net.inet.carp.allow +Accept incoming +.Nm +packets. +Enabled by default. +.It net.inet.carp.preempt +Allow virtual hosts to preempt each other. +It is also used to failover +.Nm +interfaces as a group. +When the option is enabled and one of the +.Nm +enabled physical interfaces +goes down, advskew is changed to 240 on all +.Nm +interfaces. +See also the first example. +Disabled by default. +.It net.inet.carp.log +Log bad +.Nm +packets. +Enabled by default. +.It net.inet.carp.arpbalance +Balance local traffic using ARP. +Disabled by default. +.El +.Sh EXAMPLES +For firewalls and routers with multiple interfaces, it is desirable to +failover all of the +.Nm +interfaces together, when one of the physical interfaces goes down. +This is achieved by the preempt option. +Enable it on both host A and B: +.Pp +.Dl # sysctl net.inet.carp.preempt=1 +.Pp +Assume that host A is the preferred master and 192.168.1.x/24 is +configured on one physical interface and 192.168.2.y/24 on another. +This is the setup for host A: +.Bd -literal -offset indent +# ifconfig carp0 create +# ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.1 \e + 255.255.255.0 +# ifconfig carp1 create +# ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.2.1 \e + 255.255.255.0 +.Ed +.Pp +The setup for host B is identical, but it has a higher advskew: +.Bd -literal -offset indent +# ifconfig carp0 create +# ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e + 192.168.1.1 255.255.255.0 +# ifconfig carp1 create +# ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e + 192.168.2.1 255.255.255.0 +.Ed +.Pp +Because of the preempt option, when one of the physical interfaces of +host A fails, advskew is adjusted to 240 on all its +.Nm +interfaces. +This will cause host B to preempt on both interfaces instead of +just the failed one. +.Pp +In order to set up an ARP balanced virtual host, it is necessary to configure +one virtual host for each physical host which would respond to ARP requests +and thus handle the traffic. +In the following example, two virtual hosts are configured on two hosts to +provide balancing and failover for the IP address 192.168.1.10. +.Pp +First the +.Nm +interfaces on Host A are configured. +The +.Cm advskew +of 100 on the second virtual host means that its advertisements will be sent +out slightly less frequently. +.Bd -literal -offset indent +# ifconfig carp0 create +# ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10 \e + 255.255.255.0 +# ifconfig carp1 create +# ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e + 192.168.1.10 255.255.255.0 +.Ed +.Pp +The configuration for host B is identical, except the skew is on +virtual host 1 rather than virtual host 2. +.Bd -literal -offset indent +# ifconfig carp0 create +# ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e + 192.168.1.10 255.255.255.0 +# ifconfig carp1 create +# ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10 \e + 255.255.255.0 +.Ed +.Pp +Finally, the ARP balancing feature must be enabled on both hosts: +.Pp +.Dl # sysctl net.inet.carp.arpbalance=1 +.Pp +When the hosts receive an ARP request for 192.168.1.10, the source IP address +of the request is used to compute which virtual host should answer the request. +The host which is master of the selected virtual host will reply to the +request, the other(s) will ignore it. +.Pp +This way, locally connected systems will receive different ARP replies and +subsequent IP traffic will be balanced among the hosts. +If one of the hosts fails, the other will take over the virtual MAC address, +and begin answering ARP requests on its behalf. +.Pp +Note: ARP balancing only works on the local network segment. +It cannot balance traffic that crosses a router, because the router +itself will always be balanced to the same virtual host. +.Sh SEE ALSO +.Xr inet 4 , +.Xr rc.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device first appeared in +.Ox 3.5 . +The +.Nm +device was imported to +.Fx 5.4 . -- cgit v1.1