Administrator's Guide to the BABAR Database
DRAFT VERSION
BABARDatabase Group
Version Information
Last updated: 1 th July 1998
This document is still under development. If you have any questions or comments, please address them to David Quarrie (DRQuarrie@LBL.Gov).
This document describes how to install the software that is required to run the BABAR database. It is designed
for site database adminstrators and involves activities that require system administrator privilege. It is one of a suite of documents that describe different aspects of the use of the database. Other documents include:
Return to Table of Contents.
The following concepts should be understood by database administrators:
- Pages. A page is the unit of transfer between a file server and the client application. It may be in the range of 4096 to 65536 bytes in size, and is determined by the database
designers.
- Database ordatabase file. Each persistent object is created in an Objectivity database. Currently each database corresponds to a Unix file, although this
one-to-one mapping is expected to be removed in a future release of Objectivity. Each database is associated with a particular file server (see later) and is identified both by its file system location and by a unique Database ID
(DBID).
- Federated Database or Federation. This is a set of related database files and objects that can be accessed by a single application. Each federation consists of
possibly multiple databases distributed across multiple file servers, together with the schema definitions. Each federation is identified by a Federated Database ID (FDID).
- Lock Server. This is a process running on a designated computer that manages concurrent access to the databases. No data passes through the lock server, but it ensures that data within
the federation is consistent and prevents simultaneous updates from multiple clients.
- File Server. Two sorts of file systems are supported by the BABAR database. The
first is local file systems, attached directly to the computer upon which the client application resides. The second is remote file systems, attached to remote computers. Such file systerms are accessed via the Advanced Multi-threaded Server (AMS) by a
network protocol. AMS is a daemon that has to be installed on the file server machine by a systtem administrator. NFS or AFS file systems are not supported apart from the Boot File (see later).
- Boot File and Federated Database File. The Federated Database File contains the schema definitions and database catalog for a Federation. By
BABAR convention it is called BaBar.FDDB and is located on the Boot File Server. The Boot File is a file that describes the federated
database configuration, the location and file server of the Federated Database File, the Federated Database ID, lock server node and other parameters describing the federation. In principle the Boot File is the only file that must be directly visible to
the client applications and is used to bootstrap the applications. By BABAR convention the boot file is called BaBar and should reside on a file system that
is visible to all desired client computers. Unlike the other database files it may reside on a NFS or AFS file system.
Return to Table of Contents.
Before a BABAR collaborator is allowed access to this software, they must read a license agreement form, sign it and return it to Charlotte Hee at SLAC.
Details of the installation procedure are given at the following URL:
/BFROOT/www/Computing/Offline/Databases/Docs/objyInstal.html
Return to Table of Contents.
The daemon (called pud: "Perl Universal Daemon") is meant to handle all file-system-related operations like creating, deleting directories / files, checking available space on a disk, etc. It is required
to run a daemon on every machine which runs Objectivity’s Advanced Multithreaded Server (AMS); the daemon should be started by the same user who launched AMS. Every mount point should be served by one dedicated daemon, which implies that many daemon
can run on the same host.
Other requirements
- the path : /usr/local/bin/perl5 must point to the perl interpreter version 5
- module Shareable.pm has to be installed. You can download it from CPAN - perl archive (see www.perl.com)
- the pud must be installed as discribed below
- all clients running application which talks to the daemon should belong to bfactory group.
The default place for the pud files is the directory: /usr/object/babar/bin/pud/. If this directory can not be used by any reason, the environment variable: BDBPUDPATH should point to the valid
location of pud files. The BaBar software is first looking for pud-files in the default place, and if they can not be found there, the environment variable is used.
The following is the complete set of pud files:
| pud |
daemon executable |
| pud_common.pm |
definition of methods common across all file system |
| pud_AIX.pm |
definition of additional methods (AIX-related) |
| pud_OSF1.pm |
definition of additional methods (OSF1-related) |
| pud_SunOS.pm |
definition of additional methods (SunOS-related) |
| pud_AIX.conf |
configuration file for AIX |
| pud_OSF1.conf |
configuration file for OSF1 |
| pud_SunOS.conf |
configuration file for SunOS |
| pud_misc.pm |
definition of internal, miscellanous functions |
| pud.1 |
man pages - daemon |
| pudc |
client executable (communicates with the daemon) |
| pudc.conf |
client configuration file |
| pudc.conf |
client configuration file |
| pudc.1 |
man pages - daemon client |
| BdbAdminDaemon |
tool for maintaining the daemon |
It is mandatory to keep all these files in one directory (excluding man pages). Man pages can be install eg. under /usr/local/man/man1 or read using eg. "nroff -man pud.1 | less" command.
These files can be copied directly from the daemon directory which is part of the BdbUtil package. Mode of files: pud, pudc and BdbAdminDaemon has to be changed to 775.
Changing configuration parameters
1. Client configuration - pudc.conf file:
By default the period, client waits for daemon’s response is about 8 seconds (after this time it is assumed that daemon is not running). If the interval should be adjusted, "ctries" values defined in
pudc.conf need to be changed. See the file pudc.conf for further details.
2. Daemon configuration - pud_AIX.conf, pud_OSF1.conf files
The only configuration field, we suggest local administrator should change is "xauth" setting [... incomplete] See pud_AIX.conf and pud_OSF1.conf files for further details.
3. BdbStartDaemon file
Setting a default port number - change value of the $DefaultPortNr variable
Maintainance
BdbAdminDaemon is a tool dedicated to maintain the daemon.
Starting a daemon: BdbAdminDaemon -start [-p portNr] [-v]
Terminating daemon: BdbAdminDaemon -terminate [-p portNr] [-v]
Checking if daemon is running: BdbAdminDaemon [-p portNr] [-v]
where:
portrNr : if the flag –p portNr is ommited, the default port number: 3333 is used. The port number has to match the right number loaded into the federation (see File Server and File
System Configuration)
-v turns on verbose mode. By default verbosity is disabled.
Current version of BdbAdminDaemon is supported on AIX, SunOS and OSF1.
The log file
Once daemon is started, various type of messages are routed to the log file. The place of the file is /tmp/ and the file name is of the format: pud_<day>.log, where <day> is the three letter day of the
week (e.g. pud_tue.log). Note, that log files are recycled every seven days. The place of the log file can be changed, see pud_AIX.conf and pud_OSF1.conf files for further details.
Format of the log file:
<date> <type of info> message <pid of the daemon> <user name>@<host name> <request> <parameters> <return status>
If no authentication is enabled, <user name> field will be left empty.
Example:
15:05:15 Error: File /nfs/objyserv1/testA does not exist. PudID=41540, becla@percheron.slac.stanford.edu, req=checkExist, parms= /nfs/objyserv1/testA, rc=-1
Return to Table of Contents.
Note that these features are not available in release 6.5.0, they will become a part of the next release, now they are available on the head of CVS. It is a subject to change.
FS related information (FSInfo) is meant to provide full information about all file systems available for storing BaBar databases.
If the site is ever going to place databases on more then one file system, the FSInfo should be loaded into the federation before any database is created, as it is needed by BaBar clustering hint classes to
efficiently distribute event components among the file systems. If the FSInfo is not loaded, usage of daemon is automatically disabled (see File system operations with daemon turned off).
The FSInfo needs to be prepared in an ASCII file using the format as described below. Then the file can be loaded into the federation using BaBar tool. The file contents can be changed and re-loaded overwriting
stored data whenever the latter becomes obsolete.
The FSInfo carries following information:
- complete list of all file systems available for BaBar database placement divided into user-defined groups (at SLAC at least 3 different groups can be foreseen at this time: HPSS, slow-access FS and fast-access
FS).
- mapping event components into the groups of file systems mentioned above.
Format of the configuration file
The file is interpreted line by line, duplicated lines are detected and discarded, all empty lines are ignored (an empty line is also a line with separators: spaces or tabulators, not more then 20).
Format of one line:
Identifier delimiter [separators] data
The only allowed identifiers are: FileSystem, FS-Group, CatalogFS, MaxContNr, MaxContSize, NrDbInDir
The delimiter ‘:’ must appear immediately after the identifier.
Format of the data after the delimiter is different depending on the identifier. Total length of data in one line cannot exceed 256 characters.
All lines starting with FileSystem must appear before all others.
Data format after the identifier "FileSystem"
hostName baseDirName portNr minimumDiskSpace groupName
Spaces or tabulators are valid separators between the fields.
Port number is interpreted as a decimal number (daemons must be started on ports as specify here).
Minimum disk space is interpreted as a decimal number and is stored persistenly as d_ULong. Specified number is treated as number of KB (1000 = 1 MB, etc).
Data format after the identifier "Catalog-FS"
portNr minimumDiskSpace
The line with the identifier "Catalog-FS" must appear in the configuration file exactly once. The missing information about catalog file system (host and baseDirName) is obtain from the bootfile. The
interpretation of both portNr and minimumDiskSpace fields is the same as for "FileSystem" identifier.
Data format after the identifier "FS-Group"
domainName authLevel realUserName component groupName
The specified groupName must appear at least ones after "FileSystem" identifier (mapping can not be performed to an empty group).
Valid domainName: "conditions", "events", *
* = all
Valid authLevel: "system", "user", *
* = all
Valid realUserName: userName or *
Group name must end with "P" or "S" which indicated parallel of sequential database distribution across the entire group.
Parallel database distribution means that every database is placed on next FS in the group, when last FS is reached the next db is placed on the first one etc. Sequential database distribution means that all databases are placed on the same FS untill it
is full, then the next FS is used etc.
Component must be 3-character string containing only alphanumeric characters (0-9, a-z, A-Z), it is important to use the names which corresponds to names used in the BaBar C++ software, otherwise the parameters
specified here will be ignored. Example of valid component: "raw", "rec", "sim", "eod", "asd", "tag", "emc", "ifr", etc.
"*" = all components valid for specified domain
The priority of the lines increases as one approaches the bottom of the file
FS-Group: events system becla * FAST-P
FS-Group: * * * * SLOW-S
All the components (even while running under SYSTEM privileges) will be placed on the SLOW file systems (because the second line covers the definition from the first line).
If not all combinations of mapping are defined, the not-defined spots are assigned to the catalog FS. As an example consider the following configuration file:
FileSystem: objyserv1.slac.stanford.edu /nfs/objyserv1/u5/databases/ 3333 12500 SLOW-S
FileSystem: objyserv1.slac.stanford.edu /nfs/objyserv1/u6/databases/ 3333 20000 FAST-P
CatalogFS: 3333 30000
FS-Group: * system * * FAST-P
FS-Group: * user raw quarrie SLOW-S
FS-Group: * user rec becla SLOW-S
Under "user" privileges all components apart from "raw" and "rec" will go to catalog FS.
See Database Parametrs Configuration for additional information on data which can be provided in the same ASCII file.
Example configuration file can be found in BdbAccess package, file name: config.BaBar
Loading the information
BdbFileConfigLoader is a tool for loading information from an ASCII configuration file into the federated database. Usage:
BdbFileConfigLoader [-f file] [-v]
where:
-v turns on verbose mode. By default verbosity is disabled.
-f file fully qualified path to the ASCII configuration file
If the flag -f file is not specified, current FS-related information stored in the federation is displayed (read only access, no change to the data).
Every time, the new data is loaded (tool is called with a flag –f) the existing data is deleted.
The configuration file is scanned from the top to the bottom (information after an identifier is stored in a database in the same order as they appear in the file). Lines with different identifiers can be mixed (no
influence on the order in database). Example:
FileSystem: objyserv1.slac.stanford.edu /nfs/objyserv1/u5/databases 3333 FAST-P
FS-Group: * * * * * SLOW-S
FileSystem: morgan12.slac.stanford.edu /nfs/objyserv1/u6/databases 3333 SLOW-S
FileSystem: morgan05.slac.stanford.edu /nfs/objyserv1/u6/databases 3333 SLOW-S
FileSystem: online04.lbl.gov /home/online1/db 3333 FAST-P
CatalogFS: 3333
FS-Group: * system * * SLOW-S
The group FAST-P consists of two FS, databases will be first stored on the objyserv1::/nfs/objyserv1/u5/databases, and when this disk will be filled up, online04.lbl.gov::/home/online1/db will
be used.
File system operations with daemon turned off
The pud (Perl Universal Daemon) is meant to handle all file-system-related operations even on the local file system. The advantage of doing so is that both databases and all directories are owned by the same user
(daemon is started by the same user who starts AMS).
If the daemon is turned off, a user who runs the application becomes the owner of a directory created by that application. When application creates a new directory:
- The group permission bit of this directory is set to writable.
- Application will try to change group to "bfactory".
However in some cases changing group can fail, because on some systems only authorized users are allowed to perform this operation (that is the reason why errors returned by chgrp are ignored in the application).
This could result in problems with writing to this directory by other users, including daemon owner.
That is the case at SLAC where chgrp fails while run on a directory in AFS space. In this case it is acl that really matters; if the directory is created with the correct acl there should be no problems, but there
is no guarantee that in some systems disabling daemon will not cause similar clashes.
Return to Table of Contents.
Note that these features are not available in release 6.5.0, they will become a part of the next release, now they are available on the head of CVS. It is a subject to change.
There are three database parameters, which can be configured while setting up the system:
- number of containers per one database
- size of one container
- number of databases per one directory
The first two numbers determine the size of a database. The last one says, when the new directory should be created (in order to avoid having thousands of databases in one directory).
Listed parameters can be configured "per domain", "per authorization level" and "per component" independently. It basically means, that components writen by the user running in "Conditions" domain under "system"
rights have their own setting independent on the setting of the same component writen by user under other authorization rights or on the setting of other component.
The configuration is done in the same way as FS-related configuration, using the same configuration file and the same loading tool. Note, that the part of the configuration file beeing described in this chapter is
independent on the part descibed in previous chapter. In particular that means, that it will not turn the daemon, if "FileSystem", "CatalogFS" and "FS-Group" identifiers are unavailable.
Data format after the identifier "MaxContNr", "MaxContSize", or "NrDbInDir"
domainName authLevel relaUserName component value
The first three fields are interpreted as described for "FS-Group" identified (see Data format after the identifier "FS-Group")
The last field "value" is interpreted as unsigned long (kept persistently as d_ULong). MaxContSize is a number of KB, thus the number of 1000 is interpreted as 1 MB.
Example:
MaxContNr: * * * * 12
MaxContNr: events system becla *15
MaxContSize: events system quarrie * 250000
NrDbInDir: events system becla * 15
If not all combinations of mapping are defined, the not-defined spots will get the default values, which are defined as:
- 10 containers per database
- 200 MB - size of a container (database size 2 GB)
- 256 databases in one directory.
It means, that if only one or two cases need to be "adjusted", one or two lines in the config file needs to be provided.
In order to access the BABAR database, the correct set of environment variables and search paths needs to be setup.
Environment variables that are necessary at software release build time are:
- BFARCH. This should be set to one of the supported database architectures. These are:
AIX4-native-Objy
OSF1V4-native-Objy
SunOS5-native-Objy
[This section incomplete.]
Return to Table of Contents.
[This section missing.]
Return to Table of Contents.
DB Home | BaBar Home | Computing | Online | Reconstruction |
Simulation | Search
|
