1keepalived.conf(5)     Keepalived Configuration's Manual    keepalived.conf(5)
2
3
4

NAME

6       keepalived.conf - configuration file for Keepalived
7

DESCRIPTION

9       keepalived.conf  is  the  configuration  file  which  describes all the
10       Keepalived keywords. Keywords are placed in hierarchies of  blocks  and
11       subblocks, each layer being delimited by '{' and '}' pairs.
12
13       Comments  start  with  '#'  or '!' to the end of the line and can start
14       anywhere in a line.
15
16       The keyword 'include' allows inclusion  of  other  configuration  files
17       from  within the main configuration file, or from subsequently included
18       files.
19
20       The format of the include directive is:
21
22       include FILENAME
23
24       FILENAME can be a fully qualified or relative pathname, and can include
25       wildcards,    including   csh   style   brace   expressions   such   as
26       "{foo/{,cat,dog},bar}" if glob() supports them.
27
28       After opening an included file, the current directory  is  set  to  the
29       directory  of  the  file  itself, so any relative paths included from a
30       file are relative to the directory of the including file itself.
31
32       Note: This documentation MUST be considered as THE exhaustive source of
33       information in order to configure Keepalived. This documenation is sup‐
34       ported and maintained by Keepalived Core-Team.
35

PARAMETER SYNTAX

37       <BOOL> is one of on|off|true|false|yes|no
38

SCRIPTS

40       There are three classes of scripts can be configured to be executed.
41
42       (a) Notify scripts that are run when a  vrrp  instance  or  vrrp  group
43       changes state, or a virtual server quorum changes between up and down.
44
45       (b)  vrrp tracking scripts that will cause vrrp instances to go down it
46       they exit a non-zero exist status, or if a weight is specified will add
47       or subtract the weight to/from the priority of that vrrp instance.
48
49       (c)  LVS  checker misc scripts that will cause a real server to be con‐
50       figured down if they exit with a non-zero status.
51
52       By default the scripts will be executed by  user  keepalived_script  if
53       that user exists, or if not by root, but for each script the user/group
54       under which it is to be executed can be specified.
55
56       There are significant security implications  if  scripts  are  executed
57       with  root privileges, especially if the scripts themselves are modifi‐
58       able or replaceable by a non root user. Consequently,  security  checks
59       are  made  at  startup  to ensure that if a script is executed by root,
60       then it cannot be modified or replaced by a non root user.
61
62       All scripts should be written so that they will terminate on receipt of
63       a  SIGTERM  signal. Scripts will be sent SIGTERM if their parent termi‐
64       nates, or it is a script the keepalived is awaiting its exit status and
65       it has run for too long.
66

Quoted strings

