DESCRIPTION

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.

OPTIONS

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

-d|--debug Don't start as daemon and log verbosly.

-h|--help Print user manual and exit.

-v|--version Print version and exit.

start the daemon for the specified configuration.

stop the daemon for the specified configuration. This is the same as sending a TERM signal to 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.

SYNTAX

Description of how to write configuration files

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 "-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, external and ping checks. If the
timeout is exceeded then the real server is declared dead.

If defined in a virtual server section then the global value is
overridden.

If undefined then the value of negotiatetimeout is used.
negotiatetimeout is also a global value that may be overriden by a pervirtual setting.

If both checktimeout and negotiatetimeout are unset, the default is
used.

Default: 5 seconds

negotiatetimeout = n

Timeout in seconds for negotiate checks.

If defined in a virtual server section then the global value is
overridden.

If undefined then the value of connecttimeout is used. connecttimeout is also a global value that may be overriden by a per-virtual setting.

If both negotiatetimeout and connecttimeout are unset, the default is
used.

Default: 30 seconds

checkinterval = n

Defines the number of second between server checks.

Default: 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/negotiatetimeout is additive, so if a connect check is
used, checkcount is 3 and checktimeout is 2 seconds, then a total of 6 seconds worth of timeout will occur becore the check fails.

If defined in a virtual server section then the global value is
overridden.

Default: 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: 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.

If defined in a virtual server section then the global value is
overridden.

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.

Default: log directly to the file /var/log/ldirectord.log.

emailalert = "emailaddress"

A valid email address for sending alerts about the changed connection
status to any real server defined in the virtual service. This option requires perl module MailTools to be installed. Automatically tries to send email using any of the built-in methods. See perldoc Mail::Mailer for more info on methods.

If defined in a virtual server section then the global value is
overridden.

emailalertfreq = n

Delay in seconds between repeating email alerts while any given real
server in the virtual service remains inaccessible. A setting of zero seconds will inhibit the repeating alerts. The email timing accuracy of this setting is dependent on the number of seconds defined in the
checkinterval configuration option.

If defined in a virtual server section then the global value is
overridden.

Default: 0

emailalertstatus = all|none|starting|running|stopping|reloading,...

Comma delimited list of server states in which email alerts should be
sent. all is a short-hand for "starting,running,stopping,reloading". If none is specified, no other option may be specified, otherwise options are ored with each other.

If defined in a virtual server section then the global value is
overridden.

Default: all

execute = "configuration"

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

supervised = yes|no

If yes, then ldirectord does not go into background mode. All logmessages 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.

Default: no

fork = yes|no

If yes, then ldirectord will spawn a child proccess for every virtual server, and run checks against the real servers from them. This will
increase response times to changes in real server status in
configurations with many virtual servers. This may also use less
memory then running many seperate instances of ldirectord. Child
processes will be automaticly restarted if they die.

Default: no

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.

This side-effect can be avoided by running the following:

echo 1 > /proc/sys/net/ipv4/vs/expire_quiescent_template

If the proc file isn't present this probably means that the kernel
doesn't have lvs support, LVS support isn't loaded, or the kernel is
too old to have the proc file. Running ipvsadm as root should load LVS into the kernel if it is possible.

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

If defined in a virtual server section then the global value is
overridden.

Default: yes

Section virtual

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. If omitted then a weight of 1 will be used. The last two arguments are also 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.

For TCP and UDP (non fwmark) virtual services, unless the forwarding

method is masq and the IP address of a real server is non-local (not present on a interface on the host running ldirectord) then the port of the real server will be set to that of its virtual service. That is, port-mapping is only available to if the real server is another machine and the forwarding method is masq. This is due to the way that the underlying LVS code in the kernel functions.

More than one of these entries may be inside a virtual section. The

checktimeout, negotiatetimeout, checkcount, fallback, emailalert, emailalertfreq and quiescent options listed above may also appear inside a virtual section, in which case the global setting is overridden.
checktype = connect|external|negotiate|off|on|ping|checktimeoutN

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 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 =
dns|ftp|http|https|imap|imaps|ldap|mysql|nntp|none|oracle|pgsql|pop|pops|radius|simpletcp|sip|smtp

