ldirectord - Linux Director Daemon

Daemon to monitor remote services and control Linux Virtual Server

ldirectord [-d] [-h] configuration start|stop|restart|reload|status

ldirectord is a daemon to monitor and administer real servers in a cluster of load balanced virtual servers. ldirectord typically is started from heartbeat but can also be run from the command line. On startup ldirectord reads the file /etc/ha.d/conf/configuration. After parsing the file, entries for virtual servers are created on the LVS. Now at regular intervals the specified real servers are monitored and if they are considered alive, added to a list for each virtual server. If a real server fails, it is removed from that list. Only one instance of ldirectord can be started for each configuration, but more instances of ldirectord may be started for different configurations. This helps to group clusters of services. Normally one would put an entry inside /etc/ha.d/haresources

nodename virtual-ip-address ldirectord::configuration

to start ldirectord from heartbeat.

configuration: This is the name for the configuration as specified in the file /etc/ha.d/conf/configuration

-d Don't start as daemon. Useful for debugging.

-h Help. Print user manual of ldirectord.

start the daemon for the specified configuration.

stop the daemon for the specified configuration. This is the same as sending a TERM signal the the running daemon.

restart the daemon for the specified configuration. The same as stopping and starting.

reload the configuration file. This is only useful for modifications inside a virtual server entry. It will have no effect on adding or removing a virtual server block. This is the same as sending a HUP signal to the running daemon.

status of the running daemon for the specified configuration.

virtual = (ip_address|hostname:portnumber|servicename)|firewall-mark

Defines a virtual service by IP-address (or hostname) and port (or servicename) or firewall-mark. A firewall-mark is an integer greater than zero. The configuration of marking packets is controled using the CW-m option to ipchains(8). All real services and flags for a virtual service must follow this line immediately and be indented.

checktimeout = n

Timeout in seconds for connect checks. If the timeout is exceeded then the real server is declared dead. Default is 5 seconds. If defined in virtual server section then the global value is overridden.

connecttimeout = n

Not used.

negotiatetimeout = n

Timeout in seconds for negotiate checks. Default is defined by the operating system. If defined in virtual server section then the global value is overridden.

checkinterval = n

Defines the number of second between server checks. Default is 10 seconds.

checkcount = n

The number of times a check will be attmpted before it is considered to have failed. Only works with ping checks. Note that the checktimeout is additive, so if checkcount is 3 and checktimeout is 2 seconds, then a total of 6 seconds worth of timeout will occur becore the check fails. Default is 1.

autoreload = [yes|no]

Defines if <ldirectord> should continuously check the configuration file for modification. If this is set to 'yes' and the configuration file changed on disk and its modification time (mtime) is newer than the previous version, the configuration is automatically reloaded. Default is no.

callback = "/path/to/callback"

If this directive is defined, ldirectord automatically calls the executable /path/to/callback after the configuration file has changed on disk. This is useful to update the configuration file through scp on the other heartbeated host. The first argument to the callback is the name of the configuration.

This directive might also be used to restart ldirectord automatically after the configuration file changed on disk. However, if autoreload is set to yes, the configuration is reloaded anyway.

fallback = ip_address|hostname[:portnumber|sercvicename] [gate|masq|ipip]

the server onto which a webservice is redirected if all real servers are down. Typically this would be 127.0.0.1 with an emergency page.

This directive may also appear within a virtual server, in which case it will overide the global fallback server, if set.

logfile = "/path/to/logfile"|syslog_facility

An alternative logfile might be specified with this directive. If the logfile does not have a leading '/', it is assumed to be a syslog(3) facility name.

The default is to log directly to the file /var/log/ldirectord.log.

execute = "configuration"

Use this directive to start an instance of ldirectord for the named configuration.

supervised

If this directive is specified, the daemon does not go into background mode. All log-messages are redirected to stdout instead of a logfile. This is useful to run ldirectord supervised from daemontools. See http://untroubled.org/rpms/daemontools/ or http://cr.yp.to/daemontools.html for details.

quiescent = [yes|no]

If yes, then when real or failback servers are determined to be down, they are not actually removed from the kernel's LVS table. Rather, their weight is set to zero which means that no new connections will be accepted. This has the side effect, that if the real server has persistent connections, new connections from any existing clients will continue to be routed to the real server, until the persistant timeout can expire. See ipvsadm for more information on persistant connections.

If no, then the real or failback servers will be removed from the kernel's LVS table. The default is yes.

This directive may also appear within a virtual server, in which case it will overide the global fallback server, if set.

The following commands must follow a virtual entry and must be indented with a minimum of 4 spaces or one tab.

real = ip_address|hostname[->ip_address|hostname][:portnumber|servicename] gate|masq|ipip [weight] ["request, receive"]

