$Id: INSTALL,v 1.18 2003/12/22 17:39:33 ggw Exp $

BIND 9 now supported!

---
Intended Audience

Linux system -via bash or tcsh shell- admins. Or people learning and with time 
to learn how to use bash as root and live with their mistakes. Must know how
-or learn- to setup Apache httpd daemon and configure httpd.conf. Must 
understand the basics of DNS/Bind (www.isc.org.)

-Now supports BIND 9!
-This mysqlBind release should be more than stable enough for production servers.
-Some reseller/customer level searching and other related issues have not been 
 tested.
-We recommend running mysqlBind via mysqlISP jobs created by unixservice.com 
 ism|4 or 5 interface.

---
Prerequisites

mySQL server and client libs installed and running on same server as the 
application.
You must know the mysql server root password. (Paranoids: Check the install 
script in mainfunc.h)

Must have a running Apache server on the same server with cgi capabilities.
Should be SSL enabled if possible (see below for intranet or other just 
"testing" non-SSL setup). Typical setup involves user openisp httpd daemon on 
some random port number like 9023 for non SSL and 8045 for SSL connections. 
~openisp should have everything mysqlISP related in it (More on this below.)

See mysqlISP tutorial for info on setting up apache 1.3.29 mod_ssl in ~openisp
or cool http://www.modssl.org example. But use wget and tar xzf instead of their
somewhat outdated commands.


---
Example Bash Install Instructions 
(Must edit makefile and use GNU make on FreeBSD builds. Usually gmake)

shell>tar xzf mysqlBind1.8.tar.gz
shell>cd mysqlBind
shell>export CGIDIR=/usr/local/apache/cgi-bin/ (or whatever your Apache cgi-bin dir is)
						(note the trailing / needed!)
shell>vi local.h (change for your setup. BIND 9: Uncomment #define BIND9 line.)
shell>make
shell>make install
shell>export ISMROOT=/home/joe (or whatever dir mysql application project dir is in)
shell>chown mysql $ISMROOT/mysqlBind/data (make sure initialize data is readable by mysql)
shell>chmod o+x $ISMROOT (etc...maybe needed to also insure initialize data is readable by mysql)
shell>/cgi-bin/mysqlBind.cgi Initialize <your mysql password for root>

This will setup application and allow you to login as user "Root" password 
"wsxedc"

If something fails you will probably have to login to mysql command line client as root and:
shell>mysql -u root -pmyrootpwd
mysql>drop database mysqlbind;
mysql>\q

Then fix whatever was missing usually ISMROOT set wrong... or permissions for mysql to get
to $ISMROOT/data files.

Then do the Initialize again.

---
Post Initialize stuff
Then you need to use our named configuration builder. This is easy...
Example:
shell>/cgi-bin/mysqlBind.cgi installbind 192.168.200.23

Note our example named running at 192.168.200.23:53 (IP:Port), for further examples below.

Bind 9 extra step.
Then you will probably need to edit /usr/local/mysqlbind/named.conf and/or
/etc/rndc.conf. It is all explained in the file itself.

You will end up with a nice little /usr/local/mysqlbind/ filesystem all ready to go.


---
Starting and testing your new named server

shell>/usr/local/sbin/named -c /usr/local/mysqlbind/named.conf

will start it and if not provide error messages in /var/log files at least.

Is it running check with
shell>ps -ef | grep named
compare the PID with the pid file contents as specified in named.conf

If it is not check

shell>tail /var/log/messages
Or
shell>tail /var/log/named-mysqlbind.log

and fix your setup until it runs (email support questions always welcome.)

---
Advanced system admin starting and stopping:

To start/stop named and start/stop it on reboot/halt use:

/etc/rc.d/init/mysqlbind-named

symbolically linked into the /etc/rc.d/rc3.d dir like S98mysqlbind etc.

An example RH style startup file can be downloaded here:

http://openisp.net/mysqlBind/mysqlbind-named

---
How to check if it works

shell>dig @192.168.200.23 localhost
shell>dig @192.168.200.23 -x 127.0.0.1
shell>dig @127.0.0.1 localhost
If recursive
shell>dig @192.168.200.23 yahoo.com

All should work.

Remember that you will have to use the webconsole interface to setup your nameservers, for
things like this to work:


shell>dig @192.168.200.23 -x 192.168.200.23

Setup and use the supplied nph-dnstest.cgi copy it to your cgi-bin dir and edit 
to taste.


---
More on the webconsole and basic backup plan.


---
SSL Setup

If you have an SSL server handy edit local.h and comment out:
//#define SSLONLY
like so...
#define SSLONLY
Then
shell>make clean
shell>make

This is much safer for remote management.

---
Read More

cp docs/tutorial.html to a browser accesible place or sym link to it if possible.
Read it! It explains more on how to install bind system files and have a running 
named in seconds, also how to setup required crontabs for local and remote job 
queue processing.


---
Standard OpenISP setup backup operations

(Loose instructions adjust to fit for your particular setup)
shell>useradd -d openisp -s /bin/nologin (this may have been done standard in 
							mysqlISP setup)
shell>mkdir -p ~openisp/mysqlBind/data
shell>chown mysql ~openisp/mysqlBind/data
shell>crontab -e
Adding the following: Where mysqlpasswd is replaced by YOUR real mysql root 
passwd.

#
#mysqlBind
#
##backup
20 3 * * * ISMROOT=~openisp;export ISMROOT;/cgi-bin/mysqlBind.cgi Backup mysqlpasswd > /dev/null

---
Other backup ideas

You should probably cross server backup all your OpenISP module data like so. 
Note that this involves using GRANT ALL mysql statements and a very secure internal 
ISP LAN. See mysql manual.
Think about ISP organization with edge servers with 2 NICs and an ISP admin 
firewall zone with the mysql database server or replication cluster servers.

All servers should have internal mirror backup drives or other cheap fast and 
reliable backup system (NFS and cpio in ISP admin firewall zone?)

shell>crontab -e
Add something like the following after setting up mysql for remote access from 
ONLY the IP in question in a VERY secure LAN (non routable IP's...switched
hubs...behind firewall...etc)

#Extra backup of mysqlBind data only even days, using mysqldump from 192.168.100.23
20 4 * * */2 /usr/local/mysql/bin/mysqldump -e -h 192.168.0.43 -u mysqlbind -pwsxedc --all mysqlbind > ~openisp/mysqlBind/data/dumpall.txt

---
Lose your data and your fired

Don't be lazy backup and rebackup and database warehouse your mission critical data ALWAYS!
Need help contact us!

---
Legalese

This doc is GPL. Don't forget to give us credit when you quote this stuff.
Copyleft 2003 OpenISP and Gary Wallis

---
Thanks

www.isc.org
Thanks to a real internet guru Paul Vixie for his kind words of support!
