Back to Installation Guide

Maintenance Guide for the Australian Speleological Federation KID

Scope

This is a guide to the running and maintenance of the Australian Speleological Federation's Web-based Karst Index Database. See the Installation Guide for how to install a KID system from scratch. This document does not cover how to use the KID as a user.

This document is written for a System Administrator. Knowledge and experience in basic UNIX system administration, including database administration, is required to understand this document and the ASF's KID.

The code for the ASF's KID software is released under the GNU Public Licence. All of the code used for the KID is open source. Most of this code is released under the GPL, the exception being the PDFLib Lite library which is used to create PDF's. This is open source and available from http://www.pdflib.com but is released under their own licence which allows it to be used for free under certain conditions.

Authors

Original Author: Rick Welykochy (rick@praxis.com.au) 2000-11-29
Changes by: Mike Lake (mikeL@speleonics.com.au)

Referenced Files

The following documents/files are referenced by this document.

Contents

Introduction

The Development KID
New Installation of Development KID

Backups and Restores of the KID Data

The save_tables script
The load_tables script
Examples

New Software Release at caves.org.au

Release Numbering
Subversion Release Tagging
1. Preparing for the New Production Release
2. Deploying the New Production Release
3. Preparing the Next Development Version

New Software Release from a tar.gz File

Updating your Local Copy of the KID from Subversion

The ASF KID Environment

Web Configuration
Shell Configuration
Shell Configuration for Subversion
Shell Configuration for init

Invoking MySQL Directly for Viewing or Managing KID Data

dbconv - list database conversions that have not been applied to the KID
kidpasswd - change an ASF KID web password
tsearch - running the search facility from the shell
version - finding version numbers
init - starting and stopping Apache & MySQL services

Change History of this Document

Introduction

In this guide the following conventions are used.

Anything that is typed by the user in a terminal is shown in a yellow box like this:

Descriptions of files are shown like this:

top

The Development KID

On the ASF's server there are actually two Karst Index Databases; kid is the production one and kiddev is a database for development and test.
Likewise there are two UNIX users; kid and kiddev.

The scripts for the production KID reside in user kid's home: /home/kid/asf-kid/
The scripts for the development KID reside in user kiddev's home: /home/kiddev/asf-kid/.
The scripts in user kid only act on the kid database. i.e. the production one.
The scripts in user kiddev only act on the kiddev database i.e. the development one.

This way there no possibility of contaminating the production database with incorrect data while testing new scripts.

To maintain this separation at the web server level there are two copies of apache running; one listening on the normal port 80 and another on port 8080. The two apaches use different httpd.conf files and they are setup so that the production KID is accessable at http://www.caves.org.au/kid and the development KID at http://www.caves.org.au:8080/kid/ (note the :8080 immediately after au).

How is this acomplished?
In both apache config files the DocumentRoot is set to /home/caves/www but in the first httpd.conf file we have an alias:

Alias /kid /home/kid/asf-kid/html

In the second httpd2.conf (used by the second apache) the alias is set to:

Alias /kid /home/kiddev/asf-kid/html

Thus the URL http://www.caves.org.au:8080/kid/ takes us to the directory /home/kiddev/asf-kid/html

Similarly there are two databases on the one MySQL server:

NOTE: If you don't want to run a development system on the server and just want to have a production only system then you don't need the user 'kiddev' nor do you need to install a second Apache web server or a second database.

top

New Installation of Development KID

Installation of the development KID is similar to the installation of the production database except that 'kid' becomes 'kidev', you have to create another apache config file httpd2.conf and make some changes to it, and there are several steps that don't have to be done. Below is a summary of the steps that have to be done with the ones that don't need to be done again crossed out.

1. Create User 'kiddev'
2. Install KID software into /home/kiddev/asf-kid/
3. Build & Install Required Perl Modules
4. Build & Install the Mod_Auth_MySQL Module
5. Create and Edit the Second httpd2.conf File
6. Ensure that mod_perl is Running Properly
7. Edit asf-kid/lib/KID/DB.pm and put in 'the_mysql_www_password'
8. Create a new user 'www' in the mysql database
9. Create an auto-login config file for MySQL access in the Shell
10. Create the kiddev Database

Create User 'kiddev'

