BIRCH
BIRCH Administration
Key Concepts


What do I need to know to create and maintain a BIRCH site?

A BIRCH administrator should have the following knowledge and skills:

How BIRCH is organized?

Table 1. BIRCH hierarchical directory structure (for simplicity, not all directories are shown).
/home/birch
admin
bin-linux-intel
bin-solaris-sparc
doc
dat
local
admin
bin-solaris-sparc
bin-linux-intel
doc
dat
pkg
public_html
and so on...
pkg
public_html
and so on...

The BIRCH home directory
BIRCH is organized as described in Table 1. In the example, BIRCH is located in '/home/birch'. A sample of directories is shown. The location of the BIRCH home directory is set in the environment variables $BIRCH and $birch, which will be used throughout this document. "$BIRCH" is generally used for readability in documentation, while "$birch" is easier to type.

Local customizations are contained in a separate directory, allowing easy upgrades.
The high-level organization of BIRCH is borrowed from Unix. All Unix systems have standard system directories, and a directory called /usr/local. /usr/local contains directories such as /usr/local/bin/, usr/local/lib etc. Ideally, the system adminiatrator would add new programs only to /usr/local, and not to other directories such as /bin or /lib, which can be thought of as belonging to the operating system. Consequently, upgrades of the operating system shouldn't affect anything in /usr/local/, and changes to installed software shouldn't affect the operating system.

Similarly, the high-level structure of BIRCH is mirrored in $BIRCH/local. With very few exceptions, the local BIRCH administration should never have to make changes in directories other than $BIRCH/local. More importantly, programs and documentation added $BIRCH/local are not clobbered when BIRCH is upgraded to a new version.

Table 2. Summary of BIRCH directories
Directory
Description
admin
files and scripts related to BIRCH administration
bin-os-hardware
executable binaries, specific for a particular operating system and hardware platform
dat
ancilliary datafiles used by programs
doc
documentation
install
working directory for installation tasks
install-birch
working directory for initial installation of BIRCH system
java
Java applications
lib-os-hardware libraries, specific for a particular operating system and hardware platform
local
locally-installed software, libraries, documentation etc.
manl
Unix-style manual pages for BIRCH software
pkg
packages that need to be kept together in a specific directory structure
public_html
BIRCH Web pages
script
(presumably) platform-independent scripts. When possible, scripts are installed here, rather than being duplicated several times in independent platform-specific bin directories
tutorials
BIRCH tutorials

The BIRCH system administrator should never have to make changes on individual user accounts

In order to use the programs and datafiles in BIRCH, environment variables need to be set when a user logs in. Most importantly, the directories containing executable files must be added to the $PATH. As well, enviroment variables governing how different programs work must also be set.  The exact mechanism for how these settings are made when a user logs in depends on their default shell, as summarized in the table below:

Family
The BOURNE shell family
The C-shell family
shell executable
/bin/sh, /bin/ash, /bin/ksh, /bin/bash, /bin/zsh
/bin/csh, /bin/tcsh
files in $HOME directory
.profile - executed at login and when starting a new process
.cshrc - executed at login and when starting a new process
.login -executed at login only

For example, if a user's default shell is /bin/sh, then $HOME/.profile will be run at login time. Likewise, if a user's default shell is /bin/csh, then $HOME/.cshrc, followed by $HOME/.login, will be run at login.

To avoid the nightmare in which each user has to modify and update these files themselves, it is imperative that settings be centrally administered and automatically set for the user. To make this work, a few changes must be made to each user's account. When the user runs  $BIRCH/admin/newuser, the following line is copied from $BIRCH/local/admin/add_to_login  to the user's .login file:

source birch_home_dir/admin/login.source

Similarly, the following line is copied from $BIRCH/local/admin/add_to_cshrc  to the user's .login file:

source birch_home_dir/admin/cshrc.source

Finally, the following line is copied from $BIRCH/local/admin/add_to_profile  to the user's .profile, .bash_profile and .bash_login files:

. birch_home_dir/admin/profile.source

Thus, regardless of the user's default shell, the correct environment variables will be set.

Note: If you have root access, it is possible to eliminate the need for users to run the newuser script. Simply add the contents of admin/add_to_cshrc, add_to_login and add_to_profile, respectively, to the systemwide cshrc, login and profile scripts. All users on the system will have the complete set of BIRCH environment variables. This should probably be done after you have gotten BIRCH installed and working.

ORDER OF EVENTS: The C-shell Family

  1. $BIRCH/admin/cshrc.source
  2. $BIRCH/admin/login.source
Each time a new process is started (eg. a new window is opened, only part 1 is executed).

ORDER OF EVENTS: The Bourne Shell Family

Since $PATH is set at login, profile.login.source and local.login.source will only be executed at login.

The important take home lesson is that the user never, ever, makes changes to parameters in their own account. Any environment variable, alises, paths etc. that need to be tailored to the local system should be changed (for C-shell users) in  $BIRCH/local/admin/local.cshrc.source and $BIRCH/local/admin/login.source, or for Bourne shell users, in local.profile.soruce or local.profile.login.source. Since these files execute after their counterparts in $BIRCH/admin, any changes made here will supersede settings in $BIRCH/admin. To ensure that updates of BIRCH don't overwrite local changes, changes should be made to files in $BIRCH/local/admin, and not in $BIRCH/admin.

Further reading

A more thorough treatment of these concepts can be found in a preprint chapter from Introduction to Bioinformatics (Krawetz & Womble, Eds.),
Humana Press. Chapter 16 Installing Bioinformatics Software in a Server-Based Bioinformatics Resource. (1.1 Mb, PDF)

The structure of BIRCH has evolved significantly since this chapter was written, but the main concepts are still consistent with BIRCH's current organization. Perhaps the one thing to mention is that the environment variable $DB, which points to the main BIRCH directory, has been changed to $BIRCH in the current implementation.


Please send suggestions of comments regarding this page to psgendb@cc.umanitoba.ca