choose: sw hd | installObjy | setup: ams ls pud chs oids | confCH | maintain: ams ls pud chs oids | moveFD | creaBri
	Search | Site Map .

How do I configure placement?

• What can be configured?
• What are the defaults?
• When is reconfiguration needed?
• How do I reconfigure placement?
• What is the format of the configuration file?
• How do I change where databases are stored?
• How do I change database parameters?
• What distribution algorithms are supported?
• componentSpecInfo
• Examples
• Glossary

What can be configured?

The following clustering and placement parameters are configurable:

• Location where new database files are placed:
  • hosts
  • base path, directory
• How new database files are created:
  • Number of containers
  • Initial number of pages per container
  • Type of containers (hashed/non-hashed)
• How databases grow
  • Percentage growth of a container
• When databases become full
  • Max size of a database / container

All these parameters are federation-specific.

What are the defaults?

The default values and behaviors are predefined in Bdb C++ code:

• Databases are placed on a catalog server
• Base directory is the directory where the federated database file resides
• Number of database files per directory is 256
• Maximum database size is 2 GB
• Maximum container size is 2 MB
• Number of containers per database is 1000
• Initial number of pages - depends on component. Usually 10
• Container hashing - depends on component. Turned off for event store
• Hard container limit is 32500
• Minimum number of precreated databases is 0
• Maximum number of precreated databases is 0
• Number of precreated containers per database is 0

When is reconfiguration needed?

You would need to reconfigure the placement when:

• More than one file system will be used to store data
• A database parameter different that the default is needed. For instance:
  • Some database should be smaller than 2 GB in size
  • Number of database files per directory should be different that 256
• The clustering hint server will be used to manage placement and clustering

How do I reconfigure placement?

To configure (for the first time) or reconfigure (change existing settings):

• Prepare an ASCII file using a format as described below
• Load it using BdbFileConfigLoader

What is the format of the configuration file?

Format of a line:

<Identifier>:[separators] <data>

Format of the data after the identifier depends on the identifier. Each line is interpreted independently.

Here are some notes and restrictions:

• All lines starting with the identifier FileSystem must appear before all others.
• Total length of data in one line cannot exceed 256 characters.
• Duplicated lines are detected and discarded.
• Valid separators are: space or tabulator.
• All empty lines are ignored (an empty line is also a line with separators).
• Comment lines can be included. Such lines should start with #:
• Two versions are currently supported:
  • Version 1 (default); used with federations where the clustering hint server is not used (placement is managed by client code)
  • Version 2; used exclusively with federations where the clustering hint server manages placement

To indicate the version, add the line:

Version: <x>

Where <x> is either 1 or 2. The line with version information should be the very first one (excluding comments).

How do I change where databases are stored?

To override the default placement of new databases (catalog file system), you need to know how to use three identifiers: Catalog-FS, FileSystem, and FS-Group.

Catalog-FS

Catalog-FS: <portNr> <minDiskSpace>

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 obtained from the bootfile. The interpretation the both the portNr and minDiskSpace fields is the same as for FileSystem identifier.

FileSystem

FileSystem: <hostName> <baseDirName> <portNr> <minDiskSpace> <groupName>

hostName is the full name of the host.
baseDirName is the full path of the base directory where the database files are stored. A whole directory structure is created automatically in that directory (one directory with many subdirectories per each domain).

portNr is interpreted as a decimal number (pud daemon must be started on the port as specified here).

minDiskSpace is interpreted as a decimal number and is stored persistently as d_ULong. The specified number is treated as number of KB (1000 = 1 MB). When available space on the file system is below minDiskSpace, the file system is treated as full. Always allow some space for existing databases that were already created to expand to their max size.

FS-Group

FS-Group: <componentSpecificInfo> <groupName>

The specified groupName must appear at least once after FileSystem identifier (mapping cannot be performed on an empty group).

The group name must end with R (round robin database distribution) or S (sequential database distribution). See Distribution of databases across file systems for more information.

If not all combinations of mapping are defined, the not-defined spots are assigned to the catalog FS.

Example:

CatalogFS: 3333 30000
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-S
FS-Group: * system * * FASTS
FS-Group: * user rec becla SLOWS

All databases other than "rec" for user "becla" will be placed on catalog file system.

How do I change database parameters?

Depending whether placement is managed by a client code (Version 1) or the clustering hint server (Version 2), two different sets of identifiers are supported as indicated below.

Supported by both Version 1 and 2

ContHashing

ContHashing: <componentSpecificInfo> <contHashing>

contHashing is interpreted as a boolean: 0 - hashing turned off, 1 - hashing turned on. Default depends on component. It is supported by both Version 1 and 2.

CPercGrowth

CPercGrowth: <componentSpecificInfo> <cPercGrowth>

cPercGrowth is interpreted as a decimal number. It must be between 1 and 100. It specifies container percentage growth. Default is 10%. Is supported by both Version 1 and 2.

DirRange

DirRange: <componentSpecificInfo> <dirRange>

dirRange is interpreted as a decimal number. It specifies number of database files per one directory. Default is 256. It is supported by both Version 1 and 2.

InitNrPages

InitNrPages: <componentSpecificInfo> <initNrPages>

initNrPages is interpreted as a decimal number. It specifies the initial number of pages (1 page = 16 KB) to be created in each new container. The default depends on component, but it is usually around 10 pages. It is supported by both Version 1 and 2.

