NAME

An overview of the xCAT database.


DESCRIPTION

The xCAT database contains user settings for the cluster and information gathered from the cluster. It consists of a series of tables, which are described below. To get more information about a particular table, run man for that table name. The tables can be manipulated directly using the tabedit or chtab commands. They can be viewed using nodels or tabdump.

Alternatively, the xCAT database can be viewed and edited as logical objects, instead of flat tables. In this mode, xCAT takes care of which table each attribute should go in. To treat the database as logical object definitions, use the commands: lsdef, mkdef, chdef, rmdef. See Object Definitions below.

xCAT allows the use of different database applications, depending on the needs of your cluster. The default database is SQLite, which is a daemonless, zero-config database. But you could instead choose to use something like postgresql for greater scalability and remote access in the hierarchical/service node case. To use a different database or a different location, create the file /etc/xcat/cfgloc. See the appropriate xCAT docuementation for the format of the file for the database you choose. The following example is for PostgreSQL:

Pg:dbname=xcat;host=<mgmtnode>|<pgadminuserid>|<pgadminpasswd>

where mgmtnode is the hostname of the management node adapter on the cluster side, and the pgadminuserid and pgadminpasswd are the database admin and password.

The xCAT database spans a number of tables, some with records associated with particular nodes (such as nodelist and nodehm) and others that do not have a direct relationship with any given node. The tables not associated with a given node are straightforward, the data is stored and retrieved as-is from the database without interpretation, and without any generic inheritance (though some calling code may implement inheritance for specific fields, for example nodehm.power inheriting from nodehm.mgt).

The tables with records typically retrieved by node name have some extra features to enable a more template-based style to be used:

Any group name can be used in lieu of a node name in the node field, and that record will then be taken to be applicable to any node in that group. If a field is requested for a specific node, and either a record doesn't exist specifically for that nodename or a record exists, but has no definition for the requested field, that node's groups are then used to search for records. If multiple records could apply from two different groups, the precedence is the order the groups are specified in the nodelist table for that node. This is nearly identical to most xCAT 1.x tab file conventions. This is useful in tables such as noderes, where typical configurations have exactly the same field values for large sets of nodes.

xCAT 2 extends the above to be made useful where a field will vary for every node with a given tag, but in ways that would be trivial to describe. If a field is of the format /pattern/replacement/, it is taken to be a perl regular expression, to be performed on the nodename. For example, the bmc field of the ipmi table might be /\z/-bmc/ for a record with node=ipmi to specify that the BMC hostname is derived by appending -bmc to the end of the nodename of every node in the ipmi group.

As an extension to the above, a regular expression extended with arithmetic operators is available, by using the format |pattern|replacement|. This behaves similarly to the above, but () enclosed parts in replacement are taken to signify arithmetic operations and substituted in. All operations are integer arithmetic, so 5/4 would come out as 1. The typical perl positional variables are available in such expressions.

For example, if you have many blades in your cluster and their hostnames have a regular pattern of blade1, blade2, etc., and your BladeCenter management modules also have a hostname pattern of amm1, amm2, etc., then your mp table could be expressed by the following single row:

  "blade","|\D+(\d+)|amm(($1-1)/14+1)|","|\D+(\d+)|(($1-1)%14+1)|",,

Before you panic, let me explain each column:

blade

This is a group name. In this example, we are assuming that all of your blades belong to this group. Each time the xCAT software accesses the mp table to get the management module and slot number of a specific blade (e.g. blade20), this row will match (because blade20 is in the blade group). Once this row is matched for blade20, then the processing described in the following items will take place.

|\D+(\d+)|amm(($1-1)/14+1)|

This is a perl substitution pattern that will produce the value for the second column of the table (the management module hostname). The text \D+(\d+) between the 1st two vertical bars is a regular expression that matches the node name that was searched for in this table (in this example blade20). The text that matches within the 1st set of parentheses is set to $1. (If there was a 2nd set of parentheses, it would be set to $2, and so on.) In our case, the \D+ matches the non-numeric part of the name (blade) and the \d+ matches the numeric part (20). So $1 is set to 20. The text amm(($1-1)/14+1) between the 2nd and 3rd vertical bars produces the string that should be used as the value for this column in a hypothetical row for blade20. Since $1 is set to 20, the expression ($1-1)/14+1 equals 19/14 + 1, which equals 2. Therefore the whole string is amm2, which will be used as the hostname of the management module.

|\D+(\d+)|(($1-1)%14+1)|

This item is similar to the one above. This substituion pattern will produce the value for the 3rd column (the BladeCenter chassis slot number for this blade). Because this row was the match for blade20, the parentheses within the 1st set of vertical bars will set $1 to 20. Since % means modulo division, the expression ($1-1)%14+1 will evaluate to 6.

See http://www.perl.com/doc/manual/html/pod/perlre.html for information on perl regular expressions.


OBJECT DEFINITIONS

Because it can get confusing what attributes need to go in what tables, the xCAT database can also be viewed and edited as logical objects, instead of flat tables. Use mkdef, chdef, lsdef, and rmdef to create, change, list, and delete objects. When using these commands, the object attributes will be stored in the same tables, as if you edited the tables by hand. The only difference is that the object commands take care of knowing which tables all of the information should go in.

To run man for any of the object definitions below, use section 7. For example: man 7 node

The object types are:

auditlog(7)
boottarget(7)
eventlog(7)
firmware(7)
group(7)
monitoring(7)
network(7)
node(7)
notification(7)
osimage(7)
policy(7)
route(7)
site(7)


TABLES

To manipulate the tables directly, use nodels(1), chtab(8), tabdump(8), tabedit(8), nodeadd(8), nodech(1).

