.\" 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

node[14-56]
.br

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

/node.*
.br

^/tmp/nodes
.br

node10+5
.br

10-15,-13
.br

group1@group2
.br

.br
.SH DESCRIPTION
.B noderange
is a syntax that can be used in most xCAT commands to conveniently
specify a list of nodes.  The result is that the command will
be applied to a range of nodes, often in parallel.

.B noderange
is a comma-separate list.  Each token (text between commas) in the list can be any
of the forms listed below:

Individual node or group:

.I node01
.br
.I group1
.br

A range of nodes or groups:

.I node01-node10
(equivalent to: node01,node02,node03,...node10)
.br
.I group1-group3
(equivalent to: group1,group2,group3)
.br

A regular expression match of nodes or groups:

.I /node[345].*
(will match any nodes that start with node3, node4, or node5)
.br
.I /group[12].*
(will match any groups that start with group1 or group2)
.br

An incremented range of nodes:

.I node10+3
(equivalent to: node10,node11,node12,node13)
.br

The full path of a file containing noderanges of nodes or groups:

.I ^/tmp/nodelist
.br

A node shorthand range of nodes:

.I 10-20
(if prefix is 'node', equivalent to: node10,node11,node12,...node20)
.br
.I 10+3
(if prefix is 'node', equivalent to: node10,node11,node12,node13)
.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 ^).

The intersection operator @ calculates the intersection of the left and right sides:

.I group1@group2
(will result in the list of nodes group1 and group2 have in common)

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
.B nodelist
table 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 a
.B nodelist
table only listing
.I aa
through
.IR ay,
.B noderange
will fail to return any values.

Example of
\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 of non-\fIxCAT Node Format\fR
node/group names, but still valid:

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


The supported
.B noderange
syntaxes are checked for, and processed, in a specific order.  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 (must be a full path name)
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
will not confuse the exclusion or range
operators with the
- character in names.

Next
.B noderange
checks for a numeric only range (e.g. 10-20, 5+3, or just 10), then uses
.I $XCAT_NODE_PREFIX
(default is 'node') and
.I $XCAT_NODE_SUFFIX
(optional)
as the defaults to complete the node names.
.B nodeRange
tries to be intelligent about detecting padding, so you can specify 'node001-node200'
and it will add the proper number of zeroes to make all numbers 3 digits.
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 for the regular expression operator (default /).
Regular expressions offer the most flexibility.  If you are
interested in learning regex read the book
\fIMastering Regular Expressions\fR.
This operator supports nodes and groups.

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 5
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
.IR number_of_sequential_nodes .
If not in
\fIxCAT Node Format\fR
then a sorted
.B nodelist
table 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 the
.B nodelist
and
.B nodetype
tables.
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
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 the
.B nodelist
table 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 the
.B nodelist
table 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.