Important: ensure that initNrPages does not force creation of containers that are already full. Example: if MaxContSize (Version 1) or PrefContSize(Version 2) = 1250 KB, a full container will consist of 79 pages (1250 KB / 16 KB = 78.1). InitNrPage cannot be larger than 77.

Supported only by Version 1

MaxContNr

MaxContNr: <componentSpecificInfo> <maxContNr>

maxContNr is interpreted as a decimal number. It specifies the preferred maximum number of containers in a database. Default is 1000. It is supported only by Version 1.

MaxContSize

MaxContSize: <componentSpecificInfo> <maxContSize>

maxContSize is interpreted as a decimal number. It specifies the preferred maximum size of a container. The number is in KB. Default is 2 MB. It is supported only by Version 1.

Supported only by Version 2

HardContLimit

HardContLimit: <componentSpecificInfo> hardContLimit>

hardContLimit is interpreted as a decimal number. It specifies the absolute max number of containers that can be created in a database. It is supported only by Version 2.

MaxDbSize

MaxDbSize: <componentSpecificInfo> <maxNoPrecrDbs>

maxNoPrecrDbs is interpreted as a decimal number. It specifies the preferred maximum size of a database file. The number is in KB. Default is 2 GB. It is supported only by Version 2.

MaxNoPrecrDbs

MaxNoPrecrDbs: <componentSpecificInfo> <maxNoPrecrDbs>

maxNoPrecrDbs is interpreted as a decimal number. It specifies the maximum number of empty (precreated) databases that can effectively be maintained at any time by the clustering hint server. Default is 0. It is supported only by Version 2.

MinNoPrecrDbs

MinNoPrecrDbs: <componentSpecificInfo> <minNoPrecrDbs>

minNoPrecrDbs is interpreted as a decimal number. It specifies the minimum number of empty (precreated) databases that can effectively be maintained at any time by the clustering hint server. Default is 0. It is supported only by Version 2.

PrecrContSize

PrecrContSize: <componentSpecificInfo> <precrContSize>

precrContSize is interpreted as a decimal number. It is treated as number of pages; one page = 16 KB. It specifies the size of a new container. Default is 0. It is supported only by Version 2.

PrefContSize

PrefContSize: <componentSpecificInfo> <prefContSize>

precrContSize is interpreted as a decimal number. It specifies the preferred size of a new container in KB. Default is 2000 (2 MB). It is supported only by Version 2.

What distribution algorithms are supported?

Two algorithms are currently supported: round robin and sequential.

How does round robin distribution work? Each next new database from a group is placed in the next file system. Example:

FileSystem: objyserv1.slac.stanford.edu /nfs/objyserv1/u1/databases/ 3333 20000 fs-S
FileSystem: objyserv2.slac.stanford.edu /nfs/objyserv1/u1/databases/ 3333 20000 fs-S
FileSystem: objyserv3.slac.stanford.edu /nfs/objyserv1/u1/databases/ 3333 20000 fs-S

FS-Group: * user rec becla SLOWS
FS-Group: * user rec becla SLOWS

Say we want to create databases raw1, rec1, raw2, raw3, raw4, rec2, rec3, raw5. Here is how these databases are placed:

raw1 -> objyserv1
rec1 -> objyserv2
raw2 -> objyserv3
raw3 -> objyserv1
raw4 -> objyserv2
rec2 -> objyserv3
rec3 -> objyserv1
raw5 -> objyserv2

This algorithm is supported only in Version 2.

Sequential database distribution means that all databases are placed on the same file system until it is full, then the next file system is used, and so on. Here is how the databases from the previous example would be placed:

raw1 -> objyserv1
rec1 -> objyserv1
raw2 -> objyserv1
raw3 -> objyserv1 [say the disk has less than 20000KB free space now]
raw4 -> objyserv2
rec2 -> objyserv2
rec3 -> objyserv2
raw5 -> objyserv2

componentSpecificInfo

<componentSpecificInfo> denotes

<domainName> <authLevel> <realUserName> <component>

Valid domainName are: conditions, events, ambient, spatial, temporal, *, where * = all

Valid authLevel are: system, groups, user, *, where * = all

realUserName is simply a UNIX user name.

Component must be 3-character string containing only alphanumeric characters (0-9, a-z, AZ). It is important to use names that correspond to names used in the BaBar C++ software, otherwise the parameters specified here will be ignored. Examples of valid components: raw, rec, sim, aod, esd, tag, emc, ifr.
* = all components valid for specified domain

Examples

Here are two real examples taken from a production system at SLAC:

• example file config (no clustering hint server)
• example file config (clustering hint server used)

Glossary of the supported identifiers

• Catalog-FS (both)
• ContHashing (both)
• CPercGrowth (both)
• DirRange (both)
• FileSystem (both)
• FS-Group (both)
• HardContLimit (Version 2 only)
• InitNrPages (both)
• MaxContNr (Version 1 only)
• MaxContSize (Version 1 only)
• MaxDbSize (Version 2 only)
• MinNoPrecrDbs (Version 2 only)
• MaxNoPrecrDbs (Version 2 only)
• PrecrContSize (Version 2 only)
• PrefContSize (Version 2 only)
• Version (both)

 

---

BaBar Public Site | SLAC | News | Links | Who's Who | Contact Us

Page Owner: Jacek Becla
Last Update: August 13, 2002