# adduser kiddev
Adding user kiddev...
Adding new group kiddev (1002).
Adding new user kiddev (1002) with group kiddev.
Creating home directory /home/kiddev.
Copying files from /etc/skel
Enter new UNIX password: 
Retype new UNIX password: 
passwd: password updated successfully
Changing the user information for kiddev
Enter the new value, or press return for the default
        Full Name []: KID Development
        Room Number []: 
        Work Phone []: 
        Home Phone []: 
        Other []: 
Is the information correct? [y/n] y

#

Logout as root and login as kiddev. Then edit .bashrc and add alias rm='rm -i' for some safety.

Add the following lines to the end of their .bash_profile file as was done with user 'kid'.

export ASFBASEURL=/kid
export ASFDIR=/home/kiddev/asf-kid
export ASFISDEV=1
export ASFHTTPPORT=8080
export ASFDATABASENAME=kiddev

# ASF KID environment
ASFBEGIN=~/asf-kid/bin/begin
if [ -x $ASFBEGIN ]; then $ASFBEGIN; fi

Install KID software into /home/kiddev/asf-kid/

$ cd /home/kiddev

$ tar xzf asf-kid-x.yz.tar.gz 

$

Create and Edit the Second httpd2.conf File

The second Apache server will read a separate config file from the first Apache. This second config file will be called httpd2.conf

Copy the /etc/apache/httpd.conf file to /etc/apache/httpd2.conf and make the following changes.
The format below is from:
diff /etc/apache/httpd.conf /etc/apache/httpd2.conf

< ## httpd.conf -- Apache HTTP server configuration file
> ## httpd2.conf -- Apache Number 2 HTTP server configuration file

< LockFile /var/lock/apache-perl.lock
> LockFile /var/lock/apache-perl2.lock

< PidFile /var/run/apache-perl.pid
> PidFile /var/run/apache-perl2.pid

< ScoreBoardFile /var/run/apache-perl.scoreboard
> ScoreBoardFile /var/run/apache-perl2.scoreboard

< Port 80
> Port 8080

< Alias /kid /home/kid/asf-kid/html
> Alias /kid /home/kiddev/asf-kid/html

< PerlSetEnv ASFHTTPPORT 80
> PerlSetEnv ASFHTTPPORT 8080

< PerlSetEnv ASFISDEV 0
> PerlSetEnv ASFISDEV 1

< PerlSetEnv ASFDIR /home/kid/asf-kid
> PerlSetEnv ASFDIR /home/kiddev/asf-kid

< PerlSetEnv PERL5LIB /home/kid/asf-kid/lib
> PerlSetEnv PERL5LIB /home/kiddev/asf-kid/lib

< ErrorLog /var/log/apache-perl/error.log
> ErrorLog /var/log/apache-perl/error2.log

< CustomLog /var/log/apache-perl/access.log combined
> CustomLog /var/log/apache-perl/access2.log combined

Create and Edit the Second Apache Control Script

The second Apache also needs a control script to start and stop it. On a Debian system the Apache (with mod_perl) control script is /usr/sbin/apache-perlctl

# which apache-perlctl

# /usr/sbin/apache-perlctl

# cp /usr/sbin/apache-perlctl /usr/local/bin/apache-perlctl2

Now edit apache-perlctl2 and make the following changes. The format below is from:
diff /usr/sbin/apache-perlctl apache-perlctl

> # MRL Dec 2003: This is a copy of the apache control script from /usr/sbin/
> # which has been edited and renamed to control the second apache.

< PIDFILE=/var/run/apache-perl.pid
> PIDFILE=/var/run/apache-perl2.pid

< HTTPD='/usr/sbin/apache-perl'
> HTTPD='/usr/sbin/apache-perl -f /etc/apache/httpd2.conf'

Start the second Apache server

# apache-perlctl2 start
/usr/local/bin/apache-perlctl2 start: httpd started
# 

There should be no errors above and a process list should show the second apache running as follows:

# ps ax | grep apache

9269 ?      S    0:00 /usr/sbin/apache-perl
9270 ?      S    0:00 /usr/sbin/apache-perl
9271 ?      S    0:01 /usr/sbin/apache-perl
etc...

