genders/source/man/nodeattr.1

.\"############################################################################
.\"  $Id: nodeattr.1,v 1.24 2010-02-02 00:04:34 chu11 Exp $
.\"############################################################################
.\"  Copyright (C) 2007-2019 Lawrence Livermore National Security, LLC.
.\"  Copyright (C) 2001-2007 The Regents of the University of California.
.\"  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
.\"  Written by Jim Garlick <garlick@llnl.gov> and Albert Chu <chu11@llnl.gov>.
.\"  UCRL-CODE-2003-004.
.\"  
.\"  This file is part of Genders, a cluster configuration database.
.\"  For details, see <http://www.llnl.gov/linux/genders/>.
.\"  
.\"  Genders is free software; you can redistribute it and/or modify it under
.\"  the terms of the GNU General Public License as published by the Free
.\"  Software Foundation; either version 2 of the License, or (at your option)
.\"  any later version.
.\"  
.\"  Genders is distributed in the hope that it will be useful, but WITHOUT ANY
.\"  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
.\"  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
.\"  details.
.\"  
.\"  You should have received a copy of the GNU General Public License along
.\"  with Genders.  If not, see <http://www.gnu.org/licenses/>.
.\"############################################################################
.\"
.\" Author: Jim Garlick
.\" Adapted from IBM SP version for linux 4/00.
.\"
.TH NODEATTR 1 "August 2003" "LLNL" "NODEATTR"
.SH NAME
nodeattr \- query genders file
.SH SYNOPSIS
.B nodeattr
.I "[-f genders] [-q | -c | -n | -s] [-X exclude_query] query"
.br
.B nodeattr
.I "[-f genders] [-q | -c | -n | -s] -A"
.br
.B nodeattr
.I "[-f genders] [-v] [node] attr[=val]"
.br
.B nodeattr
.I "[-f genders] -Q [node] query"
.br
.B nodeattr
.I "[-f genders] -V [-U] attr"
.br
.B nodeattr
.I "[-f genders] -l [node]"
.br
.B nodeattr
.I "[-f genders] -k"
.br
.B nodeattr
.I "[-f genders] -d genders"
.br
.B nodeattr
.I "[-f genders] --expand"
.br
.B nodeattr
.I "[-f genders] --compress"
.br
.B nodeattr
.I "[-f genders] --compress-hosts"
.br
.SH DESCRIPTION
When invoked with the 
.I "-q"
,
.I "-c"
,
.I "-n"
, or 
.I "-s"
arguments,
.B nodeattr
reads the genders file and outputs a list of nodes that match the
specified query.  The nodes are listed in hostlist format, comma
separated lists, newline separated lists, or space separated lists
respectively.  The
.I "-q"
form is returned by default.  Genders queries will query the genders database for a set
of nodes based on the union, intersection, difference, or complement of genders
attributes and values.  The set operation union is represented by two pipe
symbols ('||'), intersection by two ampersand symbols ('&&'), difference by two
minus symbols ('--'), and
complement by a tilde ('~').  Parentheses may be used to change the order of
operations.
The 
.I "-X"
argument and query can be used to exclude nodes from the resulting
output.  A query can be replaced with the
.I "-A"
option to cause
.B nodeattr
to print all the nodes listed in the genders database.
.LP
When called with a node name (optional) and attribute name,
.B nodeattr
returns \fI0\fR to the environment if the node has the attribute; else
\fI1\fR.  If \fI-v\fR is present, the attribute name and any value
(see below) is printed on the standard output.  If a node name is not
specified, the local host is assumed.
.LP
When called with the
.I "-Q"
argument,
.B nodeattr
will check if the node name (optional) is met by the attribute and
value conditions specified in the query.  If the conditions are met,
.B nodeattr
returns \fI0\fR to the environment; else \fI1\fR.  The query format is
identical to the format listed above.  If a node name is not
specified, the local host is assumed.
.LP
The
.I "-V"
option causes
.B nodeattr
to print all of the values that exist for a particular attribute.
Also specifing
.I "-U"
with 
.I "-V"
causes 
.B nodeattr
to print out only unique values for the particular attribute.
.LP
The 
.I "-l"
option causes
.B nodeattr
to print all of the attributes of the specified node or list of nodes.  If no
node is listed, all attributes in the genders file are listed.
.LP
The
.I "-k"
option checks the genders file for parse errors and proper formatting.
If errors are found, information about the error will be output to
standard error.
.LP
.B Nodeattr 
will always check the default genders file, but a different genders
file can be specified with the
.I "-f"
option.  
.LP
The
.I "-d"
option allows the specified genders database to be compared to the
filename indicated by the
.I -f
option or the default genders database.  The differences contained in
the specified database will be output to standard error.
Attribute names may optionally appear in the genders file with an
equal sign followed by a value.
.B Nodeattr
ignores these values except when the 
.I -v 
option requests that the value, if any, be displayed; and when an
attribute is specified on the command line with a value, in which case
only an attribute with the specified value in the genders file will
match.
.LP
For 
.I "--expand"
.I "--compress"
.I "--compress-attrs"
.I "--compress-hosts"
see HOSTRANGE EXPANSION AND COMPRESSION below.
.LP
.SH HOSTRANGE EXPANSION AND COMPRESSION
The
.I "--expand"
option will take a genders database, expand all hostranges, and output
a new genders database.  The subsequent database will be identical to
the first, but every node will be listed on a separate line.  This
option may be useful for debugging or determining the difference
between databases.
.LP
The
.I "--compress"
option is the opposite of the
.I "--expand"
option.  It will output a new identical genders database with
hostranges of nodes with identical attributes.  Depending on the setup
of your genders database, the resulting database may be longer or
shorter.  This option may be useful as a beginning step to compressing
an existing genders database.
.LP
The
.I "--compress-hosts"
option is similar to the
.I "--compress"
option.  With
.I "--compress"
a given attr only appears once.  With
.I "--compress-hosts"
a given node only appears once. The
.I "--compress-hosts"
option combines attributes for each node first and then groups nodes
with identical attribute sets rather than creating a group of nodes for each
attribute and then merging common groups.  This is useful for identifying
"different" nodes.  For example:
.LP
for the genders file:
    cluster[1-20]       attr1,attr2
    cluster10           attr3
    cluster20           attr3
    cluster[2,5,10]     attr4
    cluster[7,20]       attr5
