1keepalived.conf(5) Keepalived Configuration's Manual keepalived.conf(5)
2
3
4
6 keepalived.conf - configuration file for Keepalived
7
9 This documentation MUST be considered as THE exhaustive source of in‐
10 formation in order to configure Keepalived. This documenation is sup‐
11 ported and maintained by Keepalived Core-Team.
12
14 keepalived.conf is the configuration file which describes all the
15 Keepalived keywords. Keywords are placed in hierarchies of blocks and
16 subblocks, each layer being delimited by '{' and '}' pairs.
17
18 Comments start with '#' or '!' to the end of the line and can start
19 anywhere in a line.
20
21 The keyword 'include' and variants allow inclusion of other configura‐
22 tion files from within the main configuration file, or from subse‐
23 quently included files.
24
25 The format of the include directive is:
26
27 include FILENAME
28
29 FILENAME can be a fully qualified or relative pathname, and can include
30 wildcards, including csh style brace expressions such as
31 "{foo/{,cat,dog},bar}" if glob() supports them.
32
33 After opening an included file, the current directory is set to the di‐
34 rectory of the file itself, so any relative paths included from a file
35 are relative to the directory of the including file itself.
36
37 The include variants add additional include checks to the current in‐
38 clude_check level (see below) The variants are:
39 includer FILENAME - same as include_check readable
40 includem FILENAME - same as include_check match
41 includew FILENAME - same as include_check wildcard_match
42 includeb FILENAME - same as include_check brace_match
43 includea FILENAME - all include_check checks
44
45 NOTE: If the libc glob() function does not support GLOB_ALTDIRFUNC
46 (e.g. Musl libc as on Alpine Linux etc.), then only includea, includer
47 and includew of the above options will work.
48
49 Why do we want to allow errors? Suppose a configuration has optional
50 files in /etc/keepalived/conf.d, then include_/etc/keepalived/conf.d/*
51 could be specified, but it should not error if there are no files in
52 the directory; in this case includer should be used. Otherwise it is
53 sensible to use includea.
54
55 include handling will not work with if the include line uses condi‐
56 tional configuration or parameter substitution, since the detection of
57 the include keywords is done before the processing on conditional con‐
58 figuration and parameter substitution.
59
60 The basic include keyword is retained for backward compatibility, since
61 it does not produce config errors if files could not be opened etc.
62
64 <BOOL> is one of on|off|true|false|yes|no
65 <TIMER> is a time value in seconds, including fractional seconds, e.g.
66 2.71828 or 3; resolution of timer is micro-seconds.
67
69 There are three classes of scripts can be configured to be executed.
70
71 (a) Notify scripts that are run when a vrrp instance or vrrp group
72 changes state, or a virtual server quorum changes between up and down.
73
74 (b) vrrp tracking scripts that will cause vrrp instances to go down it
75 they exit a non-zero exist status, or if a weight is specified will add
76 or subtract the weight to/from the priority of that vrrp instance.
77
78 (c) LVS checker misc scripts that will cause a real server to be con‐
79 figured down if they exit with a non-zero status.
80
81 By default the scripts will be executed by user keepalived_script if
82 that user exists, or if not by root, but for each script the user/group
83 under which it is to be executed can be specified.
84
85 There are significant security implications if scripts are executed
86 with root privileges, especially if the scripts themselves are modifi‐
87 able or replaceable by a non root user. Consequently, security checks
88 are made at startup to ensure that if a script is executed by root,
89 then it cannot be modified or replaced by a non root user.
90
91 All scripts should be written so that they will terminate on receipt of
92 a SIGTERM signal. Scripts will be sent SIGTERM if their parent termi‐
93 nates, or it is a script that keepalived is awaiting its exit status
94 and it has run for too long.
95
97 Quoted strings are specified between " or ' characters and strings are
98 delimited by whitespace. In the examples below the ´ characters are not
99 part of the strings and should not be specified:
100
101 ´abcd" efg h jkl "mnop´
102
103 will be the single string:
104
105 ´abcd efg h jkl mnop´
106
107 whereas:
108
109 ´abcd "efg h jkl" mnop´
110
111 will be the three strings:
112
113 ´abcd´, ´efg h jkl´ and ´mnop´
114
115 i.e. the " and ' characters are removed and any intervening whitespace is retained.
116
117 Quoted strings can also have escaped characters, like the shell. \a, \b, \E, \f,
118 \n, \r, \t, \v, \nnn and \xXX (where nnn is up to 3 octal digits, and XX is any
119 sequence of hex digits) and \cC (which produces the control version of
120 character C) are all supported. \C for any other character C is just
121 treated as an escaped version of character C, so \\ is a \ character and
122 \" will be a " character, but it won't start or terminate a quoted string.
123
124 For specifying scripts with parameters, unquoted spaces will separate the parameters.
125 If it is required for a parameter to contain a space, it should be enclosed in single
126 quotes (').
127
128
130 Traditionally the configuration file parser has not been one of the
131 strengths of keepalived. Lot of efforts have been put to correct this
132 even if this is not the primal goal of the project.
133
135 Keepalived configuration file is articulated around a set of configura‐
136 tion blocks. Each block is focusing and targetting a specific daemon
137 family feature. These features are:
138
139 GLOBAL CONFIGURATION
140
141 BFD CONFIGURATION
142
143 VRRPD CONFIGURATION
144
145 LVS CONFIGURATION
146
148 contains subblocks of Global definitions, Linkbeat interfaces, Inter‐
149 face up/down transition delays, Static track groups, Static addresses,
150 Static routes, and Static rules
151
153 # Following are global daemon facilities for running
154 # keepalived in a separate network namespace:
155 # --
156 # Set the network namespace to run in.
157 # The directory /run/keepalived will be created as an
158 # unshared mount point, for example for pid files.
159 # syslog entries will have _NAME appended to the ident.
160 # Note: the namespace cannot be changed on a configuration reload.
161 net_namespace NAME
162
163 # Add the IPVS configuration in the specified net namespace. It allows to easily
164 # split the VIP traffic on a given namespace and keep the healthchecks traffic
165 # in another namespace. If NAME is not specified, then the default namespace
166 # will be used.
167 net_namespace_ipvs NAME
168
169 # ipsets wasn't network namespace aware until Linux 3.13, and so
170 # if running with an earlier version of the kernel, by default
171 # use of ipsets is disabled if using a namespace and vrrp_ipsets
172 # has not been specified. This options overrides the default and
173 # allows ipsets to be used with a namespace on kernels prior to 3.13.
174 namespace_with_ipsets
175
176 # If multiple instances of keepalived are run in the same namespace,
177 # this will create pid files with NAME as part of the file names,
178 # in /run/keepalived.
179 # Note: the instance name cannot be changed on a configuration reload
180 instance NAME
181
182 # Create pid files in /run/keepalived
183 use_pid_dir
184
185 # Poll to detect media link failure using ETHTOOL, MII or ioctl interface
186 # otherwise uses netlink interface.
187 linkbeat_use_polling
188
189 # Time for main process to allow for child processes to exit on termination
190 # in seconds. This can be needed for very large configurations.
191 # (default: 5)
192 child_wait_time SECS
193
194 Note: All processes/scripts run by keepalived are run with parent death signal set
195 to SIGTERM. All such processes/scripts should either not change the action for
196 SIGTERM, or ensure that the process/script terminates once SIGTERM is received,
197 possibly following any cleanup actions needed.
198
199 # Global definitions configuration block
200 global_defs {
201 # In order to ensure that all processes read exactly the same configuration,
202 # while the config is first read it is written, by default, to a memory based
203 # file (or to an anonymous file in /tmp/ if memfd_create() is not supported).
204 # If your configuration is very large, you may not want the copy to be
205 # held in memory, in which case specifing the tmp_config_directory causes the
206 # configuration to be written to an anonymous file on the filesystem on which
207 # the specified directory resides, which must be writeable by keepalived.
208 # This setting cannot be changed on a reload, and it should be specified as
209 # early as possible in the configuration.
210 tmp_config_directory DIRECTORY
211
212 # config_save_dir causes keepalived to save configuration state and
213 # configuration files before and after each reload. This is used for debugging
214 # purposes if there appear to be problems related to repeated reloads.
215 # The directory will be created if it does not exist, but all parent
216 # directories must exist.
217 config_save_dir DIRECTORY
218
219 # Set the process names of the keepalived processes to the default values:
220 # keepalived, keepalived_vrrp, keepalived_ipvs, keepalived_bfd
221 process_names
222
223 # Specify the individual process names
224 process_name NAME
225 vrrp_process_name NAME
226 checker_process_name NAME
227 bfd_process_name NAME
228
229 # The startup and shutdown scripts are run once, when keepalived starts
230 # before any child processes are run, and when keepalived stops after
231 # all child processes have terminated, respectively.
232 # The original motivation for adding this feature was that although
233 # keepalived can setup IPVS configuration using firewall marks, there
234 # was no mechanism for adding configuration to set the firewall marks
235 # (or for removing it afterwards).
236 # This feature can also be used to setup the iptables framework required
237 # if using iptables (see vrrp_iptables option below), modify interface
238 # settings, or anything else that can be done from a script or program.
239 # Only one startup script and one shutdown script can be specified.
240 # The timeouts (in seconds default 10 seconds) are the time allowed for
241 # scripts to run; if the timeout expires the scripts will be killed (this
242 # is to stop keepalived hanging waiting for the scripts to terminate).
243 startup_script SCRIPT_NAME [username [groupname]]
244 startup_script_timeout SECONDS # range [1,1000]
245 shutdown_script SCRIPT_NAME [username [groupname]]
246 shutdown_script_timeout SECONDS # range [1,1000]
247
248 # Set of email To: notify
249 notification_email {
250 admin@example1.com
251 ...
252 }
253
254 # email from address that will be in the header
255 # (default: keepalived@<local host name>)
256 notification_email_from admin@example.com
257
258 # Remote SMTP server used to send notification email.
259 # IP address or domain name with optional port number.
260 # (default port number: 25)
261 smtp_server 127.0.0.1 [<PORT>]
262
263 # Name to use in HELO messages.
264 # (default: local host name)
265 smtp_helo_name <STRING>
266
267 # SMTP server connection timeout in seconds.
268 smtp_connect_timeout 30
269
270 # Sets default state for all smtp_alerts
271 smtp_alert <BOOL>
272
273 # Sets default state for vrrp smtp_alerts
274 smtp_alert_vrrp <BOOL>
275
276 # Sets default state for checker smtp_alerts
277 smtp_alert_checker <BOOL>
278
279 # Logs every failed real server check in syslog
280 # (nevertheless, SMTP alert is only sent when all retry checks failed
281 # and real server transitions to DOWN state)
282 checker_log_all_failures <BOOL>
283
284 # Don't send smtp alerts for fault conditions
285 no_email_faults
286
287 # String identifying the machine (doesn't have to be hostname).
288 # (default: local host name)
289 router_id <STRING>
290
291 # Multicast Group to use for IPv4 VRRP adverts
292 # Defaults to the RFC5798 IANA assigned VRRP multicast address 224.0.0.18
293 # which You typically do not want to change.
294 vrrp_mcast_group4 224.0.0.18
295
296 # Multicast Group to use for IPv6 VRRP adverts
297 # (default: ff02::12)
298 vrrp_mcast_group6 ff02::12
299
300 # sets the default interface for static addresses.
301 # (default: eth0)
302 default_interface p33p1.3
303
304 # The sync daemon as provided by the IPVS kernel code only supports
305 # one master and one backup daemon instance at a time to synchronize
306 # the IPVS connection table.
307 # See ipvsadm(8) man page for more details of the sync daemon.
308 # Parameters are binding interface, and optional:
309 # inst VRRP_INSTANCE (inst can be omitted for backward compatibility)
310 # syncid (0 to 255) for lvs syncd, default is the VRID of vrrp instance,
311 # or 0 if no vrrp instance
312 # maxlen (1..65507) maximum packet length (limit is mtu - 20 - 8)
313 # port (1..65535) UDP port number to use, default 8848
314 # ttl (1..255)
315 # group - multicast group address(IPv4 or IPv6), default 224.0.0.81
316 # If VRRP_INSTANCE is not specified, both the master and backup sync daemons
317 # will be run as long as keepalived is running, otherwise the sync daemon
318 # master/backup state tracks the state of the specified vrrp instance: if
319 # the vrrp instance is in master state, only the master sync daemon will run,
320 # if the vrrp instance is not master, only the backup sync daemon will run.
321 # NOTE: maxlen, port, ttl and group are only available on Linux 4.3 or later.
322 # See kernel source doc/Documentation/networking/ipvs-sysctl.txt for details of
323 # parameters controlling IPVS and the sync daemon.
324 # /proc/net/ip_vs* provide some details about the state of IPVS.
325 lvs_sync_daemon <INTERFACE> [[inst] <VRRP_INSTANCE>] [id <SYNC_ID>] \
326 [maxlen <LEN>] [port <PORT>] [ttl <TTL>] [group <IP ADDR>]
327
328 # lvs_timeouts specifies the tcp, tcp_fin and udp connection tracking timeouts
329 # in seconds. At least one value must be specified; not setting a value leaves
330 # it unchanged from when keepalived started.
331 lvs_timeouts [tcp SECS] [tcpfin SECS] [udp SECS]
332
333 # flush any existing LVS configuration at startup
334 lvs_flush
335
336 # flush remaining LVS configuration at shutdown (for large configurations
337 # this is much faster than the default approach of deleting each RS and
338 # each VS individually).
339 # If VS is specified, remove each keepalived managed virtual
340 # server without explicitly removing the real servers (the kernel will
341 # remove them).
342 lvs_flush_on_stop [VS]
343
344 # delay for second set of gratuitous ARPs after transition to MASTER.
345 # in seconds, 0 for no second set.
346 # (default: 5)
347 vrrp_garp_master_delay 10
348
349 # number of gratuitous ARP messages to send at a time after
350 # transition to MASTER.
351 # (default: 5)
352 vrrp_garp_master_repeat 1
353
354 # delay for second set of gratuitous ARPs after lower priority
355 # advert received when MASTER.
356 # (default: vrrp_garp_master_delay)
357 vrrp_garp_lower_prio_delay 10
358
359 # Default value for vrrp down_timer_adverts.
360 vrrp_down_timer_adverts [1:100]
361
362 # number of gratuitous ARP messages to send at a time after
363 # lower priority advert received when MASTER.
364 # (default: vrrp_garp_master_repeat)
365 vrrp_garp_lower_prio_repeat 1
366
367 # minimum time interval for refreshing gratuitous ARPs while MASTER.
368 # in seconds (resolution seconds).
369 # (default: 0 (no refreshing))
370 vrrp_garp_master_refresh 60
371
372 # number of gratuitous ARP messages to send at a time while MASTER
373 # (default: 1)
374 vrrp_garp_master_refresh_repeat 2
375
376 # Delay between gratuitous ARP messages sent on an interface
377 # decimal, seconds (resolution usecs).
378 # (default: 0)
379 vrrp_garp_interval 0.001
380
381 # Delay between unsolicited NA messages sent on an interface
382 # decimal, seconds (resolution usecs).
383 # (default: 0)
384 vrrp_gna_interval 0.000001
385
386 # By default keepalived sends 5 gratuitions ARP/NA messages at a
387 # time, and after transitioning to MASTER sends a second block of
388 # 5 messages 5 seconds later.
389 # With modern switches this is unnecessary, so setting vrrp_min_garp
390 # causes only one ARP/NA message to be sent, with no repeat 5 seconds
391 # later.
392 vrrp_min_garp [<BOOL>]
393
394 # The following option causes periodic GARP/NA messages to be sent on
395 # interfaces of VIPs/eVIPs that are not the interface of the VRRP
396 # instance, in order to ensure that switch MAC caches are maintained
397 # (specified in seconds).
398 # Many switches have a default cache timeout of 300 seconds, and so
399 # a garp repeat rate of 1/3rd of that would be sensible. The maximum
400 # permitted value is 1 day (86400 seconds);
401 # By default, it will only send on VMAC interfaces; specifying all
402 # will cause it to send GARP/NA on each interface used by the VRRP instance.
403 vrrp_garp_extra_if [all] 100
404
405 # If a lower priority advert is received, don't send another advert.
406 # This causes adherence to the RFCs. Defaults to false, unless
407 # strict_mode is set.
408 vrrp_lower_prio_no_advert [<BOOL>]
409
410 # If we are master and receive a higher priority advert, send an advert
411 # (which will be lower priority than the other master), before we
412 # transition to backup. This means that if the other master has
413 # garp_lower_priority_repeat set, it will resend garp messages.
414 # This is to get around the problem of their having been two simultaneous
415 # masters, and the last GARP messages seen were from us.
416 vrrp_higher_prio_send_advert [<BOOL>]
417
418 # Set the default VRRP version to use
419 # (default: 2, but IPv6 instances will use version 3)
420 vrrp_version <2 or 3>
421
422 # keepalived uses a firewall (either nftables or iptables) for two purposes:
423 # i) To implement no_accept mode
424 # ii) To stop IGMP/MLD packets being sent on VMAC interfaces, and to move
425 # them onto the underlying interface.
426 # If both vrrp_iptables and vrrp_nftables are specified, keepalived will use
427 # nftables and not iptables. Similarly, if the iptables command is generating
428 # nftables configuration, or there is no iptables command installed,
429 # keepalived will use nftables rather than iptables.
430 # If neither vrrp_nftables or vrrp_iptables are specified but VMACs are in use
431 # or no_accept is specified, keepalived will use nftables if it is available.
432
433 # Use nftables as the firewall.
434 # TABLENAME must not exist, and must be different for each
435 # instance of keepalived running in the same network namespace.
436 # Default tablename is keepalived, and priority is -1.
437 # keepalived will create base chains in the table.
438 # counters means counters are added to the rules (primarily for
439 # debugging purposes).
440 # ifindex means create IPv6 link local sets using ifindex rather
441 # than ifnames. This is the default unless the vrrp_instance has
442 # set dont_track_primary. The alternative is to use interface names
443 # as part of the set key, but the nft utility prior to v0.8.3 will
444 # then not output interface names properly.
445 nftables [TABLENAME]
446 nftables_priority PRIORITY
447 nftables_counters
448 nftables_ifindex
449
450 # Similarly for IPVS iptables - used for setting fwmarks for virtual
451 # server groups. keepalived will allocate a fwmark for each virtual
452 # server group, so that only one virtual server for each group needs
453 # to be configured in IPVS, by using a fwmark, and nftables will be
454 # used to set the fwmark for each of the virtual server
455 # address/protocol/port combinations specified.
456 # nftables_ipvs_start_fwmark specifies the first fwmark for keepalived
457 # to use (default 1000). This will be incremented for each subsequent
458 # virtual server group.
459 nftables_ipvs [TABLENAME]
460 nftables_ipvs_priority PRIORITY
461 nftables_ipvs_start_fwmark NUMBER
462
463 # Use iptables as the firewall.
464 # Note: it is necessary for the specified chain to exist in
465 # the iptables and/or ip6tables configuration, and for the chain
466 # to be called from an appropriate point in the iptables configuration.
467 # It will probably be necessary to have this filtering after accepting
468 # any ESTABLISHED,RELATED packets, because IPv4 might select the VIP as
469 # the source address for outgoing connections.
470 # Note: although the default chains that are used are INPUT and OUTPUT,
471 # since those are the only chains that will always exist, it is not safe
472 # or sensible to use those chains and specific chains should be created
473 # and called from appropriate points in the iptables configuration. The
474 # chains used for keepalived should not be used for any other purpose, and
475 # should have no rules configured, other than the rules that keepalived
476 # manages.
477 # A startup_script (see above) can be used to create the chains and to
478 # add rules to call them. A shutdown_script can be used to remove the
479 # iptables configuration added by the startup_script.
480 # Note2: If using ipsets, the iptables VIP rules are appended to the end
481 # of the specified chains; if not using ipsets, the VIP rules are inserted
482 # at the beginning of the chains. Any IGMP rules are always appended to
483 # the end of the chains.
484 # (default: INPUT)
485 vrrp_iptables keepalived
486
487 # or for outbound filtering as well
488 # Note, outbound filtering won't work with IPv4, since the VIP can be
489 # selected as the source address for an outgoing connection. With IPv6
490 # this is unlikely since the addresses are deprecated.
491 vrrp_iptables keepalived_in keepalived_out
492
493 # or to to use default chains (INPUT and OUTPUT)
494 vrrp_iptables
495
496 # Keepalived may have the option to use ipsets in conjunction with
497 # iptables. If so, then the ipset names can be specified, defaults
498 # as below. If no names are specified, ipsets will not be used,
499 # otherwise any omitted names will be constructed by adding "_if"
500 # and/or "6" and _igmp/_mld to previously specified names.
501 vrrp_ipsets [keepalived [keepalived6 [keepalived_if6 [keepalived_igmp [keepalived_mld]]]]]
502
503 # An alternative to moving IGMP messages from VMACs to their parent interfaces
504 # is to disable them altogether in the kernel by setting
505 # igmp_link_local_mcast_reports false.
506 # This stops IGMP join etc messages for 224.0.0.0/24, since they should
507 # always be forwarded to all interfaces (see RFC4541).
508 # This is available from Linux 4.3 onwards.
509 disable_local_igmp
510
511 # The following enables checking that when in unicast mode, the
512 # source address of a VRRP packet is one of our unicast peers.
513 vrrp_check_unicast_src
514
515 # Checking all the addresses in a received VRRP advert can be time
516 # consuming. Setting this flag means the check won't be carried out
517 # if the advert is from the same master router as the previous advert
518 # received.
519 # (default: don't skip)
520 vrrp_skip_check_adv_addr
521
522 # Enforce strict VRRP protocol compliance. This currently includes
523 # enforcing the following. Please note that other checks may be
524 # added in the future if they are found to be missing:
525 # 0 VIPs not allowed
526 # unicast peers not allowed
527 # IPv6 addresses not allowed in VRRP version 2
528 # First IPv6 VIP is not link local
529 # State MASTER can be configured if and only if priority is 255
530 # Authentication is not supported
531 # Preempt delay is not supported
532 # Accept mode cannot be set for VRRPv2
533 # If accept/no accept is not specified, accept is set if priority
534 # is 255 aand cleared otherwise
535 # Gratuitous ARP repeats cannot be enabled
536 # Cannot clear lower_prio_no_advert
537 # Cannot set higher_prio_send_advert
538 # Cannot use vmac_xmit_base
539 vrrp_strict
540
541 # Send vrrp instance priority notifications on notify FIFOs.
542 vrrp_notify_priority_changes <BOOL>
543
544 # The following options can be used if vrrp, checker or bfd processes
545 # are timing out. This can be seen by a backup vrrp instance becoming
546 # master even when the master is still running, because the master or
547 # backup system is too busy to process vrrp packets.
548 # --
549 # keepalived can, if it detects that it is not running sufficiently
550 # soon after a timer should expire, increase its priority, first
551 # of all switching to realtime scheduling, and if that is not
552 # sufficient, it will then increase its realtime priority by one each
553 # time it detects a further delay in running. If the event that realtime
554 # scheduling is enabled, RLIMIT_RTTIME will be set, using the values for
555 # {bfd,checker,vrrp}_rlimit_rttime (see below). These values may need
556 # to be increased for slower processors.
557 # --
558 # To limit the maximum increased automatic priority, specify the following
559 # (0 doesn't use automatic priority increases, and is the default. -1 disables
560 # the warning message at startup). Omitting the priority sets the maximum value.
561 max_auto_priority [<-1 to 99>] # 99 is really sched_get_priority_max(SCHED_RR)
562
563 # Minimum delay in microseconds after timer expires before keeplalived is
564 # scheduled after which the process priority will be auto incremented
565 # (default is 1000000 usecs (1 second), maximum is 10000000 (10 seconds))
566 min_auto_priority_delay <delay in usecs>
567
568 # Set the vrrp child process priority (Negative values increase priority)
569 vrrp_priority <-20 to 19>
570
571 # Set the checker child process priority
572 checker_priority <-20 to 19>
573
574 # Set the BFD child process priority
575 bfd_priority <-20 to 19>
576
577 # Set the vrrp child process non swappable
578 vrrp_no_swap
579
580 # Set the checker child process non swappable
581 checker_no_swap
582
583 # Set the BFD child process non swappable
584 bfd_no_swap
585
586 # The following options can be used to force vrrp, checker and bfd
587 # processes to run on a restricted CPU set.
588 # You can either bind processes to a single CPU or define a set of
589 # cpu. In that last case Linux kernel will be restricted to that cpu
590 # set during scheduling. Forcing process binding to single CPU can
591 # increase performances on heavy loaded box.
592 # INTEGER following configuration keyword are representing cpu_id
593 # as shown in /proc/cpuinfo on line "processor:"
594 # --
595 # Set CPU Affinity for the vrrp child process
596 vrrp_cpu_affinity <INTEGER> [<INTERGER>]...[<INTEGER>]
597
598 # Set CPU Affinity for the checker child process
599 checker_cpu_affinity <INTEGER> [<INTERGER>]...[<INTEGER>]
600
601 # Set CPU Affinity for the bfd child process
602 bfd_cpu_affinity <INTEGER> [<INTERGER>]...[<INTEGER>]
603
604 # Set the vrrp child process to use real-time scheduling
605 # at the specified priority
606 vrrp_rt_priority <1..99>
607
608 # Set the checker child process to use real-time scheduling
609 # at the specified priority
610 checker_rt_priority <1..99>
611
612 # Set the BFD child process to use real-time scheduling
613 # at the specified priority
614 bfd_rt_priority <1..99>
615
616 # Set the limit on CPU time between blocking system calls,
617 # in microseconds
618 # (default: 10000)
619 vrrp_rlimit_rttime >=2
620 checker_rlimit_rttime >=2
621 bfd_rlimit_rttime >=2
622
623 # If Keepalived has been build with SNMP support, the following
624 # keywords are available.
625 # Note: Keepalived, checker and RFC support can be individually
626 # enabled/disabled
627 # --
628 # Specify socket to use for connecting to SNMP master agent
629 # (see source module keepalived/vrrp/vrrp_snmp.c for more details)
630 # (default: unix:/var/agentx/master)
631 snmp_socket udp:1.2.3.4:705
632
633 # enable SNMP handling of vrrp element of KEEPALIVED MIB
634 enable_snmp_vrrp
635
636 # enable SNMP handling of checker element of KEEPALIVED MIB
637 enable_snmp_checker
638
639 # enable SNMP handling of RFC2787 and RFC6527 VRRP MIBs
640 enable_snmp_rfc
641
642 # enable SNMP handling of RFC2787 VRRP MIB
643 enable_snmp_rfcv2
644
645 # enable SNMP handling of RFC6527 VRRP MIB
646 enable_snmp_rfcv3
647
648 # enable SNMP traps
649 enable_traps
650
651 # If Keepalived has been build with DBus support, the following
652 # keywords are available.
653 # --
654 # Enable the DBus interface
655 enable_dbus
656
657 # Name of DBus service
658 # Useful if you want to run multiple keepalived processes with DBus enabled
659 # (default: org.keepalived.Vrrp1)
660 dbus_service_name SERVICE_NAME
661
662 # Specify the default username/groupname to run scripts under.
663 # If this option is not specified, the user defaults to keepalived_script
664 # if that user exists, otherwise root.
665 # If groupname is not specified, it defaults to the user's group.
666 script_user username [groupname]
667
668 # Don't run scripts configured to be run as root if any part of the path
669 # is writable by a non-root user.
670 enable_script_security
671
672 # Rather than using notify scripts, specifying a fifo allows more
673 # efficient processing of notify events, and guarantees that they
674 # will be delivered in the correct sequence.
675 # NOTE: the FIFO names must all be different
676 # --
677 # FIFO to write notify events to
678 # See vrrp_notify_fifo and lvs_notify_fifo for format of output
679 # For further details, see the description under vrrp_sync_group.
680 # see doc/samples/sample_notify_fifo.sh for sample usage.
681 notify_fifo FIFO_NAME [username [groupname]]
682
683 # script to be run by keepalived to process notify events
684 # The FIFO name will be passed to the script as the last parameter
685 notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
686
687 # FIFO to write vrrp notify events to.
688 # The string written will be a line of the form: INSTANCE "VI_1" MASTER 100
689 # and will be terminated with a new line character.
690 # For further details of the output, see the description under vrrp_sync_group
691 # and doc/samples/sample_notify_fifo.sh for sample usage.
692 vrrp_notify_fifo FIFO_NAME [username [groupname]]
693
694 # script to be run by keepalived to process vrrp notify events
695 # The FIFO name will be passed to the script as the last parameter
696 vrrp_notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
697
698 # FIFO to write notify healthchecker events to
699 # The string written will be a line of the form:
700 # VS [192.168.201.15]:tcp:80 {UP|DOWN}
701 # RS [1.2.3.4]:tcp:80 [192.168.201.15]:tcp:80 {UP|DOWN}
702 # and will be terminated with a new line character.
703 lvs_notify_fifo FIFO_NAME [username [groupname]]
704
705 # script to be run by keepalived to process healthchecher notify events
706 # The FIFO name will be passed to the script as the last parameter
707 lvs_notify_fifo_script STRING|QUOTED_STRING [username [groupname]]
708
709 # Allow configuration to include interfaces that don't exist at startup.
710 # This allows keepalived to work with interfaces that may be deleted and restored
711 # and also allows virtual and static routes and rules on VMAC interfaces.
712 # allow_if_changes allows an interface to be deleted and recreated with a
713 # different type or underlying interface, eg changing from vlan to macvlan
714 # or changing a macvlan from eth1 to eth2. This is predominantly used for
715 # reporting duplicate VRID errors at startup if allow_if_changes is not set.
716 dynamic_interfaces [allow_if_changes]
717
718 # The following options are only needed for large configurations, where either
719 # keepalived creates a large number of interface, or the system has a large
720 # number of interface. These options only need using if
721 # "Netlink: Receive buffer overrun" messages are seen in the system logs.
722 # If the buffer size needed exceeds the value in /proc/sys/net/core/rmem_max
723 # the corresponding force option will need to be set.
724 # --
725 # Set netlink receive buffer size. This is useful for
726 # very large configurations where a large number of interfaces exist, and
727 # the initial read of the interfaces on the system causes a netlink buffer
728 # overrun.
729 vrrp_netlink_cmd_rcv_bufs BYTES
730 vrrp_netlink_cmd_rcv_bufs_force <BOOL>
731 vrrp_netlink_monitor_rcv_bufs BYTES
732 vrrp_netlink_monitor_rcv_bufs_force <BOOL>
733
734 # The vrrp netlink command and monitor socket the checker command and
735 # and monitor socket and process monitor buffer sizes can be independently set.
736 # The force flag means to use SO_RCVBUFFORCE, so that the buffer size
737 # can exceed /proc/sys/net/core/rmem_max.
738 lvs_netlink_cmd_rcv_bufs BYTES
739 lvs_netlink_cmd_rcv_bufs_force <BOOL>
740 lvs_netlink_monitor_rcv_bufs BYTES
741 lvs_netlink_monitor_rcv_bufs_force <BOOL>
742
743 # As a guide for process_monitor_rcv_bufs for 1400 processes terminating
744 # simultaneously, 212992 (the default on some systems) is insufficient, whereas
745 # 500000 is sufficient.
746 process_monitor_rcv_bufs BYTES
747 process_monitor_rcv_bufs_force <BOOL>
748
749 # When a socket is opened, the kernel configures the max rx buffer size for
750 # the socket to /proc/sys/net/core/rmem_default. On some systems this can be
751 # very large, and even generally this can be much larger than necessary.
752 # This isn't a problem so long as keepalived is reading all queued data from
753 # it's sockets, but if rmem_default was set sufficiently large, and if for
754 # some reason keepalived stopped reading, it could consume all system memory.
755 # The vrrp_rx_bufs_policy allows configuring of the rx bufs size when the
756 # sockets are opened. If the policy is MTU, the rx buf size is configured
757 # to the total of interface's MTU * vrrp_rx_bufs_multiplier for each vrrp
758 # instance using the socket. Likewise, if the policy is ADVERT, then it is
759 # the total of each vrrp instances advert packet size * multiplier.
760 # (default: use system default)
761 vrrp_rx_bufs_policy [MTU|ADVERT|NUMBER]
762
763 # (default: 3)
764 vrrp_rx_bufs_multiplier NUMBER
765
766 # Send notifies at startup for real servers that are starting up
767 rs_init_notifies
768
769 # Don't send an email every time a real server checker changes state;
770 # only send email when a real server is added or removed
771 no_checker_emails
772
773 # The umask to use for creating files. The number can be specified in hex, octal
774 # or decimal. BITS are I{R|W|X}{USR|GRP|OTH}, e.g. IRGRP, separated by '|'s.
775 # The default umask is IWGRP | IWOTH. This option cannot override the
776 # command-line option.
777 umask [NUMBER|BITS]
778
779 # On some systems when bond interfaces are created, they can start passing traffic
780 # and then have a several second gap when they stop passing traffic inbound. This
781 # can mean that if keepalived is started at boot time, i.e. at the same time as
782 # bond interfaces are being created, keepalived doesn't receive adverts and hence
783 # can become master despite an instance with higher priority sending adverts.
784 # This option specifies a delay in seconds before vrrp instances start up after
785 # keepalived starts,
786 vrrp_startup_delay 5.5
787
788 # The following will cause logging of receipt of VRRP adverts for VRIDs not configured
789 # on the interface on which they are received.
790 log_unknown_vrids
791
792 # Specify the prefix for generated VMAC names (default "vrrp")
793 vmac_prefix STRING
794
795 # Specify the prefix for generated VMAC names for VIPs which use a VMAC but are not
796 # on the VRRP instance's interface (default vmac_prefix value)
797 vmac_addr_prefix STRING
798
799 # Specify random seed for ${_RANDOM}, to make configurations repeatable (default
800 # is to use a seed based on the time, so that each time a different configuration
801 # will be generated).
802 random_seed UNSIGNED_INT
803
804 # If a configuration reload is attempted with an updated configuration file that has
805 # errors, keepalived may terminate, and possibly enter a loop indefinitely restarting
806 # and terminating. If reload_check_config is set, then keepalived will attempt to
807 # validate the configuration before initiating a reload, and only initiate the reload
808 # if the configuration is valid.
809 reload_check_config [LOG_FILE]
810
811 # Treat any missing include file as an error. The OPTIONS can be any combination of
812 # readable - error if a match is not a readable file
813 # match - error if no file matches (unless wildcard specified)
814 # wildcard_match - error if no file matches (even if wildcard specified)
815 # brace_match - error if a brace expansion does not match a file
816 # Note: match, wildcard_match and brace_match include the readable check.
817 # The setting of include_check is saved when a new include file is opened, and restored
818 # when the file is closed. This means that the include_check setting when reading a
819 # file cannot be changed by a subsequently included file. To change the setting for all
820 # included files, include_check should be set at the beginning of the configuration file
821 # specified in the command line (default /etc/keepalived/keepalived.conf).
822 # Note2: If the libc glob() function does not support GLOB_ALTDIRFUNC (e.g. Musl libc as
823 # on Alpine Linux etc.), then only readable and wildcard_match of the above options will work.
824 # It is possible to add or remove individual settings; '+' means add the following
825 # checks, '-' means remove the following checks. For example
826 # include_check +match -wildcard_match
827 # adds the requirement that there is a matching file, and removes the requirement for
828 # wildcard matches.
829 # If no option is specified, it is the same as specifying all options.
830 include_check [OPTIONS]
831
832 # reload_time_file allows a reload of keepalived to be scheduled in the future. This is
833 # particularly useful if there is a master keepalived and one or more backup keepalived
834 # instances and the new configuration is incompatible with the previous configuration,
835 # e.g. adding or removing VIPs which would cause adverts to be rejected.
836 # All the instances can be scheduled to reload at the same time, thereby ensuring that
837 # no mismatching adverts are received by the backup instances.
838 # The configuration specifies a file which keepalived will monitor. The first line of
839 # the file must contain a valid time or date/time exactly in the formats specified below.
840 # When keepalived starts up, it reads the file if it exists, and schedules a reload at
841 # the specified time. If the file does not exist, then when it is subsequently created
842 # a reload will be scheduled. If the file is updated, the reload time will be modified
843 # accordingly. If the file is deleted, the reload is cancelled.
844 # Normally when the reload occurs the specified file is deleted, since the reload has
845 # been done; if the file included a date then the reload will be in the past and so
846 # ignored. However, if there is no date, then if the file were reread following the
847 # reload, a reload would be scheduled for 24 hours time. In order to stop this, the
848 # file is deleted (unlinked) by default. If reload_repeat is specified, then the
849 # file is not deleted, and if the file contains a time only with no date, then
850 # keepalived will keep reloading at that time every day until the file is removed or
851 # modified.
852 # If the directory containing the file does not exist at startup/reload, or if the
853 # directory is removed or renamed, then no future scheduled reloads will occur until
854 # a manual (SIGHUP) reload is done or keepalived restarts.
855 # The permitted formats of the entry in the timer file are precisely:
856 # HH:MM:SS
857 # YY-MM-DD HH:MM:SS
858 # YYYY-MM-DD HH:MM:SS
859 # each with an optional 'Z' at the end.
860 # There must be no leading or trailing whitespace, and only one space between the date
861 # and the time.
862 # If there is a 'Z' at the end of the time, the time is parsed as UTC, otherwise the
863 # time is the localtime for the environment in which keepalived is running. If the
864 # systems which are being reloaded are in different timezones, it is probably safer to
865 # use UTC.
866 # If using local time with daylight savings, beware that some times don't exist and
867 # some times are duplicated and hence ambiguous.
868 reload_time_file ABSOLUTE-PATHNAME-OF-FILE
869 reload_repeat
870
871 # Some users frequently update their configurations and reload keepalived. reload_file
872 # provides a mechanism that allows the configuration update processes not to update the
873 # configuration files while keepalived is reading them.
874 # The reload file will be created by keepalived before it starts reading configuration
875 # files, unless the file exists. If the file already exists, it will be truncated. Once
876 # keepalived has completed reading the files it will remove the reload file.
877 # If reload_file with no file name is specified, the default filename keepalived.reload
878 # in the PID directory will be used.
879 # The best way to use the reload file is for the configuration update process to touch
880 # the reload file before it signals keepalived to reload, and then wait for the file
881 # to be deleted, which indicates that keepalived has finished reading the config files.
882 # When keepalived starts reading the configuration files, since it truncates the reload
883 # file, if update process creates the reload_file with non-zero size, it can detect
884 # the reloading starting by the reload_file becoming zero length.
885 reload_file [ABSOLUTE-PATHNAME-OF-FILE]
886
887 # Sending SIGUSR1 to keepalived causes it to dump its data structures
888 # for debugging purposes, although some users use this feature and
889 # process the output. Please note that the format of the .data files
890 # produced is not guaranteed to maintain backward compatibility.
891 # The standard file names are keepalived_parent.data, keepalived.data,
892 # keepalived_check.data and keepalived_bfd.data. This causes a problem
893 # if more than one keepalived instance is running on a system.
894 # In order to alleviate this, enabling data_use_instance includes the
895 # instance name and network namespace in the file name of the .data files.
896 data_use_instance [<BOOL>]
897 }
898
900 The linkbeat_interfaces block allows specifying which interfaces should
901 use polling via MII, Ethtool or ioctl status rather than rely on
902 netlink status updates. This allows more granular control of global
903 definition linkbeat_use_polling.
904
905 This option is preferred over the deprecated use of
906 linkbeat_use_polling in a vrrp_instance block, since the latter only
907 allows using linkbeat on the interface of the vrrp_instance itself,
908 whereas track_interface and virtual_ipaddresses and virtual_iproutes
909 may require monitoring other interfaces, which may need to use linkbeat
910 polling.
911
912 The default polling type to use is MII, unless that isn't supported in
913 which case ETHTOOL is used, and if that isn't supported then ioctl
914 polling. The preferred type of polling to use can be specified with MII
915 or ETHTOOL or IOCTL after the interface name, but if that type isn't
916 supported, a supported type will be used.
917
918 The syntax for linkbeat_interfaces is:
919 linkbeat_interfaces {
920 eth2
921 enp2s0 ETHTOOL
922 }
923
925 Static track groups are used to allow vrrp instances to track static
926 addresses, routes and rules. If a static address/route/rule specifies a
927 track group, then if the address/route/rule is deleted and cannot be
928 restored, the vrrp instance will transition to fault state.
929
930 The syntax for a track group is:
931 track_group GROUP1 {
932 group {
933 VI_1
934 VI_2
935 }
936 }
937
939 Keepalived can configure static addresses, routes, and rules. These ad‐
940 dresses are NOT moved by vrrpd, they stay on the machine. If you al‐
941 ready have IPs and routes on your machines and your machines can ping
942 each other, you don't need this section. The syntax for rules and
943 routes is that same as for ip rule add/ip route add (except shortened
944 option names are not supported due to ambiguities). The track_group
945 specification refers to a named track_group which lists the vrrp in‐
946 stances which will track the address, i.e. if the address is deleted
947 the vrrp instances will transition to backup.
948
949 NOTE: since rules without preferences can be added in different orders
950 due to vrrp instances transitioning from master to backup etc, rules
951 need to have a preference. If a preference is not specified, keepalived
952 will assign one, but it will probably not be what you want.
953
954 The syntax is the same for virtual addresses and virtual routes. If no
955 dev element is specified, it defaults to default_interface (default
956 eth0). Note: the broadcast address may be specified as '-' or '+' to
957 clear or set the host bits of the address.
958
959 If a route or rule could apply to either IPv4 or IPv6 it will default
960 to IPv4. To force a route/rule to be IPv6, add the keyword "inet6".
961
962 static_ipaddress {
963 <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
964 [label <LABEL>] [peer <IPADDR>] [home]
965 [-nodad] [mngtmpaddr] [noprefixroute]
966 [autojoin] [track_group GROUP] [preferred_lft nn|forever]
967 192.168.1.1/24 dev eth0 scope global
968 ...
969 }
970
971 static_routes {
972 192.168.2.0/24 via 192.168.1.100 dev eth0 track_group GROUP1
973
974 192.168.100.0/24 table 6909 nexthop via 192.168.101.1 dev wlan0
975 onlink weight 1 nexthop via 192.168.101.2
976 dev wlan0 onlink weight 2
977
978 192.168.200.0/24 dev p33p1.2 table 6909 tos 0x04 protocol bird
979 scope link priority 12 mtu 1000 hoplimit 100
980 advmss 101 rtt 102 rttvar 103 reordering 104
981 window 105 cwnd 106 ssthresh lock 107 realms
982 PQA/0x14 rto_min 108 initcwnd 109 initrwnd 110
983 features ecn
984
985 2001:470:69e9:1:2::4 dev p33p1.2 table 6909 tos 0x04 protocol
986 bird scope link priority 12 mtu 1000
987 hoplimit 100 advmss 101 rtt 102 rttvar 103
988 reordering 104 window 105 cwnd 106 ssthresh
989 lock 107 rto_min 108 initcwnd 109
990 initrwnd 110 features ecn fastopen_no_cookie 1
991 ...
992 }
993
994 static_rules {
995 from 192.168.2.0/24 table 1 track_group GROUP1
996
997 to 192.168.2.0/24 table 1
998
999 from 192.168.28.0/24 to 192.168.29.0/26 table small iif p33p1
1000 oif wlan0 tos 22 fwmark 24/12
1001 preference 39 realms 30/20 goto 40
1002
1003 to 1:2:3:4:5:6:7:0/112 from 7:6:5:4:3:2::/96 table 6908
1004 uidrange 10000-19999
1005
1006 to 1:2:3:4:6:6:7:0/112 from 8:6:5:4:3:2::/96 l3mdev protocol 12
1007 ip_proto UDP sport 10-20 dport 20-30
1008 ...
1009 }
1010
1012 Adds a file to be monitored. The file will be read whenever it is modi‐
1013 fied. The value in the file will be recorded for all VRRP instances,
1014 sync groups and real servers which monitor it. Note that the file will
1015 only be read if at least one VRRP instance, sync group or real server
1016 monitors it.
1017
1018 A value will be read as a number in text from the file. If the weight
1019 configured against the track_file is 0, a non-zero value in the file
1020 will be treated as a failure status, and a zero value will be treated
1021 as an OK status, otherwise the value will be multiplied by the weight
1022 configured in the track_file statement.
1023
1024 For VRRP instances, if the result is less than -253 anything monitoring
1025 the script will transition to the fault state (the weight can be 254 to
1026 allow for a negative value being read from the file).
1027
1028 If the vrrp instance or sync group is not the address owner and the re‐
1029 sult is between -253 and 253, the result will be added to the initial
1030 priority of the VRRP instance (a negative value will reduce the prior‐
1031 ity), although the effective priority will be limited to the range
1032 [1,254]. Likewise for real servers.
1033
1034 If a vrrp instance using a track_file is a member of a sync group, un‐
1035 less sync_group_tracking_weight is set on the group weight 0 must be
1036 set. Likewise, if the vrrp instance is the address owner, weight 0
1037 must also be set.
1038
1039 For real servers monitoring the file, the limits of values read from
1040 the track file are 2147483648 to -2147483648. The value, once multi‐
1041 plied by the weight, will be added to the real server's IPVS weight. If
1042 the result is <= than 2147483648 then the checker will be in the FAULT
1043 state.
1044
1045 NOTE: weights for track_file for real servers are not fully implemented
1046 yet. In particular allowing weight 0, handling negative calculated val‐
1047 ues and reloading.
1048
1049 The syntax for track file is:
1050
1051 track_file <STRING> { # vrrp_track_file is a deprecated synonym
1052 # file to track (weight defaults to 1)
1053 file <QUOTED_STRING>
1054
1055 # optional default weight
1056 weight <-2147483647..2147483647> [reverse]
1057
1058 # create the file and/or initialise the value
1059 # This causes VALUE (default 0) to be written to
1060 # the specified file at startup if the file doesn't
1061 # exist, unless overwrite is specified in which case
1062 # any existing file contents will be overwritten with
1063 # the specified value.
1064 init_file [VALUE] [overwrite]
1065 }
1066
1068 The configuration block looks like:
1069
1070 vrrp_track_process <STRING> {
1071 # process to monitor (with optional parameters)
1072 # A quoted string is treated as a single element, so if the first item
1073 # after the process keyword is quoted, that will be the command name.
1074 # For example:
1075 # process "/tmp/a b" param1 "param 2"
1076 # would mean a process named '/tmp/a b' (quotes removed) with 2 parameters
1077 # 'param1' and 'param 2'.
1078 process <STRING>|<QUOTED_STRING> [<STRING>|<QUOTED_STRING> ...]
1079
1080 # If matching parameters, this specifies a partial match (i.e. the first
1081 # n parameters match exactly), or an initial match, i.e. the last
1082 # parameter may be longer that the parameter configured.
1083 # To specify that a command must have no parameters, don't specify
1084 # any parameters, but specify param_match.
1085 param_match {initial|partial}
1086
1087 # default weight (default is 1). For description of reverse, see track_process.
1088 # 'weight 0 reverse' will cause the vrrp instance to be down when the
1089 # quorum is up, and vice versa.
1090 weight <-254..254> [reverse]
1091
1092 # minimum number of processes for success
1093 quorum NUM
1094
1095 # maximum number of processes for success. For example, setting
1096 # this to 1 would cause a failure if two instances of the process
1097 # were running (but beware forks - see fork_delay below).
1098 # Setting this to 0 would mean failure if the matching process were
1099 # running at all.
1100 quorum_max NUM
1101
1102 # time to delay after process quorum gained after fork before
1103 # consider process up (in fractions of second)
1104 # This is to avoid up/down bounce for fork/exec
1105 fork_delay SECS
1106
1107 # time to delay after process quorum lost before
1108 # consider process down (in fractions of second)
1109 # This is to avoid down/up bounce after terminate/parent refork.
1110 terminate_delay SECS
1111
1112 # this sets fork_delay and terminate_delay
1113 delay SECS
1114
1115 # Normally process string is matched against the process name,
1116 # as shown on the Name: line in /proc/PID/status, unless
1117 # parameters are specified.
1118 # This option forces matching the full command line
1119 full_command
1120 }
1121
1122 To avoid having to frequently run a track_script to monitor the exis‐
1123 tance of processes (often haproxy or nginx), vrrp_track_process can
1124 monitor whether other processes are running.
1125
1126 One difference from pgrep is track_process doesn't do a regular expres‐
1127 sion match of the command string, but does an exact match. 'pgrep ssh'
1128 will match an sshd process, this track_process will not (it is equiva‐
1129 lent to pgrep "^ssh$").
1130
1131 If full_command is used (equivalent to pgrep -f), /proc/PID/cmdline is
1132 used, but any updates to cmdline will not be detected (a process
1133 shouldn't normally change it, although it is possible with great care,
1134 for example systemd).
1135
1136 Prior to Linux v3.2 track_process will not support detection of changes
1137 to a process name, since the kernel did not notify changes of process
1138 name prior to 3.2. Most processes do not change their process name,
1139 but, for example, firefox forks processes that change their process
1140 name to "Web Content". The process name referred to here is the con‐
1141 tents of /proc/PID/comm.
1142
1143 Quorum is the number of matching processes that must be run for an OK
1144 status.
1145
1146 Delay might be useful if it anticipated that a process may be reloaded
1147 (stopped and restarted), and it isn't desired to down and up a vrrp in‐
1148 stance.
1149
1150 A positive weight means that an OK status will add <weight> to the pri‐
1151 ority of all VRRP instances which monitor it. On the opposite, a nega‐
1152 tive weight will be subtracted from the initial priority in case of in‐
1153 sufficient processes.
1154
1155 If the vrrp instance or sync group is not the address owner and the re‐
1156 sult is between -253 and 253, the result will be added to the initial
1157 priority of the VRRP instance (a negative value will reduce the prior‐
1158 ity), although the effective priority will be limited to the range
1159 [1,254].
1160
1161 If a vrrp instance using a track_process is a member of a sync group,
1162 unless sync_group_tracking_weight is set on the group weight 0 must be
1163 set. Likewise, if the vrrp instance is the address owner, weight 0
1164 must also be set.
1165
1166 Rational for not using pgrep/pidof/killall and the likes:
1167
1168 Every time pgrep or its equivalent is run, it iterates though the
1169 /proc/[1-9][0-9]* directories, and opens the status and cmdline pseudo
1170 files in each directory. The cmdline pseudo file is mapped to the
1171 process's address space, and so if that part of the process is swapped
1172 out, it will have to be fetched from the swap space. pgrep etc also
1173 include zombie processes whereas keepalived does not, since they aren't
1174 running.
1175
1176 This implementation only iterates though /proc/[1-9][0-9]*/ directories
1177 at start up, and it won't even read the cmdline pseudo files if
1178 'full_command' is not specified for any of the vrrp_track_process en‐
1179 tries. After startup, it uses the process_events kernel <-> userspace
1180 connector to receive notification of process changes. If full_command
1181 is specified for any track_process instance, the cmdline pseudo file
1182 will have to be read upon notification of the creation of the new
1183 process, but at that time it is very unlikely that it will have already
1184 been swapped out.
1185
1186 On a busy system with a high number of process creations/terminations,
1187 using a track_script with pgrep/pidof/killall may be more efficient,
1188 although those processes are inefficient compared to the minimum that
1189 keepalived needs.
1190
1191 Using pgrep etc on a system that is swapping can have a significant
1192 detrimental impact on the performance of the system, due to having to
1193 fetch swapped memory from the swap space, thereby causing additional
1194 swapping.
1195
1197 This is an implementation of RFC5880 (Bidirectional forwarding detec‐
1198 tion), and this can be configured to work between 2 keepalived in‐
1199 stances, but using unweighted track_bfds between a master/backup pair
1200 of VRRP instances means that the VRRP instance will only be able to
1201 come up if both VRRP instance are running, which somewhat defeats the
1202 purpose of VRRP.
1203
1204 This implementation has been tested with OpenBFDD (available at
1205 https://github.com/dyninc/OpenBFDD).
1206
1207 The syntax for bfd instance is :
1208
1209 bfd_instance <STRING> {
1210 # BFD Neighbor IP (synonym neighbour_ip)
1211 neighbor_ip <IP ADDRESS>
1212
1213 # Source IP to use (optional, except in order to ensure that the
1214 # local port is valid, it is required)
1215 source_ip <IP ADDRESS>
1216
1217 # Required min RX interval, in ms (resolution is micro-seconds e.g. 3.312)
1218 # (default is 10 ms)
1219 min_rx <DECIMAL>
1220
1221 # Desired min TX interval, in ms (resolution is micro-seconds)
1222 # (default is 10 ms)
1223 min_tx <DECIMAL>
1224
1225 # Desired idle TX interval, in ms (resolution is micro-seconds)
1226 # (default is 1000 ms)
1227 idle_tx <DECIMAL>
1228
1229 # Number of missed packets after
1230 # which the session is declared down
1231 # (default is 5)
1232 multiplier <INTEGER>
1233
1234 # Operate in passive mode (default is active)
1235 passive
1236
1237 # outgoing IPv4 ttl to use (default 255)
1238 ttl <INTEGER>
1239
1240 # outgoing IPv6 hoplimit to use (default 64)
1241 hoplimit <INTEGER>
1242
1243 # maximum reduction of ttl/hoplimit
1244 # in received packet (default 0)
1245 # (255 disables hop count checking)
1246 max_hops <INTEGER>
1247
1248 # Default tracking weight
1249 # Normally, positive weights are added to the vrrp instance priority when
1250 # the bfd instance is up, negative weights reduce the priority when it is down.
1251 # However, if reverse is specified, the priority is decreased when up and
1252 # increased when down. 'weight 0 reverse' will cause the vrrp instance to be down
1253 # when the bfd instance is up, and vice versa.
1254 weight <-253:253> [reverse]
1255
1256 # Normally bfd event notifications are sent to both the VRRP and checker processes.
1257 # Specifying vrrp or checker will cause event notifications for this bfd_instance
1258 # only to be sent to the specified process
1259 vrrp
1260 checker
1261 }
1262
1264 contains subblocks of VRRP script(s), VRRP synchronization group(s),
1265 VRRP gratuitous ARP and unsolicited neighbour advert delay group(s) and
1266 VRRP instance(s)
1267
1269 The script will be executed periodically, every <interval> seconds. Its
1270 exit code will be recorded for all VRRP instances which monitor it.
1271 Note that the script will only be executed if at least one VRRP in‐
1272 stance monitors it.
1273
1274 The default weight equals 0, which means that any VRRP instance moni‐
1275 toring the script will transition to the fault state after <fall> con‐
1276 secutive failures of the script. After that, <rise> consecutive suc‐
1277 cesses will cause VRRP instances to leave the fault state, unless they
1278 are also in the fault state due to other scripts or interfaces that
1279 they are tracking.
1280
1281 A positive weight means that <rise> successes will add <weight> to the
1282 priority of all VRRP instances which monitor it. On the opposite, a
1283 negative weight will be subtracted from the initial priority in case of
1284 <fall> failures.
1285
1286 The syntax for the vrrp script is:
1287
1288 # Adds a script to be executed periodically. Its exit code will be
1289 # recorded for all VRRP instances and sync groups which are monitoring it.
1290 vrrp_script <SCRIPT_NAME> {
1291 # path of the script to execute
1292 script <STRING>|<QUOTED-STRING>
1293
1294 # seconds between script invocations, (default: 1 second)
1295 interval <INTEGER>
1296
1297 # seconds after which script is considered to have failed
1298 timeout <INTEGER>
1299
1300 # adjust priority by this weight, (default: 0)
1301 # For description of reverse, see track_script.
1302 # 'weight 0 reverse' will cause the vrrp instance to be down when the
1303 # script is up, and vice versa.
1304 weight <INTEGER:-253..253> [reverse]
1305
1306 # required number of successes for OK transition
1307 rise <INTEGER>
1308
1309 # required number of successes for KO transition
1310 fall <INTEGER>
1311
1312 # user/group names to run script under.
1313 # group default to group of user
1314 user USERNAME [GROUPNAME]
1315
1316 # assume script initially is in failed state
1317 init_fail
1318 }
1319
1321 VRRP Sync Group is an extension to VRRP protocol. The main goal is to
1322 define a bundle of VRRP instance to get synchronized together so that
1323 transition of one instance will be reflected to others group members.
1324
1325 In addition there is an enhanced notify feature for fine state transi‐
1326 tion catching.
1327
1328 You can also define multiple track policy in order to force state tran‐
1329 sition according to a third party event such as interface, scripts,
1330 file, BFD.
1331
1332 Important: for a SYNC group to run reliably, it is vital that all in‐
1333 stances in the group are MASTER or that they are all either BACKUP or
1334 FAULT. A situation with half instances having higher priority on ma‐
1335 chine A half others with higher priority on machine B will lead to con‐
1336 stant re-elections. For this reason, when instances are grouped, any
1337 track scripts/files configured against member VRRP instances will have
1338 their tracking weights automatically set to zero, in order to avoid in‐
1339 consistent priorities across instances.
1340
1341 The syntax for vrrp_sync_group is :
1342
1343 vrrp_sync_group <STRING> {
1344 group {
1345 # name of the vrrp_instance (see below)
1346 # Set of VRRP_Instance string
1347 <STRING>
1348 <STRING>
1349 ...
1350 }
1351
1352 # Synchronization group tracking interface, script, file & bfd will
1353 # update the status/priority of all VRRP instances which are members
1354 # of the sync group.
1355 # 'weight 0 reverse' will cause the vrrp instance to be down when the
1356 # interface is up, and vice versa.
1357 track_interface {
1358 eth0
1359 eth1
1360 eth2 weight <-253..253> [reverse]
1361 ...
1362 }
1363
1364 # add a tracking script to the sync group (<SCRIPT_NAME> is the name
1365 # of the vrrp_script entry) go to FAULT state if any of these go down
1366 # if unweighted.
1367 # reverse causes the direction of the adjustment of the priority to be reversed.
1368 track_script {
1369 <SCRIPT_NAME>
1370 <SCRIPT_NAME> weight <-253..253> [reverse|no_reverse]
1371 }
1372
1373 # Files whose state we monitor, value is added to effective priority.
1374 # <STRING> is the name of a track_file
1375 # weight defaults to weight configured in track_file
1376 track_file {
1377 <STRING>
1378 <STRING> weight <-254..254> [reverse|noreverse]
1379 ...
1380 }
1381
1382 # Process to monitor, weight is added to effective priority.
1383 # <STRING> is the name of a vrrp_track_process
1384 # weight defaults to weight configured in vrrp_track_process.
1385 # See vrrp_instance track_process for description of weight.
1386 track_process {
1387 <STRING>
1388 <STRING> weight <-254..254> [reverse|noreverse]
1389 ...
1390 }
1391
1392 # BFD instances we monitor, value is added to effective priority.
1393 # <STRING> is the name of a BFD instance
1394 track_bfd {
1395 <STRING>
1396 <STRING>
1397 <STRING> weight <INTEGER: -253..253> [reverse|noreverse]
1398 ...
1399 }
1400
1401 # notify scripts and alerts are optional
1402 #
1403 # filenames of scripts to run on transitions can be unquoted (if
1404 # just filename) or quoted (if it has parameters)
1405 # The username and groupname specify the user and group
1406 # under which the scripts should be run. If username is
1407 # specified, the group defaults to the group of the user.
1408 # If username is not specified, they default to the
1409 # global script_user and script_group
1410
1411 # to MASTER transition
1412 notify_master /path/to_master.sh [username [groupname]]
1413
1414 # to BACKUP transition
1415 notify_backup /path/to_backup.sh [username [groupname]]
1416
1417 # FAULT transition
1418 notify_fault "/path/fault.sh VG_1" [username [groupname]]
1419
1420 # executed when stopping vrrp
1421 notify_stop <STRING>|<QUOTED-STRING> [username [groupname]]
1422
1423 # notify_deleted causes DELETED to be sent to notifies rather
1424 # than the default FAULT after a vrrp instance is deleted during a
1425 # reload. If a script is specified, that script will be executed
1426 # as well.
1427 notify_deleted [<STRING>|<QUOTED-STRING> [username [groupname]]]
1428
1429 # for ANY state transition.
1430 # "notify" script is called AFTER the notify_* script(s) and
1431 # is executed with 4 additional arguments after the configured
1432 # arguments provided by Keepalived:
1433 # $(n-3) = "GROUP"|"INSTANCE"
1434 # $(n-2) = name of the group or instance
1435 # $(n-1) = target state of transition (stop only applies to instances)
1436 # ("MASTER"|"BACKUP"|"FAULT"|"STOP"|"DELETED")
1437 # $(n) = priority value
1438 # $(n-3) and $(n-1) are ALWAYS sent in uppercase, and the possible
1439 # strings sent are the same ones listed above
1440 # ("GROUP"/"INSTANCE", "MASTER"/"BACKUP"/"FAULT"/"STOP"/"DELETED")
1441 # (note: DELETED is only applicable to instances)
1442 notify <STRING>|<QUOTED-STRING> [username [groupname]]
1443
1444 # The notify fifo output is the same as the last 4 parameters for the "notify"
1445 # script, with the addition of "MASTER_RX_LOWER_PRI" instead of state for an
1446 # instance, and also "MASTER_PRIORITY" and "BACKUP_PRIORITY" if the priority
1447 # changes and notify_priority_changes is configured.
1448 # MASTER_RX_LOWER_PRI is used if a master needs to set some external state, such
1449 # as setting a secondary IP address when using Amazon AWS; if another keepalived
1450 # has transitioned to master due to a communications break, the lower priority
1451 # instance will have taken over the secondary IP address, and the proper master
1452 # needs to be able to restore it.
1453
1454 # Send FIFO notifies for vrrp priority changes
1455 notify_priority_changes <BOOL>
1456
1457 # Send email notification during state transition,
1458 # using addresses in global_defs above (default no,
1459 # unless global smtp_alert/smtp_alert_vrrp set)
1460 smtp_alert <BOOL>
1461
1462 # DEPRECATED. Use track_interface, track_script and
1463 # track_file on vrrp_sync_groups instead.
1464 global_tracking
1465
1466 # allow sync groups to use differing weights.
1467 # This probably WON'T WORK, but is a replacement for
1468 # global_tracking in case different weights were used
1469 # across different vrrp instances in the same sync group.
1470 sync_group_tracking_weight
1471 }
1472
1474 specifies the setting of delays between sending gratuitous ARPs and un‐
1475 solicited neighbour advertisements. This is intended for when an up‐
1476 stream switch is unable to handle being flooded with ARPs/NAs.
1477
1478 Use interface when the limits apply on the single physical interface.
1479 Use interfaces when a group of interfaces are linked to the same switch
1480 and the limits apply to the switch as a whole.
1481
1482 Note: Only one of interface or interfaces should be used per block.
1483
1484 If the global vrrp_garp_interval and/or vrrp_gna_interval are set, any
1485 interfaces that aren't specified in a garp_group will inherit the
1486 global settings.
1487
1488 The syntax for garp_group is :
1489
1490 garp_group {
1491 # Sets the interval between Gratuitous ARP (in seconds, resolution microseconds)
1492 garp_interval <DECIMAL>
1493
1494 # Sets the default interval between unsolicited NA (in seconds, resolution microseconds)
1495 gna_interval <DECIMAL>
1496
1497 # The physical interface to which the intervals apply
1498 interface <STRING>
1499
1500 # A list of interfaces across which the delays are aggregated.
1501 interfaces {
1502 <STRING>
1503 <STRING>
1504 ...
1505 }
1506 }
1507
1509 A VRRP Instance is the VRRP protocol key feature. It defines and con‐
1510 figures VRRP behaviour to run on a specific interface. Each VRRP In‐
1511 stance is related to a unique interface.
1512
1513 The syntax for vrrp_instance is :
1514
1515 vrrp_instance <STRING> {
1516 # Initial state, MASTER|BACKUP
1517 # If the priority is 255, then the instance will transition immediately
1518 # to MASTER if state MASTER is specified; otherwise the instance will
1519 # wait between 3 and 4 advert intervals before it can transition,
1520 # depending on the priority.
1521 state MASTER
1522
1523 # interface for inside_network, bound by vrrp.
1524 # Note: if using unicasting, the interface can be omitted as long
1525 # as the unicast addresses are not IPv6 link local addresses (this is
1526 # necessary, for example, if using asymmetric routing).
1527 # If the interface is omitted, then all VIPs and eVIPs should specify
1528 # the interface they are to be configured on, otherwise they will be
1529 # added to the default interface.
1530 interface eth0
1531
1532 # Use VRRP Virtual MAC (macvlan).
1533 # The macvlan will be created on the configured interface for
1534 # the VRRP instance, and the VIPs, and eVIPs of the matching address
1535 # family, which do not specify a different interface will be configured
1536 # on the macvlan.
1537 # The VRRP adverts will also be sent and received on the macvlan
1538 # interface, unless vmac_xmit_base is configured.
1539 # NOTE: If sysctl net.ipv4.conf.all.rp_filter is set,
1540 # and this vrrp_instance is an IPv4 instance, using
1541 # this option will cause the individual interfaces to be
1542 # updated to the greater of their current setting, and
1543 # all.rp_filter, as will default.rp_filter, and all.rp_filter
1544 # will be set to 0.
1545 # The original settings are restored on termination.
1546 # NOTE 2: If using use_vmac with unicast peers,
1547 # vmac_xmit_base must be set.
1548 use_vmac [<VMAC_INTERFACE>]
1549
1550 # use_vmac_addr is used to create VMAC (macvlan) interfaces for
1551 # each interface that is used by a VIP or eVIP where the interface
1552 # is not the same as the interface on which the VRRP instance is
1553 # configured or the eVIP's address family does not match the VRRP
1554 # instance's. Alternatively, use_vmac can be specified against each
1555 # VIP/eVIP that specifies an interface (dev).
1556 # NOTE: if use_vmac is specfied and an eVIP is not the same address
1557 # family as the vrrp instance, unless use_vmac_addr is specified, or
1558 # use_vmac is specified for the eVIP, the eVIP will be configured on
1559 # the vrrp instance's VMAC, which will have the wrong MAC address for
1560 # the address family of the eVIP.
1561 use_vmac_addr
1562
1563 # Send/Recv VRRP messages from base interface instead of
1564 # VMAC interface
1565 vmac_xmit_base
1566
1567 # Use IPVLAN interface. keepalived will create a mode L2
1568 # ipvlan interface on top of the specified interface.
1569 # For IPv4 instances, an IP address is required, for IPv6
1570 # the address is optional, in which case the link local
1571 # address will be used.
1572 # The mode flags default to bridge. NOTE: the mode flags must be the
1573 # same for all ipvlans on the same underlying interface.
1574 # It is safer to configure an interface name, in case keepalived crashes
1575 # and restarts, in which case it can more reliably find a previously
1576 # created interface.
1577 use_ipvlan [<INTERFACE_NAME>] [IP_ADDRESS] [bridge|private|vepa]
1578
1579 # force instance to use IPv6 (this option is deprecated since
1580 # the virtual ip addresses determine whether IPv4 or IPv6 is used).
1581 native_ipv6
1582
1583 # Ignore VRRP interface faults (default unset).
1584 # Note: when using IPv6, setting the interface administratively down, e.g.
1585 # 'ip link set IF down' will by default cause all IPv6 addresses to be
1586 # deleted from the interface, and consequently the VRRP instance will
1587 # go to fault state due to the addresses being deleted. Setting sysctl
1588 # net.ipv6.conf.IF.keep_addr_on_down to 1 will allow non link-local addresses
1589 # to remain when the interface is downed.
1590 dont_track_primary
1591
1592 # optional, monitor these as well.
1593 # go to FAULT state if any of these go down if unweighted.
1594 # When a weight is specified in track_interface, instead of setting the vrrp
1595 # instance to the FAULT state in case of failure, its priority will be
1596 # increased by the weight when the interface is up (for positive weights),
1597 # or decreased by the weight's absolute value when the interface is down
1598 # (for negative weights), unless reverse is specified, in which case the
1599 # direction of adjustment of the priority is reversed.
1600 # The weight must be comprised between -253 and +253 inclusive.
1601 # 0 is the default behaviour which means that a failure implies a
1602 # FAULT state. The common practice is to use positive weights to count a
1603 # limited number of good services so that the server with the highest count
1604 # becomes master. Negative weights are better to count unexpected failures
1605 # among a high number of interfaces, as it will not saturate even with high
1606 # number of interfaces. Use reverse to increase priority if an interfaces is down
1607 track_interface {
1608 eth0
1609 eth1
1610 eth2 weight <-253..253> [reverse]
1611 ...
1612 }
1613
1614 # add a tracking script to the interface
1615 # (<SCRIPT_NAME> is the name of the vrrp_track_script entry)
1616 # The same principle as track_interface can be applied to track_script entries,
1617 # except that an unspecified weight means that the default weight declared in
1618 # the script will be used (which itself defaults to 0).
1619 # reverse causes the direction of the adjustment of the priority to be reversed.
1620 track_script {
1621 <SCRIPT_NAME>
1622 <SCRIPT_NAME> weight <-253..253> [reverse|no_reverse]
1623 }
1624
1625 # Files whose state we monitor, value is added to effective priority.
1626 # <STRING> is the name of a track_file
1627 track_file {
1628 <STRING>
1629 <STRING>
1630 <STRING> weight <-254..254> [reverse|noreverse]
1631 ...
1632 }
1633
1634 # Positive weights are added/subtracted when the process is running,
1635 # negative weights are subtracted/added when the not running.
1636 # If reverse is specified, the addition/subtraction is reversed.
1637 # <STRING> is the name of a vrrp_track_process
1638 # weight defaults to weight configured in vrrp_track_process
1639 track_process {
1640 <STRING>
1641 <STRING> weight <-254..254> [reverse|noreverse]
1642 ...
1643 }
1644
1645 # BFD instances we monitor, value is added to effective priority,
1646 # unless reverse is specified, when the value is subtracted.
1647 # Positive weights are add/subtracted when the bfd instance is up,
1648 # negative weights are subtracted/added when the bfd instance is down.
1649 # <STRING> is the name of a BFD instance
1650 track_bfd {
1651 <STRING>
1652 <STRING>
1653 <STRING> weight <INTEGER: -253..253> [reverse|noreverse]
1654 ...
1655 }
1656
1657 # default IP for binding vrrpd is the primary IP
1658 # on interface. If you want to hide the location of vrrpd,
1659 # use this IP as src_addr for multicast or unicast vrrp
1660 # packets. (since it's multicast, vrrpd will get the reply
1661 # packet no matter what src_addr is used).
1662 # optional
1663 mcast_src_ip <IPADDR>
1664 unicast_src_ip <IPADDR>
1665
1666 # if the configured src_ip doesn't exist or is removed put the
1667 # instance into fault state
1668 track_src_ip
1669
1670 # VRRP version to run on interface
1671 # default is global parameter vrrp_version, but IPv6 instances will
1672 # always use version 3.
1673 version <2 or 3>
1674
1675 # The following enables checking that when in unicast mode, the
1676 # source address of a VRRP packet is one of our unicast peers.
1677 check_unicast_src
1678
1679 # Do not send VRRP adverts over a VRRP multicast group.
1680 # Instead it sends adverts to the following list of
1681 # ip addresses using unicast. It can be cool to use
1682 # the VRRP FSM and features in a networking
1683 # environment where multicast is not supported!
1684 # IP addresses specified can be IPv4 as well as IPv6.
1685 # If min_ttl and/or max_ttl are specified, the TTL/hop limit
1686 # of any received packet is checked against the specified
1687 # TTL range, and is discarded if it is outside the range.
1688 # Specifying min_ttl or max_ttl turns on check_unicast_src.
1689 unicast_peer {
1690 <IPADDR> [min_ttl {0..255}] [max_ttl {0..255}]
1691 ...
1692 }
1693
1694 # Specify the unicast TTL/HLIM for sending unicast adverts
1695 unicast_ttl {0..255}
1696
1697 # The checksum calculation when using VRRPv3 changed after v1.3.6.
1698 # Setting this flag forces the old checksum algorithm to be used
1699 # to maintain backward compatibility, although keepalived will
1700 # attempt to maintain compatibility anyway if it sees an old
1701 # version checksum. Specifying never will turn off auto detection
1702 # of old checksums. [This option may not be enabled - check output
1703 # of `keepalived -v` for OLD_CHKSUM_COMPAT.]
1704 old_unicast_checksum [never]
1705
1706 # interface specific settings, same as global parameters.
1707 # default to global parameters
1708 garp_master_delay 10
1709 garp_master_repeat 1
1710 garp_lower_prio_delay 10
1711 garp_lower_prio_repeat 1
1712 garp_master_refresh 60
1713 garp_master_refresh_repeat 2
1714 garp_extra_if [all] 100 # specifying 0 disables feature
1715
1716 # The VRRP RFCs state that the master down timer is 3 advert intervals plus
1717 # a skew time. Setting down_timer_adverts means the master down timer will be
1718 # down_timer_adverts advert intervals.
1719 # The default is 3, to conform with the VRRP RFCs. Setting this to any other
1720 # value is a deviation from the VRRP protocol. All virtual routers for a given
1721 # VRRP instance MUST use the same value.
1722 down_timer_adverts [1-100]
1723
1724 # If a lower priority advert is received, don't send another advert.
1725 # This causes adherence to the RFCs (defaults to global
1726 # vrrp_lower_priority_dont_send_advert).
1727 lower_prio_no_advert [<BOOL>]
1728
1729 # If we are master and receive a higher priority advert, send an advert
1730 # (which will be lower priority than the other master), before we transition
1731 # to backup. This means that if the other master has garp_lower_prio_repeat
1732 # set, it will resend garp messages. This is to get around the problem of
1733 # their having been two simultaneous masters, and the last GARP
1734 # messages seen were from us.
1735 higher_prio_send_advert [<BOOL>]
1736
1737 # arbitrary unique number from 1 to 255
1738 # used to differentiate multiple instances of vrrpd
1739 # running on the same network interface and address
1740 # family (and hence same socket).
1741 # Note: using the same virtual_router_id with the same
1742 # address family on different interfaces has been known
1743 # to cause problems with some network switches; if you
1744 # are experiencing problems with using the same
1745 # virtual_router_id on different interfaces, but the problems
1746 # are resolved by not duplicating virtual_router_ids, the
1747 # your network switches are probably not functioning correctly.
1748 virtual_router_id 51
1749
1750 # for electing MASTER, highest priority wins.
1751 # to be MASTER, make this 50 more than on other machines.
1752 priority 100
1753
1754 # VRRP Advert interval in seconds (e.g. 0.92) (use default)
1755 advert_int 1
1756
1757 # Note: authentication was removed from the VRRPv2 specification by
1758 # RFC3768 in 2004.
1759 # Use of this option is non-compliant and can cause problems; avoid
1760 # using if possible, except when using unicast, where it can be helpful.
1761 authentication {
1762 # PASS|AH
1763 # PASS - Simple password (suggested)
1764 # AH - IPSEC (not recommended))
1765 auth_type PASS
1766
1767 # Password for accessing vrrpd.
1768 # should be the same on all machines.
1769 # Only the first eight (8) characters are used.
1770 auth_pass 1234
1771 }
1772
1773 # addresses add|del on change to MASTER, to BACKUP.
1774 # With the same entries on other machines,
1775 # the opposite transition will be occurring.
1776 # For virtual_ipaddress, virtual_ipaddress_excluded,
1777 # virtual_routes and virtual_rules most of the options
1778 # match the options of the command ip address/route/rule add.
1779 # The track_group option only applies to static addresses/routes/rules.
1780 # no_track is specific to keepalived and means that the
1781 # vrrp_instance will not transition out of master state
1782 # if the address/route/rule is deleted and the address/route/rule
1783 # will not be reinstated until the vrrp instance next transitions
1784 # to master.
1785 # <LABEL>: is optional and creates a name for the alias.
1786 For compatibility with "ifconfig", it should
1787 be of the form <realdev>:<anytext>, for example
1788 eth0:1 for an alias on eth0.
1789 # <SCOPE>: ("site"|"link"|"host"|"nowhere"|"global")
1790 # preferred_lft is set to 0 to deprecate IPv6 addresses (this is the
1791 # default if the address mask is /128). Use "preferred_lft forever"
1792 # to specify that a /128 address should not be deprecated.
1793 # NOTE: care needs to be taken if dev is specified for an address and
1794 # your network uses MAC learning switches. The VRRP protocol ensures
1795 # that the source MAC address of the interface sending adverts is
1796 # maintained in the MAC cache of switches; however by default this
1797 # will not work for the MACs of any VIPs/eVIPs that are configured on
1798 # different interfaces from the interface on which the VRRP instance is
1799 # configured, since the interface, especially if it is a VMAC interface,
1800 # will only send using the MAC address of the interface in response to
1801 # ARP requests. This may mean that the interface MAC addresses may
1802 # time out in the MAC caches of switches. In order to avoid this, use
1803 # the garp_extra_if or garp_extra_if_vmac options to send periodic
1804 # GARP/ND messages on those interfaces.
1805 virtual_ipaddress {
1806 <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [use_vmac] [scope <SCOPE>]
1807 [label <LABEL>] [peer <IPADDR>] [home]
1808 [-nodad] [mngtmpaddr] [noprefixroute]
1809 [autojoin] [no_track] [preferred_lft nn|forever]
1810 192.168.200.17/24 dev eth1
1811 192.168.200.18/24 dev eth2 label eth2:1
1812 }
1813
1814 # VRRP IP excluded from VRRP optional.
1815 # For cases with large numbers (eg 200) of IPs
1816 # on the same interface. To decrease the number
1817 # of addresses sent in adverts, you can exclude
1818 # most IPs from adverts.
1819 # The IPs are add|del as for virtual_ipaddress.
1820 # Can also be used if you want to be able to add
1821 # a mixture of IPv4 and IPv6 addresses, since all
1822 # addresses in virtual_ipaddress must be of the
1823 # same family.
1824 virtual_ipaddress_excluded {
1825 <IPADDR>[/<MASK>] [brd <IPADDR>] [dev <STRING>] [scope <SCOPE>]
1826 [label <LABEL>] [peer <IPADDR>] [home]
1827 [-nodad] [mngtmpaddr] [noprefixroute]
1828 [autojoin] [no_track]
1829 <IPADDR>[/<MASK>] ...
1830 ...
1831 }
1832
1833 # Set the promote_secondaries flag on the interface to stop other
1834 # addresses in the same CIDR being removed when 1 of them is removed
1835 # For example if 10.1.1.2/24 and 10.1.1.3/24 are both configured on an
1836 # interface, and one is removed, unless promote_secondaries is set on
1837 # the interface the other address will also be removed.
1838 promote_secondaries
1839
1840 # routes add|del when changing to MASTER, to BACKUP.
1841 # See static_routes for more details
1842 virtual_routes {
1843 # src <IPADDR> [to] <IPADDR>/<MASK> via|gw <IPADDR>
1844 # [or <IPADDR>] dev <STRING> scope <SCOPE> table <TABLE>
1845 src 192.168.100.1 to 192.168.109.0/24 via 192.168.200.254 dev eth1
1846 192.168.110.0/24 via 192.168.200.254 dev eth1
1847 192.168.111.0/24 dev eth2 no_track
1848 192.168.112.0/24 via 192.168.100.254
1849 192.168.113.0/24 via 192.168.200.254 or 192.168.100.254 dev eth1
1850 blackhole 192.168.114.0/24
1851 0.0.0.0/0 gw 192.168.0.1 table 100 # To set a default gateway into table 100.
1852 }
1853
1854 # rules add|del when changing to MASTER, to BACKUP
1855 # See static_rules for more details
1856 virtual_rules {
1857 from 192.168.2.0/24 table 1
1858 to 192.168.2.0/24 table 1 no_track
1859 }
1860
1861 # VRRPv3 has an Accept Mode to allow the virtual router when not the
1862 # address owner to receive packets addressed to a VIP. This is the default
1863 # setting unless strict mode is set. As an extension, this also works for
1864 # VRRPv2 (RFC 3768 doesn't define an accept mode).
1865 # --
1866 # Accept packets to non address-owner
1867 accept
1868
1869 # Drop packets to non address-owner.
1870 no_accept
1871
1872 # A higher priority VRRP instance will normally preempt a lower priority instance
1873 # when it comes online. "nopreempt" stops the higher priority machine taking
1874 # over the master role, and allows the lower priority machine to remain as
1875 # master.
1876 # NOTE: For this to work, the initial state must not be MASTER.
1877 # --
1878 nopreempt
1879
1880 # for backwards compatibility
1881 preempt
1882
1883 # Seconds of delay until preemption after getting the advertisement timeout
1884 # at startup or when seeing a lower priority master.
1885 #
1886 # Since it is a delay, it cannot speed up taking over as master.
1887 # "preempt_delay" specifies the time in seconds to delay preempting compared
1888 # to if "preempt_delay" is not specified. Advertisement timeout is
1889 # 3 * advert_int + skew_time. Skew_time is defined by RFC3768 and RFC5798.
1890 #
1891 # So if "advert_int" is 1, and priority is 128, the instance would normally
1892 # wait 3.5 seconds before taking over as master. If "preempt_delay 2" is
1893 # specified, then the delay before taking over as master would be approximately
1894 # 5.5 seconds.
1895 #
1896 # (if not disabled by "nopreempt").
1897 # Range: 0 (default) to 1000 (e.g. 4.12)
1898 # NOTE: For this to work, the initial state must not be MASTER.
1899 preempt_delay 300 # waits 5 minutes
1900
1901 # See description of global vrrp_skip_check_adv_addr, which
1902 # sets the default value. Defaults to vrrp_skip_check_adv_addr
1903 skip_check_adv_addr [on|off|true|false|yes|no]
1904
1905 # See description of global vrrp_strict
1906 # If strict_mode is not specified, it takes the value of vrrp_strict.
1907 # If strict_mode without a parameter is specified, it defaults to on.
1908 strict_mode [on|off|true|false|yes|no]
1909
1910 # Debug level, not implemented yet.
1911 # LEVEL is a number in the range 0 to 4
1912 debug <LEVEL>
1913
1914 # notify scripts, alert as above
1915 notify_master <STRING>|<QUOTED-STRING> [username [groupname]]
1916 notify_backup <STRING>|<QUOTED-STRING> [username [groupname]]
1917 notify_fault <STRING>|<QUOTED-STRING> [username [groupname]]
1918 # executed when stopping vrrp
1919 notify_stop <STRING>|<QUOTED-STRING> [username [groupname]]
1920 notify <STRING>|<QUOTED-STRING> [username [groupname]]
1921
1922 # The notify_master_rx_lower_pri script is executed if a master
1923 # receives an advert with priority lower than the master's priority.
1924 notify_master_rx_lower_pri <STRING>|<QUOTED-STRING> [username [groupname]]
1925
1926 # Send vrrp instance priority notifications on notify FIFOs.
1927 notify_priority_changes <BOOL>
1928
1929 # Send SMTP alerts
1930 smtp_alert <BOOL>
1931
1932 # Set socket receive buffer size (see global_defs
1933 # vrrp_rx_bufs_policy for explanation)
1934 kernel_rx_buf_size
1935
1936 # Set use of linkbeat for the interface of this VRRP instance. This option is
1937 # deprecated - use linkbeat_interfaces block instead.
1938 linkbeat_use_polling
1939 }
1940
1942 If an interface that is being used (or tracked) by a VRRP instance
1943 goes to down state,
1944 the VRRP instance(s) will, by default, immediately transition to
1945 FAULT state, and when
1946 all relevant interfaces are back up again the VRRP instance(s) will
1947 immediately transition
1948 to BACKUP state.
1949
1950 This can cause problems if interfaces are bouncing, and so delays
1951 can be specified
1952 between the interface state change and the transition to
1953 FAULT/BACKUP state. If the
1954 interface returns to its original state before the delay expires,
1955 no associated VRRP
1956 instance state transition will occur.
1957
1958 interface_up_down_delays {
1959 ifname down_delay [up_delay]
1960 ifname2 down_delay [up_delay]
1961 ...
1962 }
1963
1964 The delays are specified in seconds, with a resolution of microseconds, e.g. a delay of
1965 0.00001 means 10 usecs. A delay of 0 means no delay in state change. The maximum delay
1966 that can be specified is 255 seconds.
1967
1968 If up_delay is omitted, it is set to be the same as the down delay.
1969
1970 The delay on an interface must be less than two (or more precisely one less than
1971 down_timer_adverts (default 3)) times the advert interval of any VRRP instance
1972 using that interface (otherwise a backup instance, while not receiving adverts
1973 may time out and become master before this instance transitions to FAULT state).
1974 Consequently the up/down delays can be dynamically reduced if another instance is
1975 master with a shorter advert interval.
1976
1977 If the VRRP instance is using a VMAC, it will inherit the up/down debounce delays of
1978 its parent interface.
1979
1981 contains subblocks of Virtual server group(s) and Virtual server(s)
1982
1983 The subblocks contain arguments for configuring Linux IPVS (LVS) fea‐
1984 ture. Knowledge of ipvsadm(8) will be helpful here. Configuring LVS is
1985 achieved by defining virtual server groups, virtual servers and option‐
1986 ally SSL configuration. Every virtual server defines a set of real
1987 servers, you can attach healthcheckers to each real server. Keepalived
1988 will then lead LVS operation by dynamically maintaining topology.
1989
1990 For details of what configuration combinations are valid, see the
1991 ipvsadm(8) man page.
1992
1993 Note: Where an option can be configured for a virtual server, real
1994 server, and possibly checker, the virtual server setting is the default
1995 for real servers, and the real server setting is the default for check‐
1996 ers.
1997
1998 Note: Tunnelled real/sorry servers can differ from the address family
1999 of the virtual server and non tunnelled real/sorry servers, which all
2000 have to be the same. If a virtual server uses a fwmark, and all the
2001 real/sorry servers are tunnelled, the address family of the virtual
2002 server will be the same as the address family of the real/sorry servers
2003 if they are all the same, otherwise it will default to IPv4 (use
2004 ip_family inet6 to override this).
2005
2006 Note: The port for the virtual server can only be omitted if the vir‐
2007 tual service is persistent.
2008
2010 This feature offers a way to simplify your configuration by factorizing
2011 virtual server definitions. If you need to define a bunch of virtual
2012 servers with exactly the same real server topology then this feature
2013 will make your configuration much more readable, optimize the duplica‐
2014 tion of IPVS virtual servers if nftables_ipvs is used, and will opti‐
2015 mize healthchecking task by only spawning one healthchecker where mul‐
2016 tiple virtual servers declaration would spawn a dedicated healthchecker
2017 for every real server which will waste system resources.
2018
2019 Any combination of IP addresses, IP address ranges and firewall marks
2020 can be used, provided that the family of the IP addresses of the vir‐
2021 tual server group match the IP address family of all the real servers
2022 of any virtual server using the virtual server group. The one exception
2023 to this is that the virtual server group can be configured with both
2024 IPv4 and IPv6 addresses and fwmarks provided that all the real servers
2025 (and sorry servers) of all virtual servers using the virtual server
2026 group use tunnel forwarding; if fwmarks are specified in this case, the
2027 address family must be specified (the one exception to this is if the
2028 virtual server group has no IP addresses (i.e. fwmarks only) and all
2029 the real/sorry servers are tunnelled, it will default to IPv4; it is
2030 not good practice to rely on this and the address families of the fw‐
2031 marks should be configured). Use of this option is intended for very
2032 large LVSs, but note, this can create a huge number of virtual servers
2033 unless nftables_ipvs is used. The use of nftables_ipvs is stringly rec‐
2034 ommended due to the very significant optimisations and efficiencies it
2035 provides.
2036
2037 NOTE: do not configure more than one TCP, one UDP and one SCTP virtual
2038 server with the same IP address family using the same virtual server
2039 group (or to put it another way do not have two virtual servers with
2040 the same protocol and address family using the same virtual server
2041 group); if all the real servers are tunnelled, then you must not have
2042 both IPv4 and IPv6 virtual servers with the same protocol.
2043
2044 The syntax for virtual_server_group is :
2045
2046 virtual_server_group <STRING> {
2047 # Virtual IP Address and Port
2048 <IPADDR> [<PORT>]
2049 <IPADDR> [<PORT>]
2050 ...
2051 # <IPADDR RANGE> is any of the following forms (or their IPv6 equivalents)
2052 # XXX.YYY.ZZZ.WWW-VVV eg 192.168.200.1-10 (includes both .1 and .10)
2053 # AAA.BBB.CCC.DDD-EEE.FFF.GGG.HHH eg 192.168.200.250-192.168.201.10
2054 # III.JJJ.KKK.LLL/nn eg 192.168.202.8/29
2055 <IPADDR RANGE> [<PORT>] # VIP range [VPORT]
2056 <IPADDR RANGE> [<PORT>]
2057 ...
2058 # Firewall Mark (fwmark)
2059 # inet/inet6 should only be specified for virtual server groups
2060 # where all real servers of the virtual servers are tunnelled.
2061 fwmark <INTEGER>
2062 fwmark <INTEGER> [inet|inet6]
2063 ...
2064 }
2065
2067 A virtual_server can be a declaration of one of <IPADDR> [<PORT>] , fw‐
2068 mark <INTEGER> or group <STRING>
2069
2070 The syntax for virtual_server is :
2071
2072 virtual_server <IPADDR> [<PORT>] |
2073 virtual_server fwmark <INTEGER> |
2074 virtual_server group <STRING> {
2075 # LVS scheduler
2076 lvs_sched rr|wrr|lc|wlc|lblc|sh|mh|dh|fo|ovf|lblcr|sed|nq
2077
2078 # Enable flag-1 for scheduler (-b flag-1 in ipvsadm)
2079 flag-1
2080 # Enable flag-2 for scheduler (-b flag-2 in ipvsadm)
2081 flag-2
2082 # Enable flag-3 for scheduler (-b flag-3 in ipvsadm)
2083 flag-3
2084 # Enable sh-port for sh scheduler (-b sh-port in ipvsadm)
2085 sh-port
2086 # Enable sh-fallback for sh scheduler (-b sh-fallback in ipvsadm)
2087 sh-fallback
2088 # Enable mh-port for mh scheduler (-b mh-port in ipvsadm)
2089 mh-port
2090 # Enable mh-fallback for mh scheduler (-b mh-fallback in ipvsadm)
2091 mh-fallback
2092 # Enable One-Packet-Scheduling for UDP (-o in ipvsadm)
2093 ops
2094
2095 # Override default LVS forwarding method (default is NAT).
2096 # Default tunnel type is ipip. Since Linux 5.2 the GUE tunnel type can
2097 # be specified. If using GUE, a port number is required. Since Linux 5.3
2098 # if the tunnel type is GUE, the checksum option can also be specified.
2099 # Since Linux 5.3, GRE tunnel type is also supported, but without the
2100 # remcsum option.
2101 lvs_method NAT|DR
2102 or
2103 lvs_method TUN [type {ipip|gue port NUM|gre} [nocsum|csum|remcsum]]
2104 # LVS persistence engine name (currently only sip supported)
2105 persistence_engine <STRING>
2106 # LVS persistence timeout in seconds, default 6 minutes
2107 persistence_timeout [<INTEGER>]
2108 # LVS granularity mask (-M in ipvsadm)
2109 persistence_granularity <NETMASK>
2110 # L4 protocol
2111 protocol TCP|UDP|SCTP
2112 # If VS IP address is not set,
2113 # suspend healthchecker's activity
2114 ha_suspend
2115
2116 # Send email notification during quorum up/down transition,
2117 # using addresses in global_defs above (default no,
2118 # unless global smtp_alert/smtp_alert_checker set)
2119 smtp_alert <BOOL>
2120
2121 # Default VirtualHost string for HTTP_GET or SSL_GET
2122 # eg virtualhost www.firewall.loc
2123 # Overridden by virtualhost config of real server or checker
2124 virtualhost <STRING>
2125
2126 # snmp_name is a text string that is returned as part of the snmp
2127 # data for this virtual server. It can be used to help identify the
2128 # virtual server when parsing SNMP output.
2129 snmp_name <STRING>
2130
2131 # On daemon startup assume that all RSs are down
2132 # and healthchecks failed. This helps to prevent
2133 # false positives on startup. Alpha mode is
2134 # disabled by default.
2135 alpha
2136
2137 # On daemon shutdown consider quorum and RS
2138 # down notifiers for execution, where appropriate.
2139 # Omega mode is disabled by default.
2140 omega
2141
2142 # Minimum total weight of all live servers in
2143 # the pool necessary to operate VS with no
2144 # quality regression. Defaults to 1.
2145 quorum <INTEGER>
2146
2147 # Tolerate this much weight units compared to the
2148 # nominal quorum, when considering quorum gain
2149 # or loss. A flap dampener. Defaults to 0.
2150 hysteresis <INTEGER>
2151
2152 # Script to execute when quorum is gained.
2153 quorum_up <STRING>|<QUOTED-STRING> [username [groupname]]
2154
2155 # Script to execute when quorum is lost.
2156 quorum_down <STRING>|<QUOTED-STRING> [username [groupname]]
2157
2158 # IP family for a fwmark service (only needed if all real servers are tunnelled
2159 # and persistence_granularity is not specified). Defaults to inet if not specified.
2160 ip_family inet|inet6
2161
2162 # setup realserver(s)
2163
2164 # RS to add to LVS topology when the quorum isn't achieved.
2165 # If a sorry server is configured, all real servers will
2166 # be brought down when the quorum is not achieved and be
2167 # replaced with the sorry server.
2168 sorry_server <IPADDR> [<PORT>]
2169 # applies inhibit_on_failure behaviour to the sorry_server
2170 sorry_server_inhibit
2171 # Sorry server LVS forwarding method. Default is the virtual
2172 # server's default.
2173 # For details of tunnel type, see virtual_server details.
2174 sorry_server_lvs_method NAT|DR
2175 or
2176 sorry_server_lvs_method TUN [type {ipip|gue port NUM|gre} [nocsum|csum|remcsum]]
2177
2178 # Optional connection timeout in seconds.
2179 # The default is 5 seconds
2180 connect_timeout <TIMER>
2181
2182 # Retry count to make additional checks if check
2183 # of an alive server fails. Default: 1 unless specified below
2184 retry <INTEGER>
2185
2186 # delay before retry after failure. Defaults to delay_loop for DNS_CHECK,
2187 # 3 seconds for HTTP_GET and SSL_GET, and 1 second otherwise.
2188 delay_before_retry <TIMER>
2189
2190 # Optional random delay to start the initial check
2191 # for maximum N seconds.
2192 # Useful to scatter multiple simultaneous
2193 # checks to the same RS. Enabled by default, with
2194 # the maximum at delay_loop. Specify 0 to disable
2195 warmup <TIMER>
2196
2197 # delay timer for checker polling (60 seconds if not specified)
2198 delay_loop <TIMER>
2199
2200 # Set weight to 0 when healthchecker detects failure
2201 inhibit_on_failure
2202
2203 # one entry for each realserver
2204 real_server <IPADDR> [<PORT>] {
2205 # relative weight to use, default: 1
2206 weight <INTEGER>
2207 # LVS forwarding method
2208 # For details of tunnel type, see virtual_server details. The default
2209 # setting is taken from the virtual_server's setting.
2210 lvs_method NAT|DR
2211 or
2212 lvs_method TUN [type {ipip|gue port NUM|gre} [nocsum|csum|remcsum]]
2213
2214 # Script to execute when healthchecker
2215 # considers service as up.
2216 notify_up <STRING>|<QUOTED-STRING> [username [groupname]]
2217 # Script to execute when healthchecker
2218 # considers service as down.
2219 notify_down <STRING>|<QUOTED-STRING> [username [groupname]]
2220
2221 # maximum number of connections to server
2222 uthreshold <INTEGER>
2223 # minimum number of connections to server
2224 lthreshold <INTEGER>
2225
2226 # Send email notification during state transition,
2227 # using addresses in global_defs above (default yes,
2228 # unless global smtp_alert/smtp_alert_checker set)
2229 smtp_alert <BOOL>
2230
2231 # Default VirtualHost string for HTTP_GET or SSL_GET
2232 # eg virtualhost www.firewall.loc
2233 # Overridden by virtualhost config of a checker
2234 virtualhost <STRING>
2235
2236 # snmp_name is a text string that is returned as part of the snmp
2237 # data for this real server. It can be used to help identify the
2238 # real server when parsing SNMP output.
2239 snmp_name <STRING>
2240
2241 alpha <BOOL> # see above
2242 connect_timeout <TIMER> # see above
2243 retry <INTEGER> # see above
2244 delay_before_retry <TIMER> # see above
2245 warmup <TIMER> # see above
2246 delay_loop <TIMER> # see above
2247 inhibit_on_failure <BOOL> # see above
2248
2249 # healthcheckers. Can be multiple of each type
2250 # HTTP_GET|SSL_GET|TCP_CHECK|SMTP_CHECK|DNS_CHECK|MISC_CHECK|BFD_CHECK|UDP_CHECK|PING_CHECK|FILE_CHECK
2251
2252 # All checkers have the following options, except MISC_CHECK which only
2253 # has options alpha onwards, and BFD_CHECK and FILE_CHECK which have none
2254 # of the standard options:
2255 CHECKER_TYPE {
2256 # ======== generic connection options
2257 # Optional IP address to connect to.
2258 # The default is the realserver IP
2259 connect_ip <IPADDR>
2260
2261 # Optional port to connect to
2262 # The default is the realserver port
2263 connect_port <PORT>
2264
2265 # Optional address to use to
2266 # originate the connection
2267 bindto <IPADDR>
2268
2269 # Optional interface to use; needed if
2270 # the bindto address is IPv6 link local
2271 bind_if <IFNAME>
2272
2273 # Optional source port to
2274 # originate the connection from
2275 bind_port <PORT>
2276
2277 # Optional fwmark to mark all outgoing
2278 # checker packets with
2279 fwmark <INTEGER>
2280
2281 alpha <BOOL> # see above
2282 connect_timeout <TIMER> # see above
2283 retry <INTEGER> # see above
2284 delay_before_retry <TIMER> # see above
2285 warmup <TIMER> # see above
2286 delay_loop <TIMER> # see above
2287 log_all_failures <BOOL> # log all failures when checker up
2288 }
2289
2290 # The following options are additional checker specific
2291
2292 # HTTP and SSL healthcheckers
2293 HTTP_GET|SSL_GET {
2294 # HTTP protocol version, one of 1.0, 1.0C, 1.1
2295 # Protocol version 1.0C means version 1.0 with the addition
2296 # of a "Connection: close" line, which is included in
2297 # version 1.1 by default.
2298 http_protocol <PROTOCOL>
2299 # When alpha mode is set, or when recovering from a failure,
2300 # each URL is checked, with a delay of <delay_loop> between
2301 # each check. if there were 20 URLs, and the <delay_loop> were
2302 # 3 seconds, it would take 1 minute before the RS would come up
2303 # following startup, or recovery from a failure. Setting
2304 # fast_recovery removes the delay, both at start up and after
2305 # recovery from a failure, meaning that the RS will come up
2306 # once all the URLs have been checked, with no delay between
2307 # checking each URL.
2308 fast_recovery [<BOOL>]
2309 # An url to test
2310 # can have multiple entries here
2311 url {
2312 #eg path / , or path /mrtg2/
2313 path <STRING>
2314 # healthcheck needs digest
2315 # or status_code and digest
2316 # Digest computed with genhash
2317 # eg digest 9b3a0c85a887a256d6939da88aabd8cd
2318 digest <STRING>
2319 # status code returned in the HTTP header
2320 # eg status_code 200 or status_code 200-299 400-499 503 505
2321 # Default is 200-299
2322 status_code <INTEGER|RANGE> [<INTEGER|RANGE>] ...
2323 # VirtualHost string. eg virtualhost www.firewall.loc
2324 # If not set, uses virtualhost from real or virtual server
2325 virtualhost <STRING>
2326 # Regular expression to search returned data against.
2327 # A failure to match causes the check to fail.
2328 regex <STRING>
2329 # Reverse the sense of the match, so a match of the
2330 # returned text causes the check to fail.
2331 regex_no_match
2332 # Space separated list of options for regex.
2333 # See man pcre2api for a description of the options.
2334 # The following option are supported:
2335 # allow_empty_class alt_bsux auto_callout caseless
2336 # dollar_endonly dotall dupnames extended firstline
2337 # match_unset_backref multiline never_ucp never_utf
2338 # no_auto_capture no_auto_possess no_dotstar_anchor
2339 # no_start_optimize ucp ungreedy utf never_backslash_c
2340 # alt_circumflex alt_verbnames use_offset_limit
2341 regex_options <OPTIONS>
2342 # For complicated regular expressions a larger stack
2343 # may be needed, and this allows the start and maximum
2344 # sizes in bytes to be specified. For more details see
2345 # the documentation for pcre2_jit_stack_create()
2346 regex_stack <START> <MAX>
2347 # The minimum offset into the returned data to start
2348 # checking for the regex pattern match. This can save
2349 # processing time if the returned data is large.
2350 regex_min_offset <OFFSET>
2351 # The maximum offset into the returned data for the
2352 # start of the subject match.
2353 regex_max_offset <OFFSET>
2354 }
2355 }
2356
2357 SSL_GET {
2358 # when provided, send Server Name Indicator during SSL handshake
2359 enable_sni
2360 }
2361
2362 # TCP healthchecker
2363 TCP_CHECK {
2364 # No additional options
2365 }
2366
2367 # SMTP healthchecker
2368 SMTP_CHECK {
2369 # Optional string to use for the SMTP HELO request
2370 helo_name <STRING>|<QUOTED-STRING>
2371 }
2372
2373 # DNS healthchecker. Uses UDP protocol.
2374 DNS_CHECK {
2375 # The retry default is 3.
2376
2377 # DNS query type
2378 # A|NS|CNAME|SOA|MX|TXT|AAAA
2379 # The default is SOA
2380 type <STRING>
2381
2382 # Domain name to use for the DNS query
2383 # The default is . (dot)
2384 name <STRING>
2385 }
2386
2387 # MISC healthchecker, run a program
2388 MISC_CHECK {
2389 # The retry default is 0.
2390
2391 # External script or program
2392 misc_path <STRING>|<QUOTED-STRING>
2393 # Script execution timeout
2394 misc_timeout <INTEGER>
2395
2396 # If misc_dynamic is set, the exit code from healthchecker
2397 # is used to dynamically adjust the weight as follows:
2398 # exit status 0: svc check success, weight
2399 # unchanged.
2400 # exit status 1: svc check failed.
2401 # exit status 2-255: svc check success,
2402 # then the RS weight is increased by
2403 # (exit status - 2 - rs configured weight).
2404 # An exit status of 10 will set the RS weight to 10. If
2405 # the exit status subsequently changes to 20, the RS
2406 # weight will become 20.
2407 # If there is only one MISC_CHECK and no FILE_CHECKers
2408 # the effect is to set the RS weight to two less than
2409 # the exit status.
2410 # (for example: an exit status of 255 would set
2411 # weight to 253 if no other MISC_CHECKers or
2412 # FILE_CHECKers where configured on the RS)
2413 misc_dynamic
2414
2415 # Specify the username/groupname that the script should
2416 # be run under.
2417 # If GROUPNAME is not specified, the group of the user
2418 # is used
2419 user USERNAME [GROUPNAME]
2420 }
2421
2422 # BFD instance name to check
2423 BFD_CHECK {
2424 name <STRING>
2425 }
2426
2427 # PING healthchecker
2428 # Note: using this checker may cause /proc/sys/net/ipv4/ping_group_range to be
2429 # updated to allow root to use an IPPROTO_ICMP socket.
2430 PING_CHECK {
2431 # No additional options
2432 }
2433
2434 # UDP healthchecker
2435 # Note: for this checker to work properly, it relies on ICMP error messages such as
2436 # HOST_UNREACH, NET_UNREACH, PORT_UNREACH. HOST_UNREACH relies on ARP requests
2437 # timing out, and so connect_timeout should be long enough to allow for this (e.g.
2438 # at least 4 seconds).
2439 # If payload is specified, the HEX_STR will be sent as the UDP data, otherwise a
2440 # random payload will be sent.
2441 # If require_reply is specified, the received data length is checked to ensure that it
2442 # lies between min_reply_length and max_reply_length.
2443 # If require_reply without a hex string is specified, udp reply data must be received
2444 # but the data content is not checked.
2445 # If a require_reply HEX_STR is specified, the reply data will be checked against the
2446 # HEX_STR, which must match up to the minimum of the received data length and the length
2447 # of the require_reply HEX_STR.
2448 # The format of HEX_STR is quite free format, for example:
2449 # Ab12f 3 456 546443123
2450 # would be interpreted as:
2451 # AB 12 0F 03 45 06 54 64 43 12 03
2452 # For the require_reply HEX_STR, a character can be specified as X or x, in which case
2453 # the value of those 4 bits in the reply is ignored. This allows, for example, for
2454 # some form of counter or otherwise.
2455 # It may be that you will want to use PING_CHECK to the same server as well.
2456 UDP_CHECK {
2457 payload <HEX_STR>
2458 require_reply [<HEX_STR>] # Require a reply packet for check to be successful
2459 min_reply_length <INT> # default 0
2460 max_reply_length <INT> # default is 255
2461 }
2462
2463 # File checker
2464 # This reads and monitors the contents of a file, where STRING is the name specified
2465 # in the track_file configuration block (see above).
2466 FILE_CHECK {
2467 track_file <STRING>
2468
2469 # If dynamic is set, the value from the file is used
2470 # to dynamically adjust the weight by adding the weight
2471 # to the quorum and the LVS weight
2472 dynamic
2473
2474 # The weight multiplier to apply to the value read from the file
2475 weight <-2147483647..2147483647> [reverse]
2476 }
2477 }
2478 }
2479
2480 # Parameters used for SSL_GET check.
2481 # If none of the parameters are specified, the SSL context
2482 # will be auto generated.
2483 SSL {
2484 # Password
2485 password <STRING>
2486 # CA file
2487 ca <STRING>
2488 # Certificate file
2489 certificate <STRING>
2490 # Key file
2491 key <STRING>
2492 }
2493
2495 Configuration parser has been extended to support advanced features
2496 such as conditional configuration and parameter substitution. These
2497 features are very useful for any scripted environment where configura‐
2498 tion templates are generated (datacenters).
2499
2501 The config-id defaults to the first part of the node name as returned
2502 by uname, and can be overridden with the -i or --config-id command line
2503 option.
2504
2505 Any configuration line starting with '@' is a conditional configuration
2506 line. The word immediately following (i.e. without any space) the '@'
2507 character is compared against the config-id, and if they don't match,
2508 the configuration line is ignored.
2509
2510 Alternatively, '@^' is a negative comparison, so if the word immedi‐
2511 ately following does NOT match the config-id, the configuration line IS
2512 included.
2513
2514 The purpose of this is to allow a single configuration file to be used
2515 for multiple systems, where the only differences are likely to be the
2516 router_id, vrrp instance priorities, and possibly interface names and
2517 unicast addresses.
2518
2519 For example:
2520
2521 global_defs {
2522 @main router_id main_router
2523 @backup router_id backup_router
2524 }
2525 ...
2526 vrrp_instance VRRP {
2527 ...
2528 @main unicast_src_ip 1.2.3.4
2529 @backup unicast_src_ip 1.2.3.5
2530 @backup2 unicast_src_ip 1.2.3.6
2531 unicast_peer {
2532 @^main 1.2.3.4
2533 @^backup 1.2.3.5
2534 @^backup2 1.2.3.6
2535 }
2536 ...
2537 }
2538
2539 If keepalived is invoked with -i main, then the router_id will be set
2540 to main_router, if invoked with -i backup, then backup_router, if not
2541 invoked with -i, or with -i anything else, then the router_id will not
2542 be set. The unicast peers for main will be 1.2.3.5 and 1.2.3.6.
2543
2545 Substitutable parameters can be specified. The format for defining a
2546 parameter is:
2547
2548 $PARAMETER=VALUE
2549
2550 where there must be no space before the '=' and only whitespace may
2551 preceed to '$'. Empty values are allowed.
2552
2553 Parameter names can be made up of any combination of A-Za-z0-9 and _,
2554 but cannot start with a digit. Parameter names starting with an under‐
2555 score should be considered reserved names that keepalived will define
2556 for various pre-defined options.
2557
2558 After a parameter is defined, any occurrence of $PARAMETER followed by
2559 whitespace, or any occurrence of ${PARAMETER} (which need not be fol‐
2560 lowed by whitespace) will be replaced by VALUE.
2561
2562 Replacement is recursive, so that if a parameter value itself includes
2563 a replaceable parameter, then after the first substitution, the parame‐
2564 ter in the value will then be replaced; the substitution is done at re‐
2565 placement time and not at definition time, so for example:
2566
2567 $ADDRESS_BASE=10.2.${ADDRESS_BASE_SUB}
2568 $ADDRESS_BASE_SUB=0
2569 ${ADDRESS_BASE}.100/32
2570 $ADDRESS_BASE_SUB=10
2571 ${ADDRESS_BASE}.100/32
2572
2573 will produce:
2574 10.2.0.100/32
2575 10.2.10.100/32
2576
2577 Note in the above examples the use of both ADDRESS_BASE and AD‐
2578 DRESS_BASE_SUB required braces ({}) since the parameters were not fol‐
2579 lowed by whitespace (after the first substitution which produced
2580 10.2.${ADDRESS_BASE_SUB}.100/32 the parameter is still not followed by
2581 whitespace).
2582
2583 If a parameter is not defined, it will not be replaced at all, so for
2584 example ${UNDEF_PARAMETER} will remain in the configuration if it is
2585 undefined; this means that existing configuration that contains a '$'
2586 character (for example in a script definition) will not be changed so
2587 long as no new parameter definitions are added to the configuration.
2588
2589 Parameter substitution works in conjunction with conditional configura‐
2590 tion. For example:
2591
2592 @main $PRIORITY=240
2593 @backup $PRIORITY=200
2594 ...
2595 vrrp_instance VI_0 {
2596 priority $PRIORITY
2597 }
2598
2599 will produce:
2600 ...
2601 vrrp_instance VI_0 {
2602 priority 240
2603 }
2604 if the config_id is main.
2605
2606 $IF_MAIN=@main
2607 $IF_MAIN priority 240
2608
2609 will produce:
2610 priority 240
2611 if the config_id is main and nothing if the config_id is not main,
2612 although why anyone would want to use this rather than simply the
2613 following is not known (but still possible):
2614 @main priority 240
2615
2616 Multiline definitions are also supported, but when used there must be
2617 nothing on the line after the parameter name. A multiline definition is
2618 specified by ending each line except the last with a '\' character.
2619
2620 Example:
2621 $INSTANCE= \
2622 vrrp_instance VI_${NUM} { \
2623 interface eth0.${NUM} \
2624 use_vmac vrrp${NUM}.1 \
2625 virtual_router_id 1 \
2626 @high priority 130 \
2627 @low priority 120 \
2628 advert_int 1 \
2629 virtual_ipaddress { \
2630 10.0.${NUM}.254/24 \
2631 } \
2632 track_script { \
2633 offset_instance_${NUM} \
2634 } \
2635 }
2636
2637 $NUM=0
2638 $INSTANCE
2639
2640 $NUM=1
2641 $INSTANCE
2642
2643 The use of multiline definitions can be nested.
2644
2645 Example:
2646 $RS= \
2647 real_server 192.168.${VS_NUM}.${RS_NUM} 80 { \
2648 weight 1 \
2649 inhibit_on_failure \
2650 smtp_alert \
2651 MISC_CHECK { \
2652 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" \
2653 } \
2654
2655 MISC_CHECK { \
2656 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" \
2657 } \
2658
2659 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" \
2660
2661 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" \
2662
2663 }
2664
2665 $VS= \
2666 virtual_server 10.0.${VS_NUM}.4 80 { \
2667 quorum 2 \
2668 quorum_up "${_PWD}/scripts/notify.sh VS_notify.${INST} UP 10.0.${VS_NUM}.4:80" \
2669 quorum_down "${_PWD}/scripts/notify.sh VS_notify.${INST} DOWN 10.0.${VS_NUM}.4:80" \
2670 $RS_NUM=1 \
2671 $RS \
2672 $RS_NUM=2 \
2673 $RS \
2674 $RS_NUM=3 \
2675 $RS \
2676 }
2677
2678 $VS_NUM=0
2679 $ALPHA=alpha
2680 $VS
2681
2682 $VS_NUM=1
2683 $ALPHA=
2684 $VS
2685
2686 The above will create 2 virtual servers, each with 3 real servers
2687
2689 The following definitions are pre-defined:
2690
2691 ${_PWD} : The directory of the current configuration file (this can be
2692 changed if using the include directive).
2693 ${_INSTANCE} : The instance name (as defined by the -i option, defaults
2694 to hostname).
2695 ${_RANDOM [MIN [MAX]]} : This is replaced by a random integer in the
2696 range [MIN, MAX], where MIN and MAX are optional non-negative integers.
2697 Defaults are MIN=0 and MAX=32767.
2698 ${_HASH} : This is replaced by a '#' character, which would otherwise
2699 start a comment
2700 ${_BANG} : This is replaced by a '!' character, which would otherwise
2701 start a comment
2702
2703 Additional pre-defined definitions will be added as their need is iden‐
2704 tified. It will normally be quite straightforward to add additional
2705 pre-defined definitions, so if you need one, or have a good idea for
2706 one, then raise an issue at https://github.com/acassen/keepalived/is‐
2707 sues requesting it.
2708
2710 A line starting ~SEQ(var, start, step, end) will cause the remainder of
2711 the line to be processed multiple times, with the variable $var set
2712 initially to start, and then $var will be incremented by step repeat‐
2713 edly, terminating when it is greater than end. step may be omitted, in
2714 which case it defaults to 1 or -1, depending on whether end is greater
2715 or less than start. start may also be omitted, in which case it de‐
2716 faults to 1 if end > 0 or -1 if end < 0. ~SEQx(...) is the same as
2717 ~SEQ(...), except the variable $var will for formatted in hexadecimal,
2718 which would be useful for IPv6 addresses.
2719
2720 Note: At the moment it is necessary to use different variables for the
2721 ~SEQ block from any previously defined variable, including one used as
2722 the variable in a previous ~SEQ block. This may change in the future,
2723 so do not rely on a ~SEQ block variable being defined after the end of
2724 the block.
2725
2726 Examples:
2727
2728 ~SEQ(SUBNET, 0, 3) ip_address 10.0.${SUBNET}.1
2729
2730 would produce:
2731 ip_address 10.0.0.1
2732 ip_address 10.0.1.1
2733 ip_address 10.0.2.1
2734 ip_address 10.0.3.1
2735
2736 and
2737 ~SEQx(SUBNET, 144, 16, 192) ip_address fe80::20:${SUBNET}:1
2738 or better
2739 ~SEQx(SUBNET, 0x90, 0x10, 0xc0) ip_address fe80::20:${SUBNET}:1
2740
2741 would produce:
2742 ip_address fe80::20:90:1
2743 ip_address fe80::20:a0:1
2744 ip_address fe80::20:b0:1
2745 ip_address fe80::20:c0:1
2746
2747 Another example:
2748
2749 virtual_ipaddress {
2750 ~SEQx(AD2, 0x90, 0x10, 0xc0) ~SEQx(AD1, 0x12, -1, 0x0c) fe81::10:${AD2}:${AD1}
2751 }
2752
2753 There can be multiple ~SEQ elements on a line, so for example:
2754
2755 $VI4= \
2756 track_file offset_instance_4.${IF}.${NUM}.${ID} { \
2757 file "${_PWD}/679/track_files/4.${IF}.${NUM}.${ID}" \
2758 weight -100 \
2759 } \
2760 vrrp_instance vrrp4.${IF}.${NUM}.${ID} { \
2761 interface bond${IF}.${NUM} \
2762 use_vmac vrrp4.${IF}.${NUM}.${ID} \
2763 virtual_router_id ${ID} \
2764 priority 130 \
2765 virtual_ipaddress { \
2766 10.${IF}.${NUM}.${ID}/24 \
2767 } \
2768 track_file { \
2769 offset_instance_4.${IF}.${NUM}.${ID} \
2770 } \
2771 }
2772
2773 ~SEQ(IF,0,7) ~SEQ(NUM,0,31) ~SEQ(ID,1,254) $VI4
2774
2775 will produce 65024 vrrp instances with names from vrrp4.0.0.1 through to
2776 vrrp4.7.31.254.
2777
2779 List blocks are similar to sequence blocks, except that the values to
2780 substitute into the variable are listed in the ~LST specification.
2781
2782 A line starting ~LST(var, val1, val2, val3) will cause the remainder of
2783 the line to be processed multiple times, with the variable $var set
2784 initially to val1, and then val2, and finally val3. Any number of val‐
2785 ues can be specified, as long as at least one value is (although only
2786 one value would be pointless).
2787
2788 If it is desired to substitute more than one variable at a time, the
2789 variables and values need to be enclosed in {...} blocks. For example:
2790
2791 ~LST({IP, IP1}, {10,1},{20,4},{5,6},{12,8}) 192.168.${IP}.${IP1}
2792
2793 would first set IP=10 and IP1=1, then IP=20 and IP1=4, etc, and pro‐
2794 duces:
2795
2796 192.168.10.1
2797 192.168.20.4
2798 192.168.5.6
2799 192.168.12.8
2800
2801 List blocks can be nested, so:
2802
2803 ~LST(IP, 1, 2, 3, 4) ~LST(IP1, 5,6,7) 192.169.${IP}.${IP1}
2804
2805 produces:
2806 192.169.1.5
2807 192.169.1.6
2808 192.169.1.7
2809 192.169.2.5
2810 192.169.2.6
2811 192.169.2.7
2812 192.169.3.5
2813 192.169.3.6
2814 192.169.3.7
2815 192.169.4.5
2816 192.169.4.6
2817 192.169.4.7
2818
2819 Finally, list blocks and sequence blocks can be combined, so:
2820
2821 ~LST({IP, IP1}, {10,1},{20,4},{5,6},{12,8}) ~SEQ(IP2,168,2,172)
2822 192.${IP2}.${IP}.${IP1}
2823
2824 produces:
2825
2826 192.168.10.1
2827 192.170.10.1
2828 192.172.10.1
2829 192.168.20.4
2830 192.170.20.4
2831 192.172.20.4
2832 192.168.5.6
2833 192.170.5.6
2834 192.172.5.6
2835 192.168.12.8
2836 192.170.12.8
2837 192.172.12.8
2838
2840 It has been identified that if proxy_arp and proxy_arp_pvlan are en‐
2841 abled on an interface that has VIPs or eVIPs configured on it, it can
2842 cause incorrect replies to ARP requests due to the proxy replying to
2843 the ARP request as well as the keepalived host. Both need to be set to
2844 0 to function properly.
2845
2847 Initial by Joseph Mack. Extensive updates by Alexandre Cassen & Quentin
2848 Armitage.
2849
2851 ipvsadm(8), ip --help.
2852
2853
2854
2855Keepalived 2021-08-13 keepalived.conf(5)