1LDIRECTORD(8)         User Contributed Perl Documentation        LDIRECTORD(8)
2
3
4

NAME

6       ldirectord - Linux Director Daemon
7
8       Daemon to monitor remote services and control Linux Virtual Server
9

SYNOPSIS

11       ldirectord [-d|--debug] [--] [configfile] start | stop | restart | try-
12       restart | reload | force-reload | status
13
14       ldirectord [-h|-?|--help|-v|--version]
15

DESCRIPTION

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
30       nodename virtual-ip-address ldirectord::configuration
31
32       to start ldirectord from heartbeat.
33

OPTIONS

35       configuration: This is the name for the configuration as specified in
36       the file /etc/ha.d/conf/configuration
37
38       -d|--debug Don't start as daemon and log verbosely.
39
40       -h|--help Print user manual and exit.
41
42       -v|--version Print version and exit.
43
44       start the daemon for the specified configuration.
45
46       stop the daemon for the specified configuration. This is the same as
47       sending a TERM signal to the running daemon.
48
49       restart the daemon for the specified configuration. The same as
50       stopping and starting.
51
52       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
57       status of the running daemon for the specified configuration.
58

SYNTAX

60   Description of how to write configuration files
61       virtual = (ip_address|hostname:portnumber|servicename)|firewall-mark
62
63       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
69       checktimeout = n
70
71       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
75       If defined in a virtual server section then the global value is
76       overridden.
77
78       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
82       If both checktimeout and negotiatetimeout are unset, the default is
83       used.
84
85       Default: 5 seconds
86
87       negotiatetimeout = n
88
89       Timeout in seconds for negotiate checks.
90
91       If defined in a virtual server section then the global value is
92       overridden.
93
94       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
97       If both negotiatetimeout and checktimeout are unset, the default is
98       used.
99
100       Default: 30 seconds
101
102       checkinterval = n
103
104       Defines the number of second between server checks.
105
106       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
110       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
114       If set in the virtual server section then the global value is
115       overridden, but ONLY if using forking mode (fork = yes).
116
117       Default: 10 seconds
118
119       checkcount = n
120
121       This option is deprecated and slated for removal in a future version.
122       Please see the 'failurecount' option.
123
124       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
130       If defined in a virtual server section then the global value is
131       overridden.
132
133       Default: 1
134
135       failurecount = n
136
137       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
142       If defined in a virtual server section then the global value is
143       overridden.
144
145       Default: 1
146
147       autoreload = yes | no
148
149       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
154       Default: no
155
156       callback = "/path/to/callback"
157
158       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
164       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
168       fallback = ip_address|hostname[:portnumber|sercvicename] [gate | masq |
169       ipip]
170
171       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
174       If defined in a virtual server section then the global value is
175       overridden.
176
177       fallbackcommand = "path to script"
178
179       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
187       If defined in a virtual server section then the global value is
188       overridden.
189
190       logfile = "/path/to/logfile"|syslog_facility
191
192       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
196       Default: log directly to the file /var/log/ldirectord.log.
197
198       emailalert = "emailaddress[, emailaddress]..."
199
200       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
206       Multiple addresses may be supplied, comma delimited.
207
208       If defined in a virtual server section then the global value is
209       overridden.
210
211       emailalertfrom = emailaddress
212
213       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
219       Default: unset, take system generated default (probably root@hostname)
220
221       emailalertfreq = n
222
223       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
229       If defined in a virtual server section then the global value is
230       overridden.
231
232       Default: 0
233
234       emailalertstatus = all | none | starting | running | stopping |
235       reloading,...
236
237       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
242       If defined in a virtual server section then the global value is
243       overridden.
244
245       Default: all
246
247       smtp = ip_address|hostname"
248
249       A valid SMTP server address to use for sending email via SMTP.
250
251       If defined in a virtual server section then the global value is
252       overridden.
253
254       execute = "configuration"
255
256       Use this directive to start an instance of ldirectord for the named
257       configuration.
258
259       supervised = yes | no
260
261       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
267       Default: no
268
269       fork = yes | no
270
271       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
278       Default: no
279
280       quiescent = yes | no
281
282       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
287       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
292       This side-effect can be avoided by running the following:
293
294       echo 1 > /proc/sys/net/ipv4/vs/expire_quiescent_template
295
296       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
301       If no, then the real or failback servers will be removed from the
302       kernel's LVS table. The default is yes.
303
304       If defined in a virtual server section then the global value is
305       overridden.
306
307       Default: yes
308
309       readdquiescent = yes | no
310
311       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
316       cleanstop = yes | no
317
318       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
321       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
327       If defined in a virtual server section then the global value is
328       overridden.
329
330       Default: yes
331
332       maintenancedir = directoryname
333
334       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
340       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
345       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
352       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
355       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
361       This option is not valid in a virtual server section.
362
363       Default: disabled
364
365   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
369       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
374       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
391    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
406       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
419       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
423       The type of service to monitor when using checktype=negotiate. None
424       denotes a service that will not be monitored.
425
426       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
431       Default:
432
433       •   Virtual server port is 21: ftp
434
435       •   Virtual server port is 25: smtp
436
437       •   Virtual server port is 53: dns
438
439       •   Virtual server port is 80: http
440
441       •   Virtual server port is 110: pop
442
443       •   Virtual server port is 119: nntp
444
445       •   Virtual server port is 143: imap
446
447       •   Virtual server port is 389: ldap
448
449       •   Virtual server port is 443: https
450
451       •   Virtual server port is 587: submission
452
453       •   Virtual server port is 636 ldaps
454
455       •   Virtual server port is 993: imaps
456
457       •   Virtual server port is 995: pops
458
459       •   Virtual server port is 1521: oracle
460
461       •   Virtual server port is 1812: radius
462
463       •   Virtual server port is 3128: http_proxy
464
465       •   Virtual server port is 3306: mysql
466
467       •   Virtual server port is 5432: pgsql
468
469       •   Virtual server port is 5060: sip
470
471       •   Otherwise: none
472
473       checkcommand = "path to script"
474
475       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
479       Four parameters are passed to the script:
480
481       •   virtual server ip/firewall mark
482
483       •   virtual server port
484
485       •   real server ip
486
487       •   real server port
488
489       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
495       Default: /bin/true
496
497       checkport = n
498
499       Number of port to monitor. Sometimes check port differs from service
500       port.
501
502       Default: port specified for each real server
503
504       request = "uri to requested object"
505
506       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
510       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
514       For a DNS check this should the name of an A record, or the address of
515       a PTR record to look up.
516
517       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
521       For a simpletcp check, this string is sent verbatim except any
522       occurrences of \n are replaced with a new line character.
523
524       receive = "regexp to compare"
525
526       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
532       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
537       For a MySQL check, the receive setting is not used.
538
539       httpmethod = GET | HEAD
540
541       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
545       Default: GET
546
547       virtualhost = "hostname"
548
549       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
556       login = "username"
557
558       For FTP, IMAP, LDAP, MySQL, Oracle, POP and PostgreSQL, the username
559       used to log in.
560
561       For RADIUS the username is used for the attribute User-Name.
562
563       For SIP, the username is used as both the to and from address for an
564       OPTIONS query.
565
566       Default:
567
568       •   FTP: Anonymous
569
570       •   MySQL Oracle, and PostgreSQL: Must be specified in the
571           configuration
572
573       •   SIP: ldirectord\@<hostname>, hostname is derived as per the passwd
574                option below.
575
576       •   Otherwise: empty string, which denotes that      case
577           authentication will not be attempted.
578
579       passwd = "password"
580
581       Password to use to login to FTP, IMAP, LDAP, MySQL, Oracle, POP,
582       PostgreSQL and SIP servers.
583
584       For RADIUS the passwd is used for the attribute User-Password.
585
586       Default:
587
588       •   FTP: ldirectord\@<hostname>,      where hostname is the environment
589           variable HOSTNAME evaluated at      run time, or sourced from uname
590           if unset.
591
592       •   Otherwise: empty string.       In the case of LDAP, MySQL, Oracle,
593           and PostgreSQL this means      that authentication will not be
594           performed.
595
596       database = "databasename"
597
598       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
602       secret = "radiussecret"
603
604       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
608       Default: empty string
609
610       scheduler = scheduler_name
611
612       Scheduler to be used by LVS for loadbalancing.  For an information on
613       the available sehedulers please see the ipvsadm(8) man page.
614
615       Default: "wrr"
616
617       persistent = n
618
619       Number of seconds for persistent client connections.
620
621       netmask = w.x.y.z | prefixlen
622
623       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
627       protocol = tcp | udp | fwm
628
629       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
633       Default:
634
635       •   Virtual is an IP address and port, and the port is not 53: tcp
636
637       •   Virtual is an IP address and port, and the port is 53: udp
638
639       •   Virtual is a firewall mark: fwm
640
641       monitorfile = "/path/to/monitorfile"
642
643       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
647       The log format is: [timestamp|pid|real_service_id|status|message]
648
649       Default: no separate logging of service checks.
650
651       ops = yes | no
652
653       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
659       servicename = short name
660
661       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
665       comment = comment
666
667       Notes about this service to be included in e-mail notifications (for
668       example, purpose of the service or relevant administrator to contact).
669

IPv6

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
675       Following checktype and service are supported.
676
677       checktype: connect | external | external-perl | negotiate | off | on |
678       checktimeoutN
679
680       service: dns | http | https | nntp | none | simpletcp | sip
681
682       Note: When using a service type with http or https, you need to install
683       perl module perl-Net-INET6Glue.
684

FILES

686       /etc/ha.d/ldirectord.cf
687
688       /var/log/ldirectord.log
689
690       /var/run/ldirectord.configuration.pid
691
692       /etc/services
693

SEE ALSO

695       ipvsadm, heartbeat
696
697       Ldirectord Web Page: http://www.vergenet.net/linux/ldirectord/
698

AUTHORS

700       Horms <horms@verge.net.au>
701
702       Jacob Rief <jacob.rief@tiscover.com>
703
704
705
706perl v5.36.1                      2023-10-11                     LDIRECTORD(8)
Impressum