To run man for any of the table descriptions below, use section 5. For example: man 5 nodehm

The tables are:

auditlog(5)
 Audit Data log.
bootparams(5)

Current boot settings to be sent to systems attempting network boot for deployment, stateless, or other reasons. Mostly automatically manipulated by xCAT.

boottarget(5)

Specify non-standard initrd, kernel, and parameters that should be used for a given profile.

chain(5)

Controls what operations are done (and it what order) when a node is discovered and deployed.

deps(5)

Describes dependencies some nodes have on others. This can be used, e.g., by rpower -d to power nodes on or off in the correct order.

domain(5)

Mapping of nodes to domain attributes

eventlog(5)

Stores the events occurred.

firmware(5)

Maps node to firmware values to be used for setup at node discovery or later

hosts(5)

IP address and hostnames of nodes. This info can be used to populate /etc/hosts or DNS.

hypervisor(5)

Hypervisor parameters

ipmi(5)

Settings for nodes that are controlled by an on-board BMC via IPMI.

iscsi(5)

Contains settings that control how to boot a node from an iSCSI target

kvm_masterdata(5)

Persistant store for KVM plugin for masters

kvm_nodedata(5)

Persistant store for KVM plugin, not intended for manual modification.

linuximage(5)

Information about a Linux operating system image that can be used to deploy cluster nodes.

litefile(5)

The litefile table specifies the directories and files on the statelite nodes that should be readwrite, persistent, or readonly overlay. All other files in the statelite nodes come from the readonly statelite image.

litetree(5)

Directory hierarchy to traverse to get the initial contents of node files. The files that are specified in the litefile table are searched for in the directories specified in this table.

mac(5)

The MAC address of the node's install adapter. Normally this table is populated by getmacs or node discovery, but you can also add entries to it manually.

monitoring(5)

Controls what external monitoring tools xCAT sets up and uses. Entries should be added and removed from this table using the provided xCAT commands monstart and monstop.

monsetting(5)

Specifies the monitoring plug-in specific settings. These settings will be used by the monitoring plug-in to customize the behavior such as event filter, sample interval, responses etc. Entries should be added, removed or modified by chtab command. Entries can also be added or modified by the monstart command when a monitoring plug-in is brought up.

mp(5)

Contains the hardware control info specific to blades. This table also refers to the mpa table, which contains info about each Management Module.

mpa(5)

Contains info about each Management Module and how to access it.

networks(5)

Describes the networks in the cluster and info necessary to set up nodes on that network.

nimimage(5)

All the info that specifies a particular AIX operating system image that can be used to deploy AIX nodes.

nodegroup(5)

Contains group definitions, whose membership is dynamic depending on characteristics of the node.

nodehm(5)

Settings that control how each node's hardware is managed. Typically, an additional table that is specific to the hardware type of the node contains additional info. E.g. the ipmi, mp, and ppc tables.

nodelist(5)

The list of all the nodes in the cluster, including each node's current status and what groups it is in.

nodepos(5)

Contains info about the physical location of each node. Currently, this info is not used by xCAT, and therefore can be in whatevery format you want. It will likely be used in xCAT in the future.

noderes(5)

Resources and settings to use when installing nodes.

nodetype(5)

A few hardware and software characteristics of the nodes.

notification(5)

Contains registrations to be notified when a table in the xCAT database changes. Users can add entries to have additional software notified of changes. Add and remove entries using the provided xCAT commands regnotif and unregnotif.

osimage(5)

Basic information about an operating system image that can be used to deploy cluster nodes.

passwd(5)

Contains default userids and passwords for xCAT to access cluster components. In most cases, xCAT will also actually set the userid/password in the relevant component when it is being configured or installed. Userids/passwords for specific cluster components can be overidden in other tables, e.g. mpa, ipmi, ppchcp, etc.

performance(5)

Describes the system performance every interval unit of time.

policy(5)

The policy table in the xCAT database controls who has authority to run specific xCAT operations. It is basically the Access Control List (ACL) for xCAT.

postscripts(5)
 The scripts that should be run on each node after installation or diskless boot.
ppc(5)

List of system p hardware: HMCs, IVMs, FSPs, BPCs, CECs, Frames.

ppcdirect(5)

Info necessary to use FSPs/BPAs to control system p CECs/Frames.

ppchcp(5)

Info necessary to use HMCs and IVMs as hardware control points for LPARs.

prescripts(5)

The scripts that will be run at the beginning and the end of the nodeset(Linux), nimnodeset(AIX) or mkdsklsnode(AIX) command.

prodkey(5)

Specify product keys for products that require them

routes(5)

Describes the additional routes needed to be setup in the os routing table. These routes usually are used to connect the management node to the compute node using the servie node as gateway.

servicenode(5)

List of all Service Nodes and services that will be set up on the Service Node.

site(5)

Global settings for the whole cluster. This table is different from the other tables in that each attribute is just named in the key column, rather than having a separate column for each attribute. The following is a list of the attributes currently used by xCAT.

statelite(5)

The location on an NFS server where a nodes persistent files are stored. Any file marked persistent in the litefile table will be stored in the location specified in this table for that node.

switch(5)

Contains what switch port numbers each node is connected to.

switches(5)

Parameters to use when interrogating switches

vm(5)

Virtualization parameters

vmmaster(5)

Inventory of virtualization images for use with clonevm. Manual intervention in this table is not intended.

vpd(5)

The Machine type, Model, and Serial numbers of each node.

websrv(5)

Web service parameters

zvm(5)

List of z/VM virtual servers.


SEE ALSO

nodels(1), chtab(8), tabdump(8), tabedit(8), lsdef(1), mkdef(1), chdef(1), rmdef(1)