1LDIRECTORD(8) User Contributed Perl Documentation LDIRECTORD(8)
2
6 ldirectord - Linux Director Daemon
7 Daemon to monitor remote services and control Linux Virtual Server
9
11 ldirectord [-d|--debug] [--] [configfile] start | stop | restart | try-
12 restart | reload | force-reload | status
13 ldirectord [-h|-?|--help|-v|--version]
15
17 ldirectord is a daemon to monitor and administer real servers in a
18 cluster of load balanced virtual servers. ldirectord typically is
19 started from heartbeat but can also be run from the command line. On
20 startup ldirectord reads the file /etc/ha.d/conf/configuration. After
21 parsing the file, entries for virtual servers are created on the LVS.
22 Now at regular intervals the specified real servers are monitored and
23 if they are considered alive, added to a list for each virtual server.
24 If a real server fails, it is removed from that list. Only one instance
25 of ldirectord can be started for each configuration, but more instances
26 of ldirectord may be started for different configurations. This helps
27 to group clusters of services. Normally one would put an entry inside
28 /etc/ha.d/haresources
29 nodename virtual-ip-address ldirectord::configuration
31 to start ldirectord from heartbeat.
33
35 configuration: This is the name for the configuration as specified in
36 the file /etc/ha.d/conf/configuration
37 -d|--debug Don't start as daemon and log verbosely.
39 -h|--help Print user manual and exit.
41 -v|--version Print version and exit.
43 start the daemon for the specified configuration.
45 stop the daemon for the specified configuration. This is the same as
47 sending a TERM signal to the running daemon.
48 restart the daemon for the specified configuration. The same as
50 stopping and starting.
51 reload the configuration file. This is only useful for modifications
53 inside a virtual server entry. It will have no effect on adding or
54 removing a virtual server block. This is the same as sending a HUP
55 signal to the running daemon.
56 status of the running daemon for the specified configuration.
58
60 Description of how to write configuration files
61 virtual = (ip_address|hostname:portnumber|servicename)|firewall-mark
62 Defines a virtual service by IP-address (or hostname) and port (or
64 servicename) or firewall-mark. A firewall-mark is an integer greater
65 than zero. The configuration of marking packets is controlled using the
66 "-m" option to ipchains(8). All real services and flags for a virtual
67 service must follow this line immediately and be indented.
68 checktimeout = n
70 Timeout in seconds for connect, external, external-perl and ping
72 checks. If the timeout is exceeded then the real server is declared
73 dead.
74 If defined in a virtual server section then the global value is
76 overridden.
77 If undefined then the value of negotiatetimeout is used.
79 negotiatetimeout is also a global value that may be overridden by a
80 per-virtual setting.
81 If both checktimeout and negotiatetimeout are unset, the default is
83 used.
84 Default: 5 seconds
86 negotiatetimeout = n
88 Timeout in seconds for negotiate checks.
90 If defined in a virtual server section then the global value is
92 overridden.
93 If undefined then the value of checktimeout is used. checktimeout is
95 also a global value that may be overridden by a per-virtual setting.
96 If both negotiatetimeout and checktimeout are unset, the default is
98 used.
99 Default: 30 seconds
101 checkinterval = n
103 Defines the number of second between server checks.
105 When fork=no this option defines the amount of time ldirectord sleeps
107 between running all of the realserver checks in all virtual service
108 pools.
109 When fork=yes this option defines the amount of time each forked child
111 sleeps per virtual service pool after running all realserver checks for
112 that pool.
113 If set in the virtual server section then the global value is
115 overridden, but ONLY if using forking mode (fork = yes).
116 Default: 10 seconds
118 checkcount = n
120 This option is deprecated and slated for removal in a future version.
122 Please see the 'failurecount' option.
123 The number of times a check will be attempted before it is considered
125 to have failed. Only works with ping checks. Note that the
126 checktimeout/negotiatetimeout is additive, so if a connect check is
127 used, checkcount is 3 and checktimeout is 2 seconds, then a total of 6
128 seconds worth of timeout will occur before the check fails.
129 If defined in a virtual server section then the global value is
131 overridden.
132 Default: 1
134 failurecount = n
136 The number of consecutive times a failure will have to be reported by a
138 check before the realserver is considered to have failed. A value of 1
139 will have the realserver considered failed on the first failure. A
140 successful check will reset the failure counter to 0.
141 If defined in a virtual server section then the global value is
143 overridden.
144 Default: 1
146 autoreload = yes | no
148 Defines if <ldirectord> should continuously check the configuration
150 file for modification. If this is set to 'yes' and the configuration
151 file changed on disk and its modification time (mtime) is newer than
152 the previous version, the configuration is automatically reloaded.
153 Default: no
155 callback = "/path/to/callback"
157 If this directive is defined, ldirectord automatically calls the
159 executable /path/to/callback after the configuration file has changed
160 on disk. This is useful to update the configuration file through scp on
161 the other heartbeated host. The first argument to the callback is the
162 name of the configuration.
163 This directive might also be used to restart ldirectord automatically
165 after the configuration file changed on disk. However, if autoreload is
166 set to yes, the configuration is reloaded anyway.
167 fallback = ip_address|hostname[:portnumber|sercvicename] [gate | masq |
169 ipip]
170 the server onto which a webservice is redirected if all real servers
172 are down. Typically this would be 127.0.0.1 with an emergency page.
173 If defined in a virtual server section then the global value is
175 overridden.
176 fallbackcommand = "path to script"
178 If this directive is defined, the supplied script is executed whenever
180 all real servers for a virtual service are down or when the first real
181 server comes up again. In the first case, it is called with "start" as
182 its first argument, in the latter with "stop". Additional parameters
183 are vserver with vport (vserver:vport) as second param and protocol
184 (tcp/udp) as third param to identify the virtual service within the
185 fallback script.
186 If defined in a virtual server section then the global value is
188 overridden.
189 logfile = "/path/to/logfile"|syslog_facility
191 An alternative logfile might be specified with this directive. If the
193 logfile does not have a leading '/', it is assumed to be a syslog(3)
194 facility name.
195 Default: log directly to the file /var/log/ldirectord.log.
197 emailalert = "emailaddress[, emailaddress]..."
199 A valid email address for sending alerts about the changed connection
201 status to any real server defined in the virtual service. This option
202 requires perl module MailTools to be installed. Automatically tries to
203 send email using any of the built-in methods. See perldoc Mail::Mailer
204 for more info on methods.
205 Multiple addresses may be supplied, comma delimited.
207 If defined in a virtual server section then the global value is
209 overridden.
210 emailalertfrom = emailaddress
212 A valid email address to use as the from address of the email alerts.
214 You can use a plain email address or any RFC-compliant string for the
215 From header in the body of an email message (such as: "ldirectord
216 Alerts" <alerts@example.com>) Do not quote this string unless you want
217 the quotes passed in as part of the From header.
218 Default: unset, take system generated default (probably root@hostname)
220 emailalertfreq = n
222 Delay in seconds between repeating email alerts while any given real
224 server in the virtual service remains inaccessible. A setting of zero
225 seconds will inhibit the repeating alerts. The email timing accuracy of
226 this setting is dependent on the number of seconds defined in the
227 checkinterval configuration option.
228 If defined in a virtual server section then the global value is
230 overridden.
231 Default: 0
233 emailalertstatus = all | none | starting | running | stopping |
235 reloading,...
236 Comma delimited list of server states in which email alerts should be
238 sent. all is a short-hand for "starting,running,stopping,reloading".
239 If none is specified, no other option may be specified, otherwise
240 options are ored with each other.
241 If defined in a virtual server section then the global value is
243 overridden.
244 Default: all
246 smtp = ip_address|hostname"
248 A valid SMTP server address to use for sending email via SMTP.
250 If defined in a virtual server section then the global value is
252 overridden.
253 execute = "configuration"
255 Use this directive to start an instance of ldirectord for the named
257 configuration.
258 supervised = yes | no
260 If yes, then ldirectord does not go into background mode. All log-
262 messages are redirected to stdout instead of a logfile. This is useful
263 to run ldirectord supervised from daemontools. See
264 http://untroubled.org/rpms/daemontools/ or
265 http://cr.yp.to/daemontools.html for details.
266 Default: no
268 fork = yes | no
270 If yes, then ldirectord will spawn a child process for every virtual
272 server, and run checks against the real servers from them. This will
273 increase response times to changes in real server status in
274 configurations with many virtual servers. This may also use less
275 memory then running many separate instances of ldirectord. Child
276 processes will be automatically restarted if they die.
277 Default: no
279 quiescent = yes | no
281 If yes, then when real or failback servers are determined to be down,
283 they are not actually removed from the kernel's LVS table. Rather,
284 their weight is set to zero which means that no new connections will be
285 accepted.
286 This has the side effect, that if the real server has persistent
288 connections, new connections from any existing clients will continue to
289 be routed to the real server, until the persistent timeout can expire.
290 See ipvsadm for more information on persistent connections.
291 This side-effect can be avoided by running the following:
293 echo 1 > /proc/sys/net/ipv4/vs/expire_quiescent_template
295 If the proc file isn't present this probably means that the kernel
297 doesn't have LVS support, LVS support isn't loaded, or the kernel is
298 too old to have the proc file. Running ipvsadm as root should load LVS
299 into the kernel if it is possible.
300 If no, then the real or failback servers will be removed from the
302 kernel's LVS table. The default is yes.
303 If defined in a virtual server section then the global value is
305 overridden.
306 Default: yes
308 readdquiescent = yes | no
310 If yes, then when real or failback servers are determined to be down,
312 they are readded to the kernel's LVS table with weight 0 if they do not
313 exist in the table. Setting the value to no, allows manually removing
314 the realserver to manually disable all persistent connections.
315 cleanstop = yes | no
317 If yes, then when ldirectord exits it will remove all of the virtual
319 server pools that it is managing from the kernel's LVS table.
320 If no, then the virtual server pools it is managing and any real or
322 failback servers listed in them at the time ldirectord exits will be
323 left as-is. If you want to be able to stop ldirectord without having
324 traffic to your realservers interrupted you will want to set this to
325 no.
326 If defined in a virtual server section then the global value is
328 overridden.
329 Default: yes
331 maintenancedir = directoryname
333 If this option is set ldirectord will look for a special file in the
335 specified directory and, if found, force the status of the real server
336 identified by the file to down, skipping the normal health check. This
337 would be useful if you wish to force servers down for maintenance
338 without having to modify the actual ldirectord configuration file.
339 For example, given a realserver with IP 172.16.1.2, service on port
341 4444, and a resolvable reverse DNS entry pointing to
342 "realserver2.example.com" ldirectord will check for the existence of
343 the following files:
344 172.16.1.2:4444
346 172.16.1.2
347 realserver2.example.com:4444
348 realserver2.example.com
349 realserver2:4444
350 realserver2
351 If any one of those files is found then ldirectord will immediately
353 force the status of the server to down as if the check had failed.
354 Note: Since it checks for the IP/hostname without the port this means
356 you can decide to place an entire realserver into maintenance across a
357 large number of virtual service pools with a single file (if you were
358 going to reboot the server, for instance) or include the port number
359 and put just a particular service into maintenance.
360 This option is not valid in a virtual server section.
362 Default: disabled
364 Section virtual
366 The following commands must follow a virtual entry and must be indented
367 with a minimum of 4 spaces or one tab.
368 real =
370 ip_address|hostname[->ip_address|hostname][:portnumber|servicename]
371 gate | masq | ipip [weight] ["request", "receive"] [ "<l:l-threshold>"
372 ] [ "<u:u-threshold>" ]
373 Defines a real service by IP-address (or hostname) and port (or
375 servicename). If the port is omitted then a 0 will be used, this is
376 intended primarily for fwmark services where the port for real servers
377 is ignored. Optionally a range of IPv4 addresses (or two hostnames) may
378 be given, in which case each IPv4 address in the range will be treated
379 as a real server using the given port. The second argument defines the
380 forwarding method, must be gate, ipip or masq. The third argument is
381 optional and defines the weight for that real server. If omitted then a
382 weight of 1 will be used. The next two arguments are also optional.
383 They define a request-receive pair to be used to check if a server is
384 alive. They override the request-receive pair in the virtual server
385 section. These two strings must be quoted. If the request string starts
386 with http://... the IP-address and port of the real server is
387 overridden, otherwise the IP-address and port of the real server is
388 used. The last two optionals arguments set lower and upper connection
389 thresholds for real servers using -y and -x ipvsadm argument.
390 For TCP and UDP (non fwmark) virtual services, unless the forwarding
392 method is masq and the IP address of a real server is non-local (not
393 present on a interface on the host running ldirectord) then the port of
394 the real server will be set to that of its virtual service. That is,
395 port-mapping is only available to if the real server is another machine
396 and the forwarding method is masq. This is due to the way that the
397 underlying LVS code in the kernel functions.
398 More than one of these entries may be inside a virtual section. The
399 checktimeout, negotiatetimeout, checkcount, fallback, emailalert,
400 emailalertfreq and quiescent options listed above may also appear
401 inside a virtual section, in which case the global setting is
402 overridden.
403 checktype = connect | external | external-perl | negotiate | off | on |
404 ping | checktimeoutN
405 Type of check to perform. Negotiate sends a request and matches a
407 receive string. Connect only attempts to make a TCP/IP connection, thus
408 the request and receive strings may be omitted. If checktype is a
409 number then negotiate and connect is combined so that after each N
410 connect attempts one negotiate attempt is performed. This is useful to
411 check often if a service answers and in much longer intervals a
412 negotiating check is done. Ping means that ICMP ping will be used to
413 test the availability of real servers. Ping is also used as the
414 connect check for UDP services. Off means no checking will take place
415 and no real or fallback servers will be activated. On means no
416 checking will take place and real servers will always be activated.
417 Default is negotiate.
418 service = dns | ftp | http | https | http_proxy | imap | imaps | ldap |
420 ldaps | mysql | nntp | none | oracle | pgsql | pop | pops | radius |
421 simpletcp | sip | smtp | submission
422 The type of service to monitor when using checktype=negotiate. None
424 denotes a service that will not be monitored.
425 simpletcp sends the request string to the server and tests it against
427 the receive regexp. The other types of checks connect to the server
428 using the specified protocol. Please see the request and receive
429 sections for protocol specific information.
430 Default:
432 • Virtual server port is 21: ftp
434 • Virtual server port is 25: smtp
436 • Virtual server port is 53: dns
438 • Virtual server port is 80: http
440 • Virtual server port is 110: pop
442 • Virtual server port is 119: nntp
444 • Virtual server port is 143: imap
446 • Virtual server port is 389: ldap
448 • Virtual server port is 443: https
450 • Virtual server port is 587: submission
452 • Virtual server port is 636 ldaps
454 • Virtual server port is 993: imaps
456 • Virtual server port is 995: pops
458 • Virtual server port is 1521: oracle
460 • Virtual server port is 1812: radius
462 • Virtual server port is 3128: http_proxy
464 • Virtual server port is 3306: mysql
466 • Virtual server port is 5432: pgsql
468 • Virtual server port is 5060: sip
470 • Otherwise: none
472 checkcommand = "path to script"
474 This setting is used if checktype is external or external-perl and is
476 the command to be run to check the status of a real server. It should
477 exit with status 0 if everything is ok, or non-zero otherwise.
478 Four parameters are passed to the script:
480 • virtual server ip/firewall mark
482 • virtual server port
484 • real server ip
486 • real server port
488 If the checktype is external-perl then the command is assumed to be a
490 Perl script and it is evaluated into an anonymous subroutine which is
491 called at check time, avoiding a fork-exec. The argument signature and
492 exit code conventions are identical to checktype external. That is, an
493 external-perl checktype should also work as an external checktype.
494 Default: /bin/true
496 checkport = n
498 Number of port to monitor. Sometimes check port differs from service
500 port.
501 Default: port specified for each real server
503 request = "uri to requested object"
505 This object will be requested each checkinterval seconds on each real
507 server. The string must be inside quotes. Note that this string may be
508 overridden by an optional per real-server based request-string.
509 For an HTTP/HTTPS check, this should be a relative URI, while it has to
511 be absolute for the 'http_proxy' check type. In the latter case, this
512 URI will be requested through the proxy backend that is being checked.
513 For a DNS check this should the name of an A record, or the address of
515 a PTR record to look up.
516 For a MySQL, Oracle or PostgeSQL check, this should be an SQL SELECT
518 query. The data returned is not checked, only that the answer is one
519 or more rows. This is a required setting.
520 For a simpletcp check, this string is sent verbatim except any
522 occurrences of \n are replaced with a new line character.
523 receive = "regexp to compare"
525 If the requested result contains this regexp to compare, the real
527 server is declared alive. The regexp must be inside quotes. Keep in
528 mind that regexps are not plain strings and that you need to escape the
529 special characters if they should as literals. Note that this regexp
530 may be overridden by an optional per real-server based receive regexp.
531 For a DNS check this should be any one the A record's addresses or any
533 one of the PTR record's names. In case of dynamic DNS answers
534 (different answers on the same question) a regex to match multiple
535 addresses or PTR record names could also defined.
536 For a MySQL check, the receive setting is not used.
538 httpmethod = GET | HEAD
540 Sets the HTTP method which should be used to fetch the URI specified in
542 the request-string. GET is the method used by default if the parameter
543 is not set. If HEAD is used, the receive-string should be unset.
544 Default: GET
546 virtualhost = "hostname"
548 Used when using a negotiate check with HTTP or HTTPS. Sets the host
550 header used in the HTTP request. In the case of HTTPS this generally
551 needs to match the common name of the SSL certificate. If not set then
552 the host header will be derived from the request url for the real
553 server if present. As a last resort the IP address of the real server
554 will be used.
555 login = "username"
557 For FTP, IMAP, LDAP, MySQL, Oracle, POP and PostgreSQL, the username
559 used to log in.
560 For RADIUS the username is used for the attribute User-Name.
562 For SIP, the username is used as both the to and from address for an
564 OPTIONS query.
565 Default:
567 • FTP: Anonymous
569 • MySQL Oracle, and PostgreSQL: Must be specified in the
571 configuration
572 • SIP: ldirectord\@<hostname>, hostname is derived as per the passwd
574 option below.
575 • Otherwise: empty string, which denotes that case
577 authentication will not be attempted.
578 passwd = "password"
580 Password to use to login to FTP, IMAP, LDAP, MySQL, Oracle, POP,
582 PostgreSQL and SIP servers.
583 For RADIUS the passwd is used for the attribute User-Password.
585 Default:
587 • FTP: ldirectord\@<hostname>, where hostname is the environment
589 variable HOSTNAME evaluated at run time, or sourced from uname
590 if unset.
591 • Otherwise: empty string. In the case of LDAP, MySQL, Oracle,
593 and PostgreSQL this means that authentication will not be
594 performed.
595 database = "databasename"
597 Database to use for MySQL, Oracle and PostgreSQL servers, this is the
599 database that the query (set by receive above) will be performed
600 against. This is a required setting.
601 secret = "radiussecret"
603 Secret to use for RADIUS servers, this is the secret used to perform an
605 Access-Request with the username (set by login above) and passwd (set
606 by passwd above).
607 Default: empty string
609 scheduler = scheduler_name
611 Scheduler to be used by LVS for loadbalancing. For an information on
613 the available sehedulers please see the ipvsadm(8) man page.
614 Default: "wrr"
616 persistent = n
618 Number of seconds for persistent client connections.
620 netmask = w.x.y.z | prefixlen
622 Netmask to be used for granularity of persistent client connections.
624 IPv4 netmask should be specified in dotted quad notation. IPv6 netmask
625 should be specified as a prefix length between 1 and 128.
626 protocol = tcp | udp | fwm
628 Protocol to be used. If the virtual is specified as an IP address and
630 port then it must be one of tcp or udp. If a firewall mark then the
631 protocol must be fwm.
632 Default:
634 • Virtual is an IP address and port, and the port is not 53: tcp
636 • Virtual is an IP address and port, and the port is 53: udp
638 • Virtual is a firewall mark: fwm
640 monitorfile = "/path/to/monitorfile"
642 File to continuously log the real service checks to for this virtual
644 service. This is useful for monitoring when and why real services were
645 down or for statistics.
646 The log format is: [timestamp|pid|real_service_id|status|message]
648 Default: no separate logging of service checks.
650 ops = yes | no
652 Specify that a virtual service uses one-packet scheduling. This option
654 can be used only for UDP services. If this option is specified, all
655 connections are created only to schedule one packet. Option is useful
656 to schedule UDP packets from same client port to different real
657 servers.
658 servicename = short name
660 A name for this service. This is for the sole purpose of making it
662 easier to know which service is affected when e-mail notifications are
663 sent out. It will be included in the e-mail subject and body.
664 comment = comment
666 Notes about this service to be included in e-mail notifications (for
668 example, purpose of the service or relevant administrator to contact).
669
671 Directives for IPv6 are virtual6, real6, fallback6. IPv6 addresses
672 specified for virtual6, real6, fallback6 and a file of maintenance
673 directory should be enclosed by brackets ([2001:db8::abcd]:80).
674 Following checktype and service are supported.
676 checktype: connect | external | external-perl | negotiate | off | on |
678 checktimeoutN
679 service: dns | http | https | nntp | none | simpletcp | sip
681 Note: When using a service type with http or https, you need to install
683 perl module perl-Net-INET6Glue.
684
686 /etc/ha.d/ldirectord.cf
687 /var/log/ldirectord.log
689 /var/run/ldirectord.configuration.pid
691 /etc/services
693
695 ipvsadm, heartbeat
696 Ldirectord Web Page: http://www.vergenet.net/linux/ldirectord/
698
700 Horms <horms@verge.net.au>
701 Jacob Rief <jacob.rief@tiscover.com>
703perl v5.36.0 2023-01-25 LDIRECTORD(8)