.\" Process this file with
.\" groff -man -Tascii noderange.3
.\"
.TH NODERANGE 3 "JUNE 2002" xCAT "xCAT"
.SH NAME
noderange \- generate a list of node names
.SH SYNOPSIS
.B noderange
[\fIcomma delimited nodelists and grouplists\fR]
.br

.I e.g.
.br

node1,node2,node8,node20,group1
.br

node14-node56,node70-node203,group1-group10
.br

node1,node2,node8,node20,node14-node56,node70-node203
.br

all,-node129-node256,-frame01-frame03
.br

@node.*
.br

^/tmp/nodes
.br

node10+5
.br

10-15,-13
.br

.br
.SH DESCRIPTION
.B noderange
is a function 
that a single
operation may be applied to a range of nodes often in parallel.

.B noderange
lists can be an individual node and/or group:

.I node01
.br
.I group1
.br

a range of nodes and/or groups:

.I node01-node10
.br
.I group1-group3
.br

a regular expression match of nodes and/or groups:

.I @node[345].*
.br
.I @group[12].*
.br

an incremented range of nodes:

.I node10+5
.br

a file containing noderanges of nodes and/or groups:

.I ^/tmp/nodelist
.br

a node shorthand range of nodes:

.I 10-20
.br
.I 10+5
.br

or any combination:

.I node01-node30,node40,^/tmp/nodes,@node[13].*,2-10,node50+5
.br

Any individual
.B noderange
may be prefixed with an exclusion operator
(default -) with the exception of the file operator (default ^).

Any combination or multiple combinations of inclusive
and exclusive ranges of nodes and groups is legal.  There
is no precedence implied in the order of the
arguments.  Exclusive ranges have precedence over inclusive.

Nodes have precedence over groups.  If a node range match is made
then no group range match will be attempted.

All node names are validated against
the nodelist table.
Invalid nodes are ignored and return nothing.

All group names are validated against
the nodelist and nodetype table.
Invalid groups are ignored and return nothing.

Throughout this
man page the term
\fIxCAT Node Format\fR
will be used.

\fIxCAT Node Format\fR is defined by the following regex:

^([A-Za-z-]+)([0-9]+)(([A-Za-z-]+[A-Za-z0-9-]*)*)

In plain english a node or group is in
\fIxCAT Node Format\fR
if starting from the begining there are one or more
alpha characters of any case and any number of - in any
combination, followed by
one or more numbers, then optionally followed by one 
alpha character of any case or the - followed by any
combination of case mixed alphanumerics and the -.

.B noderange
supports node/group names in
.I any
format.
\fIxCAT Node Format\fR
is
.B not
required, however some node range
methods used to determine range will not be used.
E.g. If using a
.B noderange
of
.I node1a-node9a
with a
.BR nodelist.tab (5)
only listing
.I node1a
through
.IR node5a ,
.B noderange
will enumerate then validate and return a proper
range.  If using a node range of
.I aa-az
with
.BR nodelist.tab (5)
only listing
.I aa
through
.IR ay,
.B noderange
will fail to return any values.

Example
\fIxCAT Node Format\fR
node/group names:

.B nodename			prefix	number	suffix
.br
node1			node		1
.br
node001			node		001
.br
node-001			node-	001
.br
node-foo-001-bar	node-foo-	001		-bar
.br
node-foo-1bar		node-foo-	1		bar
.br
foo1bar2			foo		1		bar2
.br
rack01unit34		rack		01		unit34
.br
unit34rack01		unit		34		rack01
.br
pos0134			pos		0134
.br

Example non-\fIxCAT Node Format\fR
node/group names, but still valid:

aa
.br
yellow
.br
red
.br
12foo
.br


First
.B noderange
checks for the multiple range operator (default ,).  Each range is
also processed by
.BR noderange .

Next
.B noderange
checks for the file operator (default ^).  If the file exists
each line will be processed as a
.BR noderange .
Lines starting
with
.I #
or the file operator (default ^) are ignored.  Only
one
.B noderange
per line is read.  All characters are ignored
after the first white space.

e.g.

^/tmp/nodes

where

cat /tmp/nodes outputs:

#my node list (this line ignored)
.br
^/tmp/foo #ignored
.br
node01    #node comment
.br
node02
.br
node03
.br
node10-node20
.br
@group[456].*
.br
-node50
.br

