From 5f1971d0b70d65c85d11f98097e6129ed9d4b857 Mon Sep 17 00:00:00 2001 From: bp-sawyers Date: Wed, 5 Mar 2008 16:49:19 +0000 Subject: [PATCH] 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 --- perl-xCAT-2.0/db2man | 100 ++++++++++++++++++- xCAT-client-2.0/pods/man1/gettab.1.pod | 70 +++++++++++++ xCAT-client-2.0/pods/man1/nodels.1.pod | 98 ++++++++++++------ xCAT-client-2.0/pods/man1/tabdump.1.pod | 66 ++++++++---- xCAT-client-2.0/pods/man1/tabedit.1.pod | 72 +++++++++++++ xCAT-client-2.0/pods/man1/tabgrep.1.pod | 69 +++++++++++++ xCAT-client-2.0/pods/man1/tabrestore.1.pod | 42 ++++++-- xCAT-client-2.0/sbin/tabedit | 30 ++++-- xCAT-server-2.0/lib/xcat/plugins/tabutils.pm | 33 +++++- 9 files changed, 510 insertions(+), 70 deletions(-) create mode 100644 xCAT-client-2.0/pods/man1/gettab.1.pod create mode 100644 xCAT-client-2.0/pods/man1/tabedit.1.pod create mode 100644 xCAT-client-2.0/pods/man1/tabgrep.1.pod diff --git a/perl-xCAT-2.0/db2man b/perl-xCAT-2.0/db2man index effddd106..b14b51ea6 100755 --- a/perl-xCAT-2.0/db2man +++ b/perl-xCAT-2.0/db2man @@ -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 or B commands. They can be viewed using B or B. + +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 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 + +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 table to get the management module and slot number +of a specific blade (e.g. B), this row will match (because B is in the B group). +Once this row is matched for B, 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). 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) and the \d+ matches the numeric part (B<20>). So $1 is set to B<20>. The text B 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, 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, 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 to see the list of +objects supported by xCAT. Use B, B, and B 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 diff --git a/xCAT-client-2.0/pods/man1/gettab.1.pod b/xCAT-client-2.0/pods/man1/gettab.1.pod new file mode 100644 index 000000000..7a63404e1 --- /dev/null +++ b/xCAT-client-2.0/pods/man1/gettab.1.pod @@ -0,0 +1,70 @@ +=head1 NAME + +B - search through tables using keys and return attributes. + +=head1 SYNOPSIS + +B I + +B [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 set to B in the nodehm table: + +B I + +The output would be similar to: + nodehm.node: blades + +=item * + +To display setting for B (management node) in the site table: + +B I + +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) \ No newline at end of file diff --git a/xCAT-client-2.0/pods/man1/nodels.1.pod b/xCAT-client-2.0/pods/man1/nodels.1.pod index 6c71a4e6b..b01d29c7e 100644 --- a/xCAT-client-2.0/pods/man1/nodels.1.pod +++ b/xCAT-client-2.0/pods/man1/nodels.1.pod @@ -4,11 +4,11 @@ B - lists the nodes in the noderange. =head1 SYNOPSIS -I +B [I] [I | I] I<...> -I +B [B<-?> | B<-h> | B<--help>] -I +B [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 . A few shortcut names can also be used as aliases to common attributes: -=over 4 +=over 10 -=item I - nodelist.groups +=item I -=item I - nodelist.groups +nodelist.groups -=item I - nodehm.mgt +=item I -=item I - switch.switch +nodelist.groups + +=item I + +nodehm.mgt + +=item I + +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 +=item * + +To list all defined nodes, enter: + +B Output is similar to: node1 node2 node3 -2. To list nodes in noderange ppc, enter: +=item * -I +To list nodes in node group ppc, enter: + +B I Output is similar to: ppcnode1 ppcnode2 ppcnode3 -3. To list the groups each node is part of: +=item * -I +To list the groups each node is part of: + +B I I 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 +To list the groups each node is part of: + +B I I 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 I I + +Output is similar to: + blade1: nodehm.mgt: blade + +=back =head1 FILES /opt/xcat/bin/nodels - =head1 SEE ALSO -The B man page. - - -=head1 NOTES - -This command is part of the xCAT software product. - - +noderange(5) diff --git a/xCAT-client-2.0/pods/man1/tabdump.1.pod b/xCAT-client-2.0/pods/man1/tabdump.1.pod index 4e0cb9de2..1cc498a33 100644 --- a/xCAT-client-2.0/pods/man1/tabdump.1.pod +++ b/xCAT-client-2.0/pods/man1/tabdump.1.pod @@ -1,12 +1,12 @@ =head1 NAME -B - display a database table in CSV format. +B - display an xCAT database table in CSV format. =head1 SYNOPSIS -I +B [I<-d>] [I] -I +B [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 I -3. To back up all the xCAT database tables: +=item * + +To see what tables exist in the xCAT database: + + B + +=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 I<-d> - tabdump -d nodehm +=item * + +To display a description of each column in the nodehm table: + + B I<-d nodehm> + +=back =head1 FILES /opt/xcat/sbin/tabdump -=head1 NOTES +=head1 SEE ALSO -This command is part of the xCAT software product. \ No newline at end of file +tabrestore(1), tabedit(1) \ No newline at end of file diff --git a/xCAT-client-2.0/pods/man1/tabedit.1.pod b/xCAT-client-2.0/pods/man1/tabedit.1.pod new file mode 100644 index 000000000..7430899f8 --- /dev/null +++ b/xCAT-client-2.0/pods/man1/tabedit.1.pod @@ -0,0 +1,72 @@ +=head1 NAME + +B - view an xCAT database table in an editor and make changes. + +=head1 SYNOPSIS + +B [I
] + +B [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 is not set, the value from B will be used. If B 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 I + +=back + +=head1 FILES + +/opt/xcat/sbin/tabedit + +=head1 SEE ALSO + +tabrestore(1), tabdump(1), chtab(1) \ No newline at end of file diff --git a/xCAT-client-2.0/pods/man1/tabgrep.1.pod b/xCAT-client-2.0/pods/man1/tabgrep.1.pod new file mode 100644 index 000000000..e61ba81f5 --- /dev/null +++ b/xCAT-client-2.0/pods/man1/tabgrep.1.pod @@ -0,0 +1,69 @@ +=head1 NAME + +B - list table names in which an entry for the given node appears. + +=head1 SYNOPSIS + +B I + +B [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 I + +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) \ No newline at end of file diff --git a/xCAT-client-2.0/pods/man1/tabrestore.1.pod b/xCAT-client-2.0/pods/man1/tabrestore.1.pod index f8876938c..040435a22 100644 --- a/xCAT-client-2.0/pods/man1/tabrestore.1.pod +++ b/xCAT-client-2.0/pods/man1/tabrestore.1.pod @@ -4,9 +4,9 @@ B - replaces the contents of an xCAT database table with the content =head1 SYNOPSIS -I +B I -I +B [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 I 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. \ No newline at end of file +tabdump(1), tabedit(1) \ No newline at end of file diff --git a/xCAT-client-2.0/sbin/tabedit b/xCAT-client-2.0/sbin/tabedit index 36c9d3004..48c4e73b4 100755 --- a/xCAT-client-2.0/sbin/tabedit +++ b/xCAT-client-2.0/sbin/tabedit @@ -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 "; + 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" diff --git a/xCAT-server-2.0/lib/xcat/plugins/tabutils.pm b/xCAT-server-2.0/lib/xcat/plugins/tabutils.pm index 23dc4b1d8..cea5efe33 100644 --- a/xCAT-server-2.0/lib/xcat/plugins/tabutils.pm +++ b/xCAT-server-2.0/lib/xcat/plugins/tabutils.pm @@ -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]= " ";