9277 ?      S    0:00 /usr/sbin/apache-perl -f /etc/apache/httpd2.conf
9281 ?      S    0:00 /usr/sbin/apache-perl -f /etc/apache/httpd2.conf
9899 ?      S    0:00 /usr/sbin/apache-perl -f /etc/apache/httpd2.conf
etc....

9928 pts/2  S    0:00 grep apache
#

top

Create an auto-login config file for MySQL access in the Shell

This file is identical to that in /home/kid/.my.cnf. Note that you can't copy it over from /home/kid/ when you are logged in as kiddev as its permissions are just 400 only.

[client]
host=localhost
user=root
password=the_mysql_root_password

$ chmod 400 .my.cnf

$ ls -al .my*
-r--------    1 kiddev    kiddev          50 Jan  1 15:50 .my.cnf

Create the kiddev database in mysql

Change to the asf-kid/bin directory and run the create_kid_db script but remember to give it an argument of kiddev not kid.

$ cd asf-kid/model/empty_tables

asf-kid/model/init_tables$ load_tables

$ cd saved_tables

saved_tables$ load_tables

The Development version of the Karst Index Database should now be up and running and accessable from:  http://localhost:8080/kid

top

Backups and Restores of the KID Data

Backing up the ASF KID database is easy and it is quite simple to restore as well.

Both scripts have a help option: --help

The save_tables script

The save_tables script saves an instance of the ASF KID database to flat files in a directory you can specify. The files in that directory can be reloaded into (another) ASF KID database.

Here is the help information for save_tables:

$ save_tables --help

save_tables: save an instance of the ASF KID database to flat files

use: save_tables databasename [outdir]

   databasename     is the name of the database to be saved in file format

   outdir           is the optional output directory; default is .

Current databases:
+----------+
| Database |
+----------+
| kid      |
| kiddev   |
| maps     |
| mysql    |
| test     |
+----------+

$ 

The load_tables script

The load_tables script is used to load the ASF KID database from flat files previously created by the save_tables script.

Caveat: you must manually remove the database if it already exists. The load_tables script will NOT do this for you - it is too dangerous.

Here is the help information for load_tables:

$ load_tables --help

load_tables: load an instance of the ASF KID database from flat files
  to a fresh mysql database

use: load_tables databasename [indir] [OPTION]

   databasename     is the name of the new database to be loaded
                    with the data saved previously by save_tables

   indir            is the input directory; default is .

Current databases:
+----------+
| Database |
+----------+
| kid      |
| kiddev   |
| mysql    |
| test     |
+----------+

The current database must first be removed by running:
mysql -e 'DROP DATABASE databasename'

$ 

Examples

Here are some examples of saving the database tables and restoring the tables again.

Here we specify a directory for the table data to be placed in. If you don't specify a directory the data will be placed in the current working directory.

kid$ save_tables kid saved_tables/

TABLENAMES=AR0000 AR0331 AR0333 CA0000 CA0007 CA0008 CA0011
CA0012 CA0018 CA0030 CA0035 CA0037 CA0041 CA0043 CA0046 CA0048 CA0049 CA0050
CA0051 CA0052 CA0053 CA0055 CA0066 CA0069 CA0070 CA0071 CA0072 CA0074 CA0075
CA0231 CA0241 CA0245 CA0257 CA0258 CA0259 CA0421 CA0427 CA0439 CA0447 OR0000
PE0000 PL0218 PL0219 RE0000 SYS00SPA SYS00SPB SYS00SPC
sys_fid sys_fieldvalue
sys_search sys_table_description sys_user
AR0000 ==> saved_tables//AR0000
AR0331 ==> saved_tables//AR0331
AR0333 ==> saved_tables//AR0333
CA0000 ==> saved_tables//CA0000
CA0007 ==> saved_tables//CA0007

... etc ....

PL0218 ==> saved_tables//PL0218
PL0219 ==> saved_tables//PL0219
RE0000 ==> saved_tables//RE0000
SYS00SPA ==> saved_tables//SYS00SPA
SYS00SPB ==> saved_tables//SYS00SPB
SYS00SPC ==> saved_tables//SYS00SPC
sys_fid ==> saved_tables//sys_fid
sys_fieldvalue ==> saved_tables//sys_fieldvalue
sys_search ==> saved_tables//sys_search
sys_table_description ==> saved_tables//sys_table_description
sys_user ==> saved_tables//sys_user
kid$ 

