This document provides installation and configuration instructions for the Enhanced DNS server application.
Eddie is a 100% software solution for delivering commercial grade, quality of service to Internet sites.
Eddie consists of two main software packages:
1. The Enhanced DNS server which provides load balancing and monitoring of site accessibility for geographically distributed web sites.
2. The Intelligent HTTP Gateway which provides site based:
This document provides detailed instructions on the installation and configuration of the Eddie Enhanced DNS and describes two example configurations. For installation information on the Eddie Intelligent HTTP Gateway, see Eddie Intelligent HTTP Gateway: Installation and Configuration Guide.
Back End- A computer running a web server.
Erlang- A functional programming language developed by Ericsson. Information on Open Source Erlang may be found at www.erlang.org/erlang.html.
Front End - A computer running one or more instances of the Intelligent HTTP Gateway.
Node- An Erlang node. In this case, either an instance of the Intelligent HTTP Gateway (on a Front End), or an instance on a Back End which receives HTTP requests from Front Ends.
Successful installation of Eddie using these guidelines assumes the following:
1) Open Source Erlang 47.4.1 and patch must be installed on all computers.
2) The program "GNU make" must be available. See www.gnu.org for details.
3) The Enhanced DNS server is plug-in compatible with named-4.x.y (BIND). Understanding of how to configure and use "named" is required to configure the base functionality of this server, e.g. knowledge about named.boot files, master files, and zone transfer configurations. There are a number of books available on this topic.
4) Each computer is running either:
5) Minor variations from the above should still work, but we have encountered minor problems on occasion. For help in such situations, please email talk@eddieware.org.
1) Download the Eddie tar ball eddie-1.3.1.tar.gz from the Eddie web site www.eddieware.org.
2) Ensure erl and erlc are in your standard path.
3) Extract the Eddie files using "GNU tar."
tar zxf eddie-1.3.1.tar.gz | tar xf -
Note: If you don't have "GNU make", use the following command:
5) The following command must be run before compiling the source code:
This will prepare the scripts to install Eddie into the following directories:
To change the default installation directories (i.e, change /usr/local/ ) use the following command:
./configure --prefix=<install prefix>
6) Then compile Eddie using the following command:
Note: "GNU make" must be used. If "make" isn't GNU make then type the appropriate command to invoke GNU make. You must also edit the eddie.mk produced by configure so that the make variable equals "gmake" (or whatever GNU make is on your system).
7) Then install Eddie as superuser using the following command:
This should build Eddie successfully. Getting Eddie running requires an understanding of how you want to configure your cluster(s). Please read the documentation in the doc/ subtrees.
8) To clean up after installation use the following command:
Now set up some links and directory permissions. Erlang 47.4.1 has a bug that requires the person running Eddie to be able to write to the directory from which they start Eddie, hence the change of ownership to eddie_operator . An example of how to do this if you are using Apache is shown below.
ln -s $APACHE_ROOT/conf/access.conf
ln -s $APACHE_ROOT/conf/srm.conf
Note: We refer to the directory in which Apache is installed as the Apache root directory, $APACHE_ROOT .
Copy the installed files to all machines that you intend to run Eddie on, preserving all symbolic links and permissions. You can install Eddie in the same locations on each machine using "rsync." This assumes; however, that each machine is running the same operating system. Otherwise, repeat the installation procedure on each machine with a different OS and then copy to all similar machines.
The DNS server must have Eddie installed to enable the load balancing features. For more details see Eddie Intelligent HTTP Gateway: Installation and Configuration Guide.
If Eddie is not installed on the Front and back Ends, the server will use primitive round-robin mechanisms for load balancing.
This setup is realized using a number of configuration files (see $DNS_ROOT/examples/ ) which are standard DNS BIND 4.x files. We do not provide information on how to set up BIND.
The Eddie Enhanced DNS server needs only one additional configuration file to enable the advanced load-balancing features. It may be found in $DNS_ROOT/examples/lb_dns.boot of the distribution.
We now describe the contents of the lb_dns.boot file.
#--------------------------------------------------------------- # File : lb_dns.boot # Purpose : A configuration file for the Enhanced DNS application. #---------------------------------------------------------- Port 6789 # This directive specifies the UDP port on which the DNS server listens for load # information from its peer hosts/LANs (default: 4567). This port must be # specified in the Eddie base package configuration as well. Cookie YourSecretCookie # This directive tells the lbdns to check the md5 signature on # the load data sent to it from the Eddie servers for security. # The cookie must be the same as defined as cookie on the Eddie # servers, otherwise the signatures will not match and the data # will be refused. If no directive is given the signature will not # be checked and the data will be accepted if it came from a # IP destination matching the NetMasks below. TTL 360 # The TTL directive is used to specify a time-to-live for the load-balanced domains # (default: 120 secs). If this time limit is set too high, the load balancing # characteristics will not reflect short-term changes and load balancing will not # be effective. If it is too short, the DNS gets pounded by everyone! Netmask 172.30.128.0/24 # The Netmask directive is used to restrict the IP addresses allowed to send load # information to the server. Otherwise, any server could send load information to # the DNS server, potentially overloading the system. In order to specify several # allowed IP addresses, either give several Netmask directives, or give several # netmasks per directive. In this case, 24 bits are used for the netmask,i.e. # 255.255.255.0. 192.168.128.35/h means the complete IP address. If no Netmask # directive is given, no IP addresses are allowed to send load information. Domain www.eddieware.org Domain www-*.eddieware.org # This directive specifies domain(s) to load-balance. To specify several # domains, give several directives, and/or specify several domains in each Domain # directive. Domains can be specified using simple wild-card notation: '*', # e.g. www.*.se where '*' is one or more characters except for '.' and '!' or # w*.mytest.se where '*' is zero or more characters except for '.' and '!'. # If no domains are specified to load balance, none will be. # End of config file
All configuration is now done and the server can be started using the "lbdns" command:
$ lbdns -b $DNS_ROOT/examples/named.boot \ -l $DNS_ROOT/examples/lb_dns.boot
If the Eddie base package has been set up accordingly, client requests are load balanced across the Eddie Front End servers. If not, primitive round-robin is used.
The "lbdns" command has the following syntax and semantics:
Usage: lbdns [-b Boot-file] [-p Port] [-l ConfigFile] [-i Directory] [-d Level] [-rv]
-b Use an alternative DNS Boot-file (default: /etc/named.boot\).
-p Use an alternative Port (default: 53).
-l Use a ConfigFile to set up load balancing.
-i Use an alternative log Directory (default: /var/tmp\).
-r Restart DNS server automatically if it has terminated. Avoid this flag until you have a stable configuration!
-v Verbose output. Inhibit -r and run in foreground.
1: Verbose output (same as -v).
2: Debug output (internal reports (incl. verbose)). Inhibit -r and run in foreground.
The -r flag starts a small monitor process (heart) which restarts the DNS server should it terminate. This a powerful concept but a plain "kill -KILL" on the DNS server process will not have the outcome you might expect. The DNS server is hard to kill.The DNS server creates a pid file in the log directory named dns.pid. This file contains two pids. The first one identifies a signalling handler and the second identifies the actual DNS server.
Killing or restarting (with a new configuration) a DNS server is done as follows with the -r flag disabled:
kill -HUP 1234 The configuration files are re-read. The internal DNS server state is cleared and a restart is done using the same process context. A new signalling handler is started.
kill -KILL 1234 Stops the DNS server.
kill -HUP | KILL 1235 Kills the DNS server.
kill -HUP 1234 The configuration files are re-read. The internal DNS server state is cleared and a restart is done using the same process context. A new signalling handler is started.
kill -KILL 1234 Stops the DNS server.
kill -HUP | KILL 1235 Kills the DNS server but a server is started by the heart process.
kill -KILL `ps aux | grep heart | awk -e '{print $2}'` Kills the DNS server.
All actions taken by the DNS server are logged in wrap log files. The log files include harmless progress reports, information about failover/takeover activities, but also fatal error reports. It consists of five log files of 500 kB each.
In this example, the Enhanced DNS Server is www.eddieware.org and Port 6789 will be used by the Front Ends to communicate load information to the Enhanced DNS.
In this example, we wish to balance traffic between the machines europa and evita shown in Figure 1. The traffic coming to the LAN is targeted for the web site www.eddieware.org, and the DNS files have been setup to have www.eddieware.org resolved to 10.0.0.162 (europa) and 10.0.0.163 (evita). Europa and evita have been configured as Eddie Front End servers, see Eddie Intelligent HTTP Gateway: Installation and Configuration Guide.
The lb_dns.boot file should have the following form:
#--------------------------------------------------------------- # File : example1.boot # Purpose : A configuration file for the Enhanced DNS application. #---------------------------------------------------------- Port 6789
Cookie YourSecretCookie TTL 120 Netmask 10.0.0.0/24 Domain www.eddieware.org # End of config file
In this example we show how to set up multiple clusters within a LAN for load balancing. The DNS configuration files in this example should be setup with:
All four machines must be configured as Eddie Front End servers, europa and evita in one Front End cluster and erika and eva in another.
Requests sent to the Enhanced DNS concerning www.eddieware.org will be load balanced across europa, evita, erika and eva.
Requests sent to the Enhanced DNS concerning www1.eddieware.org will be load balanced across europa and evita.
Requests sent to the Enhanced DNS concerning www.eddieware.org will be load balanced across
erika and eva.
The lb_dns.boot file should have the following form:
#--------------------------------------------------------------- # File : example2.boot # Purpose : A configuration file for the Enhanced DNS application. #---------------------------------------------------------- Port 6789
Cookie YourSecretCookie TTL 200 Netmask 10.0.0.0/24 Netmask 10.0.1.0/24 Domain www.eddieware.org Domain www1.eddieware.org Domain www2.eddieware.org # End of config file
Note that, even though www.eddieware.org contains all four machines, requests to www1.eddieware.org will only be load balanced across europa and evita, and requests to www2.eddieware.org will only be load balanced across erika and eva. That is, the use of multiple Domain lines in the lb_dns.boot file does not result in load balancing across all of the domains taken together.
