INSTRUCTIONS FOR INSTALLING THE 2dFGRS DATABASE ON A LINUX SYSTEM


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>
AddType text/html .shtml
AddHandler server-parsed .shtml
AddType text/html .html
AddHandler server-parsed .html

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