TinyReg Installation Instructions --------------------------------- CONTENTS * Summary * Installation * Required Perl Modules * Configuration Files - tinyReg.conf - whois.conf * Email Configuration * Initial tinyReg Database * Run tinyReg Appendix -------- * Ubuntu/Debian Linux * FreeBSD 5.4 * Sample CGI Config for VirtualHost Summary ------- tinyReg is a domain name registration system using a CGI web interface. It consists of several CGI programs: tinyReg gathers information from registrants to build domain registrations; regop manipulates user-submitted domain registrations to produce zone-published data; whois provides a public registry query interface. Also included are: Tquery, command line registry data extraction; Tedit, command-line data creator and editor; and make-db, used to create the initial, empty database. These instructions describe installation on a single-domain system where you install tinyReg in a separate directory instead of creating a separate sub-domain for the product (i.e., such as "tinyreg.domain.name"). Installation was done on a Fedora Core system. Notes for installation under different Linux/Unix flavors are included at the end of this document. Installation ------------ If you do not have current copy of tinyReg you can obtain one from: http://nsrc.org/tinyReg/dist/ The current version of tinyReg (Feb. 22, 2006) is 1.4. You should download the tinyReg compressed tarball file to a temporary location. Under Linux: /usr/local/src is reasonable. You should decompress and extract the tinyReg files by doing the following. You will need to be root to do this: # cd /usr/local/src # tar xvzf tinyReg-1.4.tar.gz This will create the directory: /usr/local/src/tinyReg-1.4/ At this point you will need to make some decisions about where you wish to store the tinyReg documentation files, programs, and log files. Here are the assumptions we will make: * Linux system using Apache web server. * Document root is /var/www/html/ * CGI root is /var/www/cgi-bin/ * Log files stored under /var/log/ * Web server runs as user "apache" * Domain name will be "example.net" * We will be using English program messages and help files for this installation. If you are using Ubuntu/Debian some of these values are different. See the notes at the end of this file for details. With this in mind we are going to install tinyReg so that you can execute it by going to: http://example.net/cgi-bin/tinyReg And, documentation will be available to both the program and users in general at: http://example.net/tinyReg/ With all this in mind here are the steps to copy files as needed and to prepare a tinyReg log file for first time execution of the program. You will need to be root do this. # mkdir /var/www/html/tinyReg # cp /usr/local/src/tinyReg-1.4/HTML/* /var/www/html/tinyReg/ # mkdir /var/www/cgi-bin/tinyReg/ # cp /usr/local/src/tinyReg-1.4/cgi/* /var/www/cgi-bin/tinyReg/ # mkdir /var/log/tinyReg # touch /var/log/tinyReg/tinyReg.log # chown -R apache.apache /var/log/tinyReg/ Now that you have the tinyReg files in their proper locations it is time to configure tinyReg to run on your system. For this you will need to rename and update two files, and then run the make-db program. Required Perl Modules --------------------- tinyReg requires Perl version 5 and several installed packages. These are: CGI, DBI, Mail::Mailer. The fastest way to ensure that these are installed on your system is to use the Comprehensive Perl Archive Network (cpan) interface. # perl -MCPAN -e shell cpan> install DBI::DBD cpan> install DBD::CSV cpan> install Mail::Mailer cpan> quit If you attempt to run the cpan module interface and discover that is not yet configured, the default answers are almost always correct during configuration. This packages relies on ncftp being installed. You may need to install this if cpan cannot find the ncftp binary location. If any of the packages are already installed and up-to-date, then issuing the "install" command at the "cpan>" prompt will not cause the package to be re-installed, but rather you will simply be notified that the package is up-to-date. Further help can be found at http://www.cpan.org/. Configuration Files ------------------- You will need to either rename or copy the files /var/www/cgi-bin/tinyReg/tinyReg.conf.example and /var/www/cgi-bin/tinyReg/whois.conf.example and update them appropriately. Then you will need to execute the /var/www/cgi-bin/tinyReg/make-db script before you can use tinyReg for the first time. We choose to copy the example configuration files. As root do: # cd /var/www/cgi-bin/tinyReg # cp tinyReg.conf.example tinyReg.conf # cp whois.conf.example whois.conf You now need to edit both these files. Choose your favorite editor to do this. tinyReg.conf ------------ Below we show the items you need to change in this file. The first column shows the original value. The second column shows the value you should have based on the assumptions we made earlier about our environment: Original Value -------------- logfile: ../www.wps.com/tinyReg.log tinyReg_URL: http://wps.com/cgi/tinyReg helpfile: /tinyReg-help.html email_server: turing.wps.com email_from: regop@wps.com email_to: regop@wps.com domain: Change to --------- logfile: /var/log/tinyReg/tinyReg.log tinyReg_URL: http://example.net/cgi-bin/tinyReg helpfile: /tinyReg/Eng/tinyReg-help.html email_server: example.net email_from: regop@example.net email_to: regop@example.net domain: .example.net Note: the "domain:" setting is at the end of the configuration file. Some sample domains are shown as well. In addition, you should verify that you have dig installed on your system. The default location is /usr/bin/dig. If dig is installed, but in a different location, then update the line that reads: dig: /usr/bin/dig You can find dig at http://htdig.sourceforge.net/ if you need to install the program. Be sure to save the file tinyReg.conf and and, then, go to the next step: whois.conf ---------- Original Value -------------- logfile: ../www.wps.com/tinyReg.log tinyReg_URL: http://wps.com/cgi/tinyReg html_path: ./HTML helpfile: /tinyReg-help.html Change to --------- logfile: /var/log/tinyReg/tinyReg.log tinyReg_URL: http://example.net/cgi-bin/tinyReg html_path: /var/www/html/tinyReg helpfile: /tinyReg/Eng/tinyReg-help.html The same comments apply to dig as with the tinyReg.conf file. Email Configuration ------------------- In the tinyReg.conf configuration file you pointed to your email server and an email address where notification mails will be sent for the tinyReg system. You can choose to create an alias for the regop@example.net address (i.e. update /etc/aliases), or you can create the account on your system. In addition, you can choose a different address if you wish. But whichever address you give it must be functioning as notice of new domain registrations will be sent to the address. Initial tinyReg Database ------------------------ Now that you have configured tinyReg for your system it is time to run the initial database creation script. This is quite simple. You should do this in the directory where the tinyReg program is installed: # cd /var/www/cgi-bin/tinyReg # ./make-db You are now ready to run tinyReg. Run tinyReg ----------- You can now run the tinyReg program, as well as the programs regop (registry operator interface to the tinyReg database), and whois. To this use the following URLs: tinyReg: http://example.net/cgi-bin/tinyReg regop: http://example.net/cgi-bin/regop whois: http://example.net/cgi-bin/whois The initial admin user name and password for tinyReg are: id: tinyReg password: qls3wh48 APPENDIX -------- Operating System Specific Notes ------------------------------- Ubuntu/Debian Linux ------------------- A few items from our original list of assumptions are different. Here is the same list, but with items updated for Ubuntu/Debian Linux. Specifically this applies to version 5.10 of Ubuntu, "The Breezy Badger" - There may be additional differences across different versions of Debian and Ubuntu. Differences are noted by "**": * Linux system using Apache web server. * Document root is ** /var/www/ ** * CGI root is ** /usr/lib/cgi-bin/ ** * Log files stored under /var/log/ * Web server runs as user ** "www-data" ** * Domain name will be "example.net" * We will be using English program messages and help files for this installation. In addition, you may not have ncftp installed. If this is the case and you need this to properly run cpan, then, as root, you can quickly install ncftp like this: # apt-get install ncftp The ncftp binary will be placed in /usr/bin/, which is what cpan expects. FreeBSD 5.4 ----------- A few items from our original list of assumptions are different. Here is the same list, but with items updated for FreeBSD version 5.4. Differences are noted by "**": * FreeBSD system using Apache web server. * Document root is ** /usr/local/www/data/ ** * CGI root is ** /usr/local/www/cgi-bin/ ** * Log files stored under /var/log/ * Web server runs as user ** "www" ** * Domain name will be "example.net" * We will be using English program messages and help files for this installation. You may find that ncftp is not installed. If you need this in order to run cpan, then you can install it in several ways. If you have the ports collection installed, then, as root: # cd /usr/ports/ftp/ncftp3 # make install Or, using the package utility (as root): # pkg_add -r ncftp This will install version 3 of ncftp by default. Note that the ncftp binary will be installed to /usr/local/bin and not /usr/bin. As a side note, remember that the Apache start-up script is here: /usr/local/etc/rc.d/apache.sh And, that you must include the line apache_enable="YES" in your /etc/rc.conf file in order to start the Apache web server on a FreeBSD system. Sample CGI Config for VirtualHost --------------------------------- If you have installed tinyReg on a web site using the Apache web server and you are using virtual hosts, then you may need to add a section in to your Apache configuration file for the tinyReg CGI directory. Here is an example. You should update the file httpd.conf. You can find this file in the following locations: * Fedora/Red Hat Linux: /etc/httpd/conf/httpd.conf * Ubuntu/Debian Linux: /etc/apache/httpd.conf * FreeBSD: /usr/local/etc/apache/httpd.conf # ADD THIS ScriptAlias /cgi-bin /home/user/cgi-bin Options ExecCGI AllowOverride None Allow from all