The type of service to monitor when using checktype=negotiate. None
denotes a service that will not be monitored.

simpletcp sends the request string to the server and tests it against the receive regexp. The other types of checks connect to the server using the specified protocol. Please see the request and receive sections for protocol specific information.

Default:

· Virtual server port is 21: ftp

· Virtual server port is 25: smtp

· Virtual server port is 53: dns

· Virtual server port is 80: http

· Virtual server port is 110: pop

· Virtual server port is 119: nntp

· Virtual server port is 143: imap

· Virtual server port is 389: ldap

· Virtual server port is 443: https

· Virtual server port is 993: imaps

· Virtual server port is 995: pops

· Virtual server port is 1521: oracle

· Virtual server port is 1812: radius

· Virtual server port is 3306: mysql

· Virtual server port is 5432: pgsql

· Virtual server port is 5060: sip

· Otherwise: none

checkcommand = "path to script"

This setting is used if checktype is external and is the command to be run to check the status of a real server. It should exit with status 0 if everything is ok, or non-zero otherwise.

Four parameters are passed to the script:

· virtual server ip/firewall mark

· virtual server port

· real server ip

· real server port

Default: /bin/true

checkport = n

Number of port to monitor. Sometimes check port differs from service
port.

Default: port specified for each 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, Oracle or PostgeSQL check, this should be an SQL SELECT
query. The data returned is not checked, only that the answer is one
or more rows. This is a required setting.

For a simpletcp check, this string is sent verbatim except any
occurances of \n are replaced with a new line character.

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 literals. 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.

Default: GET

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"

For FTP, IMAP, LDAP, MySQL, Oracle, POP and PostgreSQL, the username
used to log in.

For Radius the passwd is used for the attribute User-Name.

For SIP, the username is used as both the to and from address for an
OPTIONS query.

Default:

· FTP: Anonymous

· MySQL Oracle, and PostgreSQL: Must be specified in the

configuration

· SIP: ldirectord\@<hostname>, hostname is derived as per the passwd

option below.

· Otherwise: empty string, which denotes that case

authentication will not be attempted.

passwd = "password"

Password to use to login to FTP, IMAP, LDAP, MySQL, Oracle, POP,
PostgreSQL and SIP servers.

For Radius the passwd is used for the attribute User-Password.

Default:

· FTP: ldirectord\@<hostname>, where hostname is the environment

variable HOSTNAME evaluated at run time, or sourced from uname if unset.

· Otherwise: empty string. In the case of LDAP, MySQL, Oracle,

and PostgreSQL this means that authentication will not be
performed.

database = "databasename"

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

secret = "radiussecret"

Secret to use for Radius servers, this is the secret used to perform an Access-Request with the username (set by login above) and passwd (set by passwd above).

Default: empty string

scheduler = scheduler_name

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

Default: "wrr"

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. If a firewall mark then the
protocol must be fwm.

Default:

· Virtual is an IP address and port, and the port is not 53: tcp

· Virtual is an IP address and port, and the port is 53: udp

· Virtual is a firewall mark: fwm

FILES

/etc/ha.d/ldirectord.cf

/var/log/ldirectord.log

/var/run/ldirectord.configuration.pid

/etc/services

SEE ALSO

ipvsadm, heartbeat

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

AUTHORS

Horms <horms@verge.net.au>

Jacob Rief <jacob.rief@tiscover.com>

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 389:

=back doesn't take any parameters, but you said =back 4

Around line 410:

=back doesn't take any parameters, but you said =back 4

Around line 489:

=back doesn't take any parameters, but you said =back 4

Around line 510:

=back doesn't take any parameters, but you said =back 4

Around line 558:

=back doesn't take any parameters, but you said =back 4

perl v5.10.0 2009-04-30 LDIRECTORD(8)