Defines a real service by IP-address (or hostname) and port (or servicename). If the port is omitted then a 0 will be used, this is intended primarily for fwmark services where the port for real servers is ignored. Optionally a range of IP addresses (or two hostnames) may be given, in which case each IP address in the range will be treated as a real server using the given port. The second argument defines the forwarding method, must be gate, ipip or masq. The thrid argument is optional and defines the weight for that real server. The last two arguments are optional. They define a request-receive pair to be used to check if a server is alive. They override the request-receive pair in the virtual server section. These two strings must be quoted. If the request string starts with http://... the IP-address and port of the real server is overridden, otherwise the IP-address and port of the real server is used.

checktype = negotiate|connect|N|ping|off|on

Type of check to perform. Negotiate sends a request and matches a receive string. Connect only attemts to make a TCP/IP connection, thus the the request and receive strings may be omitted. If checktype is a number then negotiate and connect is combined so that after each N connect attempts one negotiate attempt is performed. This is useful to check often if a service answers and in much longer intervalls a negotiating check is done. Ping means that ICMP ping will be used to test the availability of real servers. Ping is also used as the connect check for UDP services. Off means no checking will take place and no real or fallback servers will be activated. On means no checking will take place and real servers will always be activated. Default is negotiate.

service = ftp|smtp|http|pop|nntp|imap|ldap|https|dns|mysql|pgsql|sip|none

The type of service to monitor when using checktype=negotiate. None denotes a service that will not be monitored. If the port specfied for the virtual server is 21, 25, 53, 80, 110, 119, 143, 389, 443, 3306, 5432 or 5060 then the default is ftp, smtp, dns, http, pop, nntp, imap, ldap, https, mysql, pgsql or sip respectivly. Otherwise the default service is none.

checkport = n

Number of port to monitor. Sometimes check port differs from service port. Default is port specified for the real server.

request = "uri to requested object"

This object will be requested each checkinterval seconds on each real server. The string must be inside quotes. Note that this string may be overridden by an optional per real-server based request-string.

For a DNS check this should the name of an A record, or the address of a PTR record to look up.

For a MySQL or PostgeSQL checks, this should be a SQL query. The data returned is not checked, only that the answer is one or more rows. This is a required setting.

receive = "regexp to compare"

If the requested result contains this regexp to compare, the real server is declared alive. The regexp must be inside quotes. Keep in mind that regexps are not plain strings and that you need to escape the special characters if they should as litterals. Note that this regexp may be overridden by an optional per real-server based receive regexp.

For a DNS check this should be any one the A record's addresses or any one of the PTR record's names.

For a MySQL check, the receive setting is not used.

httpmethod = GET|HEAD

Sets the HTTP method which should be used to fetch the URI specified in the request-string. GET is the method used by default if the parameter is not set. If HEAD is used, the receive-string should be unset.

virtualhost = "hostname"

Used when using a negotiate check with HTTP or HTTPS. Sets the host header used in the HTTP request. In the case of HTTPS this generally needs to match the common name of the SSL certificate. If not set then the host header will be derived from the request url for the real server if present. As a last resort the IP address of the real server will be used.

login = "username"

Username to use to login to FTP, POP, IMAP, MySQL and PostgreSQL servers. For FTP, the default is anonymous. For POP and IMAP, the default is the empty string, in which case authentication will not be attempted. For a MySQL and PostgreSQL, the username must be provided.

For SIP the username is used as both the to and from address for an OPTIONS query. If unset it defaults to ldirectord\@<hostname>, hostname is derived as per the passwd option below.

passwd = "password"

Password to use to login to FTP, POP, IMAP, MySQL and PostgreSQL servers. Default is for FTP is ldirectord\@<hostname>, where hostname is the environment variable HOSTNAME evaluated at run time, or sourced from uname if unset. The default for all other services is an empty password, in the case of MySQL and PostgreSQL this means authentication will not be performed.

database = "databasename"

Database to use for MySQL and PostgreSQL servers, this is the database that the query (set by receive above) will be performed against. This is a required setting.

scheduler = scheduler_name

Scheduler to be used by LVS for loadbalancing. Default is wrr. For an information on the available sehedulers please see the ipvsadm(8) man page.

persistent = n

Number of seconds for persistent client connections.

netmask = w.x.y.z

Netmask to be used for granularity of persistent client connections.

protocol = tcp|udp|fwm

Protocol to be used. If the virtual is specified as an IP address and port then it must be one of tcp or udp and will default to tcp. If a firewall mark then the protocol must be fwm, which is the default.

/etc/ha.d/ldirectord.cf

/var/log/ldirectord.log

/var/run/ldirectord.configuration.pid

/etc/services

ipvsadm, heartbeat

Ldirectord Web Page: http://www.vergenet.net/linux/ldirectord/

Horms <horms@verge.net.au>

Jacob Rief <jacob.rief@tiscover.com>