.TH KEEPALIVED.CONF 5 "Jan 2004" V1.0
.UC 4
.SH NAME
/etc/keepalived/keepalived.conf - configuration file for keepalived
.br
.SH DESCRIPTION
.B keepalived.conf
is the configuration file which describes all the keepalived keywords.
keywords are placed in hierachies of blocks (and subblocks), 
each layer being delimited by '{' and '}' pairs. 
.PP
Comments start with '#' or '!' to the end of the line and can start 
anywhere in a line.
.SH TOP HIERACHY
.PP
.B GLOBAL CONFIGURATION
.PP
.B VRRPD CONFIGURATION
.PP
.B LVS CONFIGURATION
.PP
.SH GLOBAL CONFIGURATION
contains subblocks of 
.B Global definitions
and
.B Static routes
.PP
.SH Global definitions
.PP
 global_defs           # Block id
 { 
 notification_email    # To:
        {
        admin@example1.com 
        ...
        }
 # From: from address that will be in header
 notification_email_from admin@example.com 
 smtp_server 127.0.0.1        # IP
 smtp_connect_timeout 30      # integer, seconds
 router_id my_hostname        # string identifying the machine,
                              # (doesn't have to be hostname).
 vrrp_mcast_group4 224.0.0.18 # optional, default 224.0.0.18
 vrrp_mcast_group6 ff02::12   # optional, default ff02::12
 enable_traps                 # enable SNMP traps
 }


.SH Static routes/addresses
.PP
keepalived can configure static addresses and routes. These addresses are
.B NOT
moved by vrrpd, they stay on the machine. 
If you already have IPs and routes on your machines and
your machines can ping each other, you don't need this section.
.PP
The syntax is the same as for virtual addresses and virtual routes.
.PP
 static_ipaddress
 {
 192.168.1.1/24 dev eth0 scope global
 ...
 }
.PP
 static_routes
 {
 192.168.2.0/24 via 192.168.1.100 dev eth0
 ...
 }
.PP
.SH VRRPD CONFIGURATION
contains subblocks of 
.B VRRP synchronization group(s)
and
.B VRRP instance(s)
.PP
.SH VRRP synchronization group(s)
.PP
 #string, name of group of IPs that failover together
 vrrp_sync_group VG_1 { 
    group {
      inside_network   # name of vrrp_instance (below) 
      outside_network  # One for each moveable IP. 
      ... 
    }
    
    # notify scripts and alerts are optional
    #
    # filenames of scripts to run on transitions
    # can be unquoted (if just filename) 
    # or quoted (if has parameters)
    # to MASTER transition
    notify_master /path/to_master.sh 
    # to BACKUP transition
    notify_backup /path/to_backup.sh 
    # FAULT transition 
    notify_fault "/path/fault.sh VG_1" 

    # for ANY state transition.
    # "notify" script is called AFTER the 
    # notify_* script(s) and is executed 
    # with 3 arguments provided by keepalived
    # (ie don't include parameters in the notify line).
    # arguments
    # $1 = "GROUP"|"INSTANCE"
    # $2 = name of group or instance
    # $3 = target state of transition 
    #     ("MASTER"|"BACKUP"|"FAULT")
    notify /path/notify.sh 

    # Send email notifcation during state transition, 
    # using addresses in global_defs above.
    smtp_alert
 }