Here we reload all the tables and re-create the database again. You have to manually drop the database first - the load_tables script won't do it for you.

saved_tables$ mysql -e 'drop database kid'

Now we change into the saved_tables directory and run the load_tables script with the name of the database to be loaded with the tables.

saved_tables$ load_tables kid 

~/saved_tables ~/saved_tables
TABLENAMES=AR0000 AR0331 AR0333 CA0000 CA0007 CA0008 CA0011
CA0012 CA0018 CA0030 CA0035 CA0037 CA0041 CA0043 CA0046 CA0048 CA0049 CA0050
CA0051 CA0052 CA0053 CA0055 CA0066 CA0069 CA0070 CA0071 CA0072 CA0074 CA0075
CA0231 CA0241 CA0245 CA0257 CA0258 CA0259 CA0421 CA0427 CA0439 CA0447 OR0000
PE0000 PL0218 PL0219 RE0000 SYS00SPA SYS00SPB SYS00SPC
sys_fid sys_fieldvalue
sys_search sys_table_description sys_user
./AR0000 ==> kid.AR0000
./AR0331 ==> kid.AR0331
./AR0333 ==> kid.AR0333

... etc ....

./SYS00SPA ==> kid.SYS00SPA
./SYS00SPB ==> kid.SYS00SPB
./SYS00SPC ==> kid.SYS00SPC
./sys_fid ==> kid.sys_fid
./sys_fieldvalue ==> kid.sys_fieldvalue
./sys_search ==> kid.sys_search
./sys_table_description ==> kid.sys_table_description
./sys_user ==> kid.sys_user
~/saved_tables

saved_tables$ 

top

New Software Release at caves.org.au

This section details how to make a new release of the KID software on the caves.org.au site.

ASF KID software is stored in a Subversion repository named 'asf-kid'. A release is a tagged tree in the Subversion repository.

The following policy is adhered to for the ASF KID at caves.org.au:

ASF KID Release Numbering: Production release numbers end in an even digit, e.g. 1.34, while development versions end in an odd digit e.g. 1.35.

ASF KID Subversion Release Tagging: The name of a Subversion tag for a particular software revision is formed by prepending 'release-' to the release number. Only production releases are tagged. Example: The Subversion tag for ASFKID/1.32 is release-1.32

There are three stages to making a new release:

1. preparing for the new production release
   
2. deploying the new production release
   
3. preparing the next development release
   

In the examples, assume we are development release 1.31, and thus 1.32 is going to production.

1. Preparing for the New Production Release

Login as the username that manages the asf-kid directory for development. You should then be in the development home environment i.e. /home/kiddev/.

We maintain the software revision history in the documentation area at the end of the file lib/KID.pm. During development, we document what changes are being added to the release. The documentation for a particular release begins with a one-line header, followed by a list of changes. Finally, a list of RELEASE NOTES guides an installer through the database (and other) conversion scripts that must be run to complete the rollout of the release.

Here is a brief extract from the revision documentation for ASF KID v1.32:

200607??  1.32   mikel  release ASFKID/1.32 200607?? subversion tag release-1.32 to PRODUCTION
                 mikel  explicitly left-align page 1 of advanced search columns
                 mikel  new Article class: KID::DataModel::Article

                 ... etc ...

                 RELEASE NOTES for V1.32
                 (*) database conversions in asf-kid/model/conversions
                     v1.32_sys_user.bash
                     v1.32_PL0579.bash
                     v1.32_update_PL0586.bash kid
                     v1.32_update_PL0587.bash kid
                     v1.32_PE0000.bash

The above documentation needs to be updated to reflect the new release, and a few other changes are made to the lib/KID.pm file.

1. The header line has an unknown date (200607??) - the date is filled in and the revision number is incremented to the next even number:

20060701  1.32  mikel  release ASFKID/1.32 20060701 Subversion tag release-1.32 to PRODUCTION

2. The KID variables VERSION and VERSIONDATE at the top of the KID.pm file are updated:

$KID::VERSION       = '1.32'
$KID::VERSIONDATE   = '20060701'

3. The system documentation is brought up to date:

~$ make_doc