68       Quoted  strings are specified between " characters; more specifically a
69       string will only end after a  quoted  string  if  there  is  whitespace
70       afterwards. For example:
71              "abcd" efg h jkl "mnop"
72       will  be  the  single string "abcd efg h jkl mnop", i.e. the embedded "
73       characters are removed.
74
75       Quoted strings can also have escaped characters, like  the  shell.  \a,
76       \b,  \E,  \f, \n, \r, \t, \v, \nnn and \xXX (where nnn is up to 3 octal
77       digits, and XX is any sequence of hex digits) and \cC  (which  produces
78       the control version of character C) are all supported. \C for any other
79       character C is just treated as an escaped version of character C, so \\
80       is  a  \  character and \" will be a " character, but it won't start or
81       terminate a quoted string.
82
83       For specifying scripts with parameters, unquoted spaces  will  separate
84       the  parameters.  If it is required for a parameter to contain a space,
85       it should be enclosed in single quotes (').
86
87

CONFIGURATION PARSER

89       Traditionally the configuration file parser has not  been  one  of  the
90       strengths  of  keepalived. Lot of efforts have been put to correct this
91       even if this is not the primal goal of the project.
92

TOP HIERACHY

94       Keepalived configuration file is articulated around a set of configura‐
95       tion  blocks.   Each block is focusing and targetting a specific daemon
96       family feature. These features are:
97
98       GLOBAL CONFIGURATION
99
100       BFD CONFIGURATION
101
102       VRRPD CONFIGURATION
103
104       LVS CONFIGURATION
105

GLOBAL CONFIGURATION

107       contains subblocks of Global definitions, Static track  groups,  Static
108       addresses, Static routes, and Static rules
109

Global definitions

111       # Following are global daemon facilities for running
112       # keepalived in a separate network namespace:
113       # --
114       # Set the network namespace to run in.
115       # The directory /var/run/keepalived will be created as an
116       # unshared mount point, for example for pid files.
117       # syslog entries will have _NAME appended to the ident.
118       # Note: the namespace cannot be changed on a configuration reload.
119       net_namespace NAME
120
121       # ipsets wasn't network namespace aware until Linux 3.13, and so
122       # if running with # an earlier version of the kernel, by default
123       # use of ipsets is disabled if using a namespace and vrrp_ipsets
124       # has not been specified. This options overrides the default and
125       # allows ipsets to be used with a namespace on kernels prior to 3.13.
126       namespace_with_ipsets
127
128       # If multiple instances of keepalived are run in the same namespace,
129       # this will create pid files with NAME as part of the file names,
130       # in /var/run/keepalived.
131       # Note: the instance name cannot be changed on a configuration reload
132       instance NAME
133
134       # Create pid files in /var/run/keepalived
135       use_pid_dir
136
137       # Poll to detect media link failure otherwise attempt to use
138       # ETHTOOL or MII interface
139       linkbeat_use_polling
140
141       # Time for main process to allow for child processes to exit on termination
142       # in seconds. This can be needed for very large configurations.
143       # (default: 5)
144       child_wait_time SECS
145
146       # Global definitions configuration block
147       global_defs {
148           # Set of email To: notify
149           notification_email {
150               admin@example1.com
151               ...
152           }
153
154           # email from address that will be in the header
155           # (default: keepalived@<local host name>)
156           notification_email_from admin@example.com
157
158           # Remote SMTP server used to send notification email.
159           # IP address or domain name with optional port number.
160           # (default port number: 25)
161           smtp_server 127.0.0.1 [<PORT>]
162
163           # Name to use in HELO messages.
164           # (default: local host name)
165           smtp_helo_name <STRING>
166
167           # SMTP server connection timeout in seconds.
168           smtp_connect_timeout 30
169
170           # Sets default state for all smtp_alerts
171           smtp_alert <BOOL>
172
173           # Sets default state for vrrp smtp_alerts
174           smtp_alert_vrrp <BOOL>
175
176           # Sets default state for checker smtp_alerts
177           smtp_alert_checker <BOOL>
178
179           # Don't send smtp alerts for fault conditions
180           no_email_faults
181
182           # String identifying the machine (doesn't have to be hostname).
183           # (default: local host name)
184           router_id <STRING>
185
186           # Multicast Group to use for IPv4 VRRP adverts
187           # (default: 224.0.0.18)
188           vrrp_mcast_group4 224.0.0.18
189
190           # Multicast Group to use for IPv6 VRRP adverts
191           # (default: ff02::12)
192           vrrp_mcast_group6 ff02::12
193
194           # sets the default interface for static addresses.
195           # (default: eth0)
196           default_interface p33p1.3
197
198           # Sync daemon as provided by IPVS kernel code only support
199           # a single daemon instance at a time to synchronize connection table.
200           # Binding interface, vrrp instance and optional
201           #  syncid for lvs syncd
202           #  syncid (0 to 255) for lvs syncd
203           #  maxlen (1..65507) maximum packet length
204           #  port (1..65535) UDP port number to use
205           #  ttl (1..255)
206           #  group - multicast group address (IPv4 or IPv6)
207           # NOTE: maxlen, port, ttl and group are only available on Linux 4.3 or later.
208           lvs_sync_daemon <INTERFACE> <VRRP_INSTANCE> [id <SYNC_ID>] [maxlen <LEN>] \
209                           [port <PORT>] [ttl <TTL>] [group <IP ADDR>]
210
211           # flush any existing LVS configuration at startup
212           lvs_flush
213
214           # delay for second set of gratuitous ARPs after transition to MASTER.
215           # in seconds, 0 for no second set.
216           # (default: 5)
217           vrrp_garp_master_delay 10
218
219           # number of gratuitous ARP messages to send at a time after
220           # transition to MASTER.
221           # (default: 5)
222           vrrp_garp_master_repeat 1
223
224           # delay for second set of gratuitous ARPs after lower priority
225           # advert received when MASTER.
226           vrrp_garp_lower_prio_delay 10
227
228           # number of gratuitous ARP messages to send at a time after
229           # lower priority advert received when MASTER.
230           vrrp_garp_lower_prio_repeat 1
231
232           # minimum time interval for refreshing gratuitous ARPs while MASTER.
233           # in seconds.
234           # (default: 0 (no refreshing))
235           vrrp_garp_master_refresh 60
236
237           # number of gratuitous ARP messages to send at a time while MASTER
238           # (default: 1)
239           vrrp_garp_master_refresh_repeat 2
240
241           # Delay in ms between gratuitous ARP messages sent on an interface
242           # decimal, seconds (resolution usecs).
243           # (default: 0)
244           vrrp_garp_interval 0.001
245
246           # Delay in ms between unsolicited NA messages sent on an interface
247           # decimal, seconds (resolution usecs).
248           # (default: 0)
249           vrrp_gna_interval 0.000001
250
251           # If a lower priority advert is received, don't send another advert.
252           # This causes adherence to the RFCs. Defaults to false, unless
253           # strict_mode is set.
254           vrrp_lower_prio_no_advert [<BOOL>]
255
256           # If we are master and receive a higher priority advert, send an advert
257           # (which will be lower priority than the other master), before we
258           # transition to backup. This means that if the other master has
259           # garp_lower_priority_repeat set, it will resend garp messages.
260           # This is to get around the problem of their having been two simultaneous
261           # masters, and the last GARP messages seen were from us.
262           vrrp_higher_prio_send_advert [<BOOL>]
263
264           # Set the default VRRP version to use
265           # (default: 2)
266           vrrp_version <2 or 3>
267
268           # Specify the iptables chain for ensuring a version 3 instance
269           # doesn't respond on addresses that it doesn't own.
270           # Note: it is necessary for the specified chain to exist in
271           # the iptables and/or ip6tables configuration, and for the chain
272           # to be called from an appropriate point in the iptables configuration.
273           # It will probably be necessary to have this filtering after accepting
274           # any ESTABLISHED,RELATED packets, because IPv4 might select the VIP as
275           # the source address for outgoing connections.
276           # (default: INPUT)
277           vrrp_iptables keepalived
278
279           # or for outbound filtering as well
280           # Note, outbound filtering won't work with IPv4, since the VIP can be
281           # selected as the source address for an outgoing connection. With IPv6
282           # this is unlikely since the addresses are deprecated.
283           vrrp_iptables keepalived_in keepalived_out
284
285           # or to not add any iptables rules:
286           vrrp_iptables
287
288           # Keepalived may have the option to use ipsets in conjunction with
289           # iptables. If so, then the ipset names can be specified, defaults
290           # as below. If no names are specified, ipsets will not be used,
291           # otherwise any omitted names will be constructed by adding "_if"
292           # and/or "6" to previously specified names.
293           vrrp_ipsets [keepalived [keepalived6 [keepalived_if6]]]
294
295           # The following enables checking that when in unicast mode, the
296           # source address of a VRRP packet is one of our unicast peers.
297           vrrp_check_unicast_src
298
299           # Checking all the addresses in a received VRRP advert can be time
300           # consuming. Setting this flag means the check won't be carried out
301           # if the advert is from the same master router as the previous advert
302           # received.
303           # (default: don't skip)
304           vrrp_skip_check_adv_addr
305
306           # Enforce strict VRRP protocol compliance. This will prohibit:
307           #   0 VIPs
308           #   unicast peers
309           #   IPv6 addresses in VRRP version 2
310           vrrp_strict
311
312           # The following options can be used if vrrp or checker processes
313           # are timing out. This can be seen by a backup vrrp instance becoming
314           # master even when the master is still running because the master or
315           # backup system is too busy to process vrrp packets.
316           # --
317           # Set the vrrp child process priority (Negative values increase priority)
318           vrrp_priority <-20 to 19>
319
320           # Set the checker child process priority
321           checker_priority <-20 to 19>
322
323           # Set the BFD child process priority
324           bfd_priority <-20 to 19>
325
326           # Set the vrrp child process non swappable
327           vrrp_no_swap
328
329           # Set the checker child process non swappable
330           checker_no_swap
331
332           # Set the BFD child process non swappable
333           bfd_no_swap
334
335           # Set the vrrp child process to use real-time scheduling
336           # at the specified priority
337           vrrp_rt_priority <1..99>
338
339           # Set the checker child process to use real-time scheduling
340           # at the specified priority
341           checker_rt_priority <1..99>
342
343           # Set the BFD child process to use real-time scheduling
344           # at the specified  priority
345           bfd_rt_priority <1..99>
346
347           # Set the limit on CPU time between blocking system calls,
348           # in microseconds
349           # (default: 1000)
350           vrrp_rlimit_rtime >=1
351           checker_rlimit_rtime >=1
352           bfd_rlimit_rtime >=1
353
354           # If Keepalived has been build with SNMP support, the following
355           # keywords are available.
356           # Note: Keepalived, checker and RFC support can be individually
357           # enabled/disabled
358           # --
359           # Specify socket to use for connecting to SNMP master agent
360           # (see source module keepalived/vrrp/vrrp_snmp.c for more details)
361           # (default: unix:/var/agentx/master)
362           snmp_socket udp:1.2.3.4:705
363
364           # enable SNMP handling of vrrp element of KEEPALIVED MIB
365           enable_snmp_vrrp
366
367           # enable SNMP handling of checker element of KEEPALIVED MIB
368           enable_snmp_checker
369
370           # enable SNMP handling of RFC2787 and RFC6527 VRRP MIBs
371           enable_snmp_rfc
372
373           # enable SNMP handling of RFC2787 VRRP MIB
374           enable_snmp_rfcv2
375
376           # enable SNMP handling of RFC6527 VRRP MIB
377           enable_snmp_rfcv3
378
379           # enable SNMP traps
380           enable_traps
381
382           # If Keepalived has been build with DBus support, the following
383           # keywords are available.
384           # --
385           # Enable the DBus interface
386           enable_dbus
387
388           # Name of DBus service
389           # Useful if you want to run multiple keepalived processes with DBus enabled
390           # (default: org.keepalived.Vrrp1)
391           dbus_service_name SERVICE_NAME
392
393           # Specify the default username/groupname to run scripts under.
394           # If this option is not specified, the user defaults to keepalived_script
395           # if that user exists, otherwise root.
396           # If groupname is not specified, it defaults to the user's group.
397           script_user username [groupname]
398
399           # Don't run scripts configured to be run as root if any part of the path
400           # is writable by a non-root user.
401           enable_script_security
402
403           # Rather than using notify scripts, specifying a fifo allows more
404           # efficient processing of notify events, and guarantees that they
405           # will be delivered in the correct sequence.
406           # NOTE: the FIFO names must all be different
407           # --
408           # FIFO to write notify events to
409           # See vrrp_notify_fifo and lvs_notify_fifo for format of output
410           # For further details, see the description under vrrp_sync_group see
411           # doc/samples/sample_notify_fifo.sh for sample usage.
412           notify_fifo FIFO_NAME
413
414           # script to be run by keepalived to process notify events
415           # The FIFO name will be passed to the script as the last parameter
416           notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
417
418           # FIFO to write vrrp notify events to.
419           # The string written will be a line of the form: INSTANCE "VI_1" MASTER 100
420           # and will be terminated with a new line character.
421           # For further details of the output, see the description under vrrp_sync_group
422           # and doc/samples/sample_notify_fifo.sh for sample usage.
423           vrrp_notify_fifo FIFO_NAME
424
425           # script to be run by keepalived to process vrrp notify events
426           # The FIFO name will be passed to the script as the last parameter
427           vrrp_notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
428
429           # FIFO to write notify healthchecker events to
430           # The string written will be a line of the form:
431           # VS [192.168.201.15]:tcp:80 {UP|DOWN}
432           # RS [1.2.3.4]:tcp:80 [192.168.201.15]:tcp:80 {UP|DOWN}
433           # and will be terminated with a new line character.
434           lvs_notify_fifo FIFO_NAME
435
436           # script to be run by keepalived to process healthchecher notify events
437           # The FIFO name will be passed to the script as the last parameter
438           lvs_notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
439
440           # Allow configuration to include interfaces that don't exist at startup.
441           # This allows keepalived to work with interfaces that may be deleted and restored
442           #   and also allows virtual and static routes and rules on VMAC interfaces.
443           #   allow_if_changes allows an interface to be deleted and recreated with a
444           #   different type or underlying interface, eg changing from vlan to macvlan
445           #   or changing a macvlan from eth1 to eth2. This is predominantly used for
446           #   reporting duplicate VRID errors at startup if allow_if_changes is not set.
447           dynamic_interfaces [allow_if_changes]
448
449           # The following options are only needed for large configurations, where either
450           # keepalived creates a large number of interface, or the system has a large
451           # number of interface. These options only need using if
452           # "Netlink: Receive buffer overrun" messages are seen in the system logs.
453           # If the buffer size needed exceeds the value in /proc/sys/net/core/rmem_max
454           #  the corresponding force option will need to be set.
455           # --
456           # Set netlink receive buffer size. This is useful for
457           # very large configurations where a large number of interfaces exist, and
458           # the initial read of the interfaces on the system causes a netlink buffer
459           # overrun.
460           vrrp_netlink_cmd_rcv_bufs BYTES
461           vrrp_netlink_cmd_rcv_bufs_force <BOOL>
462           vrrp_netlink_monitor_rcv_bufs BYTES
463           vrrp_netlink_monitor_rcv_bufs_force <BOOL>
464
465           # The vrrp netlink command and monitor socket and the checker command
466           # and monitor socket buffer sizes can be independently set.
467           # The force flag means to use SO_RCVBUFFORCE, so that the buffer size
468           # can exceed /proc/sys/net/core/rmem_max.
469           lvs_netlink_cmd_rcv_bufs BYTES
470           lvs_netlink_cmd_rcv_bufs_force <BOOL>
471           lvs_netlink_monitor_rcv_bufs BYTES
472           lvs_netlink_monitor_rcv_bufs_force <BOOL>
473
474           # When a socket is opened, the kernel configures the max rx buffer size for
475           # the socket to /proc/sys/net/core/rmem_default. On some systems this can be
476           # very large, and even generally this can be much larger than necessary.
477           # This isn't a problem so long as keepalived is reading all queued data from
478           # it's sockets, but if rmem_default was set sufficiently large, and if for
479           # some reason keepalived stopped reading, it could consume all system memory.
480           # The vrrp_rx_bufs_policy allows configuring of the rx bufs size when the
481           # sockets are opened. If the policy is MTU, the rx buf size is configured
482           # to the total of interface's MTU * vrrp_rx_bufs_multiplier for each vrrp
483           # instance using the socket. Likewise, if the policy is ADVERT, then it is
484           # the total of each vrrp instances advert packet size * multiplier.
485           # (default: use system default)
486           vrrp_rx_bufs_policy [MTU|ADVERT|NUMBER]
487
488           # (default: 3)
489           vrrp_rx_bufs_multiplier NUMBER
490
491           # Send notifies at startup for real servers that are starting up
492           rs_init_notifies
493
494           # Don't send an email every time a real server checker changes state;
495           # only send email when a real server is added or removed
496           no_checker_emails
497
498           # The umask to use for creating files. The number can be specified in hex, octal
499           #   or decimal. BITS are I{R|W|X}{USR|GRP|OTH}, e.g. IRGRP, separated by '|'s.
500           #   The default umask is IWGRP | IWOTH. This option cannot override the
501           #   command-line option.
502           umask [NUMBER|BITS]
503       }
504

Static track groups

506       Static  track  groups  are used to allow vrrp instances to track static
507       addresses, routes and rules. If a static address/route/rule specifies a
508       track  group,  then  if the address/route/rule is deleted and cannot be
509       restored, the vrrp instance will transition to fault state.
510
511       The syntax for a track group is:
512           track_group GROUP1 {
513               group {
514                   VI_1
515                   VI_2
516               }
517           }
518

Static routes/addresses/rules

520       Keepalived can configure static addresses,  routes,  and  rules.  These
521       addresses  are  NOT  moved  by vrrpd, they stay on the machine.  If you
522       already have IPs and routes on your machines and your machines can ping
523       each  other,  you  don't  need  this section.  The syntax for rules and
524       routes is that same as for ip rule add/ip  route  add  (except  shorted
525       option  names  aren't  supported  due to ambiguities).  The track_group
526       specification refers to  a  named  track_group  which  lists  the  vrrp
527       instances  which will track the address, i.e. if the address is deleted
528       the vrrp instances will transition to backup.
529
530       NOTE: since rules without preferences can be added in different  orders
531       due  to  vrrp  instances transitioning from master to backup etc, rules
532       need to have a preference. If a preference is not specified, keepalived
533       will assign one, but it will probably not be what you want.
534
535       The  syntax is the same for virtual addresses and virtual routes. If no
536       dev element is specified, it  defaults  to  default_interface  (default
537       eth0).   Note:  the broadcast address may be specified as '-' or '+' to
538       clear or set the host bits of the address.
539
540       If a route or rule could apply to either IPv4 or IPv6 it  will  default
541       to IPv4.  To force a route/rule to be IPv6, add the keyword "inet6".
542
543           static_ipaddress {
544               <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
545                                 [label <LABEL>] [peer <IPADDR>] [home]
546                                 [-nodad] [mngtmpaddr] [noprefixroute]
547                                 [autojoin] [track_group GROUP]
548               192.168.1.1/24 dev eth0 scope global
549               ...
550           }
551
552           static_routes {
553               192.168.2.0/24 via 192.168.1.100 dev eth0 track_group GROUP1
554
555               192.168.100.0/24 table 6909 nexthop via 192.168.101.1 dev wlan0
556                                onlink weight 1 nexthop via 192.168.101.2
557                                dev wlan0 onlink weight 2
558
559               192.168.200.0/24 dev p33p1.2 table 6909 tos 0x04 protocol bird
560                                scope link priority 12 mtu 1000 hoplimit 100
561                                advmss 101 rtt 102 rttvar 103 reordering 104
562                                window 105 cwnd 106 ssthresh lock 107 realms
563                                PQA/0x14 rto_min 108 initcwnd 109 initrwnd 110
564                                features ecn
565
566               2001:470:69e9:1:2::4 dev p33p1.2 table 6909 tos 0x04 protocol
567                                    bird scope link priority 12 mtu 1000
568                                    hoplimit 100 advmss 101 rtt 102 rttvar 103
569                                    reordering 104 window 105 cwnd 106 ssthresh
570                                    lock 107 rto_min 108 initcwnd 109
571                                    initrwnd 110 features ecn fastopen_no_cookie 1
572               ...
573           }
574
575           static_rules {
576               from 192.168.2.0/24 table 1 track_group GROUP1
577
578               to 192.168.2.0/24 table 1
579
580               from 192.168.28.0/24 to 192.168.29.0/26 table small iif p33p1
581                                    oif wlan0 tos 22 fwmark 24/12
582                                    preference 39 realms 30/20 goto 40
583
584               to 1:2:3:4:5:6:7:0/112 from 7:6:5:4:3:2::/96 table 6908
585                                      uidrange 10000-19999
586
587               to 1:2:3:4:6:6:7:0/112 from 8:6:5:4:3:2::/96 l3mdev protocol 12
588                                      ip_proto UDP sport 10-20 dport 20-30
589               ...
590           }
591

BFD CONFIGURATION

593       This  is  an implementation of RFC5880 (Bidirectional forwarding detec‐
594       tion), and  this  can  be  configured  to  work  between  2  keepalived
595       instances, but using unweighted track_bfds between a master/backup pair
596       of VRRP instances means that the VRRP instance will  only  be  able  to
597       come  up  if both VRRP instance are running, which somewhat defeats the
598       purpose of VRRP.
599
600       This  imlpementation  has  been  tested  with  OpenBFDD  (available  at
601       https://github.com/dyninc/OpenBFDD).
602
603       The syntax for bfd instance is :
604
605       bfd_instance <STRING> {
606           # BFD Neighbor IP (synonym neighbour_ip)
607           neighbor_ip <IP ADDRESS>
608
609           # Source IP to use (optional)
610           source_ip <IP ADDRESS>
611
612           # Required min RX interval, in ms
613           # (default is 10 ms)
614           mix_rx <INTEGER>
615
616           # Desired min TX interval, in ms
617           # (default is 10 ms)
618           min_tx <INTEGER>
619
620           # Desired idle TX interval, in ms
621           # (default is 1000 ms)
622           idle_tx <INTEGER>
623
624           # Number of missed packets after
625           # which the session is declared down
626           # (default is 5)
627           multiplier <INTEGER>
628
629           # Operate in passive mode (default is active)
630           passive
631
632           # outgoing IPv4 ttl to use (default 255)
633           ttl <INTEGER>
634
635           # outgoing IPv6 hoplimit to use (default 64)
636           hoplimit <INTEGER>
637
638           # maximum reduction of ttl/hoplimit
639           #  in received packet (default 0)
640           #  (255 disables hop count checking)
641           max_hops <INTEGER>
642
643           # Default tracking weight
644           weight
645       }
646

VRRPD CONFIGURATION

648       contains  subblocks  of  VRRP script(s), VRRP synchronization group(s),
649       VRRP gratuitous ARP and unsolicited neighbour advert delay group(s) and
650       VRRP instance(s)
651

VRRP script(s)

653       The script will be executed periodically, every <interval> seconds. Its
654       exit code will be recorded for all VRRP  instances  which  monitor  it.
655       Note  that  the  script  will  only  be  executed  if at least one VRRP
656       instance monitors it.
657
658       The default weight equals 0, which means that any VRRP  instance  moni‐
659       toring  the script will transition to the fault state after <fall> con‐
660       secutive failures of the script. After that,  <rise>  consecutive  suc‐
661       cesses  will cause VRRP instances to leave the fault state, unless they
662       are also in the fault state due to other  scripts  or  interfaces  that
663       they are tracking.
664
665       A  positive weight means that <rise> successes will add <weight> to the
666       priority of all VRRP instances which monitor it.  On  the  opposite,  a
667       negative weight will be subtracted from the initial priority in case of
668       <fall> failures.
669
670       The syntax for the vrrp script is:
671
672       # Adds a script to be executed periodically. Its exit code will be
673       # recorded for all VRRP instances and sync groups which are monitoring it.
674       vrrp_script <SCRIPT_NAME> {
675           # path of the script to execute
676           script <STRING>|<QUOTED-STRING>
677
678           # seconds between script invocations, (default: 1 second)
679           interval <INTEGER>
680
681           # seconds after which script is considered to have failed
682           timeout <INTEGER>
683
684           # adjust priority by this weight, (default: 0)
685           weight <INTEGER:-253..253>
686
687           # required number of successes for OK transition
688           rise <INTEGER>
689
690           # required number of successes for KO transition
691           fall <INTEGER>
692
693           # user/group names to run script under.
694           #  group default to group of user
695           user USERNAME [GROUPNAME]
696
697           # assume script initially is in failed state
698           init_fail
699       }
700

VRRP track files

702       Adds a file to be monitored. The script will be  read  whenever  it  is
703       modified. The value in the file will be recorded for all VRRP instances
704       and sync groups which monitor it.  Note that the file will only be read
705       if at least one VRRP instance or sync group monitors it.
706
707       A  value will be read as a number in text from the file.  If the weight
708       configured against the track_file is 0, a non-zero value  in  the  file
709       will  be  treated as a failure status, and a zero value will be treaded
710       as an OK status, otherwise the value will be  multiplied by the  weight
711       configured in the track_file statement. If the result is less than -253
712       any VRRP instance or sync group monitoring the script  will  transition
713       to the fault state (the weight can be 254 to allow for a negative value
714       being read from the file).
715
716       If the vrrp instance or sync group is not the  address  owner  and  the
717       result is between -253 and 253, the result will be added to the initial
718       priority of the VRRP instance (a negative value will reduce the  prior‐
719       ity),  although  the  effective  priority  will be limited to the range
720       [1,254].
721
722       If a vrrp instance using a track_file is a  member  of  a  sync  group,
723       unless  sync_group_tracking_weight is set on the group weight 0 must be
724       set.  Likewise, if the vrrp instance is the  address  owner,  weight  0
725       must also be set.
726
727       The syntax for vrrp track file is :
728
729       vrrp_track_file <STRING> {    # VRRP track file declaration
730           # file to track (weight defaults to 1)
731           file <QUOTED_STRING>
732
733           # optional default weight
734           weight <-254..254>
735
736           # create the file and/or initialise the value
737           # This causes VALUE (default 0) to be written to
738           # the specified file at startup if the file doesn't
739           # exist, unless overwrite is specified in which case
740           # any existing file contents will be overwritten with
741           # the specified value.
742           init_file [VALUE] [overwrite]
743       }
744

VRRP synchronization group(s)

746       VRRP  Sync  Group is an extension to VRRP protocol. The main goal is to
747       define a bundle of VRRP instance to get synchronized together  so  that
748       transition of one instance will be reflected to others group members.
749
750       In  addition there is an enhanced notify feature for fine state transi‐
751       tion catching.
752
753       You can also define multiple track policy in order to force state tran‐
754       sition  according  to  a  third party event such as interface, scripts,
755       file, BFD.
756
757       Important: for a SYNC group to run  reliably,  it  is  vital  that  all
758       instances in the group are MASTER or that they are all either BACKUP or
759       FAULT. A situation  with  half  instances  having  higher  priority  on
760       machine  A  half  others with higher priority on machine B will lead to
761       constant re-elections. For this reason, when instances are grouped, any
762       track  scripts/files configured against member VRRP instances will have
763       their tracking weights automatically set to zero,  in  order  to  avoid
764       inconsistent priorities across instances.
765
766       The syntax for vrrp_sync_group is :
767
768       vrrp_sync_group <STRING> {
769           group {
770               # name of the vrrp_instance (see below)
771               # Set of VRRP_Instance string
772               <STRING>
773               <STRING>
774               ...
775           }
776
777           # Synchronization group tracking interface, script, file & bfd will
778           # update the status/priority of all VRRP instances which are members
779           # of the sync group.
780           track_interface {
781               eth0
782               eth1
783               eth2 weight <-253..253>
784               ...
785           }
786
787           # add a tracking script to the sync group (<SCRIPT_NAME> is the name
788           # of the vrrp_script entry) go to FAULT state if any of these go down
789           # if unweighted.
790           track_script {
791               <SCRIPT_NAME>
792               <SCRIPT_NAME> weight <-253..253>
793           }
794
795           # Files whose state we monitor, value is added to effective priority.
796           # <STRING> is the name of a vrrp_status_file
797           # weight defaults to weight configured in vrrp_track_file
798           track_file {
799               <STRING>
800               <STRING> weight <-254..254>
801               ...
802           }
803
804           # BFD instances we monitor, value is added to effective priority.
805           # <STRING> is the name of a BFD instance
806           track_bfd {
807               <STRING>
808               <STRING>
809               <STRING> weight <INTEGER: -253..253>
810               ...
811           }
812
813           # notify scripts and alerts are optional
814           #
815           # filenames of scripts to run on transitions can be unquoted (if
816           # just filename) or quoted (if it has parameters)
817           # The username and groupname specify the user and group
818           # under which the scripts should be run. If username is
819           # specified, the group defaults to the group of the user.
820           # If username is not specified, they default to the
821           # global script_user and script_group to MASTER transition
822           notify_master /path/to_master.sh [username [groupname]]
823
824           # to BACKUP transition
825           notify_backup /path/to_backup.sh [username [groupname]]
826
827           # FAULT transition
828           notify_fault "/path/fault.sh VG_1" [username [groupname]]
829
830           # executed when stopping vrrp
831           notify_stop <STRING>|<QUOTED-STRING> [username [groupname]]
832
833           # for ANY state transition.
834           # "notify" script is called AFTER the notify_* script(s) and
835           # is executed with 4 additional arguments after the configured
836           # arguments provided by Keepalived:
837           #   $(n-3) = "GROUP"|"INSTANCE"
838           #   $(n-2) = name of the group or instance
839           #   $(n-1) = target state of transition (stop only applies to instances)
840           #            ("MASTER"|"BACKUP"|"FAULT"|"STOP")
841           #   $(n)   = priority value
842           #   $(n-3) and $(n-1) are ALWAYS sent in uppercase, and the possible
843           #
844           # strings sent are the same ones listed above
845           #   ("GROUP"/"INSTANCE", "MASTER"/"BACKUP"/"FAULT"/"STOP")
846           # (note: STOP is only applicable to instances)
847           notify <STRING>|<QUOTED-STRING> [username [groupname]]
848
849           # The notify fifo output is the same as the last 4 parameters for the "notify"
850           # script, with the addition of "MASTER_RX_LOWER_PRI" instead of state for an
851           # instance. This is used if a master needs to set some external state, such as
852           # setting a secondary IP address when using Amazon AWS; if another keepalived
853           # has transitioned to master due to a communications break, the lower priority
854           # instance will have taken over the secondary IP address, and the proper master
855           # needs to be able to restore it.
856
857           # Send email notification during state transition,
858           # using addresses in global_defs above (default no,
859           # unless global smtp_alert/smtp_alert_vrrp set)
860           smtp_alert <BOOL>
861
862           # DEPRECATED. Use track_interface, track_script and
863           # track_file on vrrp_sync_groups instead.
864           global_tracking
865
866           # allow sync groups to use differing weights.
867           # This probably WON'T WORK, but is a replacement for
868           # global_tracking in case different weights were used
869           # across different vrrp instances in the same sync group.
870           sync_group_tracking_weight
871       }
872

VRRP gratuitous ARP and unsolicited neighbour advert delay group(s)

874       specifies  the  setting  of  delays between sending gratuitous ARPs and
875       unsolicited neighbour advertisements. This  is  intended  for  when  an
876       upstream switch is unable to handle being flooded with ARPs/NAs.
877
878       Use  interface  when the limits apply on the single physical interface.
879       Use interfaces when a group of interfaces are linked to the same switch
880       and the limits apply to the switch as a whole.
881
882       Note: Only one of interface or interfaces should be used per block.
883
884       If  the global vrrp_garp_interval and/or vrrp_gna_interval are set, any
885       interfaces that aren't specified  in  a  garp_group  will  inherit  the
886       global settings.
887
888       The syntax for garp_group is :
889
890       garp_group {
891           # Sets the interval between Gratuitous ARP (in seconds, resolution microseconds)
892           garp_interval <DECIMAL>
893
894           # Sets the default interval between unsolicited NA (in seconds, resolution microseconds)
895           gna_interval <DECIMAL>
896
897           # The physical interface to which the intervals apply
898           interface <STRING>
899
900           # A list of interfaces accross which the delays are aggregated.
901           interfaces {
902               <STRING>
903               <STRING>
904               ...
905           }
906       }
907

VRRP instance(s)

909       A  VRRP  Instance is the VRRP protocol key feature. It defines and con‐
910       figures VRRP behaviour to  run  on  a  specific  interface.  Each  VRRP
911       Instances are related to a uniq interface.
912
913       The syntax for garp_group is :
914
915       vrrp_instance <STRING> {
916           # Initial state, MASTER|BACKUP
917           # As soon as the other machine(s) come up,
918           # an election will be held and the machine
919           # with the highest priority will become MASTER.
920           # So the entry here doesn't matter a whole lot.
921           state MASTER
922
923           # interface for inside_network, bound by vrrp
924           interface eth0
925
926           # Use VRRP Virtual MAC.
927           # NOTE: If sysctl net.ipv4.conf.all.rp_filter is set,
928           # and this vrrp_instance is an IPv4 instance, using
929           # this option will cause the individual interfaces to be
930           # updated to the greater of their current setting, and
931           # all.rp_filter, as will default.rp_filter, and all.rp_filter
932           # will be set to 0.
933           # The original settings are restored on termination.
934           use_vmac [<VMAC_INTERFACE>]
935
936           # Send/Recv VRRP messages from base interface instead of
937           # VMAC interface
938           vmac_xmit_base
939
940           # force instance to use IPv6 (this option is deprecated since
941           # the virtual ip addresses determine whether IPv4 or IPv6 is used).
942           native_ipv6
943
944           # Ignore VRRP interface faults (default unset)
945           dont_track_primary
946
947           # optional, monitor these as well.
948           # go to FAULT state if any of these go down if unweighted.
949           # When a weight is specified in track_interface, instead of setting the vrrp
950           # instance to the FAULT state in case of failure, its priority will be
951           # increased by the weight when the interface is up (for positive weights),
952           # or decreased by the weight's absolute value when the interface is down
953           # (for negative weights). The weight must be comprised between -254 and +254
954           # inclusive. 0 is the default behaviour which means that a failure implies a
955           # FAULT state. The common practice is to use positive weights to count a
956           # limited number of good services so that the server with the highest count
957           # becomes master. Negative weights are better to count unexpected failures
958           # among a high number of interfaces, as it will not saturate even with high
959           # number of interfaces.
960           track_interface {
961               eth0
962               eth1
963               eth2 weight <-253..253>
964                ...
965           }
966
967           # add a tracking script to the interface
968           # (<SCRIPT_NAME> is the name of the vrrp_track_script entry)
969           # The same principle as track_interface can be applied to track_script entries,
970           # except that an unspecified weight means that the default weight declared in
971           # the script will be used (which itself defaults to 0).
972           track_script {
973               <SCRIPT_NAME>
974               <SCRIPT_NAME> weight <-253..253>
975           }
976
977           # Files whose state we monitor, value is added to effective priority.
978           # <STRING> is the name of a vrrp_track_file
979           track_file {
980               <STRING>
981               <STRING>
982               <STRING> weight <-254..254>
983               ...
984           }
985
986           # BFD instances we monitor, value is added to effective priority.
987           # <STRING> is the name of a BFD instance
988           track_bfd {
989               <STRING>
990               <STRING>
991               <STRING> weight <INTEGER: -253..253>
992               ...
993           }
994
995           # default IP for binding vrrpd is the primary IP
996           # on interface. If you want to hide the location of vrrpd,
997           # use this IP as src_addr for multicast or unicast vrrp
998           # packets. (since it's multicast, vrrpd will get the reply
999           # packet no matter what src_addr is used).
1000           # optional
1001           mcast_src_ip <IPADDR>
1002           unicast_src_ip <IPADDR>
1003
1004           # if the configured src_ip doesn't exist or is removed put the
1005           # instance into fault state
1006           track_src_ip
1007
1008           # VRRP version to run on interface
1009           #  default is global parameter vrrp_version.
1010           version <2 or 3>
1011
1012           # Do not send VRRP adverts over a VRRP multicast group.
1013           # Instead it sends adverts to the following list of
1014           # ip addresses using unicast. It can be cool to use
1015           # the VRRP FSM and features in a networking
1016           # environment where multicast is not supported!
1017           # IP addresses specified can be IPv4 as well as IPv6.
1018           unicast_peer {
1019               <IPADDR>
1020               ...
1021           }
1022
1023           # The checksum calculation when using VRRPv3 changed after v1.3.6.
1024           #  Setting this flag forces the old checksum algorithm to be used
1025           #  to maintain backward compatibility, although keepalived will
1026           #  attempt to maintain compatibility anyway if it sees an old
1027           #  version checksum. Sepcifying never will turn off auto detection
1028           #  of old checksums. [This option may not be enabled - check output
1029           #  of `keepalived -v` for OLD_CHKSUM_COMPAT.]
1030           old_unicast_checksum [never]
1031
1032           # interface specific settings, same as global parameters.
1033           # default to global parameters
1034           garp_master_delay 10
1035           garp_master_repeat 1
1036           garp_lower_prio_delay 10
1037           garp_lower_prio_repeat 1
1038           garp_master_refresh 60
1039           garp_master_refresh_repeat 2
1040           garp_interval 100
1041           gna_interval 100
1042
1043           # If a lower priority advert is received, don't send another advert.
1044           # This causes adherence to the RFCs (defaults to global
1045           # vrrp_lower_priority_dont_send_advert).
1046           lower_prio_no_advert [<BOOL>]
1047
1048           # If we are master and receive a higher priority advert, send an advert
1049           # (which will be lower priority than the other master), before we transition
1050           # to backup. This means that if the other master has garp_lower_prio_repeat
1051           # set, it will resend garp messages. This is to get around the problem of
1052           # their having been two simultaneous masters, and the last GARP
1053           # messages seen were from us.
1054           higher_prio_send_advert [<BOOL>]
1055
1056           # arbitrary unique number from 0 to 255
1057           # used to differentiate multiple instances of vrrpd
1058           # running on the same NIC (and hence same socket).
1059           virtual_router_id 51
1060
1061           # for electing MASTER, highest priority wins.
1062           # to be MASTER, make this 50 more than on other machines.
1063           priority 100
1064
1065           # VRRP Advert interval in seconds (e.g. 0.92) (use default)
1066           advert_int 1
1067
1068           # Note: authentication was removed from the VRRPv2 specification by
1069           # RFC3768 in 2004.
1070           #   Use of this option is non-compliant and can cause problems; avoid
1071           #   using if possible, except when using unicast, where it can be helpful.
1072           authentication {
1073               # PASS||AH
1074               # PASS - Simple password (suggested)
1075               # AH - IPSEC (not recommended))
1076               auth_type PASS
1077
1078               # Password for accessing vrrpd.
1079               # should be the same on all machines.
1080               # Only the first eight (8) characters are used.
1081               auth_pass 1234
1082           }
1083
1084           # addresses add|del on change to MASTER, to BACKUP.
1085           # With the same entries on other machines,
1086           # the opposite transition will be occurring.
1087           # For virutal_ipaddress, virtual_ipaddress_excluded,
1088           #   virtual_routes and virtual_rules most of the options
1089           #   match the options of the command ip address/route/rule add.
1090           #   The track_group option only applies to static addresses/routes/rules.
1091           #   no_track is specific to keepalived and means that the
1092           #   vrrp_instance will not transition out of master state
1093           #   if the address/route/rule is deleted and the address/route/rule
1094           #   will not be reinstated until the vrrp instance next transitions
1095           #   to master.
1096           # <LABEL>: is optional and creates a name for the alias.
1097                      For compatibility with "ifconfig", it should
1098                      be of the form <realdev>:<anytext>, for example
1099                      eth0:1 for an alias on eth0.
1100           # <SCOPE>: ("site"|"link"|"host"|"nowhere"|"global")
1101           virtual_ipaddress {
1102               <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
1103                                 [label <LABEL>] [peer <IPADDR>] [home]
1104                                 [-nodad] [mngtmpaddr] [noprefixroute]
1105                                 [autojoin] [no_track]
1106               192.168.200.17/24 dev eth1
1107               192.168.200.18/24 dev eth2 label eth2:1
1108           }
1109
1110           # VRRP IP excluded from VRRP optional.
1111           # For cases with large numbers (eg 200) of IPs
1112           # on the same interface. To decrease the number
1113           # of addresses sent in adverts, you can exclude
1114           # most IPs from adverts.
1115           # The IPs are add|del as for virtual_ipaddress.
1116           # Can also be used if you want to be able to add
1117           # a mixture of IPv4 and IPv6 addresses, since all
1118           # addresses in virtual_ipaddress must be of the
1119           # same family.
1120           virtual_ipaddress_excluded {
1121               <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
1122                                 [label <LABEL>] [peer <IPADDR>] [home]
1123                                 [-nodad] [mngtmpaddr] [noprefixroute]
1124                                 [autojoin] [no_track]
1125               <IPADDR>[/<MASK>] ...
1126               ...
1127           }
1128
1129           # Set the promote_secondaries flag on the interface to stop other
1130           # addresses in the same CIDR being removed when 1 of them is removed
1131           # For example if 10.1.1.2/24 and 10.1.1.3/24 are both configured on an
1132           # interface, and one is removed, unless promote_secondaries is set on
1133           # the interface the other address will also be removed.
1134           prompte_secondaries
1135
1136           # routes add|del when changing to MASTER, to BACKUP.
1137           # See static_routes for more details
1138           virtual_routes {
1139               # src <IPADDR> [to] <IPADDR>/<MASK> via|gw <IPADDR>
1140               #   [or <IPADDR>] dev <STRING> scope <SCOPE> table <TABLE>
1141               src 192.168.100.1 to 192.168.109.0/24 via 192.168.200.254 dev eth1
1142               192.168.110.0/24 via 192.168.200.254 dev eth1
1143               192.168.111.0/24 dev eth2 no_track
1144               192.168.112.0/24 via 192.168.100.254
1145               192.168.113.0/24 via 192.168.200.254 or 192.168.100.254 dev eth1
1146               blackhole 192.168.114.0/24
1147               0.0.0.0/0 gw 192.168.0.1 table 100  # To set a default gateway into table 100.
1148           }
1149
1150           # rules add|del when changing to MASTER, to BACKUP
1151           # See static_rules for more details
1152           virtual_rules {
1153               from 192.168.2.0/24 table 1
1154               to 192.168.2.0/24 table 1 no_track
1155           }
1156
1157           # VRRPv3 has an Accept Mode to allow the virtual router when not the
1158           # address owner to receive packets addressed to a VIP. This is the default
1159           # setting unless strict mode is set. As an extension, this also works for
1160           # VRRPv2 (RFC 3768 doesn't define an accept mode).
1161           # --
1162           # Accept packets to non address-owner
1163           accept
1164
1165           # Drop packets to non address-owner.
1166           no_accept
1167
1168           # VRRP will normally preempt a lower priority machine when a higher priority
1169           # machine comes online.  "nopreempt" allows the lower priority machine to
1170           # maintain the master role, even when a higher priority machine comes back
1171           # online.
1172           # NOTE: For this to work, the initial state of this
1173           # entry must be BACKUP.
1174           # --
1175           nopreempt
1176
1177           # for backwards compatibility
1178           preempt
1179
1180           # See description of global vrrp_skip_check_adv_addr, which
1181           # sets the default value. Defaults to vrrp_skip_check_adv_addr
1182           skip_check_adv_addr [on|off|true|false|yes|no]
1183
1184           # See description of global vrrp_strict
1185           # If vrrp_strict is not specified, it takes the value of vrrp_strict
1186           # If strict_mode without a parameter is specified, it defaults to on
1187           strict_mode [on|off|true|false|yes|no]
1188
1189           # Seconds after startup or seeing a lower priority master until preemption
1190           # (if not disabled by "nopreempt").
1191           # Range: 0 (default) to 1000 (e.g. 4.12)
1192           # NOTE: For this to work, the initial state of this
1193           # entry must be BACKUP.
1194           preempt_delay 300    # waits 5 minutes
1195
1196           # Debug level, not implemented yet.
1197           # LEVEL is a number in the range 0 to 4
1198           debug <LEVEL>
1199
1200           # notify scripts, alert as above
1201           notify_master <STRING>|<QUOTED-STRING> [username [groupname]]
1202           notify_backup <STRING>|<QUOTED-STRING> [username [groupname]]
1203           notify_fault <STRING>|<QUOTED-STRING> [username [groupname]]
1204           # executed when stopping vrrp
1205           notify_stop <STRING>|<QUOTED-STRING> [username [groupname]]
1206           notify <STRING>|<QUOTED-STRING> [username [groupname]]
1207
1208           # The notify_master_rx_lower_pri script is executed if a master
1209           #  receives an advert with priority lower than the master's advert.
1210           notify_master_rx_lower_pri <STRING>|<QUOTED-STRING> [username [groupname]]
1211
1212           # Send SMTP alerts
1213           smtp_alert <BOOL>
1214
1215           # Set socket receive buffer size (see global_defs
1216           # vrrp_rx_bufs_policy for explanation)
1217           kernel_rx_buf_size
1218       }
1219

LVS CONFIGURATION

1221       contains subblocks of Virtual server group(s) and Virtual server(s)
1222
1223       The  subblocks  contain arguments for configuring Linux IPVS (LVS) fea‐
1224       ture.  Knowledge of ipvsadm(8) will be helpful here. Configuring LVS is
1225       achieved  by  defining virtual server group, virtual server and option‐
1226       ally SSL configuration. Every virtual  server  define  a  set  of  real
1227       server,  you  can attach healthcheckers to each real server. Keepalived
1228       will then lead LVS operation by dynamically maintaining topology.
1229
1230       Note: Where an option can be configured  for  a  virtual  server,  real
1231       server, and possibly checker, the virtual server setting is the default
1232       for real servers, and the real server setting is the default for check‐
1233       ers.
1234
1235       Note:  Tunnelled  real/sorry servers can differ from the address family
1236       of the virtual server and non tunnelled real/sorry servers,  which  all
1237       have  to  be  the  same. If a virtual server uses a fwmark, and all the
1238       real/sorry servers are tunnelled, the address  family  of  the  virtual
1239       server will be the same as the address family of the real/sorry servers
1240       if they are all the same,  otherwise  it  will  default  to  IPv4  (use
1241       ip_family inet6 to override this).
1242

Virtual server group(s)

1244       This feature offers a way to simplify your configuration by factorizing
1245       virtual server definitions. If you need to define a  bunch  of  virtual
1246       server  with  exactly  the  same real server topology then this feature
1247       will make your configuration  much  more  readable  and  will  optimize
1248       healthchecking  task by only spawning one healthchecking where multiple
1249       virtual server declaration will spawn  a  dedicated  healthchecker  for
1250       every real server which will waste system ressources.
1251
1252       The syntax for virtual_server_group is :
1253
1254       # to belong to multiple virtual services
1255       # and to only be health checked once.
1256       # Only for very large LVSs.
1257       virtual_server_group <STRING> {
1258           # Virtual IP Address and Port
1259           <IPADDR> <PORT>
1260           <IPADDR> <PORT>
1261           ...
1262           # <IPADDR RANGE> has the form
1263           # XXX.YYY.ZZZ.WWW-VVV eg 192.168.200.1-10
1264           # range includes both .1 and .10 address
1265           <IPADDR RANGE> <PORT># VIP range VPORT
1266           <IPADDR RANGE> <PORT>
1267           ...
1268           # Firewall Mark (fwmark)
1269           fwmark <INTEGER>
1270           fwmark <INTEGER>
1271           ...
1272       }
1273

Virtual server(s)

1275       A  virtual_server  can  be  a  declaration  of one of <IPADDR> <PORT> ,
1276       fwmark <INTEGER> or group <STRING>
1277
1278       The syntax for virtual_server is :
1279
1280       virtual_server <IPADDR> <PORT>  |
1281       virtual_server fwmark <INTEGER> |
1282       virtual_server group <STRING> {
1283           # delay timer for checker polling
1284           delay_loop <INTEGER>
1285
1286           # LVS scheduler
1287           lvs_sched rr|wrr|lc|wlc|lblc|sh|mh|dh|fo|ovf|lblcr|sed|nq
1288
1289           # Enable hashed entry
1290           hashed
1291           # Enable flag-1 for scheduler (-b flag-1 in ipvsadm)
1292           flag-1
1293           # Enable flag-2 for scheduler (-b flag-2 in ipvsadm)
1294           flag-2
1295           # Enable flag-3 for scheduler (-b flag-3 in ipvsadm)
1296           flag-3
1297           # Enable sh-port for sh scheduler (-b sh-port in ipvsadm)
1298           sh-port
1299           # Enable sh-fallback for sh scheduler  (-b sh-fallback in ipvsadm)
1300           sh-fallback
1301           # Enable mh-port for mh scheduler (-b mh-port in ipvsadm)
1302           mh-port
1303           # Enable mh-fallback for mh scheduler  (-b mh-fallback in ipvsadm)
1304           mh-fallback
1305           # Enable One-Packet-Scheduling for UDP (-O in ipvsadm)
1306           ops
1307
1308           # Default LVS forwarding method
1309           lvs_method NAT|DR|TUN
1310           # LVS persistence engine name
1311           persistence_engine <STRING>
1312           # LVS persistence timeout in seconds, default 6 minutes
1313           persistence_timeout [<INTEGER>]
1314           # LVS granularity mask (-M in ipvsadm)
1315           persistence_granularity <NETMASK>
1316           # L4 protocol
1317           protocol TCP|UDP|SCTP
1318           # If VS IP address is not set,
1319           # suspend healthchecker's activity
1320           ha_suspend
1321
1322           # Send email notification during quorum up/down transition,
1323           # using addresses in global_defs above (default no,
1324           # unless global smtp_alert/smtp_alert_checker set)
1325           smtp_alert <BOOL>
1326
1327           # Default VirtualHost string for HTTP_GET or SSL_GET
1328           # eg virtualhost www.firewall.loc
1329           # Overridden by virtualhost config of real server or checker
1330           virtualhost <STRING>
1331
1332           # On daemon startup assume that all RSs are down
1333           # and healthchecks failed. This helps to prevent
1334           # false positives on startup. Alpha mode is
1335           # disabled by default.
1336           alpha
1337
1338           # On daemon shutdown consider quorum and RS
1339           # down notifiers for execution, where appropriate.
1340           # Omega mode is disabled by default.
1341           omega
1342
1343           # Minimum total weight of all live servers in
1344           # the pool necessary to operate VS with no
1345           # quality regression. Defaults to 1.
1346           quorum <INTEGER>
1347
1348           # Tolerate this much weight units compared to the
1349           # nominal quorum, when considering quorum gain
1350           # or loss. A flap dampener. Defaults to 0.
1351           hysteresis <INTEGER>
1352
1353           # Script to execute when quorum is gained.
1354           quorum_up <STRING>|<QUOTED-STRING> [username [groupname]]
1355
1356           # Script to execute when quorum is lost.
1357           quorum_down <STRING>|<QUOTED-STRING> [username [groupname]]
1358
1359           # IP family for a fwmark service (optional)
1360           ip_family inet|inet6
1361
1362           # setup realserver(s)
1363
1364           # RS to add to LVS topology when the quorum isn't achieved.
1365           #  If a sorry server is configured, all real servers will
1366           #  be brought down when the quorum is not achieved.
1367           sorry_server <IPADDR> <PORT>
1368           # applies inhibit_on_failure behaviour to the sorry_server
1369           sorry_server_inhibit
1370           # Sorry server LVS forwarding method
1371           sorry_server_lvs_method NAT|DR|TUN
1372
1373           # Retry count to make additional checks if check
1374           # of an alive server fails. Default: 1 unless specified below
1375           retry <INTEGER>
1376
1377           # delay before retry
1378           delay_before_retry <INTEGER>
1379
1380           # Optional random delay to start the initial check
1381           # for maximum N seconds.
1382           # Useful to scatter multiple simultaneous
1383           # checks to the same RS. Enabled by default, with
1384           # the maximum at delay_loop. Specify 0 to disable
1385           warmup <INTEGER>
1386
1387           # delay timer for checker polling
1388           delay_loop <INTEGER>
1389
1390           # Set weight to 0 when healthchecker detects failure
1391           inhibit_on_failure
1392
1393           # one entry for each realserver
1394           real_server <IPADDR> <PORT> {
1395               # relative weight to use, default: 1
1396               weight <INTEGER>
1397               # LVS forwarding method
1398               lvs_method NAT|DR|TUN
1399
1400               # Script to execute when healthchecker
1401               # considers service as up.
1402               notify_up <STRING>|<QUOTED-STRING> [username [groupname]]
1403               # Script to execute when healthchecker
1404               # considers service as down.
1405               notify_down <STRING>|<QUOTED-STRING> [username [groupname]]
1406
1407               # maximum number of connections to server
1408               uthreshold <INTEGER>
1409               # minimum number of connections to server
1410               lthreshold <INTEGER>
1411
1412               # Send email notification during state transition,
1413               # using addresses in global_defs above (default yes,
1414               # unless global smtp_alert/smtp_alert_checker set)
1415               smtp_alert <BOOL>
1416
1417               # Default VirtualHost string for HTTP_GET or SSL_GET
1418               # eg virtualhost www.firewall.loc
1419               # Overridden by virtualhost config of a checker
1420               virtualhost <STRING>
1421
1422               alpha <BOOL>                    # see above
1423               retry <INTEGER>                 # see above
1424               delay_before_retry <INTEGER>    # see above
1425               warmup <INTEGER>                # see above
1426               delay_loop <INTEGER>            # see above
1427               inhibit_on_failure <BOOL>       # see above
1428
1429               # healthcheckers. Can be multiple of each type
1430               # HTTP_GET|SSL_GET|TCP_CHECK|SMTP_CHECK|DNS_CHECK|MISC_CHECK|BFD_CHECK
1431
1432               # All checkers have the following options, except MISC_CHECK
1433               # which only has options alpha onwards, and BFD_CHECK which has none
1434               # of the standard options:
1435               CHECKER_TYPE {
1436                   # ======== generic connection options
1437                   # Optional IP address to connect to.
1438                   # The default is the realserver IP
1439                   connect_ip <IPADDR>
1440
1441                   # Optional port to connect to
1442                   # The default is the realserver port
1443                   connect_port <PORT>
1444
1445                   # Optional address to use to
1446                   # originate the connection
1447                   bindto <IPADDR>
1448
1449                   # Optional interface to use; needed if
1450                   # the bindto address is IPv6 link local
1451                   bind_if <IFNAME>
1452
1453                   # Optional source port to
1454                   # originate the connection from
1455                   bind_port <PORT>
1456
1457                   # Optional connection timeout in seconds.
1458                   # The default is 5 seconds
1459                   connect_timeout <INTEGER>
1460
1461                   # Optional fwmark to mark all outgoing
1462                   # checker packets with
1463                   fwmark <INTEGER>
1464
1465                   alpha <BOOL>                    # see above
1466                   retry <INTEGER>                 # see above
1467                   delay_before_retry <INTEGER>    # see above
1468                   warmup <INTEGER>                # see above
1469                   delay_loop <INTEGER>            # see above
1470                   inhibit_on_failure <BOOL>       # see above
1471               }
1472
1473               # The following options are additional checker specific
1474
1475               # HTTP and SSL healthcheckers
1476               HTTP_GET|SSL_GET {
1477                   # An url to test
1478                   # can have multiple entries here
1479                   url {
1480                     #eg path / , or path /mrtg2/
1481                     path <STRING>
1482                     # healthcheck needs status_code
1483                     # or status_code and digest
1484                     # Digest computed with genhash
1485                     # eg digest 9b3a0c85a887a256d6939da88aabd8cd
1486                     digest <STRING>
1487                     # status code returned in the HTTP header
1488                     # eg status_code 200. Default is any 2xx value
1489                     status_code <INTEGER>
1490                     # VirtualHost string. eg virtualhost www.firewall.loc
1491                     # If not set, uses virtualhost from real or virtual server
1492                     virtualhost <STRING>
1493                     # Regular expression to search returned data against.
1494                     # A failure to match causes the check to fail.
1495                     regex <STRING>
1496                     # Reverse the sense of the match, so a match of the
1497                     # returned text causes the check to fail.
1498                     regex_no_match
1499                     # Space separated list of options for regex.
1500                     #  See man pcre2api for a description of the options.
1501                     #  The following option are supported:
1502                     #   allow_empty_class alt_bsux auto_callout caseless
1503                     #   dollar_endonly dotall dupnames extended firstline
1504                     #   match_unset_backref multiline never_ucp never_utf
1505                     #   no_auto_capture no_auto_possess no_dotstar_anchor
1506                     #   no_start_optimize ucp ungreedy utf never_backslash_c
1507                     #   alt_circumflex alt_verbnames use_offset_limit
1508                     regex_options <OPTIONS>
1509                     # For complicated regular expressions a larger stack
1510                     #   may be needed, and this allows the start and maximum
1511                     #   sizes in bytes to be specified. For more details see
1512                     #   the documentation for pcre2_jit_stack_create()
1513                     regex_stack <START> <MAX>
1514                     # The minimum offset into the returned data to start
1515                     #   checking for the regex pattern match. This can save
1516                     #   processing time if the returned data is large.
1517                     regex_min_offset <OFFSET>
1518                     # The maximum offset into the returned data for the
1519                     #   start of the subject match.
1520                     regex_max_offset <OFFSET>
1521                   }
1522               }
1523
1524               SSL_GET {
1525                   # when provided, send Server Name Indicator during SSL handshake
1526                   enable_sni
1527               }
1528
1529               # TCP healthchecker
1530               TCP_CHECK {
1531                   # No additional options
1532               }
1533
1534               # SMTP healthchecker
1535               SMTP_CHECK {
1536                   # Optional string to use for the SMTP HELO request
1537                   helo_name <STRING>|<QUOTED-STRING>
1538               }
1539
1540               # DNS healthchecker
1541               DNS_CHECK {
1542                   # The retry default is 3.
1543
1544                   # DNS query type
1545                   #   A|NS|CNAME|SOA|MX|TXT|AAAA
1546                   # The default is SOA
1547                   type <STRING>
1548
1549                   # Domain name to use for the DNS query
1550                   # The default is . (dot)
1551                   name <STRING>
1552               }
1553
1554               # MISC healthchecker, run a program
1555               MISC_CHECK {
1556                   # The retry default is 0.
1557
1558                   # External script or program
1559                   misc_path <STRING>|<QUOTED-STRING>
1560                   # Script execution timeout
1561                   misc_timeout <INTEGER>
1562
1563                   # If set, the exit code from healthchecker is used
1564                   # to dynamically adjust the weight as follows:
1565                   #   exit status 0: svc check success, weight
1566                   #     unchanged.
1567                   #   exit status 1: svc check failed.
1568                   #   exit status 2-255: svc check success, weight
1569                   #     changed to 2 less than exit status.
1570                   #   (for example: exit status of 255 would set
1571                   #     weight to 253)
1572                   # NOTE: do not have more than one dynamic MISC_CHECK per real_server.
1573                   misc_dynamic
1574
1575                   # Specify the username/groupname that the script should
1576                   #   be run under.
1577                   # If GROUPNAME is not specified, the group of the user
1578                   #   is used
1579                   user USERNAME [GROUPNAME]
1580               }
1581
1582               # BFD instance name to check
1583               BFD_CHECK {
1584                   name <STRING>
1585               }
1586           }
1587       }
1588
1589       # Parameters used for SSL_GET check.
1590       # If none of the parameters are specified, the SSL context
1591       # will be auto generated.
1592       SSL {
1593           # Password
1594           password <STRING>
1595           # CA file
1596           ca <STRING>
1597           # Certificate file
1598           certificate <STRING>
1599           # Key file
1600           key <STRING>
1601       }
1602

ADVANCED CONFIGURATION

1604       Configuration parser has been extended  to  support  advanced  features
1605       such  as  conditional  configuration  and parameter substitution. These
1606       features are very usefull for any scripted env where configuration tem‐
1607       plate are generated (datacenters).
1608

Conditional configuration and configuration id

1610       The  config-id  defaults to the first part of the node name as returned
1611       by uname, and can be overridden with the -i or --config-id command line
1612       option.
1613
1614       Any configuration line starting with '@' is a conditional configuration
1615       line.  The word immediately following (i.e. without any space) the  '@'
1616       character  is  compared against the config-id, and if they don't match,
1617       the configuration line is ignored.
1618
1619       Alternatively, '@^' is a negative comparison, so if  the  word  immedi‐
1620       ately following does NOT match the config-id, the configuration line IS
1621       included.
1622
1623       The purpose of this is to allow a single configuration file to be  used
1624       for  multiple  systems, where the only differences are likely to be the
1625       router_id, vrrp instance priorities, and possibly interface  names  and
1626       unicast addresses.
1627
1628       For example:
1629
1630           global_defs {
1631               @main   router_id main_router
1632               @backup router_id backup_router
1633           }
1634           ...
1635           vrrp_instance VRRP {
1636               ...
1637               @main    unicast_src_ip 1.2.3.4
1638               @backup  unicast_src_ip 1.2.3.5
1639               @backup2 unicast_src_ip 1.2.3.6
1640               unicast_peer {
1641                   @^main    1.2.3.4
1642                   @^backup  1.2.3.5
1643                   @^backup2 1.2.3.6
1644               }
1645               ...
1646           }
1647
1648       If  keepalived  is invoked with -i main, then the router_id will be set
1649       to main_router, if invoked with -i backup, then backup_router,  if  not
1650       invoked  with -i, or with -i anything else, then the router_id will not
1651       be set. The unicast peers for main will be 1.2.3.5 and 1.2.3.6.
1652

Parameter substitution

1654       Substitutable parameters can be specified. The format  for  defining  a
1655       parameter is:
1656
1657       $PARAMETER=VALUE
1658
1659       where  there  must  be  no space before the '=' and only whitespace may
1660       preceed to '$'.  Empty values are allowed.
1661
1662       Parameter names can be made up of any combination of A-Za-z0-9  and  _,
1663       but  cannot start with a digit. Parameter names starting with an under‐
1664       score should be considered reserved names that keepalived  will  define
1665       for various pre-defined options.
1666
1667       After  a parameter is defined, any occurrence of $PARAMETER followed by
1668       whitespace, or any occurrence of ${PARAMETER} (which need not  be  fol‐
1669       lowed by whitespace) will be replaced by VALUE.
1670
1671       Replacement  is recursive, so that if a parameter value itself includes
1672       a replaceable parameter, then after the first substitution, the parame‐
1673       ter  in  the  value  will then be replaced; the substitution is done at
1674       replacement time and not at definition time, so for example:
1675
1676           $ADDRESS_BASE=10.2.${ADDRESS_BASE_SUB}
1677           $ADDRESS_BASE_SUB=0
1678           ${ADDRESS_BASE}.100/32
1679           $ADDRESS_BASE_SUB=10
1680           ${ADDRESS_BASE}.100/32
1681
1682           will produce:
1683               10.2.0.100/32
1684               10.2.10.100/32
1685
1686       Note  in  the  above  examples  the  use  of  both   ADDRESS_BASE   and
1687       ADDRESS_BASE_SUB  required  braces  ({})  since the parameters were not
1688       followed by whitespace (after the  first  substitution  which  produced
1689       10.2.${ADDRESS_BASE_SUB}.100/32  the parameter is still not followed by
1690       whitespace).
1691
1692       If a parameter is not defined, it will not be replaced at all,  so  for
1693       example  ${UNDEF_PARAMETER}  will  remain in the configuration if it is
1694       undefined; this means that existing configuration that contains  a  '$'
1695       character  (for  example in a script definition) will not be changed so
1696       long as no new parameter definitions are added to the configuration.
1697
1698       Parameter substitution works in conjunction with conditional configura‐
1699       tion.  For example:
1700
1701           @main $PRIORITY=240
1702           @backup $PRIORITY=200
1703           ...
1704           vrrp_instance VI_0 {
1705               priority $PRIORITY
1706           }
1707
1708           will produce:
1709               ...
1710               vrrp_instance VI_0 {
1711                   priority 240
1712               }
1713               if the config_id is main.
1714
1715           $IF_MAIN=@main
1716           $IF_MAIN priority 240
1717
1718           will produce:
1719               priority 240
1720               if the config_id is main and nothing if the config_id is not main,
1721               although why anyone would want to use this rather than simply the
1722               following is not known (but still possible):
1723                   @main priority 240
1724
1725       Multiline  definitions  are also supported, but when used there must be
1726       nothing on the line after the parameter name. A multiline definition is
1727       specified by ending each line except the last with a '\' character.
1728
1729       Example:
1730           $INSTANCE= \
1731           vrrp_instance VI_${NUM} { \
1732               interface eth0.${NUM} \
1733               use_vmac vrrp${NUM}.1 \
1734               virtual_router_id 1 \
1735               @high priority 130 \
1736               @low priority 120 \
1737               advert_int 1 \
1738               virtual_ipaddress { \
1739                   10.0.${NUM}.254/24 \
1740               } \
1741               track_script { \
1742                   offset_instance_${NUM} \
1743               } \
1744           }
1745
1746           $NUM=0
1747           $INSTANCE
1748
1749           $NUM=1
1750           $INSTANCE
1751
1752       The use of multiline definitions can be nested.
1753
1754       Example:
1755           $RS= \
1756           real_server 192.168.${VS_NUM}.${RS_NUM} 80 { \
1757               weight 1 \
1758               inhibit_on_failure \
1759               smtp_alert \
1760               MISC_CHECK { \
1761                   misc_path "${_PWD}/scripts/vs.sh RS_misc.${INST}.${VS_NUM}.${RS_NUM}.0 10.0.${VS_NUM}.4:80->192.168.${VS_NUM}.${RS_NUM}:80" \
1762               } \
1763
1764               MISC_CHECK { \
1765                   misc_path "${_PWD}/scripts/vs.sh RS_misc.${INST}.${VS_NUM}.${RS_NUM}.1 10.0.${VS_NUM}.4:80->192.168.${VS_NUM}.${RS_NUM}:80" \
1766               } \
1767
1768               notify_up "${_PWD}/scripts/notify.sh RS_notify.${INST}.${VS_NUM}.${RS_NUM} UP 10.0.${VS_NUM}.4:80->192.168.${VS_NUM}.${RS_NUM}:80" \
1769
1770               notify_down "${_PWD}/scripts/notify.sh RS_notify.${INST}.${VS_NUM}.${RS_NUM} DOWN 10.0.${VS_NUM}.4:80->192.168.${VS_NUM}.${RS_NUM}:80" \
1771
1772           }
1773
1774           $VS= \
1775           virtual_server 10.0.${VS_NUM}.4 80 { \
1776               quorum 2 \
1777               quorum_up "${_PWD}/scripts/notify.sh VS_notify.${INST} UP 10.0.${VS_NUM}.4:80" \
1778               quorum_down "${_PWD}/scripts/notify.sh VS_notify.${INST} DOWN 10.0.${VS_NUM}.4:80" \
1779               $RS_NUM=1 \
1780               $RS \
1781               $RS_NUM=2 \
1782               $RS \
1783               $RS_NUM=3 \
1784               $RS \
1785           }
1786
1787           $VS_NUM=0
1788           $ALPHA=alpha
1789           $VS
1790
1791           $VS_NUM=1
1792           $ALPHA=
1793           $VS
1794
1795       The above will create 2 virtual servers, each with 3 real servers
1796

Pre-defined definitions

1798       The following pre-defined definitions are defined:
1799
1800       ${_PWD}  : The directory of the current configuration file (this can be
1801       changed if using the include directive).
1802       ${_INSTANCE} : The instance name (as defined by the -i option, defaults
1803       to hostname).
1804
1805       Additional pre-defined definitions will be added as their need is iden‐
1806       tified.  It will normally be quite straightforward  to  add  additional
1807       pre-defined  definitions,  so  if you need one, or have a good idea for
1808       one,         then          raise          an          issue          at
1809       https://github.com/acassen/keepalived/issues requesting it.
1810

Sequence blocks

1812       A line starting ~SEQ(var, start, step, end) will cause the remainder of
1813       the line to be processed multiple times, with  the  variable  $var  set
1814       initially  to  start, and then $var will be incremented by step repeat‐
1815       edly, terminating when it is greater than end. step may be omitted,  in
1816       which  case it defaults to 1 or -1, depending on whether end is greater
1817       or less than start. start  may  also  be  omitted,  in  which  case  it
1818       defaults to 1 if end > 0 or -1 if end < 0. so, for example:
1819
1820           ~SEQ(SUBNET, 0, 3) ip_address 10.0.$SUBNET.1
1821
1822           would produce:
1823               ip_address 10.0.0.1
1824               ip_address 10.0.1.1
1825               ip_address 10.0.2.1
1826               ip_address 10.0.3.1
1827
1828       There can be multiple ~SEQ elements on a line, so for example:
1829
1830           $VI4= \
1831           vrrp_track_file offset_instance_4.${IF}.${NUM}.${ID} { \
1832               file "${_PWD}/679/track_files/4.${IF}.${NUM}.${ID}" \
1833               weight -100 \
1834           } \
1835           vrrp_instance vrrp4.${IF}.${NUM}.${ID} { \
1836               interface bond${IF}.${NUM} \
1837               use_vmac vrrp4.${IF}.${NUM}.${ID} \
1838               virtual_router_id ${ID} \
1839               priority 130 \
1840               virtual_ipaddress { \
1841                   10.${IF}.${NUM}.${ID}/24 \
1842               } \
1843               track_file { \
1844                   offset_instance_4.${IF}.${NUM}.${ID} \
1845               } \
1846           }
1847
1848           ~SEQ(IF,0,7) ~SEQ(NUM,0,31) ~SEQ(ID,1,254) $VI4
1849
1850           will produce 65024 vrrp instances with names from vrrp4.0.0.1 through to
1851           vrrp4.7.31.254.
1852

AUTHORS

1854       Initial by Joseph Mack. Extensive updates by Alexandre Cassen & Quentin
1855       Armitage.
1856

SEE ALSO

1858       ipvsadm(8), ip --help.
1859
1860
1861
1862Keepalived                        2018-08-10                keepalived.conf(5)
Impressum