=========
 nodeset
=========

-----------------------------------
compute advanced nodeset operations
-----------------------------------

:Author: Stephane Thiell, CEA DAM  <stephane.thiell@cea.fr>
:Date:   2010-05-25
:Copyright: CeCILL-C V1
:Version: 1.3
:Manual section: 1
:Manual group: ClusterShell User Manual


SYNOPSIS
========

 ``nodeset`` [COMMAND] [OPTIONS] [nodeset1 [-ixX] nodeset2|...]


DESCRIPTION
===========
The ``nodeset`` command is an utility command provided with the ClusterShell
library which implements some features of the NodeSet and RangeSet classes.
It provides easy manipulation of indexed cluster nodes and node groups.

OPTIONS
=======

Commands:
    --count, -c
        Return the number of nodes in nodesets.
    --expand, -e
        Expand nodesets to separate nodes.
    --fold, -f
        Compact/fold nodesets (or separate nodes) into one nodeset.
    --list, -l
        List node groups (see --groupsource).
    --regroup, -r
        Fold nodes using node groups (see --groupsource).
    --groupsources
        List all configured group sources (see ``groups.conf``\(5)).

Options:
    --all, -a
        Call external node groups support to display all nodes.
    --autostep=NUMBER
        Specify auto step threshold number when folding nodesets.
        If not specified, auto step is disabled.
        Example: autostep=4, "node2 node4 node6" folds in node[2,4,6] but autostep=3, "node2 node4 node6" folds in node[2-6/2]
    --help, -h
        This help page.
    --quiet, -q
        Quiet mode, hide any parse error messages (on stderr).
    --rangeset, -R
        Switch to RangeSet instead of NodeSet. Useful when working on
        numerical cluster ranges, eg. 1,5,18-31.
    --groupsource=GROUPSOURCE, -s GROUPSOURCE
        Specify group source (section to use in ``groups.conf``\(5)).
    --groupbase, -G
        Do not display group source prefix (always `@groupname`).
    --separator=STRING, -S STRING
        Specify separator string for expanding nodesets (default: " ").
    --version, -v
        Show ClusterShell version and exit.
Operations (default is union):
    --exclude=NODESET, -x NODESET
        Exclude provided node or nodeset.
    --intersection=NODESET, -i NODESET
        Calculate nodesets intersection. This means that only nodes that
        are in the two provided nodesets are used.
    --xor=NODESET, -X NODESET
        Calculate symmetric difference (XOR) between two nodesets. This
        This means that nodes present in only one of the nodesets are
        used.


For a short explanation of these options, see ``-h, --help``.

EXTENDED PATTERNS
=================

The ``nodeset`` command benefits from ClusterShell 1.3 NodeSet basic
arithmetic addition. This feature extends recognized string patterns by
supporting operators matching all Operations seen previously. String
patterns are read from left to right, by proceeding any character
operators accordinately. 

Supported character operators
    ``,``
        indicates that the *union* of both left and right nodeset should be
        computed before continuing
    ``!``
        indicates the *difference* operation
    ``&``
        indicates the *intersection* operation
    ``^``
        indicates the *symmetric difference* (XOR) operation

    Care should be taken to escape these characters as needed when the shell
    does not interpret them literally.

Examples of use of extended patterns
  :$ nodeset -f node[0-7],node[8-10]:

  | node[0-10]
  
  :$ nodeset -f node[0-10]\!node[8-10]:
  
  | node[0-7]
  
  :$ nodeset -f node[0-10]\&node[5-13]:
  
  | node[5-10]
    
  :$ nodeset -f node[0-10]^node[5-13]:
  
  | node[0-4,11-13]

Example of advanced usage
  :$ nodeset -f @gpu^@slurm\:bigmem!@chassis[1-9/2]:

  This computes a folded nodeset containing nodes found in group @gpu and @slurm:bigmem, but not in both, minus the nodes found in odd chassis groups from 1 to 9.


EXIT STATUS
===========

An exit status of zero indicates success of the ``nodeset`` command. A non-zero
exit status indicates failure.

EXAMPLES
===========

Getting the node count
  :$ nodeset -c node[0-7,32-159]:
  
  | 136
  
  :$ nodeset -c node[0-7,32-159] node[160-163]:
  
  | 140

Folding nodesets
  :$ nodeset -f node[0-7,32-159] node[160-163]:
  
  | node[0-7,32-163]

Expanding nodesets
  :$ nodeset -e node[160-163]:

  | node160 node161 node162 node163

Excluding nodes from nodeset
  :$ nodeset -f node[32-159] -x node33:

  | node[32,34-159]

Computing nodesets intersection
  :$ nodeset -f node[32-159] -i node[0-7,20-21,32,156-159]:

  | node[32,156-159]

Computing nodesets symmetric difference (xor)
  :$ nodeset -f node[33-159] --xor node[32-33,156-159]:

  | node[32,34-155]


HISTORY
=======

Command syntax has been changed since ``nodeset`` command available with ClusterShell v1.1. Operations, like *--intersection* or *-x*, are now specified between nodesets in the command line.

ClusterShell v1.1:
    :$ nodeset -f -x node[3,5-6,9] node[1-9]:

    | node[1-2,4,7-8]

ClusterShell v1.2+:
    :$ nodeset -f node[1-9] -x node[3,5-6,9]:

    | node[1-2,4,7-8]


SEE ALSO
========

``clush``\(1), ``clubak``\(1), ``groups.conf``\(5).

BUG REPORTS
===========

Use the following URL to submit a bug report or feedback:
  http://sourceforge.net/apps/trac/clustershell/report

