$Id: INSTALL 59 2006-09-11 14:41:43Z ggw $

mySQL 4 linked version will build with no -Wall complaints
Read CHANGES and LICENSE

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

-We recommend running mysqlBind via mysqlISP jobs created by unixservice.com 
 ism|4 or 5 interface. Hire us for one time jobs or as backup 24x7x365 support!

---
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 mysqlBindN.M.tar.gz
	(Where N.M is the latest release at openisp.net/mysqlBind)
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: Comment #define BIND9 line if using BIND8.)


(Note that if your libmysqlclient.a was built with ssl support you must
	shell>export ssl=1
before running make)

shell>make
shell>make install
shell>vi makefile and remove the mail line (we only need the info once!)
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 
	(Same issues as above...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". Change ASAP!)

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.

---
!NEW! Optional mysqlBind.conf runtime database connection configuration file.

You can optionally set USECONF in local.h and create a simple text 
configuration file. This file must be in same dir as mysqlBind.cgi. Watch 
permission issues carefully (access for cgi and security concerns.)

This file mayhave none or more of the following configuration lines:

#
#Example comment line
#
#NULL DbIp == localhost socket connection
#gcDbIp=
gcDbName=mysqlbind
gcDbLogin=mysqlbind
gcDbPasswd=wsxedc
#Advanced settings not normally used
#guDbPort=0
#gcDbSocket=/var/lib/mysql/mysql4.sock
#
#Keep this file as small as possible for less cgi latency. For
#example get rid of all these commented lines. And use only the args
#you need to set diff from local.h

Args not used are replaced with local.h defines or depending on context
mysqlBind.tConfiguration name/value pairs for slaves, external job queues and
mysqlApache autozone creation. See distributed tConfiguration for more info.

More info in local.h

---
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'd. Don't forget to give us credit when you quote this stuff.
(C) 2001-2004 Gary Wallis

---
Thanks

www.isc.org
Thanks to a real internet guru Paul Vixie for his kind words of support!
Thanks to the hundreds of users worldwide that support this OSS/GPL project.
