INSTRUCTIONS FOR INSTALLING THE 2dFGRS DATABASE ON A LINUX SYSTEM


			  Bruce A. Peterson
              Research School of Astronomy and Astrophysics
                    Institute for Advanced Studies
                 The Australian National University


INTRODUCTION

The 2dFGRS Database consists of three parts: the FITS files that hold
the spectra, an mSQL database that indexes the FITS files, and HTML pages
that access the mSQL database and display the spectra and finding charts by 
reading the FITS files.

The FITS files and mSQL data base require about 4Gb of disk space. The
installation has been tested on a full install of Red Hat Linux 6.2. Other
Linux releases may work, but these may require more configuration, the
installation of programs not included in the other Linux release, etc.

Our installation procedure consists of installing all of the Red Hat
Linux 6.2 release and the updates. The updates should be installed if
your machine will have a permanent Internet connection, because Red Hat
Linux 6.2 has security problems which are largely fixed in the updates.

With Linux installed, the 2dFGRS Database installation consists of
creating the TDFgg user and group, copying files from the CD-ROMS to
disk, creating various links, editing the Apache configuration files,
and creating a cron job that will periodically clear a scratch area. The
following describes the required task, and then provides example
commands to carry out the task (to be run by root, unless specifically
stated otherwise).


CREATE USER AND GROUP

As root, use the control-panel to create the group TDFgg as number 401 and
the TDFgg user as number 401 with tcsh as the user's shell, and TDFgg
as the TDFgg users' group. This will create /home/TDFgg. Some flavors of Linux 
do not allow specification of the user and group numbers. See the appendix A.1 
for a discussion of this problem.

Mount CD-ROM No. 1 and untar the contents of the TDFgg home
directory from the CD-ROM. The commands are:
	INSERT CD-ROM No. 1
	mount /mnt/cdrom
	cd /home
	tar -xvzf /mnt/cdrom/2dFGRS_Database/TDFgg.tgz
        chmod a+rx TDFgg


mSQL DATABASE

Choose a disk with 1Gb of free space, for example /data1, make
the directory mSQL on this disk, make it owned by TDFgg, and create
a link to this directory from /home/TDFgg. The commands are:
	mkdir /data1/mSQL
	cd /home/TDFgg
	ln -s /data1/mSQL mSQL
	chown 401:401 /data1/mSQL

With CD-ROM No. 1 still mounted, untar the contents of the mSQL
database. The commands are:
	cd /data1
	tar -xvzf /mnt/cdrom/2dFGRS_Database/mSQL.tgz

Check that the new files in /data1/mSQL are owned by TDFgg. If not,
change the ownership of these files. The commands are:
	ls -l /data1/mSQL
and if required,
	chown -R 401:401 /data1/mSQL

Make a link from /home/TDFgg to a scratch directory, for example /tmp,
and create the subdirectory TDFgg. Create the file TDFgg_access_count
in /tmp, make links to these, and make them world writable. The commands are:
	mkdir /tmp/TDFgg
	touch /tmp/TDFgg_access_count
	chmod a+rw /tmp/TDFgg*
	cd /home/TDFgg
	ln -s /tmp/TDFgg Scratch
	ln -s /tmp/TDFgg_access_count access_count


FITS DATABASE

Choose a disk with 4 Gb of free space, for example /data2, make
the directory Database on this disk and create a link to this directory
from /home/TDFgg. The commands are:
	mkdir /data2/Database
	cd /home/TDFgg
	ln -s /data2/Database Database

