Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LDIRECTORD(8)	      User Contributed Perl Documentation	 LDIRECTORD(8)

NAME
       ldirectord - Linux Director Daemon

       Daemon to monitor remote	services and control Linux Virtual Server

SYNOPSIS
       ldirectord [-d|--debug] [--] [configfile] start | stop |	restart	| try-
       restart | reload	| force-reload | status

       ldirectord [-h|-?|--help|-v|--version]

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
       /usr/local/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
       /usr/local/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	/usr/local/etc/ha.d/conf/configuration

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

       -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 controlled 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, external-perl 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 overridden by a
       per-virtual 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 checktimeout is used.  checktimeout is
       also a global value that	may be overridden by a per-virtual setting.

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

       Default:	30 seconds

       checkinterval = n

       Defines the number of second between server checks.

       When fork=no this option	defines	the amount of time ldirectord sleeps
       between running all of the realserver checks in all virtual service
       pools.

       When fork=yes this option defines the amount of time each forked	child
       sleeps per virtual service pool after running all realserver checks for
       that pool.

       If set in the virtual server section then the global value is
       overridden, but ONLY if using forking mode (fork	= yes).

       Default:	10 seconds

       checkcount = n

       This option is deprecated and slated for	removal	in a future version.
       Please see the 'failurecount' option.

       The number of times a check will	be attempted 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 before the check fails.

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

       Default:	1

       failurecount = n

       The number of consecutive times a failure will have to be reported by a
       check before the	realserver is considered to have failed.  A value of 1
       will have the realserver	considered failed on the first failure.	 A
       successful check	will reset the failure counter to 0.

       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.

       fallbackcommand = "path to script"

       If this directive is defined, the supplied script is executed whenever
       all real	servers	for a virtual service are down or when the first real
       server comes up again. In the first case, it is called with "start" as
       its first argument, in the latter with "stop".  Additional parameters
       are vserver with	vport (vserver:vport) as second	param and protocol
       (tcp/udp) as third param	to identify the	virtual	service	within the
       fallback	script.

       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[, 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.

       Multiple	addresses may be supplied, comma delimited.

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

       emailalertfrom =	emailaddress

       A valid email address to	use as the from	address	of the email alerts.
       You can use a plain email address or any	RFC-compliant string for the
       From header in the body of an email message (such as: "ldirectord
       Alerts" <alerts@example.com>) Do	not quote this string unless you want
       the quotes passed in as part of the From	header.

       Default:	unset, take system generated default (probably root@hostname)

       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

       smtp = ip_address|hostname"

       A valid SMTP server address to use for sending email via	SMTP.

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

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

       Default:	no

       fork = yes | no

       If yes, then ldirectord will spawn a child process 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	separate instances of ldirectord.  Child
       processes will be automatically 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 persistent timeout can expire.
       See ipvsadm for more information	on persistent 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

       readdquiescent =	yes | no

       If yes, then when real or failback servers are determined to be down,
       they are	readded	to the kernel's	LVS table with weight 0	if they	do not
       exist in	the table. Setting the value to	no, allows manually removing
       the realserver to manually disable all persistent connections.

       cleanstop = yes | no

       If yes, then when ldirectord exits it will remove all of	the virtual
       server pools that it is managing	from the kernel's LVS table.

       If no, then the virtual server pools it is managing and any real	or
       failback	servers	listed in them at the time ldirectord exits will be
       left as-is.  If you want	to be able to stop ldirectord without having
       traffic to your realservers interrupted you will	want to	set this to
       no.

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

       Default:	yes

       maintenancedir =	directoryname

       If this option is set ldirectord	will look for a	special	file in	the
       specified directory and,	if found, force	the status of the real server
       identified by the file to down, skipping	the normal health check.  This
       would be	useful if you wish to force servers down for maintenance
       without having to modify	the actual ldirectord configuration file.

       For example, given a realserver with IP 172.16.1.2, service on port
       4444, and a resolvable reverse DNS entry	pointing to
       "realserver2.example.com" ldirectord will check for the existence of
       the following files:

       172.16.1.2:4444
       172.16.1.2
       realserver2.example.com:4444
       realserver2.example.com
       realserver2:4444
       realserver2

       If any one of those files is found then ldirectord will immediately
       force the status	of the server to down as if the	check had failed.

       Note: Since it checks for the IP/hostname without the port this means
       you can decide to place an entire realserver into maintenance across a
       large number of virtual service pools with a single file	(if you	were
       going to	reboot the server, for instance) or include the	port number
       and put just a particular service into maintenance.

       This option is not valid	in a virtual server section.

       Default:	disabled

   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 IPv4 addresses	(or two	hostnames) may
       be given, in which case each IPv4 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 third 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 |	external-perl |	negotiate | off	| on |
       ping | checktimeoutN

       Type of check to	perform. Negotiate sends a request and matches a
       receive string. Connect only attempts 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 intervals 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 | http_proxy | imap |	imaps |	ldap |
       ldaps | mysql | nntp | none | oracle | pgsql | pop | pops | radius |
       simpletcp | sip | smtp |	submission

       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:

       o   Virtual server port is 21: ftp

       o   Virtual server port is 25: smtp

       o   Virtual server port is 53: dns

       o   Virtual server port is 80: http

       o   Virtual server port is 110: pop

       o   Virtual server port is 119: nntp

       o   Virtual server port is 143: imap

       o   Virtual server port is 389: ldap

       o   Virtual server port is 443: https

       o   Virtual server port is 587: submission

       o   Virtual server port is 636 ldaps

       o   Virtual server port is 993: imaps

       o   Virtual server port is 995: pops

       o   Virtual server port is 1521:	oracle

       o   Virtual server port is 1812:	radius

       o   Virtual server port is 3128:	http_proxy

       o   Virtual server port is 3306:	mysql

       o   Virtual server port is 5432:	pgsql

       o   Virtual server port is 5060:	sip

       o   Otherwise: none

       checkcommand = "path to script"

       This setting is used if checktype is external or	external-perl 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:

       o   virtual server ip/firewall mark

       o   virtual server port

       o   real	server ip

       o   real	server port

       If the checktype	is external-perl then the command is assumed to	be a
       Perl script and it is evaluated into an anonymous subroutine which is
       called at check time, avoiding a	fork-exec.  The	argument signature and
       exit code conventions are identical to checktype	external.  That	is, an
       external-perl checktype should also work	as an external checktype.

       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 an HTTP/HTTPS check,	this should be a relative URI, while it	has to
       be absolute for the 'http_proxy'	check type. In the latter case,	this
       URI will	be requested through the proxy backend that is being checked.

       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
       occurrences 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.  In case of dynamic DNS answers
       (different answers on the same question)	a regex	to match multiple
       addresses or PTR	record names could also	defined.

       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 username 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:

       o   FTP:	Anonymous

       o   MySQL Oracle, and PostgreSQL: Must be specified in the
	   configuration

       o   SIP:	ldirectord\@<hostname>,	hostname is derived as per the passwd
		option below.

       o   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:

       o   FTP:	ldirectord\@<hostname>,	     where hostname is the environment
	   variable HOSTNAME evaluated at      run time, or sourced from uname
	   if unset.

       o   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 | prefixlen

       Netmask to be used for granularity of persistent	client connections.
       IPv4 netmask should be specified	in dotted quad notation.  IPv6 netmask
       should be specified as a	prefix length between 1	and 128.

       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:

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

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

       o   Virtual is a	firewall mark: fwm

       monitorfile = "/path/to/monitorfile"

       File to continuously log	the real service checks	to for this virtual
       service.	This is	useful for monitoring when and why real	services were
       down or for statistics.

       The log format is: [timestamp|pid|real_service_id|status|message]

       Default:	no separate logging of service checks.

       ops = yes | no

       Specify that a virtual service uses one-packet scheduling. This option
       can be used only	for UDP	services. If this option is specified, all
       connections are created only to schedule	one packet. Option is useful
       to schedule UDP packets from same client	port to	different real
       servers.

       servicename = short name

       A name for this service.	This is	for the	sole purpose of	making it
       easier to know which service is affected	when e-mail notifications are
       sent out.  It will be included in the e-mail subject and	body.

       comment = comment

       Notes about this	service	to be included in e-mail notifications (for
       example,	purpose	of the service or relevant administrator to contact).

IPv6
       Directives for IPv6 are virtual6, real6,	fallback6.  IPv6 addresses
       specified for virtual6, real6, fallback6	and a file of maintenance
       directory should	be enclosed by brackets	([2001:db8::abcd]:80).

       Following checktype and service are supported.

       checktype: connect | external | external-perl | negotiate | off | on |
       checktimeoutN

       service:	dns | http | https | nntp | none | simpletcp | sip

       Note: When using	a service type with http or https, you need to install
       perl module perl-Net-INET6Glue.

FILES
       /usr/local/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>

perl v5.32.1			  2021-02-28			 LDIRECTORD(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SYNTAX | IPv6 | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ldirectord&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help