4. The dbconv utility is run to make sure that all database conversions have been run:

$ cd model/conversions
"dbconv: your database appears to be up to date.

5. The web server is restarted:

~$ init restart

6. The new release is viewed in the admin section one more time on the web: http://www.caves.org.au:8080/kid/users/admin

    ASF-KID/V1.32 20060701

Run through all the pages quickly to make sure no glaring errors have arisen. Once you are satisfied this release is ready to go to production, the next step will commit your changes to Subversion:

7. Change to the ASF KID directory root and commit all changes to Subversion:

The Subversion comment for the commit should mention the revision number, something like the following:
"Preparing for production release 1.32 "

~$ svn ci

8. Tag the release with the production revision number:

~/asf-kid$ svn copy svn+ssh://localhost/var/lib/svn/asf-kid/trunk svn+ssh://localhost/var/lib/svn/asf-kid/tags/release-1.32 -m "Tagging production release 1.32 "

Committed revision 39.
~/asf-kid$

Note: If logged into the caves server you would use a file URL as above, if using ssh from a remote site you would use svn+ssh://www.caves.org.au/var/lib/svn/asf-kid/trunk

kiddev@vs:~/asf-kid svn info
Path: .
URL: svn+ssh://www.caves.org.au/var/lib/svn/asf-kid/trunk
Repository UUID: 51935324-4614-0410-81ae-b7c10b9c63cc
Revision: 78
Node Kind: directory
Schedule: normal
Last Changed Author: kiddev
Last Changed Rev: 78
Last Changed Date: 2006-12-27 21:06:41 +1100 (Wed, 27 Dec 2006)

kiddev@vs:~/asf-kid 

kiddev@vs:~/asf-kid svn list svn+ssh://localhost/var/lib/svn/asf-kid/tags/
release-1.30/
release-1.32/
kiddev@vs:~/asf-kid

kiddev@vs:~/asf-kid svn list svn+ssh://localhost/var/lib/svn/asf-kid/tags/release-1.32/
Makefile
bin/
doc/
html/
lib/
model/
regress/
test/
kiddev@vs:~/asf-kid

2. Deploying the New Production Release

Once you are happy that the Subversion repository is updated and the web server in development looks "production ready" you can release to production.

1. Log into the production web server.

2. Stop the web server: init stop

3. In the home directory of 'kid' (i.e. /home/kid/ ), move the entire asf-kid directory tree to a new name, for instance asf-kid-v1.30. If the new release works fine this can later on be removed entirely.

$ mv asf-kid asf-kid-v1.30

4. Export the production version of asf-kid (replacing the tag release-1.32 with the correct tag name):

$ svn export svn+ssh://localhost/var/lib/svn/asf-kid/tags/release-1.32 asf-kid

5. Follow the instructions in the release notes. If database changes are required, startup just the mysqld server (not the web server):

$ sudo /etc/init.d/mysql start

With mysqld up and running, execute the procedures as dictated by the release notes in KID.pm. This usually involves a 'cd asf-kid/model/conversions' and executing the scripts in the conversions directory that are labelled with the production version number.

Run the dbconv script which will inform you what scripts have not yet been run.

$ cd model/conversions
dbconv: the following conversions have not been executed for the database kid:
	v1.32_sys_user.bash 
	v1.32_PL0579.bash 
	v1.32_update_PL0586.bash 
	v1.32_update_PL0587.bash 
	v1.32_PE0000.bash 

Thus in our example for release 1.32 of ASF KID the following conversions were executed:

$ ./v1.32_sys_user.bash kid
$ ./v1.32_PL0579.bash kid 
$ ./v1.32_update_PL0586.bash kid
$ ./v1.32_update_PL0587.bash kid
$ ./v1.32_PE0000.bash kid 

Run the dbconv script again to be certain that all conversions have been executed.

$ cd model/conversions
dbconv: your database appears to be up to date.

6. Stop the database server:

$ sudo /etc/init.d/mysql stop

7. Now we are ready. Start up the entire production system (database and web) and test every page.

$ init start 

3. Prepare the Next Development Version

1. Ensure you are no longer logged in to the production server. Log in as a developer, like 'kiddev'.

2. Update the file lib/KID.pm to reflect a new development version:

Create a new header line for the next production release, but label it with the next development version number (in the POD, at the end of the file, after the previous release notes).

200607??  1.33   mikel  release ASFKID/1.33 200607??  development begins here

Note that in the above example, the next production release is 1.34, so the development version number is one less, i.e. 1.33. Note as well that we never create a tag in the repository with the development version number.

The KID variables VERSION and VERSIONDATE at the top of the KID.pm file are also updated:

$KID::VERSION           = '1.33';
$KID::VERSIONDATE       = '20060701';

3. The documentation is brought up to date: make_doc

4. The development web server is restarted: init restart

5. Ensure the new development release is visible in the admin area: http://www.caves.org.au:8080/kid/users/admin/ where we see the new development release version number and date:
ASF-KID/V1.33 20060701

6. Commit the changes to Subversion: cd ~/asf-kid and run 'svn commit' or the alternative command 'svn ci' which stands for 'check in' and does the same thing.

The Subversion comment for the commit should read something like the following:
"Development begins on next prod release 1.34"

And now you are done. Development can begin in any non-production ASF KID development environment that has been brought up to date with the version 1.33 software.

top

New Software Release from a tar.gz File

The ASF KID is available under the GNU Public License. They are available from http://www.caves.org.au/kid/doc/software.

These releases are created from production releases by taring and gzipping the /home/kid/asf-kid directory. Such releases are labelled as asf-kid-software-vN.NN.tar.gz where the last N is always an even number as it's from a production release (example asf-kid-software-v1.32.tar.gz)

There is also a small dataset of caves, articles and fictitious persons that accompanies the software release. This is labelled asf-kid-public-data-vN.NN.tar.gz. You must use a data set version that matches the software version.

top

Updating your Local Copy of the KID from Subversion

If you have the ASF KID software from a Subversion checkout, update your source code as follows:

$ cd asf-kid
$ svn up 

top

The ASF KID Environment

The ASF KID applications run on the web but also in the shell. In either case, an ASF KID environment must be established before running an ASF KID application. Some of this was established during installation when you edited the .bash_profile of user 'kid'. This section now describes in detail what is setup in the KID environment.

The environment variables are:

Web Configuration

The ASF KID environment for the web server is established by defining the above environment variables in the /etc/apache/httpd.conf Apache configuration file.

Example for kid:

    PerlSetEnv ASFBASEURL        /kid
    PerlSetEnv ASFDIR            /home/kid/asf-kid
    PerlSetEnv ASFISDEV          0
    PerlSetEnv ASFHTTPPORT       80
    PerlSetEnv ASFDATABASENAME   kid
    PerlSetEnv PERL5LIB          /home/kid/asf-kid/lib

Example for kiddev:

    PerlSetEnv ASFBASEURL        /kid                     <-- Note not kiddev
    PerlSetEnv ASFDIR            /home/kiddev/asf-kid
    PerlSetEnv ASFISDEV          1
    PerlSetEnv ASFHTTPPORT       8080
    PerlSetEnv ASFDATABASENAME   kiddev
    PerlSetEnv PERL5LIB          /home/kiddev/asf-kid/lib

Shell Configuration

The ASF KID environment for the shell is established by defining the above environment variables in the .bash_profile file.

Example for kid:

export ASFBASEURL=/kid
export ASFDIR=/home/kid/asf-kid
export ASFISDEV=0
export ASFHTTPPORT=80
export ASFDATABASENAME=kid

# ASF KID environment
ASFBEGIN=~/asf-kid/bin/begin
if [ -x $ASFBEGIN ]; then $ASFBEGIN; fi

Example for kiddev:

export ASFBASEURL=/kid
export ASFDIR=/home/kiddev/asf-kid
export ASFISDEV=1
export ASFHTTPPORT=8080
export ASFDATABASENAME=kiddev

# ASF KID environment
ASFBEGIN=~/asf-kid/bin/begin
if [ -x $ASFBEGIN ]; then $ASFBEGIN; fi

You can also establish the ASF KID environment by running the script asf-kid/bin/begin. In fact this is invoked whenever you login. This is the output that you should see.