.SH VRRP instance(s)
.PP
describes the moveable IP for each instance of a group in vrrp_sync_group.
Here are described two IPs (on inside_network and on outside_network), 
on machine "my_hostname", which belong to the group VG_1 and
which will transition together on any state change.
.PP
 #You will need to write another block for outside_network.
 vrrp_instance inside_network {
    # Initial state, MASTER|BACKUP
    # As soon as the other machine(s) come up, 
    # an election will be held and the machine 
    # with the highest "priority" will become MASTER.
    # So the entry here doesn't matter a whole lot.
    state MASTER

    # interface for inside_network, bound by vrrp
    interface eth0

    # Use VRRP Virtual MAC.
    use_vmac <VMAC_INTERFACE>

    # Send/Recv VRRP messages from base interface instead of
    # VMAC interface
    vmac_xmit_base

    # Ignore VRRP interface faults (default unset)
    dont_track_primary

    # optional, monitor these as well. 
    # go to FAULT state if any of these go down.
    track_interface {
      eth0 
      eth1 
      ...
    }

    # default IP for binding vrrpd is the primary IP 
    # on interface. If you want to hide location of vrrpd, 
    # use this IP as src_addr for multicast or unicast vrrp
    # packets. (since it's multicast, vrrpd will get the reply 
    # packet no matter what src_addr is used).
    # optional
    mcast_src_ip <IPADDR> 
    unicast_src_ip <IPADDR> 

    # Do not send VRRP adverts over VRRP multicast group.
    # Instead it sends adverts to the following list of
    # ip addresses using unicast design fashion. It can
    # be cool to use VRRP FSM and features in a networking
    # environement where multicast is not supported !
    # IP Addresses specified can IPv4 as well as IPv6
    unicast_peer {
      <IPADDR>
      ...
    }

    # Binding interface for lvs syncd
    lvs_sync_daemon_interface eth1 

    # delay for gratuitous ARP after transition to MASTER
    garp_master_delay 10 # secs, default 5 

    # arbitary unique number 0..255
    # used to differentiate multiple instances of vrrpd
    # running on the same NIC (and hence same socket).
    virtual_router_id 51

    # for electing MASTER, highest priority wins.
    # to be MASTER, make 50 more than other machines.
    priority 100

    # VRRP Advert interval, secs (use default)
    advert_int 1
    authentication {     # Authentication block
        # PASS||AH
        # PASS - Simple Passwd (suggested) 
        # AH - IPSEC (not recommended))
        auth_type PASS
        # Password for accessing vrrpd.
        # should be the same for all machines.
        # Only the first eight (8) characters are used.
        auth_pass 1234
    }

    #addresses add|del on change to MASTER, to BACKUP.
    #With the same entries on other machines,
    #the opposite transition will be occuring.
    virtual_ipaddress {
        <IPADDR>/<MASK> brd <IPADDR> dev <STRING> scope <SCOPE> label <LABEL>
        192.168.200.17/24 dev eth1
        192.168.200.18/24 dev eth2 label eth2:1
    }

    #VRRP IP excluded from VRRP
    #optional.
    #For cases with large numbers (eg 200) of IPs 
    #on the same interface. To decrease the number 
    #of packets sent in adverts, you can exclude 
    #most IPs from adverts.
    #The IPs are add|del as for virtual_ipaddress.
    virtual_ipaddress_excluded { 
     <IPADDR>/<MASK> brd <IPADDR> dev <STRING> scope <SCOPE> 
     <IPADDR>/<MASK> brd <IPADDR> dev <STRING> scope <SCOPE>
        ...
    }
    # routes add|del when changing to MASTER, to BACKUP
    virtual_routes {
        # src <IPADDR> [to] <IPADDR>/<MASK> via|gw <IPADDR> [or <IPADDR>] dev <STRING> scope <SCOPE> tab
        src 192.168.100.1 to 192.168.109.0/24 via 192.168.200.254 dev eth1
        192.168.110.0/24 via 192.168.200.254 dev eth1
        192.168.111.0/24 dev eth2
        192.168.112.0/24 via 192.168.100.254
	192.168.113.0/24 via 192.168.200.254 or 192.168.100.254 dev eth1
	blackhole 192.168.114.0/24
    }

    # VRRP will normally preempt a lower priority
    # machine when a higher priority machine comes
    # online.  "nopreempt" allows the lower priority
    # machine to maintain the master role, even when
    # a higher priority machine comes back online.
    # NOTE: For this to work, the initial state of this
    # entry must be BACKUP.
    nopreempt

    # Seconds after startup until preemption
    # (if not disabled by "nopreempt").
    # Range: 0 (default) to 1,000
    # NOTE: For this to work, the initial state of this
    # entry must be BACKUP.
    preempt_delay 300    # waits 5 minutes

    # Debug level, not implemented yet.
    debug

    # notify scripts, alert as above
    notify_master <STRING>|<QUOTED-STRING>
    notify_backup <STRING>|<QUOTED-STRING>
    notify_fault <STRING>|<QUOTED-STRING> 
    notify <STRING>|<QUOTED-STRING> 
    smtp_alert 
 }