Next
.B noderange
checks for the exclusion operator (default -) then continues.
This operator supports nodes and groups.
.B noderange
is smart and will not confuse the exclusion or range
operators with the
- character in names.

Next
.B noderange
checks for the for the regular expression operator (default @).
Regular expressions offer the most flexibility.  If you are
interested in learing regex read the book
\fIMastering Regular Expressions\fR.
This operator supports nodes and groups.

Next
.B noderange
checks for a numeric only range (e.g. 10-20, 5+3, or just 10), then uses
.I $XCAT_NODE_PREFIX
and
.I $XCAT_NODE_SUFFIX
(optional)
as the defaults to complete the node names.
.I $XCAT_NODE_PREFIX
must be defined to use noderange
shorthand.  If you use padded node names (e.g. node001, node002, etc...)
then you must specify
.I $XCAT_NODE_PADDING
or the default of
.I 1
will be used.  E.g. if you use node names node001, node002, etc..., then
.I $XCAT_NODE_PADDING
should be set to
.IR 3 .
Noderange shorthand supports nodes only.  Noderange shorthand can
be mixed with all other operators except regex.  i.e.  exclusion,
increment, range, and file may be used.

Next
.B noderange
checks for the increment range operator (default +).  Increment
range operator noderanges are in the format:

.IB valid_node_name + number_of_sequential_nodes

e.g.

.I node10+5

would yield node10 plus the next
.I 4
nodes.

This action is performed using two different methods.
If
.I valid_node_name
is in
\fIxCAT Node Format\fR
then the range is enumerated to one less than
.IR number_of_sequential_nodes .
If not in
\fIxCAT Node Format\fR
then a sorted
.BR nodelist.tab (5)
is used to return the node range.
This operator supports nodes only.

Next
.B noderange
checks for a single node name or group name.

Next
.B noderange
checks for the range operator (default -).  Ranges are
performed first by validating that both the start
and end nodes or groups defining the range exist and if
so the range is returned based on the content of
.BR nodelist.tab (5),
.BR nodetype.tab (5),
and
.BR nodemodel.tab (5).
If the start and end nodes or groups
defined in the range do not exist,
.I and
if both are in
\fIxCAT Node Format\fR,
.I and
if both the prefix and suffix match,
then the range is enumerated and each node/group
validated.  Only valid nodes/groups will be returned.
.B noderange
is smart and will not confuse the exclusion or range
operators with the
- character in names.

Last
.B noderange
returns nothing if no match can be found.

.B noderange
uses the smallest integer to determine
padding.  e.g.  \fInode1-node10\fR will generate a list of nodes
with numbers 1, 2, 3, 4, 5, 6, 7, 8, 9, 10.  \fInode001-node010\fR will
generate a list of nodes with numbers 001, 002, 003, 004,
005, 006, 007, 008, 009, 010.

Multiple instances of a node name are treated as one
instance.  e.g. \fInode1-node10,node4,node4,node4\fR will generate
a list of nodes numbered 1 through 10, the number 4
will only be listed once.

.SH EXAMPLES
.I all,-node5-node10

Generates a list of all nodes (assuming all is a group)
listed in
.BR nodelist.tab (5)
less node5 through node10.

.I node1-node10,-node3-node5,node4

Generates a list of nodes 1 through 10 less nodes 3,4,5.  Note
that node4 is listed twice, first in the range and then at
the end.  Because exclusion has precedence node4 will be excluded.

.I node1-node10,-node3,-node5

Generates a list of nodes 1 through 10 less nodes 3 and 5.

.I -node17-node32,all

Generates a list of all (assuming 'all' is a group) nodes in
.BR nodelist.tab (5)
less 17 through 32.

.I node1-node128,user1-user4

Generates a list of nodes 1 through 128, and user nodes 1 through 4.

.I all,-rack1-rack3,-node100-node200,node150,-storage

Generates a list of all nodes (assuming 'all' is a group), less
nodes in groups rack1 through rack3 (assuming groups rack1,
rack2, and rack3 are defined), less nodes 100 through
200, less nodes in the storage group.  Note that
node150 is listed but is excluded.

.I @node[23].*

Generates a list of nodes matching the regex
.IR node[23].* .
That is all nodes that start with node2 or node3 and end in anything
or nothing.  E.g. node2, node3, node20, node30, node21234 all match.

.SH "NOTES"
.IX Header "NOTES"
This command is part of the xCAT software product.