***************************************************************************
*
*    Entering the ASF KID shell                                                  
*                                                  
*               ASFDIR:  /home/kid/asf-kid
*             ASFISDEV:  0
*           ASFBASEURL:  /kid 
*          ASFHTTPPORT:  80
*      ASFDATABASENAME:  kid
*                                  
*    Copyright (C) 2003-2004  Australian Speleological Federation
*
***************************************************************************

asf-kid$

To ensure that the correct environment variables are set if you change shell users (e.g. from kiddev to kid) make sure you use the '-' option to the su command:

     su - 

When the '-' option is provided on the su command-line this tells su to execute the .bash_profile for username, which is quite important: you want to be in the ASF KID environment for username when you assume username's login.

Shell Configuration for init

There is a script in asf-kid/bin/init which provides a unified interface for starting, restarting and stopping ASF KID services, like the web server and the mysql daemon. For init to function correctly, four environment variables must be defined in your .bash_profile file:

    ASF_INIT_HTTPD               The path to the init script for Apache
    ASF_INIT_MYSQLD              The path to the init script for MySQL
    ASF_INIT_APACHE_ACCESS_LOG   The path to the access log for Apache
    ASF_INIT_APACHE_ERROR_LOG    The path to the error log for Apache

If you do not wish init to start/stop a particular service, set the init script for that service to /bin/true. For example, the mysql daemon is stopped and started by init when the username is kid. But when the username is kiddev, the mysql daemon is not touched.

Example for kid:

   export ASF_INIT_HTTPD=/usr/sbin/apache-perlctl
   export ASF_INIT_MYSQLD=/etc/init.d/mysql
   export ASF_INIT_APACHE_ACCESS_LOG=/var/log/apache-perl/access.log
   export ASF_INIT_APACHE_ERROR_LOG=/var/log/apache-perl/error.log

Example for kiddev:

   export ASF_INIT_HTTPD=/usr/local/bin/apache-perlctl2
   export ASF_INIT_MYSQLD=/bin/true
   export ASF_INIT_APACHE_ACCESS_LOG=/var/log/apache-perl/access2.log
   export ASF_INIT_APACHE_ERROR_LOG=/var/log/apache-perl/error2.log

If you attempt to run the init script without the above variables begin defined, you will see an error message something like the following:

$ init
  missing $ASF_INIT_HTTPD

top

Invoking MySQL Directly for Viewing or Managing KID Data

The MySQL database can be invoked directly for viewing the tables and data stored in the database. Entries can be searched for, added, removed or edited.

Be careful !.

Examples of queries are:

$ mysql kid
mysql>                                          <-- the prompt will change to this.
mysql> show tables;                             <-- don't forget the semicolon at the end.
mysql> desc sys_user;                           <-- For each table you can get a description of it.
mysql> select * from sys_user;                  <-- Do a query like this.
mysql> select username,isadmin from sys_user;   <-- or like this.

Here is a more complex example:

mysql> select cave_id,latest_update_org_code from CA0447 where cave_id='AUASF06692';
+------------+------------------------+
| cave_id    | latest_update_org_code |
+------------+------------------------+
| AUASF06692 |                        |
+------------+------------------------+
1 row in set (0.00 sec)


mysql> SELECT cave_id,latest_update_by FROM CA0447 WHERE latest_update_by RLIKE '.*WASG.*';

etc.....
| AUASF05757 | R. Webb WASG 1985      |
| AUASF05758 | R. Webb WASG 1985      |
| AUASF05769 | R. Webb WASG 1985      |
+------------+------------------------+
603 rows in set (0.21 sec)

To get a text file dump of information we spawn a mysql query from the normal shell prompt like so:

$ mysql -e "SELECT cave_id,latest_update_by FROM CA0447 WHERE latest_update_by RLIKE '.*WASG.*'" kid > outfile

$ mysql -e "desc sys_user" kid > sys_user.dump

top

Utilities

These utilities can be found in asf-kid/bin.

dbconv - list database conversions that have not been applied to the KID

$ dbconv
dbconv: the following conversions have not been executed for the database kiddev:
        v1_10_add_CA0464.bash
        v1_14_drop_cols_PE0000.bash
$ 

kidpasswd - change an ASF KID web password

This script can change an ASF KID users password.

Note that kidpasswd acts on the user and password that's stored in the 'sys_user' table of the 'kid' database. Don't confuse this with the 'www' password that's in the 'user' table in the 'mysql' database. The password in sys_user is an MD5 sum, not the mysql encoding.