.SH LVS CONFIGURATION
contains subblocks of 
.B Virtual server group(s)
and
.B Virtual server(s)
.PP
The subblocks contain arguments for 
.I ipvsadm(8). 
A knowlege of 
.I ipvsadm(8)
will be helpful here.
.PP
.SH Virtual server group(s)
.PP
 # optional
 # this groups allows a service on a real_server 
 # to belong to multiple virtual services 
 # and to be only health checked once.
 # Only for very large LVSs.
 virtual_server_group <STRING> {
        #VIP port
        <IPADDR> <PORT> 
        <IPADDR> <PORT>
        ...
        #
        # <IPADDR RANGE> has the form 
        # XXX.YYY.ZZZ.WWW-VVV eg 192.168.200.1-10 
        # range includes both .1 and .10 address
        <IPADDR RANGE> <PORT># VIP range VPORT
        <IPADDR RANGE> <PORT>
        ...
        fwmark <INT>  # fwmark
        fwmark <INT>
        ...
}

.SH Virtual server(s)
.PP
A virtual_server can be a declaration of one of 
.TP 
.B vip vport (IPADDR PORT pair)
.TP
.B fwmark <INT>
.TP
.B (virtual server) group <STRING>

    #setup service
    virtual_server IP port |
    virtual_server fwmark int |
    virtual_server group string
    {
    # delay timer for service polling
    delay_loop <INT> 

    # LVS scheduler 
    lb_algo rr|wrr|lc|wlc|lblc|sh|dh 
    # Enable One-Packet-Scheduling for UDP (-O in ipvsadm)
    ops
    # LVS forwarding method
    lb_kind NAT|DR|TUN 
    # LVS persistence timeout, sec
    persistence_timeout <INT> 
    # LVS granularity mask (-M in ipvsadm)
    persistence_granularity <NETMASK> 
    # Only TCP is implemented
    protocol TCP 
    # If VS IP address is not set, 
    # suspend healthchecker's activity
    ha_suspend
    
    # VirtualHost string for HTTP_GET or SSL_GET
    # eg virtualhost www.firewall.loc
    virtualhost <STRING>                

    # Assume silently all RSs down and healthchecks
    # failed on start. This helps preventing false
    # positive actions on startup. Alpha mode is
    # disabled by default.
    alpha

    # On daemon shutdown, consider quorum and RS
    # down notifiers for execution, where appropriate.
    # Omega mode is disabled by default.
    omega

    # Minimum total weight of all live servers in
    # the pool necessary to operate VS with no
    # quality regression. Defaults to 1.
    quorum <INT>

    # Tolerate this much weight units compared to the
    # nominal quorum, when considering quorum gain
    # or loss. A flap dampener. Defaults to 0.
    hysteresis <INT>

    # Script to launch when quorum is gained.
    quorum_up <STRING>|<QUOTED-STRING>

    # Script to launch when quorum is lost.
    quorum_down <STRING>|<QUOTED-STRING>


    # setup realserver(s)

    # RS to add when all realservers are down
    sorry_server <IPADDR> <PORT>
    # applies inhibit_on_failure behaviour to the
    # preceding sorry_server directive
    sorry_server_inhibit
    
    # one entry for each realserver 	
    real_server <IPADDR> <PORT> 
       {
           # relative weight to use, default: 1
           weight <INT> 
           # Set weight to 0
           # when healthchecker detects failure
           inhibit_on_failure 
                
           # Script to launch when healthchecker
           # considers service as up.
           notify_up <STRING>|<QUOTED-STRING> 
           # Script to launch when healthchecker
           # considers service as down.
           notify_down <STRING>|<QUOTED-STRING> 
   
           # pick one healthchecker
           # HTTP_GET|SSL_GET|TCP_CHECK|SMTP_CHECK|MISC_CHECK
   
           # HTTP and SSL healthcheckers
           HTTP_GET|SSL_GET 
           {              
               # A url to test
               # can have multiple entries here
               url {
                 #eg path / , or path /mrtg2/
                 path <STRING> 
                 # healthcheck needs status_code
                 # or status_code and digest
                 # Digest computed with genhash
                 # eg digest 9b3a0c85a887a256d6939da88aabd8cd
                 digest <STRING>
                 # status code returned in the HTTP header
                 # eg status_code 200
                 status_code <INT>     
               } 
               # number of get retry
               nb_get_retry <INT> 
               # delay before retry
               delay_before_retry <INT>

               # ======== generic connection options
               # Optional IP address to connect to.
               # The default is real server's IP
               connect_ip <IP ADDRESS>
               # Optional port to connect to if not
               # The default is real server's port
               connect_port <PORT>
               # Optional interface to use to
               # originate the connection
               bindto <IP ADDRESS>
               # Optional source port to
               # originate the connection from
               bind_port <PORT>
               # Optional connection timeout in seconds.
               # The default is 5 seconds
               connect_timeout <INTEGER>
               # Optional fwmark to mark all outgoing
               # checker pakets with
               fwmark <INTEGER>

               # Optional random delay to begin initial check for
               # maximum N seconds.
               # Useful to scatter multiple simultaneous
               # checks to the same RS. Enabled by default, with
               # the maximum at delay_loop. Specify 0 to disable
               warmup <INT>
           } #HTTP_GET|SSL_GET
   
           #TCP healthchecker (bind to IP port)
           TCP_CHECK 
           { 
               # ======== generic connection options
               # Optional IP address to connect to.
               # The default is real server's IP
               connect_ip <IP ADDRESS>
               # Optional port to connect to if not
               # The default is real server's port
               connect_port <PORT>
               # Optional interface to use to
               # originate the connection
               bindto <IP ADDRESS>
               # Optional source port to
               # originate the connection from
               bind_port <PORT>
               # Optional connection timeout in seconds.
               # The default is 5 seconds
               connect_timeout <INTEGER>
               # Optional fwmark to mark all outgoing
               # checker pakets with
               fwmark <INTEGER>

               # Optional random delay to begin initial check for
               # maximum N seconds.
               # Useful to scatter multiple simultaneous
               # checks to the same RS. Enabled by default, with
               # the maximum at delay_loop. Specify 0 to disable
               warmup <INT>
           } #TCP_CHECK

           # SMTP healthchecker
           SMTP_CHECK
           {
               # An optional host interface to check.
               # If no host directives are present, only
               # the ip address of the real server will
               # be checked.
               host {
                 # ======== generic connection options
                 # Optional IP address to connect to.
                 # The default is real server's IP
                 connect_ip <IP ADDRESS>
                 # Optional port to connect to if not
                 # the default of 25
                 connect_port <PORT>
                 # Optional interface to use to
                 # originate the connection
                 bindto <IP ADDRESS>
                 # Optional source port to
                 # originate the connection from
                 bind_port <PORT>
                 # Optional per-host connection timeout.
                 # Default is outer-scope connect_timeout
                 connect_timeout <INTEGER>
                 # Optional fwmark to mark all outgoing
                 # checker pakets with
                 fwmark <INTEGER>
              }
              # Connection and read/write timeout
              # in seconds. The default is 5 seconds
              connect_timeout <INTEGER>
              # Number of times to retry a failed check
              retry <INTEGER>
              # Delay in seconds before retrying
              delay_before_retry <INTEGER>
              # Optional string to use for the smtp HELO request
              helo_name <STRING>|<QUOTED-STRING>

              # Optional random delay to begin initial check for
              # maximum N seconds.
              # Useful to scatter multiple simultaneous
              # checks to the same RS. Enabled by default, with
              # the maximum at delay_loop. Specify 0 to disable
              warmup <INT>
           } #SMTP_CHECK

           #MISC healthchecker, run a program
           MISC_CHECK 
           {
               # External system script or program
               misc_path <STRING>|<QUOTED-STRING>
               # Script execution timeout
               misc_timeout <INT>

               # Optional random delay to begin initial check for
               # maximum N seconds.
               # Useful to scatter multiple simultaneous
               # checks to the same RS. Enabled by default, with
               # the maximum at delay_loop. Specify 0 to disable
               warmup <INT>

               # If set, exit code from healthchecker is used
               # to dynamically adjust the weight as follows:
               #   exit status 0: svc check success, weight
               #     unchanged.
               #   exit status 1: svc check failed.
               #   exit status 2-255: svc check success, weight
               #     changed to 2 less than exit status.
               #   (for example: exit status of 255 would set
               #     weight to 253)
               misc_dynamic
           }
       } # realserver defn
    } # virtual service


.SH AUTHOR 
.br
Joseph Mack. 
.br
Information derived from doc/keepalived.conf.SYNOPSIS,
doc/samples/keepalived.conf.* and Changelog by Alexandre Cassen 
for keepalived-1.1.4, 
and from HOWTOs by Adam Fletcher and Vince Worthington.
.SH "SEE ALSO"
ipvsadm(8), ip --help.
.\" Local Variables:
.\"  mode: nroff
.\" End: