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 connecttimeout is used. connecttimeout
95 is also a global value that may be overridden by a per-virtual setting.
96 If both negotiatetimeout and connecttimeout 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".
183 If defined in a virtual server section then the global value is
185 overridden.
186 logfile = "/path/to/logfile"|syslog_facility
188 An alternative logfile might be specified with this directive. If the
190 logfile does not have a leading '/', it is assumed to be a syslog(3)
191 facility name.
192 Default: log directly to the file /var/log/ldirectord.log.
194 emailalert = "emailaddress[, emailaddress]..."
196 A valid email address for sending alerts about the changed connection
198 status to any real server defined in the virtual service. This option
199 requires perl module MailTools to be installed. Automatically tries to
200 send email using any of the built-in methods. See perldoc Mail::Mailer
201 for more info on methods.
202 Multiple addresses may be supplied, comma delimited.
204 If defined in a virtual server section then the global value is
206 overridden.
207 emailalertfrom = emailaddress
209 A valid email address to use as the from address of the email alerts.
211 You can use a plain email address or any RFC-compliant string for the
212 From header in the body of an email message (such as: "ldirectord
213 Alerts" <alerts@example.com>) Do not quote this string unless you want
214 the quotes passed in as part of the From header.
215 Default: unset, take system generated default (probably root@hostname)
217 emailalertfreq = n
219 Delay in seconds between repeating email alerts while any given real
221 server in the virtual service remains inaccessible. A setting of zero
222 seconds will inhibit the repeating alerts. The email timing accuracy of
223 this setting is dependent on the number of seconds defined in the
224 checkinterval configuration option.
225 If defined in a virtual server section then the global value is
227 overridden.
228 Default: 0
230 emailalertstatus = all | none | starting | running | stopping |
232 reloading,...
233 Comma delimited list of server states in which email alerts should be
235 sent. all is a short-hand for "starting,running,stopping,reloading".
236 If none is specified, no other option may be specified, otherwise
237 options are ored with each other.
238 If defined in a virtual server section then the global value is
240 overridden.
241 Default: all
243 smtp = ip_address|hostname"
245 A valid SMTP server address to use for sending email via SMTP.
247 If defined in a virtual server section then the global value is
249 overridden.
250 execute = "configuration"
252 Use this directive to start an instance of ldirectord for the named
254 configuration.
255 supervised = yes | no
257 If yes, then ldirectord does not go into background mode. All log-
259 messages are redirected to stdout instead of a logfile. This is useful
260 to run ldirectord supervised from daemontools. See
261 http://untroubled.org/rpms/daemontools/ or
262 http://cr.yp.to/daemontools.html for details.
263 Default: no
265 fork = yes | no
267 If yes, then ldirectord will spawn a child process for every virtual
269 server, and run checks against the real servers from them. This will
270 increase response times to changes in real server status in
271 configurations with many virtual servers. This may also use less
272 memory then running many separate instances of ldirectord. Child
273 processes will be automatically restarted if they die.
274 Default: no
276 quiescent = yes | no
278 If yes, then when real or failback servers are determined to be down,
280 they are not actually removed from the kernel's LVS table. Rather,
281 their weight is set to zero which means that no new connections will be
282 accepted.
283 This has the side effect, that if the real server has persistent
285 connections, new connections from any existing clients will continue to
286 be routed to the real server, until the persistent timeout can expire.
287 See ipvsadm for more information on persistent connections.
288 This side-effect can be avoided by running the following:
290 echo 1 > /proc/sys/net/ipv4/vs/expire_quiescent_template
292 If the proc file isn't present this probably means that the kernel
294 doesn't have LVS support, LVS support isn't loaded, or the kernel is
295 too old to have the proc file. Running ipvsadm as root should load LVS
296 into the kernel if it is possible.
297 If no, then the real or failback servers will be removed from the
299 kernel's LVS table. The default is yes.
300 If defined in a virtual server section then the global value is
302 overridden.
303 Default: yes
305 cleanstop = yes | no
307 If yes, then when ldirectord exits it will remove all of the virtual
309 server pools that it is managing from the kernel's LVS table.
310 If no, then the virtual server pools it is managing and any real or
312 failback servers listed in them at the time ldirectord exits will be
313 left as-is. If you want to be able to stop ldirectord without having
314 traffic to your realservers interrupted you will want to set this to
315 no.
316 If defined in a virtual server section then the global value is
318 overridden.
319 Default: yes
321 maintenancedir = directoryname
323 If this option is set ldirectord will look for a special file in the
325 specified directory and, if found, force the status of the real server
326 identified by the file to down, skipping the normal health check. This
327 would be useful if you wish to force servers down for maintenance
328 without having to modify the actual ldirectord configuration file.
329 For example, given a realserver with IP 172.16.1.2, service on port
331 4444, and a resolvable reverse DNS entry pointing to
332 "realserver2.example.com" ldirectord will check for the existence of
333 the following files:
334 172.16.1.2:4444
336 172.16.1.2
337 realserver2.example.com:4444
338 realserver2.example.com
339 realserver2:4444
340 realserver2
341 If any one of those files is found then ldirectord will immediately
343 force the status of the server to down as if the check had failed.
344 Note: Since it checks for the IP/hostname without the port this means
346 you can decide to place an entire realserver into maintenance across a
347 large number of virtual service pools with a single file (if you were
348 going to reboot the server, for instance) or include the port number
349 and put just a particular service into maintenance.
350 This option is not valid in a virtual server section.
352 Default: disabled
354 Section virtual
356 The following commands must follow a virtual entry and must be indented
357 with a minimum of 4 spaces or one tab.
358 real =
360 ip_address|hostname[->ip_address|hostname][:portnumber|servicename]
361 gate | masq | ipip [weight] ["request", "receive"]
362 Defines a real service by IP-address (or hostname) and port (or
364 servicename). If the port is omitted then a 0 will be used, this is
365 intended primarily for fwmark services where the port for real servers
366 is ignored. Optionally a range of IPv4 addresses (or two hostnames) may
367 be given, in which case each IPv4 address in the range will be treated
368 as a real server using the given port. The second argument defines the
369 forwarding method, must be gate, ipip or masq. The third argument is
370 optional and defines the weight for that real server. If omitted then a
371 weight of 1 will be used. The last two arguments are also optional.
372 They define a request-receive pair to be used to check if a server is
373 alive. They override the request-receive pair in the virtual server
374 section. These two strings must be quoted. If the request string starts
375 with http://... the IP-address and port of the real server is
376 overridden, otherwise the IP-address and port of the real server is
377 used.
378 For TCP and UDP (non fwmark) virtual services, unless the forwarding
380 method is masq and the IP address of a real server is non-local (not
381 present on a interface on the host running ldirectord) then the port of
382 the real server will be set to that of its virtual service. That is,
383 port-mapping is only available to if the real server is another machine
384 and the forwarding method is masq. This is due to the way that the
385 underlying LVS code in the kernel functions.
386 More than one of these entries may be inside a virtual section. The
387 checktimeout, negotiatetimeout, checkcount, fallback, emailalert,
388 emailalertfreq and quiescent options listed above may also appear
389 inside a virtual section, in which case the global setting is
390 overridden.
391 checktype = connect | external | external-perl | negotiate | off | on |
392 ping | checktimeoutN
393 Type of check to perform. Negotiate sends a request and matches a
395 receive string. Connect only attempts to make a TCP/IP connection, thus
396 the request and receive strings may be omitted. If checktype is a
397 number then negotiate and connect is combined so that after each N
398 connect attempts one negotiate attempt is performed. This is useful to
399 check often if a service answers and in much longer intervals a
400 negotiating check is done. Ping means that ICMP ping will be used to
401 test the availability of real servers. Ping is also used as the
402 connect check for UDP services. Off means no checking will take place
403 and no real or fallback servers will be activated. On means no
404 checking will take place and real servers will always be activated.
405 Default is negotiate.
406 service = dns | ftp | http | https | http_proxy | imap | imaps | ldap |
408 mysql | nntp | none | oracle | pgsql | pop | pops | radius | simpletcp
409 | sip | smtp | submission
410 The type of service to monitor when using checktype=negotiate. None
412 denotes a service that will not be monitored.
413 simpletcp sends the request string to the server and tests it against
415 the receive regexp. The other types of checks connect to the server
416 using the specified protocol. Please see the request and receive
417 sections for protocol specific information.
418 Default:
420 · Virtual server port is 21: ftp
422 · Virtual server port is 25: smtp
424 · Virtual server port is 53: dns
426 · Virtual server port is 80: http
428 · Virtual server port is 110: pop
430 · Virtual server port is 119: nntp
432 · Virtual server port is 143: imap
434 · Virtual server port is 389: ldap
436 · Virtual server port is 443: https
438 · Virtual server port is 587: submission
440 · Virtual server port is 993: imaps
442 · Virtual server port is 995: pops
444 · Virtual server port is 1521: oracle
446 · Virtual server port is 1812: radius
448 · Virtual server port is 3128: http_proxy
450 · Virtual server port is 3306: mysql
452 · Virtual server port is 5432: pgsql
454 · Virtual server port is 5060: sip
456 · Otherwise: none
458 checkcommand = "path to script"
460 This setting is used if checktype is external or external-perl and is
462 the command to be run to check the status of a real server. It should
463 exit with status 0 if everything is ok, or non-zero otherwise.
464 Four parameters are passed to the script:
466 · virtual server ip/firewall mark
468 · virtual server port
470 · real server ip
472 · real server port
474 If the checktype is external-perl then the command is assumed to be a
476 Perl script and it is evaluated into an anonymous subroutine which is
477 called at check time, avoiding a fork-exec. The argument signature and
478 exit code conventions are identical to checktype external. That is, an
479 external-perl checktype should also work as an external checktype.
480 Default: /bin/true
482 checkport = n
484 Number of port to monitor. Sometimes check port differs from service
486 port.
487 Default: port specified for each real server
489 request = "uri to requested object"
491 This object will be requested each checkinterval seconds on each real
493 server. The string must be inside quotes. Note that this string may be
494 overridden by an optional per real-server based request-string.
495 For an HTTP/HTTPS check, this should be a relative URI, while it has to
497 be absolute for the 'http_proxy' check type. In the latter case, this
498 URI will be requested through the proxy backend that is being checked.
499 For a DNS check this should the name of an A record, or the address of
501 a PTR record to look up.
502 For a MySQL, Oracle or PostgeSQL check, this should be an SQL SELECT
504 query. The data returned is not checked, only that the answer is one
505 or more rows. This is a required setting.
506 For a simpletcp check, this string is sent verbatim except any
508 occurrences of \n are replaced with a new line character.
509 receive = "regexp to compare"
511 If the requested result contains this regexp to compare, the real
513 server is declared alive. The regexp must be inside quotes. Keep in
514 mind that regexps are not plain strings and that you need to escape the
515 special characters if they should as literals. Note that this regexp
516 may be overridden by an optional per real-server based receive regexp.
517 For a DNS check this should be any one the A record's addresses or any
519 one of the PTR record's names.
520 For a MySQL check, the receive setting is not used.
522 httpmethod = GET | HEAD
524 Sets the HTTP method which should be used to fetch the URI specified in
526 the request-string. GET is the method used by default if the parameter
527 is not set. If HEAD is used, the receive-string should be unset.
528 Default: GET
530 virtualhost = "hostname"
532 Used when using a negotiate check with HTTP or HTTPS. Sets the host
534 header used in the HTTP request. In the case of HTTPS this generally
535 needs to match the common name of the SSL certificate. If not set then
536 the host header will be derived from the request url for the real
537 server if present. As a last resort the IP address of the real server
538 will be used.
539 login = "username"
541 For FTP, IMAP, LDAP, MySQL, Oracle, POP and PostgreSQL, the username
543 used to log in.
544 For Radius the passwd is used for the attribute User-Name.
546 For SIP, the username is used as both the to and from address for an
548 OPTIONS query.
549 Default:
551 · FTP: Anonymous
553 · MySQL Oracle, and PostgreSQL: Must be specified in the
555 configuration
556 · SIP: ldirectord\@<hostname>, hostname is derived as per the passwd
558 option below.
559 · Otherwise: empty string, which denotes that case
561 authentication will not be attempted.
562 passwd = "password"
564 Password to use to login to FTP, IMAP, LDAP, MySQL, Oracle, POP,
566 PostgreSQL and SIP servers.
567 For Radius the passwd is used for the attribute User-Password.
569 Default:
571 · FTP: ldirectord\@<hostname>, where hostname is the environment
573 variable HOSTNAME evaluated at run time, or sourced from uname
574 if unset.
575 · Otherwise: empty string. In the case of LDAP, MySQL, Oracle,
577 and PostgreSQL this means that authentication will not be
578 performed.
579 database = "databasename"
581 Database to use for MySQL, Oracle and PostgreSQL servers, this is the
583 database that the query (set by receive above) will be performed
584 against. This is a required setting.
585 secret = "radiussecret"
587 Secret to use for Radius servers, this is the secret used to perform an
589 Access-Request with the username (set by login above) and passwd (set
590 by passwd above).
591 Default: empty string
593 scheduler = scheduler_name
595 Scheduler to be used by LVS for loadbalancing. For an information on
597 the available sehedulers please see the ipvsadm(8) man page.
598 Default: "wrr"
600 persistent = n
602 Number of seconds for persistent client connections.
604 netmask = w.x.y.z | prefixlen
606 Netmask to be used for granularity of persistent client connections.
608 IPv4 netmask should be specified in dotted quad notation. IPv6 netmask
609 should be specified as a prefix length between 1 and 128.
610 protocol = tcp | udp | fwm
612 Protocol to be used. If the virtual is specified as an IP address and
614 port then it must be one of tcp or udp. If a firewall mark then the
615 protocol must be fwm.
616 Default:
618 · Virtual is an IP address and port, and the port is not 53: tcp
620 · Virtual is an IP address and port, and the port is 53: udp
622 · Virtual is a firewall mark: fwm
624 monitorfile = "/path/to/monitorfile"
626 File to continuously log the real service checks to for this virtual
628 service. This is useful for monitoring when and why real services were
629 down or for statistics.
630 The log format is: [timestamp|pid|real_service_id|status|message]
632 Default: no separate logging of service checks.
634
636 Directives for IPv6 are virtual6, real6, fallback6. IPv6 addresses
637 specified for virtual6, real6, fallback6 and a file of maintenance
638 directory should be enclosed by brackets ([2001:db8::abcd]:80).
639 Following checktype and service are supported.
641 checktype: connect | external | external-perl | negotiate | off | on |
643 checktimeoutN
644 service: dns | nntp | none | simpletcp | sip
646
648 /etc/ha.d/ldirectord.cf
649 /var/log/ldirectord.log
651 /var/run/ldirectord.configuration.pid
653 /etc/services
655
657 ipvsadm, heartbeat
658 Ldirectord Web Page: http://www.vergenet.net/linux/ldirectord/
660
662 Horms <horms@verge.net.au>
663 Jacob Rief <jacob.rief@tiscover.com>
665perl v5.12.3 2011-07-08 LDIRECTORD(8)