$ kidpasswd --help
kidpasswd: change ASF KID web password
use: kidpasswd username [ databasename ] [ option ]...
     username       username of ASF-KID user
     databasename   optional ASF KID database name; default is kiddev

options:
 -D --debug         debug messages to STDERR
 -t --test          test password
 -? --help          print this message and exit

$ 

Changing a Password

$ kidpasswd mike
Enter new password: 
Re-enter password: 
Password changed for user mike
$

Checking a Password

$ kidpasswd --test mlake
Password: secret
Password matches.
$ 

Understanding What kidpasswd Does

   Have a look at what the password is encrypted as currently.

release-kid mysql -e "select fullname,username,password from sys_user" kiddev
+---------------+----------+---------------+
| fullname      | username | password      | 
+---------------+----------+---------------+
| Andy Updater  | andy     | b9.XTPbE.P9TU | 
| Bill Updater  | bill     | 4vDno74rY1oLY | 
| Cathy Updater | cathy    | xAUXM8qFekmvo |
+---------------+----------+---------------+

   Now change a password.

 kidpasswd andy       
Enter new password: bandy
Re-enter password: bandy
Password changed for user andy

   Now have a look at what the password is encrypted as now.

 mysql -e "select fullname,username,password from sys_user" kiddev
+---------------+----------+---------------+
| fullname      | username | password      |  
+---------------+----------+---------------+
| Andy Updater  | andy     | mYUF9UL03UgZA |  <-- this is now changed
| Bill Updater  | bill     | 4vDno74rY1oLY | 
| Cathy Updater | cathy    | xAUXM8qFekmvo |
+---------------+----------+---------------+

tsearch - running the search facility from the shell

You can have a play with the search facility from the shell. The script is called tsearch. Here is an example:

./tsearch - minimum_temperature 10 

AUASF01428   2W-2     Bullio Cave
AUASF05162   6E-22    Arramal Cave
AUASF06415   7MC-39   Little Trimmer   

To obtain help on this script:

./tsearch --help    or   ./search -?

If attempts to run scripts from the command line fail with error messages saying you are not authorised then it's probably because you are logged into the system as a UNIX user with a different username to what is in the KID's sys_user database. For instance if your sys_user table username is 'bob' for Bob Jones and your UNIX login is 'bobj' you won't be able to run KID scripts from the command line.

Here is how to check what user name you are logged in as:

DEV: kiddev$ perl -e "print getlogin.' '  "
mikelDEV: kiddev$ 

The purpose of the blank space appended to the getlogin is because the ANSI escape sequence that produces the green color of the 'DEV' gobbles up the character to its left.

version - finding version numbers

$ version 
ASFBASEURL      /kid
ASFDIR          /home/kid/asf-kid
ASFISDEV        1
ASFHTTPPORT     80
ASFVERSIONINFO  ASF-KID/V0.96 20040306
ASFDATABASENAME kid
incgi           0

init - starting and stopping Apache & MySQL services

The ASF KID 'init' script provides a uniform way to control ASF KID web and database services. It is a wrapper on top of other init scripts, like that used for starting and stopping the apache web server. The ASF KID init script lives in the asf-kid/bin directory.

Here is the help information for init:

kid$ init --help
   init: start and stop ASF KID services
   use: init {start|stop|restart|status|procs}... [option]
         start      start the services
         stop       stop  the services
         restart    stop then start the services
         status     server status
         procs      list server processes
   options:
         -D         debug mode: be a bit more verbose
         -a         don't exit: tail the access_log
         -e         don't exit: tail the error_log

To use init the following environment variables must be set in the bin/begin script.

   ASF_INIT_HTTPD               The path to the init script for Apache
   ASF_INIT_MYSQLD              The path to the init script for MySQL
   ASF_INIT_APACHE_ACCESS_LOG   The path to the access log for Apache
   ASF_INIT_APACHE_ERROR_LOG    The path to the error log for Apache

Here are some examples of using init.

1. Start services:

   init start

2. Start services and tail the error log:

   init start -e

3. Restart services:

   init restart

4. Which service processes are running?

   init procs

top

Change History of this Document

top