.LP
The
.B
nodeattr
--compress
command produces:
    cluster[2,5,10] attr4
    cluster[10,20]  attr3
    cluster[7,20]   attr5
    cluster[1-20]   attr1,attr2
.LP
Where
.B
nodeattr
--compress-hosts
produces:
    cluster[1,3-4,6,8-9,11-19] attr1,attr2
    cluster[2,5]               attr1,attr2,attr4
    cluster10                  attr1,attr2,attr3,attr4
    cluster20                  attr1,attr2,attr3,attr5
    cluster7                   attr1,attr2,attr5
.LP
In the
.I "--compress"
output, cluster7 appears in the third and fourth lines because it is a member of
ranges with attr1,attr2 and ranges with attr5.  In the
.I "--compress-hosts"
output, cluster7 appears on a new line because there are no other nodes with
the same combination of attributes.
.LP
The
.I "--compress-attrs"
option is identical to
.I "--compress"
\&.  It was added for consistency when
.I "--compress-hosts"
was added.
.SH EXAMPLES
.LP
Retrieve a comma separated list of all login nodes:
.IP
nodeattr -c login
.LP
Retrieve a hostlist formatted list of all login nodes:
.IP
nodeattr -q login
.LP
Retrieve a comma separated list of nodes with 4 cpus:
.IP
nodeattr -c cpus=4
.LP
Retrieve a comma separated list of all login and management nodes:
.IP
nodeattr -c "login||mgmt"
.LP
Retrieve a comma separated list of all login nodes with 4 cpus:
.IP
nodeattr -c "login&&cpus=4"
.LP
Retrieve a comma separated list of all nodes that are not login or management nodes:
.IP
nodeattr -c "~(login||mgmt)"
.LP
To use nodeattr with pdsh to run a command on all fddi nodes:
.IP
pdsh -w\`nodeattr -c fddi\` command
.LP
To use nodeattr in a ksh script to collect a list of users on login nodes:
.IP
for i in \`nodeattr -n login\`; do rsh $i who; done
.LP
To verify whether or not this node is a head node:
.IP
nodeattr head && echo yes
.LP
To verify whether or not this node is a head node and ntpserver:
.IP
nodeattr -Q "head&&ntpserver" && echo yes
.LP
.SH "FILES"
/etc/genders
.br
.SH "SEE ALSO"
libgenders(3)