Copy the compressed FITS files from each CD-ROM in turn. The commands are:
	INSERT CD-ROM No. 2
	mount /mnt/cdrom
	cp -a /mnt/cdrom/* /data2
	umount /mnt/cdrom
	INSERT CD-ROM No. 3
	mount /mnt/cdrom
	cp -a /mnt/cdrom/* /data2
	umount /mnt/cdrom
	INSERT CD-ROM No. 4
	mount /mnt/cdrom
	cp -a /mnt/cdrom/* /data2
	umount /mnt/cdrom

The next step is to uncompress all the FITS files using the provided perl
script. Note: you may need to change the first line of the script to
reflect the location of your local version of perl. The commands are
	cd /data2/Database
	/home/TDFgg/bin/unzipfits.pl

Make certain that the FITS Database is owned by TDFgg. The command is:
	chown -R 401:401 /data2/Database


ALTER THE HTTPD CONFIGURATION

Modify /etc/httpd/conf/httpd.conf by using the script and files given below:
  mv /etc/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.orig
  cat /etc/httpd/conf/httpd.conf.orig /home/TDFgg/httpd.conf > /etc/httpd/conf/httpd.conf

The above will append the following lines to /etc/httpd/conf/httpd.conf

ScriptAlias /TDFgg-cgi-bin/ "/home/TDFgg/cgi-bin/"
<Directory /home/TDFgg/public_html>
    AllowOverride FileInfo AuthConfig Limit
    Options MultiViews All
    Order allow,deny
    Allow from all
</Directory>
<Directory "/home/TDFgg/cgi-bin/">
    AllowOverride None
    Options ExecCGI FollowSymLinks
    Order allow,deny
    Allow from all
</Directory>

At this point you need to re-boot your computer so that the http daemon
picks up the new configuration. Login again as root.


HOSTNAME

If the Linux computer with the 2dFGRS Database is attached to a network, 
and is to be used to serve up information from the 2dFGRS Database over 
the network, then the full network name of the Linux computer must be 
given in the file /home/TDFgg/HOSTNAME. If the 2dFGRS Database will only
be accessed locally on the Linux computer, then the default name of 
localhost already in /home/TDFgg/HOSTNAME is sufficient.


RUNNING THE mSQL DAEMON

The database is served by the mSQL daemon, which will need to be started 
each time the computer is rebooted. The command to start the mSQL daemon 
must be run by the user TDFgg. 

A script file is provided to start (or restart the mSQL daemon if this should become
necessary). It is:
	/home/TDFgg/mSQL/bin/restart_mSQL.csh >& /dev/null


CLEARING THE SCRATCH AREA

Requests from the database create temporary files in the scratch area. These are
the gzipped text and FITS files requested for downloading, and the .gif files of
the finding chart and spectra that are displayed. These are written by the http
daemon which runs as user nobody. These files must be deleted by root. A convenient 
way of dealing with this is to run a root cron job that clears the scratch area. 
It is polite to stop the mSQL daemon before clearing the scratch area, and to 
restart it afterwards. Here is a cron script that stops the mSQL daemon every day 
at 06:27 and restarts it at 06:35, and another that clears the scratch area at 6:30

As user TDFgg run:
	/home/TDFgg/bin/setup_mSQLCrontab.csh >& /dev/null

As user root run:
	/home/TDFgg/bin/setup_ScratchCrontab.csh >& /dev/null


INSTALLING THE OTHER WEB PAGES

On CD-ROM No. 1, in directory Public, are all the other WWW pages. After mounting
the CD-ROM, these can be used directly from CD-ROM No. 1. The commands are:
	INSERT CD-ROM No. 1
	mount /mnt/cdrom
	netscape &
	Open Page file:/mnt/cdrom/Public/index.html
            (i.e. type <CTRL-O> or <ALT-O> and
             enter file:/mnt/cdrom/Public/index.html)

Alternatively, they can be copied to hard disk and used with the Linux web server
by making a link from /home/TDFgg/public_html to the copy on hard disk. The
commands are:
	INSERT CD-ROM No. 1
	mount /mnt/cdrom
	cp -a /mnt/cdrom/Public /data3
	cd /home/TDFgg/public_html
	ln -s /data3/Public Public
	netscape &
	Open Page httpd://localhost/~TDFgg/Public/index.html
            (i.e. type <CTRL-O> or <ALT-O> and
             enter httpd://localhost/~TDFgg/Public/index.html)


A NOTE ON THE FITS DIRECTORY STRUCTURE

The FITS files are organized in a hierarchical file structure because 
there are too many files to place in one directory. The structure is

	top level
	Database
		2nd level
		nnn = UKST field number
			3rd level
			m = least significant digit in serial number
				4th level
				xxxxm.fits = the FITS file
				where xxxxxm is the 2dFGRS serial
				number

For example, the object TGN141Z022 is in UKST field 792, and has 
serial  number 250378. Data on this object is in the FITS file 
Database/792/8/250378.fits


APPENDIX A.1

If your flavor of Linux will not allow the creation of a user and group with
name TDFgg and number 401, then the procedure is to create a new user, and
change the user and group names and numbers to TDFgg and 401. The steps are:

1) create a new user, for example new_user

2) edit /etc/group by changing the entry for new_user, altering the name to 
	TDFgg and the number to 401

3) edit /etc/passwd by changing the entry for new_user, altering the name to 
	TDFgg and the name and group numbers to 401:401, and the home directory
	and shell to /home/TDFgg:/bin/tcsh. You should end up with something like
	TDFgg:x:401:401:2dFGRS Database:/home/TDFgg:/bin/tcsh
	Note that x will be the encrypted password if you are not using 
	shadow pass words. If all the second entries in /etc/passwd are x, then
	you ARE using shadow pass words and /etc/shadow must also be edited. In
	/etc/shadow change new_user to TDFgg

4) change the ownership of the home directory from new_user to TDFgg. The
	commands are:
		cd /home
		mv new_user TDFgg
		chown -R 401:401 TDFgg