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