Added more man pages for the tab commands and fixed tabedit on AIX.

git-svn-id: https://svn.code.sf.net/p/xcat/code/xcat-core/trunk@681 8638fb3e-16cb-4fca-ae20-7b5d299a9bcd
This commit is contained in:
bp-sawyers 2008-03-05 16:49:19 +00:00
parent 848c7b6e8c
commit 5f1971d0b7
9 changed files with 510 additions and 70 deletions

View File

@ -11,12 +11,16 @@
use lib '.';
use xCAT::Schema;
use xCAT::Table;
my $poddir = 'pods/man5';
if (system("mkdir -p $poddir")) { die "Error: could not create $poddir.\n"; }
my $tabspecref = \%xCAT::Schema::tabspec;
# Build the DB overview page.
writesummarypage("$poddir/xcatdb.5.pod", xCAT::Table->getDescriptions()),
# Build the man page for each table.
my $tabspecref = \%xCAT::Schema::tabspec;
foreach my $tablekey (keys %$tabspecref) {
my $table = $tabspecref->{$tablekey};
my $summary = $table->{table_desc};
@ -28,6 +32,100 @@ foreach my $tablekey (keys %$tabspecref) {
exit;
# Create the xcatdb man page that gives a summary description of each table.
sub writesummarypage {
my $file = shift; # relative path file name of the man page
my $descriptions = shift; # a hash containing the description of each table
open(FILE, ">$file") or die "Error: could not open $file for writing.\n";
print FILE <<'EOS1';
=head1 NAME
An overview of the xCAT database.
=head1 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
B<tabedit> or B<chtab> commands. They can be viewed using B<nodels> or B<tabdump>.
xCAT also supports regular expressions in the tables. This enables one row to represent many
rows. 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 B<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:
=over 4
=item B<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 B<mp> table to get the management module and slot number
of a specific blade (e.g. B<blade20>), this row will match (because B<blade20> is in the B<blade> group).
Once this row is matched for B<blade20>, then the processing described in the following items will take
place.
=item B<|\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 B<\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 B<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
(B<blade>) and the \d+ matches the numeric part (B<20>). So $1 is set to B<20>. The text B<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 B<($1-1)/14+1> equals
19/14 + 1, which equals 2. Therefore the whole string is B<amm2>, which will be used as the hostname
of the management module.
=item B<|\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 B<blade20>, the parentheses
within the 1st set of vertical bars will set $1 to 20. Since % means modulo division, the
expression B<($1-1)%14+1> will evaluate to 6.
=back
See http://www.perl.com/doc/manual/html/pod/perlre.html for information on perl regular expressions.
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. Run B<lsdef> to see the list of
objects supported by xCAT. Use B<mkdef>, B<chdef>, and B<rmdef> to create, change, 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.
=head1 TABLES
=over 2
EOS1
foreach my $table (sort keys %$descriptions) {
print FILE "\n=item I<$table>\n\n".$descriptions->{$table}."\n";
}
print FILE <<"EOS3";
=back
=head1 SEE ALSO
nodels(1), tabedit(1), chtab(1), tabdump(1), lsdef(1), mkdef(1), chdef(1), rmdef(1)
EOS3
close FILE;
}
# Create the man page for one table.
sub writemanpage {
my $file = shift; # relative path file name of the man page

View File

@ -0,0 +1,70 @@
=head1 NAME
B<gettab> - search through tables using keys and return attributes.
=head1 SYNOPSIS
B<gettab> I<key=value,... table.attribute ...>
B<gettab> [B<-?> | B<-h> | B<--help>]
=head1 DESCRIPTION
The gettab command uses the specified key values to search the specified tables. For each matched
row, the specified attributes are displayed.
=head1 OPTIONS
=over 10
=item B<-?|-h|--help>
Display usage message.
=back
=head1 RETURN VALUE
=over 3
=item 0
The command completed successfully.
=item 1
An error has occurred.
=back
=head1 EXAMPLES
=over 2
=item *
To display node names that have B<mgt> set to B<blade> in the nodehm table:
B<gettab> I<mgt=blade nodehm.node>
The output would be similar to:
nodehm.node: blades
=item *
To display setting for B<master> (management node) in the site table:
B<gettab> I<key=master site.value>
The output would be similar to:
site.value: mgmtnode.cluster.com
=back
=head1 FILES
/opt/xcat/bin/gettab
=head1 SEE ALSO
nodels(1), chtab(1), tabdump(1)

View File

@ -4,11 +4,11 @@ B<nodels> - lists the nodes in the noderange.
=head1 SYNOPSIS
I<nodels noderange [table.attribute | shortname] ...>
B<nodels> [I<noderange>] [I<table.attribute> | I<shortname>] I<...>
I<nodels [-h| --help]>
B<nodels> [B<-?> | B<-h> | B<--help>]
I<nodels [-v| --version]>
B<nodels> [B<-v> | B<--version>]
=head1 DESCRIPTION
@ -19,83 +19,123 @@ Additional attributes of the nodes will also be displayed if the table names and
are specified after the noderange in the form: I<table.attribute> . A few shortcut names can
also be used as aliases to common attributes:
=over 4
=over 10
=item I<groups> - nodelist.groups
=item I<groups>
=item I<tags> - nodelist.groups
nodelist.groups
=item I<mgt> - nodehm.mgt
=item I<tags>
=item I<switch> - switch.switch
nodelist.groups
=item I<mgt>
nodehm.mgt
=item I<switch>
switch.switch
=back
The nodels command with a specific node and one or more table.attribute parameters is a good substitute
for grep'ing through the tab files, like was done in xCAT 1.x. This is because nodels will translate
any regular expression rows in the tables into their meaning for the specified node. The tab* commands
will not do this, instead they will just display the single regular expression row.
=head1 OPTIONS
B<-h> Display usage message.
=over 10
B<-v> Command Version.
=item B<-?|-h|--help>
Display usage message.
=item B<-v>
Command Version.
=back
=head1 RETURN VALUE
0 The command completed successfully.
=over 3
1 An error has occurred.
=item 0
The command completed successfully.
=item 1
An error has occurred.
=back
=head1 EXAMPLES
1. To list all defined nodes, enter:
=over 2
I<nodels>
=item *
To list all defined nodes, enter:
B<nodels>
Output is similar to:
node1
node2
node3
2. To list nodes in noderange ppc, enter:
=item *
I<nodels ppc>
To list nodes in node group ppc, enter:
B<nodels> I<ppc>
Output is similar to:
ppcnode1
ppcnode2
ppcnode3
3. To list the groups each node is part of:
=item *
I<nodels all groups>
To list the groups each node is part of:
B<nodels> I<all> I<groups>
Output is similar to:
node1: groups: all
node2: groups: all,storage
node3: groups: all,blade
4. To list the groups each node is part of:
=item *
I<nodels all nodehm.power>
To list the groups each node is part of:
B<nodels> I<all> I<nodehm.power>
Output is similar to:
node1: nodehm.power: blade
node2: nodehm.power: ipmi
node3: nodehm.power: ipmi
=item *
To list the out-of-band mgt method for blade1:
B<nodels> I<blade1> I<nodehm.mgt>
Output is similar to:
blade1: nodehm.mgt: blade
=back
=head1 FILES
/opt/xcat/bin/nodels
=head1 SEE ALSO
The B<noderange> man page.
=head1 NOTES
This command is part of the xCAT software product.
noderange(5)

View File

@ -1,12 +1,12 @@
=head1 NAME
B<tabdump> - display a database table in CSV format.
B<tabdump> - display an xCAT database table in CSV format.
=head1 SYNOPSIS
I<tabdump [-d] [table]>
B<tabdump> [I<-d>] [I<table>]
I<tabdump [? | -h | --help]>
B<tabdump> [I<-?> | I<-h> | I<--help>]
=head1 DESCRIPTION
@ -16,43 +16,73 @@ tables will be displayed.
=head1 OPTIONS
B<-?|-h|--help> Display usage message.
=over 10
B<-d> Show descriptions of the tables, instead of the contents of the tables. If a table name is also specified, descriptions of the columns (attributes) of the table will be displayed. Otherwise, a summary of each table will be displayed.
=item B<-?|-h|--help>
Display usage message.
=item B<-d>
Show descriptions of the tables, instead of the contents of the tables. If a table name is also specified, descriptions of the columns (attributes) of the table will be displayed. Otherwise, a summary of each table will be displayed.
=back
=head1 RETURN VALUE
0 The command completed successfully.
=over 3
1 An error has occurred.
=item 0
The command completed successfully.
=item 1
An error has occurred.
=back
=head1 EXAMPLES
1. To display the contents of the site table:
=over 2
tabdump site
=item *
2. To see what tables exist in the xCAT database:
To display the contents of the site table:
tabdump
B<tabdump> I<site>
3. To back up all the xCAT database tables:
=item *
To see what tables exist in the xCAT database:
B<tabdump>
=item *
To back up all the xCAT database tables:
mkdir -p /tmp/xcatdb.backup
for i in `tabdump`;do echo "Dumping $i..."; tabdump $i > /tmp/xcatdb.backup/$i.csv; done
4. To display a summary description of each table:
=item *
tabdump -d
To display a summary description of each table:
5. To display a description of each column in the nodehm table:
B<tabdump> I<-d>
tabdump -d nodehm
=item *
To display a description of each column in the nodehm table:
B<tabdump> I<-d nodehm>
=back
=head1 FILES
/opt/xcat/sbin/tabdump
=head1 NOTES
=head1 SEE ALSO
This command is part of the xCAT software product.
tabrestore(1), tabedit(1)

View File

@ -0,0 +1,72 @@
=head1 NAME
B<tabedit> - view an xCAT database table in an editor and make changes.
=head1 SYNOPSIS
B<tabedit> [I<table>]
B<tabedit> [I<-?> | I<-h> | I<--help>]
=head1 DESCRIPTION
The tabedit command opens the specified table in the user's editor, allows them to edit any
text, and then writes changes back to the database table. The table is flattened into a CSV
(comma separated values) format file before giving it to the editor. After the editor is
exited, the CSV file will be translated back into the database format.
=head1 OPTIONS
=over 10
=item B<-?|-h|--help>
Display usage message.
=back
=head1 ENVIRONMENT VARIABLES
=over 4
=item TABEDITOR
The editor that should be used to edit the table, for example: vi, vim, emacs, oocalc, pico, gnumeric, nano.
If B<TABEDITOR> is not set, the value from B<EDITOR> will be used. If B<EDITOR> is not set, it will
default to vi.
=back
=head1 RETURN VALUE
=over 3
=item 0
The command completed successfully.
=item 1
An error has occurred.
=back
=head1 EXAMPLES
=over 2
=item *
To edit the site table:
B<tabedit> I<site>
=back
=head1 FILES
/opt/xcat/sbin/tabedit
=head1 SEE ALSO
tabrestore(1), tabdump(1), chtab(1)

View File

@ -0,0 +1,69 @@
=head1 NAME
B<tabgrep> - list table names in which an entry for the given node appears.
=head1 SYNOPSIS
B<tabgrep> I<nodename>
B<tabgrep> [I<-?> | I<-h> | I<--help>]
=head1 DESCRIPTION
The tabgrep command displays the tables that contain a row for the specified node. Note that the
row can either have that nodename as the key or it could have a group that contains the node as
the key.
=head1 OPTIONS
=over 10
=item B<-?|-h|--help>
Display usage message.
=back
=head1 RETURN VALUE
=over 3
=item 0
The command completed successfully.
=item 1
An error has occurred.
=back
=head1 EXAMPLES
=over 2
=item *
To display the tables that contain blade1:
B<tabgrep> I<blade1>
The output would be similar to:
nodelist
nodehm
mp
chain
hosts
mac
noderes
nodetype
=back
=head1 FILES
/opt/xcat/bin/tabgrep
=head1 SEE ALSO
nodels(1), tabdump(1)

View File

@ -4,9 +4,9 @@ B<tabrestore> - replaces the contents of an xCAT database table with the content
=head1 SYNOPSIS
I<tabrestore table.csv>
B<tabrestore> I<table.csv>
I<tabrestore [? | -h | --help]>
B<tabrestore> [I<-?> | I<-h> | I<--help>]
=head1 DESCRIPTION
@ -20,34 +20,56 @@ into the xCAT database.
=head1 OPTIONS
B<-?|-h|--help> Display usage message.
=over 10
=item B<-?|-h|--help>
Display usage message.
=back
=head1 RETURN VALUE
0 The command completed successfully.
=over 3
1 An error has occurred.
=item 0
The command completed successfully.
=item 1
An error has occurred.
=back
=head1 EXAMPLES
1. To put rows into the mp table:
=over 2
tabrestore mp.csv
=item *
To put rows into the mp table:
B<tabrestore> I<mp.csv>
The file mp.csv could contain something like:
#node,mpa,id,comments,disable
"blade","|\D+(\d+)|amm(($1-1)/14+1)|","|\D+(\d+)|(($1-1)%14+1)|",,
2. To restore database tables that were dumped with tabdump:
=item *
To restore database tables that were dumped with tabdump:
cd /tmp/xcatdb.backup
for i in *.csv;do echo "Restoring $i..."; tabrestore $i; done
=back
=head1 FILES
/opt/xcat/sbin/tabrestore
=head1 NOTES
=head1 SEE ALSO
This command is part of the xCAT software product.
tabdump(1), tabedit(1)

View File

@ -1,5 +1,8 @@
#!/bin/sh
# IBM(c) 2007 EPL license http://www.eclipse.org/legal/epl-v10.html
# Opens the specified table in the users editor and writes changes back to the db
function cexit {
if [ -d /tmp/tabedit.$$ ]; then
rm -rf /tmp/tabedit.$$;
@ -16,25 +19,36 @@ if [ -z "$TABEDITOR" ]; then
#echo "WARNING: Define TABEDITOR or EDITOR environment variable before running this command"
TABEDITOR=vi
fi
if [ -z "$TABLE" ]; then
if [ -z "$TABLE" -o "$TABLE" = "-?" -o "$TABLE" = "-h" -o "$TABLE" = "--help" ]; then
echo "Usage: tabedit <tablename>";
echo " tabedit [-? | -h | --help]";
exit 1
fi
# Dump the table to a temporary file
mkdir -p /tmp/tabedit.$$/
xcatclientnnr tabdump $1 > /tmp/tabedit.$$/$1.csv
#use md5sum to check if it actually changes..
SUM=`md5sum /tmp/tabedit.$$/$1.csv`
xcatclientnnr tabdump $TABLE > /tmp/tabedit.$$/$TABLE.csv
# Save the checksum to see if it actually changes..
if [ `uname` = "AIX" ]; then
SUMPROGRAM=sum
else
SUMPROGRAM=md5sum
fi
SUM=`$SUMPROGRAM /tmp/tabedit.$$/$TABLE.csv`
# Edit the file, then check it
EXIT=0
while [ $EXIT -eq 0 ]; do
cd /tmp/tabedit.$$
"$TABEDITOR" $1.csv
cd -
NEWSUM=`md5sum /tmp/tabedit.$$/$1.csv`
"$TABEDITOR" $TABLE.csv
cd - >/dev/null
NEWSUM=`$SUMPROGRAM /tmp/tabedit.$$/$TABLE.csv`
if [ "$NEWSUM" == "$SUM" ]; then
echo "No file modifications detected, not restoring."
break;
fi
if `dirname $0`/tabrestore /tmp/tabedit.$$/$1.csv; then
if `dirname $0`/tabrestore /tmp/tabedit.$$/$TABLE.csv; then
break;
else
echo "Above errors occured, hit enter to edit, or ctrl-c to abort"

View File

@ -123,11 +123,31 @@ sub process_request
}
# Display particular attributes, using query strings.
sub gettab
{
my $req = shift;
my $callback = shift;
my $keyspec = shift @{$req->{arg}};
my $HELP;
sub gettab_usage {
my $exitcode = shift @_;
my %rsp;
push @{$rsp{data}}, "Usage: gettab key=value,... table.attribute ...";
push @{$rsp{data}}, " gettab [-?|-h|--help]";
if ($exitcode) { $rsp{errorcode} = $exitcode; }
$callback->(\%rsp);
}
# Process arguments
@ARGV = @{$req->{arg}};
if (!GetOptions('h|?|help' => \$HELP)) { gettab_usage(1); return; }
if ($HELP) { gettab_usage(0); return; }
if (scalar(@ARGV)<2) { gettab_usage(1); return; }
# Get all the key/value pairs into a hash
my $keyspec = shift @ARGV;
my @keypairs = split /,/, $keyspec;
my %keyhash;
foreach (@keypairs)
@ -135,19 +155,23 @@ sub gettab
(my $key, my $value) = split /=/, $_;
$keyhash{$key} = $value;
}
# Group the columns asked for by table (so we can do 1 query per table)
my %tabhash;
foreach my $tabvalue (@{$req->{arg}})
foreach my $tabvalue (@ARGV)
{
(my $table, my $column) = split /\./, $tabvalue;
$tabhash{$table}->{$column} = 1;
}
# Get the requested columns from each table
foreach my $tabn (keys %tabhash)
{
my $tab = xCAT::Table->new($tabn);
(my $ent) = $tab->getAttribs(\%keyhash, keys %{$tabhash{$tabn}});
foreach my $coln (keys %{$tabhash{$tabn}})
{
$callback->({data => ["$tabn.$coln:" . $ent->{$coln}]});
$callback->({data => ["$tabn.$coln: " . $ent->{$coln}]});
}
$tab->close;
}
@ -339,6 +363,7 @@ sub tabrestore
}
}
# Display a list of tables, or a specific table in CSV format
sub tabdump
{
my $args = shift;
@ -729,7 +754,7 @@ sub nodels
$rsp->{data}->[0] = "Usage:";
$rsp->{data}->[1] = " nodels [-?|-h|--help] ";
$rsp->{data}->[2] = " nodels [-v|--version] ";
$rsp->{data}->[3] = " nodels [noderange] ";
$rsp->{data}->[3] = " nodels [noderange] [table.attribute | shortname] ...";
##### xcat 1.2 nodels usage:
# $rsp->{data}->[1]= " nodels [noderange] [group|pos|type|rg|install|hm|all]";
# $rsp->{data}->[2]= " ";