1keepalived.conf(5) Keepalived Configuration's Manual keepalived.conf(5)
2
6 keepalived.conf - configuration file for Keepalived
7
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 Comments start with '#' or '!' to the end of the line and can start
14 anywhere in a line.
15 The keyword 'include' allows inclusion of other configuration files
17 from within the main configuration file, or from subsequently included
18 files.
19 The format of the include directive is:
21 include FILENAME
23 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 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 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
37 <BOOL> is one of on|off|true|false|yes|no
38
40 There are three classes of scripts can be configured to be executed.
41 (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 (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 (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 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 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 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
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 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 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
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
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 GLOBAL CONFIGURATION
99 BFD CONFIGURATION
101 VRRPD CONFIGURATION
103 LVS CONFIGURATION
105
107 contains subblocks of Global definitions, Static track groups, Static
108 addresses, Static routes, and Static rules
109
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 # 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 # 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 # Create pid files in /var/run/keepalived
135 use_pid_dir
136 # Poll to detect media link failure otherwise attempt to use
138 # ETHTOOL or MII interface
139 linkbeat_use_polling
140 # 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 # Global definitions configuration block
147 global_defs {
148 # Set of email To: notify
149 notification_email {
150 admin@example1.com
151 ...
152 }
153 # email from address that will be in the header
155 # (default: keepalived@<local host name>)
156 notification_email_from admin@example.com
157 # 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 # Name to use in HELO messages.
164 # (default: local host name)
165 smtp_helo_name <STRING>
166 # SMTP server connection timeout in seconds.
168 smtp_connect_timeout 30
169 # Sets default state for all smtp_alerts
171 smtp_alert <BOOL>
172 # Sets default state for vrrp smtp_alerts
174 smtp_alert_vrrp <BOOL>
175 # Sets default state for checker smtp_alerts
177 smtp_alert_checker <BOOL>
178 # Ssets logging all checker failes while checker up
180 checker_log_all_failures <BOOL>
181 # Don't send smtp alerts for fault conditions
183 no_email_faults
184 # String identifying the machine (doesn't have to be hostname).
186 # (default: local host name)
187 router_id <STRING>
188 # Multicast Group to use for IPv4 VRRP adverts
190 # (default: 224.0.0.18)
191 vrrp_mcast_group4 224.0.0.18
192 # Multicast Group to use for IPv6 VRRP adverts
194 # (default: ff02::12)
195 vrrp_mcast_group6 ff02::12
196 # sets the default interface for static addresses.
198 # (default: eth0)
199 default_interface p33p1.3
200 # Sync daemon as provided by IPVS kernel code only support
202 # a single daemon instance at a time to synchronize connection table.
203 # Binding interface, vrrp instance and optional
204 # syncid for lvs syncd
205 # syncid (0 to 255) for lvs syncd
206 # maxlen (1..65507) maximum packet length
207 # port (1..65535) UDP port number to use
208 # ttl (1..255)
209 # group - multicast group address (IPv4 or IPv6)
210 # NOTE: maxlen, port, ttl and group are only available on Linux 4.3 or later.
211 lvs_sync_daemon <INTERFACE> <VRRP_INSTANCE> [id <SYNC_ID>] [maxlen <LEN>] \
212 [port <PORT>] [ttl <TTL>] [group <IP ADDR>]
213 # flush any existing LVS configuration at startup
215 lvs_flush
216 # delay for second set of gratuitous ARPs after transition to MASTER.
218 # in seconds, 0 for no second set.
219 # (default: 5)
220 vrrp_garp_master_delay 10
221 # number of gratuitous ARP messages to send at a time after
223 # transition to MASTER.
224 # (default: 5)
225 vrrp_garp_master_repeat 1
226 # delay for second set of gratuitous ARPs after lower priority
228 # advert received when MASTER.
229 vrrp_garp_lower_prio_delay 10
230 # number of gratuitous ARP messages to send at a time after
232 # lower priority advert received when MASTER.
233 vrrp_garp_lower_prio_repeat 1
234 # minimum time interval for refreshing gratuitous ARPs while MASTER.
236 # in seconds.
237 # (default: 0 (no refreshing))
238 vrrp_garp_master_refresh 60
239 # number of gratuitous ARP messages to send at a time while MASTER
241 # (default: 1)
242 vrrp_garp_master_refresh_repeat 2
243 # Delay in ms between gratuitous ARP messages sent on an interface
245 # decimal, seconds (resolution usecs).
246 # (default: 0)
247 vrrp_garp_interval 0.001
248 # Delay in ms between unsolicited NA messages sent on an interface
250 # decimal, seconds (resolution usecs).
251 # (default: 0)
252 vrrp_gna_interval 0.000001
253 # If a lower priority advert is received, don't send another advert.
255 # This causes adherence to the RFCs. Defaults to false, unless
256 # strict_mode is set.
257 vrrp_lower_prio_no_advert [<BOOL>]
258 # If we are master and receive a higher priority advert, send an advert
260 # (which will be lower priority than the other master), before we
261 # transition to backup. This means that if the other master has
262 # garp_lower_priority_repeat set, it will resend garp messages.
263 # This is to get around the problem of their having been two simultaneous
264 # masters, and the last GARP messages seen were from us.
265 vrrp_higher_prio_send_advert [<BOOL>]
266 # Set the default VRRP version to use
268 # (default: 2)
269 vrrp_version <2 or 3>
270 # Specify the iptables chain for ensuring a version 3 instance
272 # doesn't respond on addresses that it doesn't own.
273 # Note: it is necessary for the specified chain to exist in
274 # the iptables and/or ip6tables configuration, and for the chain
275 # to be called from an appropriate point in the iptables configuration.
276 # It will probably be necessary to have this filtering after accepting
277 # any ESTABLISHED,RELATED packets, because IPv4 might select the VIP as
278 # the source address for outgoing connections.
279 # (default: INPUT)
280 vrrp_iptables keepalived
281 # Use nftables to implement no_accept mode.
283 # TABLENAME must not exist, and must be different for each
284 # instance of keepalived running in the same network namespace.
285 # Default tablename is keepalived, and priority is -1.
286 # keepalived will create base chains in the table.
287 # counters means counters are added to the rules (primarily for
288 # debugging purposes).
289 # ifindex means create IPv6 link local sets using ifindex rather
290 # than ifnames. This is the default unless the vrrp_instance has
291 # set dont_track_primary. The alternative is to use interface names
292 # as part of the set key, but nftables prior to v0.8.3 will then no
293 # longer work.
294 nftables [TABLENAME]
295 nftables_priority PRIORITY
296 nftables_counters
297 nftables_ifindex
298 # or for outbound filtering as well
300 # Note, outbound filtering won't work with IPv4, since the VIP can be
301 # selected as the source address for an outgoing connection. With IPv6
302 # this is unlikely since the addresses are deprecated.
303 vrrp_iptables keepalived_in keepalived_out
304 # or to not add any iptables rules:
306 vrrp_iptables
307 # Keepalived may have the option to use ipsets in conjunction with
309 # iptables. If so, then the ipset names can be specified, defaults
310 # as below. If no names are specified, ipsets will not be used,
311 # otherwise any omitted names will be constructed by adding "_if"
312 # and/or "6" to previously specified names.
313 vrrp_ipsets [keepalived [keepalived6 [keepalived_if6]]]
314 # The following enables checking that when in unicast mode, the
316 # source address of a VRRP packet is one of our unicast peers.
317 vrrp_check_unicast_src
318 # Checking all the addresses in a received VRRP advert can be time
320 # consuming. Setting this flag means the check won't be carried out
321 # if the advert is from the same master router as the previous advert
322 # received.
323 # (default: don't skip)
324 vrrp_skip_check_adv_addr
325 # Enforce strict VRRP protocol compliance. This will prohibit:
327 # 0 VIPs
328 # unicast peers
329 # IPv6 addresses in VRRP version 2
330 vrrp_strict
331 # The following options can be used if vrrp or checker processes
333 # are timing out. This can be seen by a backup vrrp instance becoming
334 # master even when the master is still running because the master or
335 # backup system is too busy to process vrrp packets.
336 # --
337 # Set the vrrp child process priority (Negative values increase priority)
338 vrrp_priority <-20 to 19>
339 # Set the checker child process priority
341 checker_priority <-20 to 19>
342 # Set the BFD child process priority
344 bfd_priority <-20 to 19>
345 # Set the vrrp child process non swappable
347 vrrp_no_swap
348 # Set the checker child process non swappable
350 checker_no_swap
351 # Set the BFD child process non swappable
353 bfd_no_swap
354 # Set the vrrp child process to use real-time scheduling
356 # at the specified priority
357 vrrp_rt_priority <1..99>
358 # Set the checker child process to use real-time scheduling
360 # at the specified priority
361 checker_rt_priority <1..99>
362 # Set the BFD child process to use real-time scheduling
364 # at the specified priority
365 bfd_rt_priority <1..99>
366 # Set the limit on CPU time between blocking system calls,
368 # in microseconds
369 # (default: 1000)
370 vrrp_rlimit_rtime >=1
371 checker_rlimit_rtime >=1
372 bfd_rlimit_rtime >=1
373 # If Keepalived has been build with SNMP support, the following
375 # keywords are available.
376 # Note: Keepalived, checker and RFC support can be individually
377 # enabled/disabled
378 # --
379 # Specify socket to use for connecting to SNMP master agent
380 # (see source module keepalived/vrrp/vrrp_snmp.c for more details)
381 # (default: unix:/var/agentx/master)
382 snmp_socket udp:1.2.3.4:705
383 # enable SNMP handling of vrrp element of KEEPALIVED MIB
385 enable_snmp_vrrp
386 # enable SNMP handling of checker element of KEEPALIVED MIB
388 enable_snmp_checker
389 # enable SNMP handling of RFC2787 and RFC6527 VRRP MIBs
391 enable_snmp_rfc
392 # enable SNMP handling of RFC2787 VRRP MIB
394 enable_snmp_rfcv2
395 # enable SNMP handling of RFC6527 VRRP MIB
397 enable_snmp_rfcv3
398 # enable SNMP traps
400 enable_traps
401 # If Keepalived has been build with DBus support, the following
403 # keywords are available.
404 # --
405 # Enable the DBus interface
406 enable_dbus
407 # Name of DBus service
409 # Useful if you want to run multiple keepalived processes with DBus enabled
410 # (default: org.keepalived.Vrrp1)
411 dbus_service_name SERVICE_NAME
412 # Specify the default username/groupname to run scripts under.
414 # If this option is not specified, the user defaults to keepalived_script
415 # if that user exists, otherwise root.
416 # If groupname is not specified, it defaults to the user's group.
417 script_user username [groupname]
418 # Don't run scripts configured to be run as root if any part of the path
420 # is writable by a non-root user.
421 enable_script_security
422 # Rather than using notify scripts, specifying a fifo allows more
424 # efficient processing of notify events, and guarantees that they
425 # will be delivered in the correct sequence.
426 # NOTE: the FIFO names must all be different
427 # --
428 # FIFO to write notify events to
429 # See vrrp_notify_fifo and lvs_notify_fifo for format of output
430 # For further details, see the description under vrrp_sync_group see
431 # doc/samples/sample_notify_fifo.sh for sample usage.
432 notify_fifo FIFO_NAME
433 # script to be run by keepalived to process notify events
435 # The FIFO name will be passed to the script as the last parameter
436 notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
437 # FIFO to write vrrp notify events to.
439 # The string written will be a line of the form: INSTANCE "VI_1" MASTER 100
440 # and will be terminated with a new line character.
441 # For further details of the output, see the description under vrrp_sync_group
442 # and doc/samples/sample_notify_fifo.sh for sample usage.
443 vrrp_notify_fifo FIFO_NAME
444 # script to be run by keepalived to process vrrp notify events
446 # The FIFO name will be passed to the script as the last parameter
447 vrrp_notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
448 # FIFO to write notify healthchecker events to
450 # The string written will be a line of the form:
451 # VS [192.168.201.15]:tcp:80 {UP|DOWN}
452 # RS [1.2.3.4]:tcp:80 [192.168.201.15]:tcp:80 {UP|DOWN}
453 # and will be terminated with a new line character.
454 lvs_notify_fifo FIFO_NAME
455 # script to be run by keepalived to process healthchecher notify events
457 # The FIFO name will be passed to the script as the last parameter
458 lvs_notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
459 # Allow configuration to include interfaces that don't exist at startup.
461 # This allows keepalived to work with interfaces that may be deleted and restored
462 # and also allows virtual and static routes and rules on VMAC interfaces.
463 # allow_if_changes allows an interface to be deleted and recreated with a
464 # different type or underlying interface, eg changing from vlan to macvlan
465 # or changing a macvlan from eth1 to eth2. This is predominantly used for
466 # reporting duplicate VRID errors at startup if allow_if_changes is not set.
467 dynamic_interfaces [allow_if_changes]
468 # The following options are only needed for large configurations, where either
470 # keepalived creates a large number of interface, or the system has a large
471 # number of interface. These options only need using if
472 # "Netlink: Receive buffer overrun" messages are seen in the system logs.
473 # If the buffer size needed exceeds the value in /proc/sys/net/core/rmem_max
474 # the corresponding force option will need to be set.
475 # --
476 # Set netlink receive buffer size. This is useful for
477 # very large configurations where a large number of interfaces exist, and
478 # the initial read of the interfaces on the system causes a netlink buffer
479 # overrun.
480 vrrp_netlink_cmd_rcv_bufs BYTES
481 vrrp_netlink_cmd_rcv_bufs_force <BOOL>
482 vrrp_netlink_monitor_rcv_bufs BYTES
483 vrrp_netlink_monitor_rcv_bufs_force <BOOL>
484 # The vrrp netlink command and monitor socket the checker command and
486 # and monitor socket and process monitor buffer sizes can be independently set.
487 # The force flag means to use SO_RCVBUFFORCE, so that the buffer size
488 # can exceed /proc/sys/net/core/rmem_max.
489 lvs_netlink_cmd_rcv_bufs BYTES
490 lvs_netlink_cmd_rcv_bufs_force <BOOL>
491 lvs_netlink_monitor_rcv_bufs BYTES
492 lvs_netlink_monitor_rcv_bufs_force <BOOL>
493 # As a guide for process_monitor_rcv_bufs for 1400 processes terminating
495 # simultaneously, 212992 (the default on some systems) is insufficient, whereas
496 # 500000 is sufficient.
497 process_monitor_rcv_bufs BYTES
498 process_monitor_rcv_bufs_force <BOOL>
499 # When a socket is opened, the kernel configures the max rx buffer size for
501 # the socket to /proc/sys/net/core/rmem_default. On some systems this can be
502 # very large, and even generally this can be much larger than necessary.
503 # This isn't a problem so long as keepalived is reading all queued data from
504 # it's sockets, but if rmem_default was set sufficiently large, and if for
505 # some reason keepalived stopped reading, it could consume all system memory.
506 # The vrrp_rx_bufs_policy allows configuring of the rx bufs size when the
507 # sockets are opened. If the policy is MTU, the rx buf size is configured
508 # to the total of interface's MTU * vrrp_rx_bufs_multiplier for each vrrp
509 # instance using the socket. Likewise, if the policy is ADVERT, then it is
510 # the total of each vrrp instances advert packet size * multiplier.
511 # (default: use system default)
512 vrrp_rx_bufs_policy [MTU|ADVERT|NUMBER]
513 # (default: 3)
515 vrrp_rx_bufs_multiplier NUMBER
516 # Send notifies at startup for real servers that are starting up
518 rs_init_notifies
519 # Don't send an email every time a real server checker changes state;
521 # only send email when a real server is added or removed
522 no_checker_emails
523 # The umask to use for creating files. The number can be specified in hex, octal
525 # or decimal. BITS are I{R|W|X}{USR|GRP|OTH}, e.g. IRGRP, separated by '|'s.
526 # The default umask is IWGRP | IWOTH. This option cannot override the
527 # command-line option.
528 umask [NUMBER|BITS]
529 }
530
532 Static track groups are used to allow vrrp instances to track static
533 addresses, routes and rules. If a static address/route/rule specifies a
534 track group, then if the address/route/rule is deleted and cannot be
535 restored, the vrrp instance will transition to fault state.
536 The syntax for a track group is:
538 track_group GROUP1 {
539 group {
540 VI_1
541 VI_2
542 }
543 }
544
546 Keepalived can configure static addresses, routes, and rules. These
547 addresses are NOT moved by vrrpd, they stay on the machine. If you
548 already have IPs and routes on your machines and your machines can ping
549 each other, you don't need this section. The syntax for rules and
550 routes is that same as for ip rule add/ip route add (except shorted
551 option names aren't supported due to ambiguities). The track_group
552 specification refers to a named track_group which lists the vrrp
553 instances which will track the address, i.e. if the address is deleted
554 the vrrp instances will transition to backup.
555 NOTE: since rules without preferences can be added in different orders
557 due to vrrp instances transitioning from master to backup etc, rules
558 need to have a preference. If a preference is not specified, keepalived
559 will assign one, but it will probably not be what you want.
560 The syntax is the same for virtual addresses and virtual routes. If no
562 dev element is specified, it defaults to default_interface (default
563 eth0). Note: the broadcast address may be specified as '-' or '+' to
564 clear or set the host bits of the address.
565 If a route or rule could apply to either IPv4 or IPv6 it will default
567 to IPv4. To force a route/rule to be IPv6, add the keyword "inet6".
568 static_ipaddress {
570 <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
571 [label <LABEL>] [peer <IPADDR>] [home]
572 [-nodad] [mngtmpaddr] [noprefixroute]
573 [autojoin] [track_group GROUP]
574 192.168.1.1/24 dev eth0 scope global
575 ...
576 }
577 static_routes {
579 192.168.2.0/24 via 192.168.1.100 dev eth0 track_group GROUP1
580 192.168.100.0/24 table 6909 nexthop via 192.168.101.1 dev wlan0
582 onlink weight 1 nexthop via 192.168.101.2
583 dev wlan0 onlink weight 2
584 192.168.200.0/24 dev p33p1.2 table 6909 tos 0x04 protocol bird
586 scope link priority 12 mtu 1000 hoplimit 100
587 advmss 101 rtt 102 rttvar 103 reordering 104
588 window 105 cwnd 106 ssthresh lock 107 realms
589 PQA/0x14 rto_min 108 initcwnd 109 initrwnd 110
590 features ecn
591 2001:470:69e9:1:2::4 dev p33p1.2 table 6909 tos 0x04 protocol
593 bird scope link priority 12 mtu 1000
594 hoplimit 100 advmss 101 rtt 102 rttvar 103
595 reordering 104 window 105 cwnd 106 ssthresh
596 lock 107 rto_min 108 initcwnd 109
597 initrwnd 110 features ecn fastopen_no_cookie 1
598 ...
599 }
600 static_rules {
602 from 192.168.2.0/24 table 1 track_group GROUP1
603 to 192.168.2.0/24 table 1
605 from 192.168.28.0/24 to 192.168.29.0/26 table small iif p33p1
607 oif wlan0 tos 22 fwmark 24/12
608 preference 39 realms 30/20 goto 40
609 to 1:2:3:4:5:6:7:0/112 from 7:6:5:4:3:2::/96 table 6908
611 uidrange 10000-19999
612 to 1:2:3:4:6:6:7:0/112 from 8:6:5:4:3:2::/96 l3mdev protocol 12
614 ip_proto UDP sport 10-20 dport 20-30
615 ...
616 }
617
619 The configuration block looks like:
620 vrrp_track_process <STRING> { # VRRP track file declaration
622 process <QUOTED_STRING> # process to monitor
623 weight <-254..254> # default weight (default is 1)
624 quorum NUM # minimum number of processes for success
625 delay SECS # time to delay after process quorum lost before
626 # consider process failed (in fractions of second)
627 full_command # Normally process string is matched against the process name,
628 # as shown on the Name: line in /proc/PID/status.
629 # This option matches the full command line
630 }
631 To avoid having to frequently run a track_script to monitor the exis‐
633 tance of processes (often haproxy or nginx), vrrp_track_process can
634 monitor whether other processes are running.
635 One difference from pgrep is track_process doesn't do a regular expres‐
637 sion match of the command string, but does an exact match. 'pgrep ssh'
638 will match an sshd process, this track_process will not (it is equiva‐
639 lent to pgrep "^ssh$").
640 If full_command is used (equivalent to pgrep -f), /proc/PID/cmdline is
642 used, but any updates to cmdline will not be detected (a process
643 shouldn't normally change it, although it is possible with great care,
644 for example systemd).
645 Quorum is the number of matching processes that must be run for an OK
647 status.
648 Delay might be useful if it anticipated that a process may be reloaded
650 (stopped and restarted), and it isn't desired to down and up a vrrp
651 instance.
652 A positive weight means that an OK status will add <weight> to the pri‐
654 ority of all VRRP instances which monitor it. On the opposite, a nega‐
655 tive weight will be subtracted from the initial priority in case of
656 insufficient processes.
657 If the vrrp instance or sync group is not the address owner and the
659 result is between -253 and 253, the result will be added to the initial
660 priority of the VRRP instance (a negative value will reduce the prior‐
661 ity), although the effective priority will be limited to the range
662 [1,254].
663 If a vrrp instance using a track_process is a member of a sync group,
665 unless sync_group_tracking_weight is set on the group weight 0 must be
666 set. Likewise, if the vrrp instance is the address owner, weight 0
667 must also be set.
668 Rational for not using pgrep/pidof/killall and the likes:
670 Every time pgrep or its equivalent is run, it iterates though the
672 /proc/[1-9][0-9]* directories, and opens the status and cmdline pseudo
673 files in each directory. The cmdline pseudo file is mapped to the
674 process's address space, and so if that part of the process is swapped
675 out, it will have to be fetched from the swap space. pgrep etc also
676 include zombie processes whereas keepalived does not, since they aren't
677 running.
678 This implementation only iterates though /proc/[1-9][0-9]*/ directories
680 at start up, and it won't even read the cmdline pseudo files if
681 'full_command' is not specified for any of the vrrp_track_process
682 entries. After startup, it uses the process_events kernel <-> userspace
683 connector to receive notification of process changes. If full_command
684 is specified for any track_process instance, the cmdline pseudo file
685 will have to be read upon notification of the creation of the new
686 process, but at that time it is very unlikely that it will have already
687 been swapped out.
688 On a busy system with a high number of process creations/terminations,
690 using a track_script with pgrep/pidof/killall may be more efficient,
691 although those processes are inefficient compared to the minimum that
692 keepalived needs.
693 Using pgrep etc on a system that is swapping can have a significant
695 detrimental impact on the performance of the system, due to having to
696 fetch swapped memory from the swap space, thereby causing additional
697 swapping.
698
700 This is an implementation of RFC5880 (Bidirectional forwarding detec‐
701 tion), and this can be configured to work between 2 keepalived
702 instances, but using unweighted track_bfds between a master/backup pair
703 of VRRP instances means that the VRRP instance will only be able to
704 come up if both VRRP instance are running, which somewhat defeats the
705 purpose of VRRP.
706 This imlpementation has been tested with OpenBFDD (available at
708 https://github.com/dyninc/OpenBFDD).
709 The syntax for bfd instance is :
711 bfd_instance <STRING> {
713 # BFD Neighbor IP (synonym neighbour_ip)
714 neighbor_ip <IP ADDRESS>
715 # Source IP to use (optional)
717 source_ip <IP ADDRESS>
718 # Required min RX interval, in ms
720 # (default is 10 ms)
721 mix_rx <INTEGER>
722 # Desired min TX interval, in ms
724 # (default is 10 ms)
725 min_tx <INTEGER>
726 # Desired idle TX interval, in ms
728 # (default is 1000 ms)
729 idle_tx <INTEGER>
730 # Number of missed packets after
732 # which the session is declared down
733 # (default is 5)
734 multiplier <INTEGER>
735 # Operate in passive mode (default is active)
737 passive
738 # outgoing IPv4 ttl to use (default 255)
740 ttl <INTEGER>
741 # outgoing IPv6 hoplimit to use (default 64)
743 hoplimit <INTEGER>
744 # maximum reduction of ttl/hoplimit
746 # in received packet (default 0)
747 # (255 disables hop count checking)
748 max_hops <INTEGER>
749 # Default tracking weight
751 weight
752 }
753
755 contains subblocks of VRRP script(s), VRRP synchronization group(s),
756 VRRP gratuitous ARP and unsolicited neighbour advert delay group(s) and
757 VRRP instance(s)
758
760 The script will be executed periodically, every <interval> seconds. Its
761 exit code will be recorded for all VRRP instances which monitor it.
762 Note that the script will only be executed if at least one VRRP
763 instance monitors it.
764 The default weight equals 0, which means that any VRRP instance moni‐
766 toring the script will transition to the fault state after <fall> con‐
767 secutive failures of the script. After that, <rise> consecutive suc‐
768 cesses will cause VRRP instances to leave the fault state, unless they
769 are also in the fault state due to other scripts or interfaces that
770 they are tracking.
771 A positive weight means that <rise> successes will add <weight> to the
773 priority of all VRRP instances which monitor it. On the opposite, a
774 negative weight will be subtracted from the initial priority in case of
775 <fall> failures.
776 The syntax for the vrrp script is:
778 # Adds a script to be executed periodically. Its exit code will be
780 # recorded for all VRRP instances and sync groups which are monitoring it.
781 vrrp_script <SCRIPT_NAME> {
782 # path of the script to execute
783 script <STRING>|<QUOTED-STRING>
784 # seconds between script invocations, (default: 1 second)
786 interval <INTEGER>
787 # seconds after which script is considered to have failed
789 timeout <INTEGER>
790 # adjust priority by this weight, (default: 0)
792 weight <INTEGER:-253..253>
793 # required number of successes for OK transition
795 rise <INTEGER>
796 # required number of successes for KO transition
798 fall <INTEGER>
799 # user/group names to run script under.
801 # group default to group of user
802 user USERNAME [GROUPNAME]
803 # assume script initially is in failed state
805 init_fail
806 }
807
809 Adds a file to be monitored. The script will be read whenever it is
810 modified. The value in the file will be recorded for all VRRP instances
811 and sync groups which monitor it. Note that the file will only be read
812 if at least one VRRP instance or sync group monitors it.
813 A value will be read as a number in text from the file. If the weight
815 configured against the track_file is 0, a non-zero value in the file
816 will be treated as a failure status, and a zero value will be treaded
817 as an OK status, otherwise the value will be multiplied by the weight
818 configured in the track_file statement. If the result is less than -253
819 any VRRP instance or sync group monitoring the script will transition
820 to the fault state (the weight can be 254 to allow for a negative value
821 being read from the file).
822 If the vrrp instance or sync group is not the address owner and the
824 result is between -253 and 253, the result will be added to the initial
825 priority of the VRRP instance (a negative value will reduce the prior‐
826 ity), although the effective priority will be limited to the range
827 [1,254].
828 If a vrrp instance using a track_file is a member of a sync group,
830 unless sync_group_tracking_weight is set on the group weight 0 must be
831 set. Likewise, if the vrrp instance is the address owner, weight 0
832 must also be set.
833 The syntax for vrrp track file is :
835 vrrp_track_file <STRING> { # VRRP track file declaration
837 # file to track (weight defaults to 1)
838 file <QUOTED_STRING>
839 # optional default weight
841 weight <-254..254>
842 # create the file and/or initialise the value
844 # This causes VALUE (default 0) to be written to
845 # the specified file at startup if the file doesn't
846 # exist, unless overwrite is specified in which case
847 # any existing file contents will be overwritten with
848 # the specified value.
849 init_file [VALUE] [overwrite]
850 }
851
853 VRRP Sync Group is an extension to VRRP protocol. The main goal is to
854 define a bundle of VRRP instance to get synchronized together so that
855 transition of one instance will be reflected to others group members.
856 In addition there is an enhanced notify feature for fine state transi‐
858 tion catching.
859 You can also define multiple track policy in order to force state tran‐
861 sition according to a third party event such as interface, scripts,
862 file, BFD.
863 Important: for a SYNC group to run reliably, it is vital that all
865 instances in the group are MASTER or that they are all either BACKUP or
866 FAULT. A situation with half instances having higher priority on
867 machine A half others with higher priority on machine B will lead to
868 constant re-elections. For this reason, when instances are grouped, any
869 track scripts/files configured against member VRRP instances will have
870 their tracking weights automatically set to zero, in order to avoid
871 inconsistent priorities across instances.
872 The syntax for vrrp_sync_group is :
874 vrrp_sync_group <STRING> {
876 group {
877 # name of the vrrp_instance (see below)
878 # Set of VRRP_Instance string
879 <STRING>
880 <STRING>
881 ...
882 }
883 # Synchronization group tracking interface, script, file & bfd will
885 # update the status/priority of all VRRP instances which are members
886 # of the sync group.
887 track_interface {
888 eth0
889 eth1
890 eth2 weight <-253..253>
891 ...
892 }
893 # add a tracking script to the sync group (<SCRIPT_NAME> is the name
895 # of the vrrp_script entry) go to FAULT state if any of these go down
896 # if unweighted.
897 track_script {
898 <SCRIPT_NAME>
899 <SCRIPT_NAME> weight <-253..253>
900 }
901 # Files whose state we monitor, value is added to effective priority.
903 # <STRING> is the name of a vrrp_status_file
904 # weight defaults to weight configured in vrrp_track_file
905 track_file {
906 <STRING>
907 <STRING> weight <-254..254>
908 ...
909 }
910 # BFD instances we monitor, value is added to effective priority.
912 # <STRING> is the name of a BFD instance
913 track_bfd {
914 <STRING>
915 <STRING>
916 <STRING> weight <INTEGER: -253..253>
917 ...
918 }
919 # notify scripts and alerts are optional
921 #
922 # filenames of scripts to run on transitions can be unquoted (if
923 # just filename) or quoted (if it has parameters)
924 # The username and groupname specify the user and group
925 # under which the scripts should be run. If username is
926 # specified, the group defaults to the group of the user.
927 # If username is not specified, they default to the
928 # global script_user and script_group to MASTER transition
929 notify_master /path/to_master.sh [username [groupname]]
930 # to BACKUP transition
932 notify_backup /path/to_backup.sh [username [groupname]]
933 # FAULT transition
935 notify_fault "/path/fault.sh VG_1" [username [groupname]]
936 # executed when stopping vrrp
938 notify_stop <STRING>|<QUOTED-STRING> [username [groupname]]
939 # for ANY state transition.
941 # "notify" script is called AFTER the notify_* script(s) and
942 # is executed with 4 additional arguments after the configured
943 # arguments provided by Keepalived:
944 # $(n-3) = "GROUP"|"INSTANCE"
945 # $(n-2) = name of the group or instance
946 # $(n-1) = target state of transition (stop only applies to instances)
947 # ("MASTER"|"BACKUP"|"FAULT"|"STOP")
948 # $(n) = priority value
949 # $(n-3) and $(n-1) are ALWAYS sent in uppercase, and the possible
950 #
951 # strings sent are the same ones listed above
952 # ("GROUP"/"INSTANCE", "MASTER"/"BACKUP"/"FAULT"/"STOP")
953 # (note: STOP is only applicable to instances)
954 notify <STRING>|<QUOTED-STRING> [username [groupname]]
955 # The notify fifo output is the same as the last 4 parameters for the "notify"
957 # script, with the addition of "MASTER_RX_LOWER_PRI" instead of state for an
958 # instance. This is used if a master needs to set some external state, such as
959 # setting a secondary IP address when using Amazon AWS; if another keepalived
960 # has transitioned to master due to a communications break, the lower priority
961 # instance will have taken over the secondary IP address, and the proper master
962 # needs to be able to restore it.
963 # Send email notification during state transition,
965 # using addresses in global_defs above (default no,
966 # unless global smtp_alert/smtp_alert_vrrp set)
967 smtp_alert <BOOL>
968 # DEPRECATED. Use track_interface, track_script and
970 # track_file on vrrp_sync_groups instead.
971 global_tracking
972 # allow sync groups to use differing weights.
974 # This probably WON'T WORK, but is a replacement for
975 # global_tracking in case different weights were used
976 # across different vrrp instances in the same sync group.
977 sync_group_tracking_weight
978 }
979
981 specifies the setting of delays between sending gratuitous ARPs and
982 unsolicited neighbour advertisements. This is intended for when an
983 upstream switch is unable to handle being flooded with ARPs/NAs.
984 Use interface when the limits apply on the single physical interface.
986 Use interfaces when a group of interfaces are linked to the same switch
987 and the limits apply to the switch as a whole.
988 Note: Only one of interface or interfaces should be used per block.
990 If the global vrrp_garp_interval and/or vrrp_gna_interval are set, any
992 interfaces that aren't specified in a garp_group will inherit the
993 global settings.
994 The syntax for garp_group is :
996 garp_group {
998 # Sets the interval between Gratuitous ARP (in seconds, resolution microseconds)
999 garp_interval <DECIMAL>
1000 # Sets the default interval between unsolicited NA (in seconds, resolution microseconds)
1002 gna_interval <DECIMAL>
1003 # The physical interface to which the intervals apply
1005 interface <STRING>
1006 # A list of interfaces accross which the delays are aggregated.
1008 interfaces {
1009 <STRING>
1010 <STRING>
1011 ...
1012 }
1013 }
1014
1016 A VRRP Instance is the VRRP protocol key feature. It defines and con‐
1017 figures VRRP behaviour to run on a specific interface. Each VRRP
1018 Instances are related to a uniq interface.
1019 The syntax for garp_group is :
1021 vrrp_instance <STRING> {
1023 # Initial state, MASTER|BACKUP
1024 # As soon as the other machine(s) come up,
1025 # an election will be held and the machine
1026 # with the highest priority will become MASTER.
1027 # So the entry here doesn't matter a whole lot.
1028 state MASTER
1029 # interface for inside_network, bound by vrrp
1031 interface eth0
1032 # Use VRRP Virtual MAC.
1034 # NOTE: If sysctl net.ipv4.conf.all.rp_filter is set,
1035 # and this vrrp_instance is an IPv4 instance, using
1036 # this option will cause the individual interfaces to be
1037 # updated to the greater of their current setting, and
1038 # all.rp_filter, as will default.rp_filter, and all.rp_filter
1039 # will be set to 0.
1040 # The original settings are restored on termination.
1041 use_vmac [<VMAC_INTERFACE>]
1042 # Send/Recv VRRP messages from base interface instead of
1044 # VMAC interface
1045 vmac_xmit_base
1046 # force instance to use IPv6 (this option is deprecated since
1048 # the virtual ip addresses determine whether IPv4 or IPv6 is used).
1049 native_ipv6
1050 # Ignore VRRP interface faults (default unset)
1052 dont_track_primary
1053 # optional, monitor these as well.
1055 # go to FAULT state if any of these go down if unweighted.
1056 # When a weight is specified in track_interface, instead of setting the vrrp
1057 # instance to the FAULT state in case of failure, its priority will be
1058 # increased by the weight when the interface is up (for positive weights),
1059 # or decreased by the weight's absolute value when the interface is down
1060 # (for negative weights). The weight must be comprised between -254 and +254
1061 # inclusive. 0 is the default behaviour which means that a failure implies a
1062 # FAULT state. The common practice is to use positive weights to count a
1063 # limited number of good services so that the server with the highest count
1064 # becomes master. Negative weights are better to count unexpected failures
1065 # among a high number of interfaces, as it will not saturate even with high
1066 # number of interfaces.
1067 track_interface {
1068 eth0
1069 eth1
1070 eth2 weight <-253..253>
1071 ...
1072 }
1073 # add a tracking script to the interface
1075 # (<SCRIPT_NAME> is the name of the vrrp_track_script entry)
1076 # The same principle as track_interface can be applied to track_script entries,
1077 # except that an unspecified weight means that the default weight declared in
1078 # the script will be used (which itself defaults to 0).
1079 track_script {
1080 <SCRIPT_NAME>
1081 <SCRIPT_NAME> weight <-253..253>
1082 }
1083 # Files whose state we monitor, value is added to effective priority.
1085 # <STRING> is the name of a vrrp_track_file
1086 track_file {
1087 <STRING>
1088 <STRING>
1089 <STRING> weight <-254..254>
1090 ...
1091 }
1092 # BFD instances we monitor, value is added to effective priority.
1094 # <STRING> is the name of a BFD instance
1095 track_bfd {
1096 <STRING>
1097 <STRING>
1098 <STRING> weight <INTEGER: -253..253>
1099 ...
1100 }
1101 # default IP for binding vrrpd is the primary IP
1103 # on interface. If you want to hide the location of vrrpd,
1104 # use this IP as src_addr for multicast or unicast vrrp
1105 # packets. (since it's multicast, vrrpd will get the reply
1106 # packet no matter what src_addr is used).
1107 # optional
1108 mcast_src_ip <IPADDR>
1109 unicast_src_ip <IPADDR>
1110 # if the configured src_ip doesn't exist or is removed put the
1112 # instance into fault state
1113 track_src_ip
1114 # VRRP version to run on interface
1116 # default is global parameter vrrp_version.
1117 version <2 or 3>
1118 # Do not send VRRP adverts over a VRRP multicast group.
1120 # Instead it sends adverts to the following list of
1121 # ip addresses using unicast. It can be cool to use
1122 # the VRRP FSM and features in a networking
1123 # environment where multicast is not supported!
1124 # IP addresses specified can be IPv4 as well as IPv6.
1125 unicast_peer {
1126 <IPADDR>
1127 ...
1128 }
1129 # The checksum calculation when using VRRPv3 changed after v1.3.6.
1131 # Setting this flag forces the old checksum algorithm to be used
1132 # to maintain backward compatibility, although keepalived will
1133 # attempt to maintain compatibility anyway if it sees an old
1134 # version checksum. Sepcifying never will turn off auto detection
1135 # of old checksums. [This option may not be enabled - check output
1136 # of `keepalived -v` for OLD_CHKSUM_COMPAT.]
1137 old_unicast_checksum [never]
1138 # interface specific settings, same as global parameters.
1140 # default to global parameters
1141 garp_master_delay 10
1142 garp_master_repeat 1
1143 garp_lower_prio_delay 10
1144 garp_lower_prio_repeat 1
1145 garp_master_refresh 60
1146 garp_master_refresh_repeat 2
1147 garp_interval 100
1148 gna_interval 100
1149 # If a lower priority advert is received, don't send another advert.
1151 # This causes adherence to the RFCs (defaults to global
1152 # vrrp_lower_priority_dont_send_advert).
1153 lower_prio_no_advert [<BOOL>]
1154 # If we are master and receive a higher priority advert, send an advert
1156 # (which will be lower priority than the other master), before we transition
1157 # to backup. This means that if the other master has garp_lower_prio_repeat
1158 # set, it will resend garp messages. This is to get around the problem of
1159 # their having been two simultaneous masters, and the last GARP
1160 # messages seen were from us.
1161 higher_prio_send_advert [<BOOL>]
1162 # arbitrary unique number from 0 to 255
1164 # used to differentiate multiple instances of vrrpd
1165 # running on the same NIC (and hence same socket).
1166 virtual_router_id 51
1167 # for electing MASTER, highest priority wins.
1169 # to be MASTER, make this 50 more than on other machines.
1170 priority 100
1171 # VRRP Advert interval in seconds (e.g. 0.92) (use default)
1173 advert_int 1
1174 # Note: authentication was removed from the VRRPv2 specification by
1176 # RFC3768 in 2004.
1177 # Use of this option is non-compliant and can cause problems; avoid
1178 # using if possible, except when using unicast, where it can be helpful.
1179 authentication {
1180 # PASS||AH
1181 # PASS - Simple password (suggested)
1182 # AH - IPSEC (not recommended))
1183 auth_type PASS
1184 # Password for accessing vrrpd.
1186 # should be the same on all machines.
1187 # Only the first eight (8) characters are used.
1188 auth_pass 1234
1189 }
1190 # addresses add|del on change to MASTER, to BACKUP.
1192 # With the same entries on other machines,
1193 # the opposite transition will be occurring.
1194 # For virutal_ipaddress, virtual_ipaddress_excluded,
1195 # virtual_routes and virtual_rules most of the options
1196 # match the options of the command ip address/route/rule add.
1197 # The track_group option only applies to static addresses/routes/rules.
1198 # no_track is specific to keepalived and means that the
1199 # vrrp_instance will not transition out of master state
1200 # if the address/route/rule is deleted and the address/route/rule
1201 # will not be reinstated until the vrrp instance next transitions
1202 # to master.
1203 # <LABEL>: is optional and creates a name for the alias.
1204 For compatibility with "ifconfig", it should
1205 be of the form <realdev>:<anytext>, for example
1206 eth0:1 for an alias on eth0.
1207 # <SCOPE>: ("site"|"link"|"host"|"nowhere"|"global")
1208 virtual_ipaddress {
1209 <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
1210 [label <LABEL>] [peer <IPADDR>] [home]
1211 [-nodad] [mngtmpaddr] [noprefixroute]
1212 [autojoin] [no_track]
1213 192.168.200.17/24 dev eth1
1214 192.168.200.18/24 dev eth2 label eth2:1
1215 }
1216 # VRRP IP excluded from VRRP optional.
1218 # For cases with large numbers (eg 200) of IPs
1219 # on the same interface. To decrease the number
1220 # of addresses sent in adverts, you can exclude
1221 # most IPs from adverts.
1222 # The IPs are add|del as for virtual_ipaddress.
1223 # Can also be used if you want to be able to add
1224 # a mixture of IPv4 and IPv6 addresses, since all
1225 # addresses in virtual_ipaddress must be of the
1226 # same family.
1227 virtual_ipaddress_excluded {
1228 <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
1229 [label <LABEL>] [peer <IPADDR>] [home]
1230 [-nodad] [mngtmpaddr] [noprefixroute]
1231 [autojoin] [no_track]
1232 <IPADDR>[/<MASK>] ...
1233 ...
1234 }
1235 # Set the promote_secondaries flag on the interface to stop other
1237 # addresses in the same CIDR being removed when 1 of them is removed
1238 # For example if 10.1.1.2/24 and 10.1.1.3/24 are both configured on an
1239 # interface, and one is removed, unless promote_secondaries is set on
1240 # the interface the other address will also be removed.
1241 prompte_secondaries
1242 # routes add|del when changing to MASTER, to BACKUP.
1244 # See static_routes for more details
1245 virtual_routes {
1246 # src <IPADDR> [to] <IPADDR>/<MASK> via|gw <IPADDR>
1247 # [or <IPADDR>] dev <STRING> scope <SCOPE> table <TABLE>
1248 src 192.168.100.1 to 192.168.109.0/24 via 192.168.200.254 dev eth1
1249 192.168.110.0/24 via 192.168.200.254 dev eth1
1250 192.168.111.0/24 dev eth2 no_track
1251 192.168.112.0/24 via 192.168.100.254
1252 192.168.113.0/24 via 192.168.200.254 or 192.168.100.254 dev eth1
1253 blackhole 192.168.114.0/24
1254 0.0.0.0/0 gw 192.168.0.1 table 100 # To set a default gateway into table 100.
1255 }
1256 # rules add|del when changing to MASTER, to BACKUP
1258 # See static_rules for more details
1259 virtual_rules {
1260 from 192.168.2.0/24 table 1
1261 to 192.168.2.0/24 table 1 no_track
1262 }
1263 # VRRPv3 has an Accept Mode to allow the virtual router when not the
1265 # address owner to receive packets addressed to a VIP. This is the default
1266 # setting unless strict mode is set. As an extension, this also works for
1267 # VRRPv2 (RFC 3768 doesn't define an accept mode).
1268 # --
1269 # Accept packets to non address-owner
1270 accept
1271 # Drop packets to non address-owner.
1273 no_accept
1274 # VRRP will normally preempt a lower priority machine when a higher priority
1276 # machine comes online. "nopreempt" allows the lower priority machine to
1277 # maintain the master role, even when a higher priority machine comes back
1278 # online.
1279 # NOTE: For this to work, the initial state of this
1280 # entry must be BACKUP.
1281 # --
1282 nopreempt
1283 # for backwards compatibility
1285 preempt
1286 # See description of global vrrp_skip_check_adv_addr, which
1288 # sets the default value. Defaults to vrrp_skip_check_adv_addr
1289 skip_check_adv_addr [on|off|true|false|yes|no]
1290 # See description of global vrrp_strict
1292 # If vrrp_strict is not specified, it takes the value of vrrp_strict
1293 # If strict_mode without a parameter is specified, it defaults to on
1294 strict_mode [on|off|true|false|yes|no]
1295 # Seconds after startup or seeing a lower priority master until preemption
1297 # (if not disabled by "nopreempt").
1298 # Range: 0 (default) to 1000 (e.g. 4.12)
1299 # NOTE: For this to work, the initial state of this
1300 # entry must be BACKUP.
1301 preempt_delay 300 # waits 5 minutes
1302 # Debug level, not implemented yet.
1304 # LEVEL is a number in the range 0 to 4
1305 debug <LEVEL>
1306 # notify scripts, alert as above
1308 notify_master <STRING>|<QUOTED-STRING> [username [groupname]]
1309 notify_backup <STRING>|<QUOTED-STRING> [username [groupname]]
1310 notify_fault <STRING>|<QUOTED-STRING> [username [groupname]]
1311 # executed when stopping vrrp
1312 notify_stop <STRING>|<QUOTED-STRING> [username [groupname]]
1313 notify <STRING>|<QUOTED-STRING> [username [groupname]]
1314 # The notify_master_rx_lower_pri script is executed if a master
1316 # receives an advert with priority lower than the master's advert.
1317 notify_master_rx_lower_pri <STRING>|<QUOTED-STRING> [username [groupname]]
1318 # Send SMTP alerts
1320 smtp_alert <BOOL>
1321 # Set socket receive buffer size (see global_defs
1323 # vrrp_rx_bufs_policy for explanation)
1324 kernel_rx_buf_size
1325 }
1326
1328 contains subblocks of Virtual server group(s) and Virtual server(s)
1329 The subblocks contain arguments for configuring Linux IPVS (LVS) fea‐
1331 ture. Knowledge of ipvsadm(8) will be helpful here. Configuring LVS is
1332 achieved by defining virtual server group, virtual server and option‐
1333 ally SSL configuration. Every virtual server define a set of real
1334 server, you can attach healthcheckers to each real server. Keepalived
1335 will then lead LVS operation by dynamically maintaining topology.
1336 Note: Where an option can be configured for a virtual server, real
1338 server, and possibly checker, the virtual server setting is the default
1339 for real servers, and the real server setting is the default for check‐
1340 ers.
1341 Note: Tunnelled real/sorry servers can differ from the address family
1343 of the virtual server and non tunnelled real/sorry servers, which all
1344 have to be the same. If a virtual server uses a fwmark, and all the
1345 real/sorry servers are tunnelled, the address family of the virtual
1346 server will be the same as the address family of the real/sorry servers
1347 if they are all the same, otherwise it will default to IPv4 (use
1348 ip_family inet6 to override this).
1349
1351 This feature offers a way to simplify your configuration by factorizing
1352 virtual server definitions. If you need to define a bunch of virtual
1353 server with exactly the same real server topology then this feature
1354 will make your configuration much more readable and will optimize
1355 healthchecking task by only spawning one healthchecking where multiple
1356 virtual server declaration will spawn a dedicated healthchecker for
1357 every real server which will waste system ressources.
1358 The syntax for virtual_server_group is :
1360 # to belong to multiple virtual services
1362 # and to only be health checked once.
1363 # Only for very large LVSs.
1364 virtual_server_group <STRING> {
1365 # Virtual IP Address and Port
1366 <IPADDR> <PORT>
1367 <IPADDR> <PORT>
1368 ...
1369 # <IPADDR RANGE> has the form
1370 # XXX.YYY.ZZZ.WWW-VVV eg 192.168.200.1-10
1371 # range includes both .1 and .10 address
1372 <IPADDR RANGE> <PORT># VIP range VPORT
1373 <IPADDR RANGE> <PORT>
1374 ...
1375 # Firewall Mark (fwmark)
1376 fwmark <INTEGER>
1377 fwmark <INTEGER>
1378 ...
1379 }
1380
1382 A virtual_server can be a declaration of one of <IPADDR> <PORT> ,
1383 fwmark <INTEGER> or group <STRING>
1384 The syntax for virtual_server is :
1386 virtual_server <IPADDR> <PORT> |
1388 virtual_server fwmark <INTEGER> |
1389 virtual_server group <STRING> {
1390 # delay timer for checker polling
1391 delay_loop <INTEGER>
1392 # LVS scheduler
1394 lvs_sched rr|wrr|lc|wlc|lblc|sh|mh|dh|fo|ovf|lblcr|sed|nq
1395 # Enable hashed entry
1397 hashed
1398 # Enable flag-1 for scheduler (-b flag-1 in ipvsadm)
1399 flag-1
1400 # Enable flag-2 for scheduler (-b flag-2 in ipvsadm)
1401 flag-2
1402 # Enable flag-3 for scheduler (-b flag-3 in ipvsadm)
1403 flag-3
1404 # Enable sh-port for sh scheduler (-b sh-port in ipvsadm)
1405 sh-port
1406 # Enable sh-fallback for sh scheduler (-b sh-fallback in ipvsadm)
1407 sh-fallback
1408 # Enable mh-port for mh scheduler (-b mh-port in ipvsadm)
1409 mh-port
1410 # Enable mh-fallback for mh scheduler (-b mh-fallback in ipvsadm)
1411 mh-fallback
1412 # Enable One-Packet-Scheduling for UDP (-O in ipvsadm)
1413 ops
1414 # Default LVS forwarding method
1416 lvs_method NAT|DR|TUN
1417 # LVS persistence engine name
1418 persistence_engine <STRING>
1419 # LVS persistence timeout in seconds, default 6 minutes
1420 persistence_timeout [<INTEGER>]
1421 # LVS granularity mask (-M in ipvsadm)
1422 persistence_granularity <NETMASK>
1423 # L4 protocol
1424 protocol TCP|UDP|SCTP
1425 # If VS IP address is not set,
1426 # suspend healthchecker's activity
1427 ha_suspend
1428 # Send email notification during quorum up/down transition,
1430 # using addresses in global_defs above (default no,
1431 # unless global smtp_alert/smtp_alert_checker set)
1432 smtp_alert <BOOL>
1433 # Default VirtualHost string for HTTP_GET or SSL_GET
1435 # eg virtualhost www.firewall.loc
1436 # Overridden by virtualhost config of real server or checker
1437 virtualhost <STRING>
1438 # On daemon startup assume that all RSs are down
1440 # and healthchecks failed. This helps to prevent
1441 # false positives on startup. Alpha mode is
1442 # disabled by default.
1443 alpha
1444 # On daemon shutdown consider quorum and RS
1446 # down notifiers for execution, where appropriate.
1447 # Omega mode is disabled by default.
1448 omega
1449 # Minimum total weight of all live servers in
1451 # the pool necessary to operate VS with no
1452 # quality regression. Defaults to 1.
1453 quorum <INTEGER>
1454 # Tolerate this much weight units compared to the
1456 # nominal quorum, when considering quorum gain
1457 # or loss. A flap dampener. Defaults to 0.
1458 hysteresis <INTEGER>
1459 # Script to execute when quorum is gained.
1461 quorum_up <STRING>|<QUOTED-STRING> [username [groupname]]
1462 # Script to execute when quorum is lost.
1464 quorum_down <STRING>|<QUOTED-STRING> [username [groupname]]
1465 # IP family for a fwmark service (optional)
1467 ip_family inet|inet6
1468 # setup realserver(s)
1470 # RS to add to LVS topology when the quorum isn't achieved.
1472 # If a sorry server is configured, all real servers will
1473 # be brought down when the quorum is not achieved.
1474 sorry_server <IPADDR> <PORT>
1475 # applies inhibit_on_failure behaviour to the sorry_server
1476 sorry_server_inhibit
1477 # Sorry server LVS forwarding method
1478 sorry_server_lvs_method NAT|DR|TUN
1479 # Retry count to make additional checks if check
1481 # of an alive server fails. Default: 1 unless specified below
1482 retry <INTEGER>
1483 # delay before retry
1485 delay_before_retry <INTEGER>
1486 # Optional random delay to start the initial check
1488 # for maximum N seconds.
1489 # Useful to scatter multiple simultaneous
1490 # checks to the same RS. Enabled by default, with
1491 # the maximum at delay_loop. Specify 0 to disable
1492 warmup <INTEGER>
1493 # delay timer for checker polling
1495 delay_loop <INTEGER>
1496 # Set weight to 0 when healthchecker detects failure
1498 inhibit_on_failure
1499 # one entry for each realserver
1501 real_server <IPADDR> <PORT> {
1502 # relative weight to use, default: 1
1503 weight <INTEGER>
1504 # LVS forwarding method
1505 lvs_method NAT|DR|TUN
1506 # Script to execute when healthchecker
1508 # considers service as up.
1509 notify_up <STRING>|<QUOTED-STRING> [username [groupname]]
1510 # Script to execute when healthchecker
1511 # considers service as down.
1512 notify_down <STRING>|<QUOTED-STRING> [username [groupname]]
1513 # maximum number of connections to server
1515 uthreshold <INTEGER>
1516 # minimum number of connections to server
1517 lthreshold <INTEGER>
1518 # Send email notification during state transition,
1520 # using addresses in global_defs above (default yes,
1521 # unless global smtp_alert/smtp_alert_checker set)
1522 smtp_alert <BOOL>
1523 # Default VirtualHost string for HTTP_GET or SSL_GET
1525 # eg virtualhost www.firewall.loc
1526 # Overridden by virtualhost config of a checker
1527 virtualhost <STRING>
1528 alpha <BOOL> # see above
1530 retry <INTEGER> # see above
1531 delay_before_retry <INTEGER> # see above
1532 warmup <INTEGER> # see above
1533 delay_loop <INTEGER> # see above
1534 inhibit_on_failure <BOOL> # see above
1535 log_all_failures <BOOL> # log all failures when checker up
1536 # healthcheckers. Can be multiple of each type
1538 # HTTP_GET|SSL_GET|TCP_CHECK|SMTP_CHECK|DNS_CHECK|MISC_CHECK|BFD_CHECK
1539 # All checkers have the following options, except MISC_CHECK
1541 # which only has options alpha onwards, and BFD_CHECK which has none
1542 # of the standard options:
1543 CHECKER_TYPE {
1544 # ======== generic connection options
1545 # Optional IP address to connect to.
1546 # The default is the realserver IP
1547 connect_ip <IPADDR>
1548 # Optional port to connect to
1550 # The default is the realserver port
1551 connect_port <PORT>
1552 # Optional address to use to
1554 # originate the connection
1555 bindto <IPADDR>
1556 # Optional interface to use; needed if
1558 # the bindto address is IPv6 link local
1559 bind_if <IFNAME>
1560 # Optional source port to
1562 # originate the connection from
1563 bind_port <PORT>
1564 # Optional connection timeout in seconds.
1566 # The default is 5 seconds
1567 connect_timeout <INTEGER>
1568 # Optional fwmark to mark all outgoing
1570 # checker packets with
1571 fwmark <INTEGER>
1572 alpha <BOOL> # see above
1574 retry <INTEGER> # see above
1575 delay_before_retry <INTEGER> # see above
1576 warmup <INTEGER> # see above
1577 delay_loop <INTEGER> # see above
1578 inhibit_on_failure <BOOL> # see above
1579 }
1580 # The following options are additional checker specific
1582 # HTTP and SSL healthcheckers
1584 HTTP_GET|SSL_GET {
1585 # An url to test
1586 # can have multiple entries here
1587 url {
1588 #eg path / , or path /mrtg2/
1589 path <STRING>
1590 # healthcheck needs status_code
1591 # or status_code and digest
1592 # Digest computed with genhash
1593 # eg digest 9b3a0c85a887a256d6939da88aabd8cd
1594 digest <STRING>
1595 # status code returned in the HTTP header
1596 # eg status_code 200. Default is any 2xx value
1597 status_code <INTEGER>
1598 # VirtualHost string. eg virtualhost www.firewall.loc
1599 # If not set, uses virtualhost from real or virtual server
1600 virtualhost <STRING>
1601 # Regular expression to search returned data against.
1602 # A failure to match causes the check to fail.
1603 regex <STRING>
1604 # Reverse the sense of the match, so a match of the
1605 # returned text causes the check to fail.
1606 regex_no_match
1607 # Space separated list of options for regex.
1608 # See man pcre2api for a description of the options.
1609 # The following option are supported:
1610 # allow_empty_class alt_bsux auto_callout caseless
1611 # dollar_endonly dotall dupnames extended firstline
1612 # match_unset_backref multiline never_ucp never_utf
1613 # no_auto_capture no_auto_possess no_dotstar_anchor
1614 # no_start_optimize ucp ungreedy utf never_backslash_c
1615 # alt_circumflex alt_verbnames use_offset_limit
1616 regex_options <OPTIONS>
1617 # For complicated regular expressions a larger stack
1618 # may be needed, and this allows the start and maximum
1619 # sizes in bytes to be specified. For more details see
1620 # the documentation for pcre2_jit_stack_create()
1621 regex_stack <START> <MAX>
1622 # The minimum offset into the returned data to start
1623 # checking for the regex pattern match. This can save
1624 # processing time if the returned data is large.
1625 regex_min_offset <OFFSET>
1626 # The maximum offset into the returned data for the
1627 # start of the subject match.
1628 regex_max_offset <OFFSET>
1629 }
1630 }
1631 SSL_GET {
1633 # when provided, send Server Name Indicator during SSL handshake
1634 enable_sni
1635 }
1636 # TCP healthchecker
1638 TCP_CHECK {
1639 # No additional options
1640 }
1641 # SMTP healthchecker
1643 SMTP_CHECK {
1644 # Optional string to use for the SMTP HELO request
1645 helo_name <STRING>|<QUOTED-STRING>
1646 }
1647 # DNS healthchecker
1649 DNS_CHECK {
1650 # The retry default is 3.
1651 # DNS query type
1653 # A|NS|CNAME|SOA|MX|TXT|AAAA
1654 # The default is SOA
1655 type <STRING>
1656 # Domain name to use for the DNS query
1658 # The default is . (dot)
1659 name <STRING>
1660 }
1661 # MISC healthchecker, run a program
1663 MISC_CHECK {
1664 # The retry default is 0.
1665 # External script or program
1667 misc_path <STRING>|<QUOTED-STRING>
1668 # Script execution timeout
1669 misc_timeout <INTEGER>
1670 # If set, the exit code from healthchecker is used
1672 # to dynamically adjust the weight as follows:
1673 # exit status 0: svc check success, weight
1674 # unchanged.
1675 # exit status 1: svc check failed.
1676 # exit status 2-255: svc check success, weight
1677 # changed to 2 less than exit status.
1678 # (for example: exit status of 255 would set
1679 # weight to 253)
1680 # NOTE: do not have more than one dynamic MISC_CHECK per real_server.
1681 misc_dynamic
1682 # Specify the username/groupname that the script should
1684 # be run under.
1685 # If GROUPNAME is not specified, the group of the user
1686 # is used
1687 user USERNAME [GROUPNAME]
1688 }
1689 # BFD instance name to check
1691 BFD_CHECK {
1692 name <STRING>
1693 }
1694 }
1695 }
1696 # Parameters used for SSL_GET check.
1698 # If none of the parameters are specified, the SSL context
1699 # will be auto generated.
1700 SSL {
1701 # Password
1702 password <STRING>
1703 # CA file
1704 ca <STRING>
1705 # Certificate file
1706 certificate <STRING>
1707 # Key file
1708 key <STRING>
1709 }
1710
1712 Configuration parser has been extended to support advanced features
1713 such as conditional configuration and parameter substitution. These
1714 features are very usefull for any scripted env where configuration tem‐
1715 plate are generated (datacenters).
1716
1718 The config-id defaults to the first part of the node name as returned
1719 by uname, and can be overridden with the -i or --config-id command line
1720 option.
1721 Any configuration line starting with '@' is a conditional configuration
1723 line. The word immediately following (i.e. without any space) the '@'
1724 character is compared against the config-id, and if they don't match,
1725 the configuration line is ignored.
1726 Alternatively, '@^' is a negative comparison, so if the word immedi‐
1728 ately following does NOT match the config-id, the configuration line IS
1729 included.
1730 The purpose of this is to allow a single configuration file to be used
1732 for multiple systems, where the only differences are likely to be the
1733 router_id, vrrp instance priorities, and possibly interface names and
1734 unicast addresses.
1735 For example:
1737 global_defs {
1739 @main router_id main_router
1740 @backup router_id backup_router
1741 }
1742 ...
1743 vrrp_instance VRRP {
1744 ...
1745 @main unicast_src_ip 1.2.3.4
1746 @backup unicast_src_ip 1.2.3.5
1747 @backup2 unicast_src_ip 1.2.3.6
1748 unicast_peer {
1749 @^main 1.2.3.4
1750 @^backup 1.2.3.5
1751 @^backup2 1.2.3.6
1752 }
1753 ...
1754 }
1755 If keepalived is invoked with -i main, then the router_id will be set
1757 to main_router, if invoked with -i backup, then backup_router, if not
1758 invoked with -i, or with -i anything else, then the router_id will not
1759 be set. The unicast peers for main will be 1.2.3.5 and 1.2.3.6.
1760
1762 Substitutable parameters can be specified. The format for defining a
1763 parameter is:
1764 $PARAMETER=VALUE
1766 where there must be no space before the '=' and only whitespace may
1768 preceed to '$'. Empty values are allowed.
1769 Parameter names can be made up of any combination of A-Za-z0-9 and _,
1771 but cannot start with a digit. Parameter names starting with an under‐
1772 score should be considered reserved names that keepalived will define
1773 for various pre-defined options.
1774 After a parameter is defined, any occurrence of $PARAMETER followed by
1776 whitespace, or any occurrence of ${PARAMETER} (which need not be fol‐
1777 lowed by whitespace) will be replaced by VALUE.
1778 Replacement is recursive, so that if a parameter value itself includes
1780 a replaceable parameter, then after the first substitution, the parame‐
1781 ter in the value will then be replaced; the substitution is done at
1782 replacement time and not at definition time, so for example:
1783 $ADDRESS_BASE=10.2.${ADDRESS_BASE_SUB}
1785 $ADDRESS_BASE_SUB=0
1786 ${ADDRESS_BASE}.100/32
1787 $ADDRESS_BASE_SUB=10
1788 ${ADDRESS_BASE}.100/32
1789 will produce:
1791 10.2.0.100/32
1792 10.2.10.100/32
1793 Note in the above examples the use of both ADDRESS_BASE and
1795 ADDRESS_BASE_SUB required braces ({}) since the parameters were not
1796 followed by whitespace (after the first substitution which produced
1797 10.2.${ADDRESS_BASE_SUB}.100/32 the parameter is still not followed by
1798 whitespace).
1799 If a parameter is not defined, it will not be replaced at all, so for
1801 example ${UNDEF_PARAMETER} will remain in the configuration if it is
1802 undefined; this means that existing configuration that contains a '$'
1803 character (for example in a script definition) will not be changed so
1804 long as no new parameter definitions are added to the configuration.
1805 Parameter substitution works in conjunction with conditional configura‐
1807 tion. For example:
1808 @main $PRIORITY=240
1810 @backup $PRIORITY=200
1811 ...
1812 vrrp_instance VI_0 {
1813 priority $PRIORITY
1814 }
1815 will produce:
1817 ...
1818 vrrp_instance VI_0 {
1819 priority 240
1820 }
1821 if the config_id is main.
1822 $IF_MAIN=@main
1824 $IF_MAIN priority 240
1825 will produce:
1827 priority 240
1828 if the config_id is main and nothing if the config_id is not main,
1829 although why anyone would want to use this rather than simply the
1830 following is not known (but still possible):
1831 @main priority 240
1832 Multiline definitions are also supported, but when used there must be
1834 nothing on the line after the parameter name. A multiline definition is
1835 specified by ending each line except the last with a '\' character.
1836 Example:
1838 $INSTANCE= \
1839 vrrp_instance VI_${NUM} { \
1840 interface eth0.${NUM} \
1841 use_vmac vrrp${NUM}.1 \
1842 virtual_router_id 1 \
1843 @high priority 130 \
1844 @low priority 120 \
1845 advert_int 1 \
1846 virtual_ipaddress { \
1847 10.0.${NUM}.254/24 \
1848 } \
1849 track_script { \
1850 offset_instance_${NUM} \
1851 } \
1852 }
1853 $NUM=0
1855 $INSTANCE
1856 $NUM=1
1858 $INSTANCE
1859 The use of multiline definitions can be nested.
1861 Example:
1863 $RS= \
1864 real_server 192.168.${VS_NUM}.${RS_NUM} 80 { \
1865 weight 1 \
1866 inhibit_on_failure \
1867 smtp_alert \
1868 MISC_CHECK { \
1869 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" \
1870 } \
1871 MISC_CHECK { \
1873 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" \
1874 } \
1875 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" \
1877 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" \
1879 }
1881 $VS= \
1883 virtual_server 10.0.${VS_NUM}.4 80 { \
1884 quorum 2 \
1885 quorum_up "${_PWD}/scripts/notify.sh VS_notify.${INST} UP 10.0.${VS_NUM}.4:80" \
1886 quorum_down "${_PWD}/scripts/notify.sh VS_notify.${INST} DOWN 10.0.${VS_NUM}.4:80" \
1887 $RS_NUM=1 \
1888 $RS \
1889 $RS_NUM=2 \
1890 $RS \
1891 $RS_NUM=3 \
1892 $RS \
1893 }
1894 $VS_NUM=0
1896 $ALPHA=alpha
1897 $VS
1898 $VS_NUM=1
1900 $ALPHA=
1901 $VS
1902 The above will create 2 virtual servers, each with 3 real servers
1904
1906 The following pre-defined definitions are defined:
1907 ${_PWD} : The directory of the current configuration file (this can be
1909 changed if using the include directive).
1910 ${_INSTANCE} : The instance name (as defined by the -i option, defaults
1911 to hostname).
1912 Additional pre-defined definitions will be added as their need is iden‐
1914 tified. It will normally be quite straightforward to add additional
1915 pre-defined definitions, so if you need one, or have a good idea for
1916 one, then raise an issue at
1917 https://github.com/acassen/keepalived/issues requesting it.
1918
1920 A line starting ~SEQ(var, start, step, end) will cause the remainder of
1921 the line to be processed multiple times, with the variable $var set
1922 initially to start, and then $var will be incremented by step repeat‐
1923 edly, terminating when it is greater than end. step may be omitted, in
1924 which case it defaults to 1 or -1, depending on whether end is greater
1925 or less than start. start may also be omitted, in which case it
1926 defaults to 1 if end > 0 or -1 if end < 0. so, for example:
1927 ~SEQ(SUBNET, 0, 3) ip_address 10.0.$SUBNET.1
1929 would produce:
1931 ip_address 10.0.0.1
1932 ip_address 10.0.1.1
1933 ip_address 10.0.2.1
1934 ip_address 10.0.3.1
1935 There can be multiple ~SEQ elements on a line, so for example:
1937 $VI4= \
1939 vrrp_track_file offset_instance_4.${IF}.${NUM}.${ID} { \
1940 file "${_PWD}/679/track_files/4.${IF}.${NUM}.${ID}" \
1941 weight -100 \
1942 } \
1943 vrrp_instance vrrp4.${IF}.${NUM}.${ID} { \
1944 interface bond${IF}.${NUM} \
1945 use_vmac vrrp4.${IF}.${NUM}.${ID} \
1946 virtual_router_id ${ID} \
1947 priority 130 \
1948 virtual_ipaddress { \
1949 10.${IF}.${NUM}.${ID}/24 \
1950 } \
1951 track_file { \
1952 offset_instance_4.${IF}.${NUM}.${ID} \
1953 } \
1954 }
1955 ~SEQ(IF,0,7) ~SEQ(NUM,0,31) ~SEQ(ID,1,254) $VI4
1957 will produce 65024 vrrp instances with names from vrrp4.0.0.1 through to
1959 vrrp4.7.31.254.
1960
1962 Initial by Joseph Mack. Extensive updates by Alexandre Cassen & Quentin
1963 Armitage.
1964
1966 ipvsadm(8), ip --help.
1967Keepalived 2018-08-10 keepalived.conf(5)