CLUSET(1)

NAME
cluset - compute advanced cluster node set operations

SYNOPSIS
        cluset [OPTIONS] [COMMAND] [nodeset1 [OPERATION] nodeset2|...]

DESCRIPTION

Note: cluset and nodeset are the same command.

cluset is a utility command provided with the ClusterShell library which implements some features of ClusterShell's NodeSet and RangeSet Python classes. It provides easy manipulation of 1D or nD-indexed cluster nodes and node groups.

Also, cluset is automatically bound to the library node group resolution mechanism. Thus, it is especially useful to enhance cluster aware administration shell scripts.

OPTIONS

            --version
                show program's version number and exit

            -h, --help
                show this help message and exit

            -s GROUPSOURCE, --groupsource=GROUPSOURCE
                optional groups.conf(5) group source to use

            --groupsconf=FILE
                use alternate config file for groups.conf(5)

            Commands:

                -c, --count
                    show number of nodes in nodeset(s)

                -e, --expand
                    expand nodeset(s) to separate nodes (see also -S SEPARATOR)

                -f, --fold
                    fold nodeset(s) (or separate nodes) into one nodeset

                -l, --list
                    list node groups, list node groups and nodes (-ll) or list node groups, nodes and node count (-lll). When no argument is specified at all, this command will list all node group names found in selected group source (see also -s GROUPSOURCE). If any nodesets are specified as argument, this command will find node groups these nodes belong to (individually). Optionally for each group, the fraction of these nodes being member of the group may be displayed (with -ll), and also member count/total group node count (with -lll). If a single hyphen-minus (-) is given as a nodeset, it will be read from standard input.

                -L, --list-all
                    list node groups from all group sources (-LL shows nodes and -LLL adds node count). Like -l, if any nodesets are specified as argument, this command will find node groups these nodes belong to (individually).

                -r, --regroup
                    fold nodes using node groups (see -s GROUPSOURCE)

                --index=NODE
                    output the index of NODE in the nodeset (reverse of -I/--slice)

                --list-sources, --groupsources
                    list all active group sources (see groups.conf(5))

            Operations:

                -x SUB_NODES, --exclude=SUB_NODES
                    exclude specified nodeset

                -i AND_NODES, --intersection=AND_NODES
                    calculate nodesets intersection

                -X XOR_NODES, --xor=XOR_NODES
                    calculate symmetric difference between nodesets

            Options:

                -a, --all
                    call external node groups support to display all nodes

                --autostep=AUTOSTEP
                    enable a-b/step style syntax when folding nodesets, value is min node count threshold (integer '4', percentage '50%' or 'auto'). If not specified, auto step is disabled (best for compatibility with other cluster tools). Example: autostep=4, "node2 node4 node6" folds in node[2,4,6] but autostep=3, "node2 node4 node6" folds in node[2-6/2].

                -d, --debug
                    output more messages for debugging purpose

                -q, --quiet
                    be quiet, print essential output only

                -R, --rangeset
                    switch to RangeSet instead of NodeSet. Useful when working on numerical cluster ranges, e.g. 1,5,18-31

                -G, --groupbase
                    do not display group source prefix (always @groupname)

                -S SEPARATOR, --separator=SEPARATOR
                    separator string to use when expanding nodesets (default: ' ')

                -O FORMAT, --output-format=FORMAT
                    output format (default: '%s')

                -I SLICE_RANGESET, --slice=SLICE_RANGESET
                    return sliced off result; examples of SLICE_RANGESET are "0" for simple index selection, or "1-9/2,16" for complex rangeset selection

                --split=MAXSPLIT
                    split result into a number of subsets

                --contiguous
                    split result into contiguous subsets (i.e. for nodeset, subsets will contain nodes with same pattern name and a contiguous range of indexes, like foobar[1-100]; for rangeset, subsets consist of contiguous index ranges)

                --axis=RANGESET
                    for nD nodesets, fold along provided axis only. Axes are indexed from 1 to n and can be specified here either using the rangeset syntax, e.g. '1', '1-2', '1,3', or by a single negative number meaning that the index is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range.

                --pick=N
                    pick N node(s) at random in nodeset

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

If a single hyphen-minus (-) is given as a nodeset, it will be read from standard input.

EXTENDED PATTERNS

The cluset command benefits from ClusterShell 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 processing any character operators accordingly.

    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

        $ cluset -f node[0-7],node[8-10]
    node[0-10]

        $ cluset -f node[0-10]!node[8-10]
    node[0-7]

        $ cluset -f node[0-10]&node[5-13]
    node[5-10]

        $ cluset -f node[0-10]^node[5-13]
    node[0-4,11-13]

    Example of advanced usage

        $ cluset -f @gpu^@slurm:bigmem!@chassis[1-9/2]

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

    "All nodes" extension
        The @* and @SOURCE:* special notations may be used in extended patterns to represent all nodes (in SOURCE) according to the all external shell command (see groups.conf(5)) and are equivalent to:

                $ cluset [-s SOURCE] -a -f

    Group names in expressions
        The @@SOURCE notation may be used to access all group names from the specified SOURCE (or from the default group source when just @@ is used) in node set expressions; this works with either file-based group sources or with external group sources that have the list or mapall upcall defined (see groups.conf(5)):

                $ cluset -f @@rack
            J[1-3]

NODE WILDCARDS

Any wildcard mask found is matched against all nodes from the group source (see groups.conf(5) and the -a/--all option above). * means match zero or more characters of any type; ? means match exactly one character of any type. This can be especially useful for server farms, or when cluster node names differ.

    Say that your group configuration is set to return the following "all nodes":

        $ cluset -f -a
    bckserv[1-2],dbserv[1-4],wwwserv[1-9]

    Then, you can use wildcards to select particular nodes, as shown below:

        $ cluset -f 'www*'
    wwwserv[1-9]

        $ cluset -f 'www*[1-4]'
    wwwserv[1-4]

        $ cluset -f '*serv1'
    bckserv1,dbserv1,wwwserv1

Wildcard masks are resolved prior to extended patterns, but each mask is evaluated as a whole node set operand. In the example below, we select all nodes matching *serv* before removing all nodes matching www*:

            $ cluset -f '*serv*!www*'
        bckserv[1-2],dbserv[1-4]

EXIT STATUS

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

EXAMPLES

    Getting the node count

        $ cluset -c node[0-7,32-159]
    136

        $ cluset -c node[0-7,32-159] node[160-163]
    140

        $ cluset -c dc[1-2]n[100-199]
    200

        $ cluset -c @login
    4

    Folding nodesets

        $ cluset -f node[0-7,32-159] node[160-163]
    node[0-7,32-163]

        $ echo node3 node6 node1 node2 node7 node5 | cluset -f
    node[1-3,5-7]

        $ cluset -f dc1n2 dc2n2 dc1n1 dc2n1
    dc[1-2]n[1-2]

        $ cluset --axis=1 -f dc1n2 dc2n2 dc1n1 dc2n1
    dc[1-2]n1,dc[1-2]n2

    Expanding nodesets

        $ cluset -e node[160-163]
    node160 node161 node162 node163

        $ echo 'dc[1-2]n[2-6/2]' | cluset -e
    dc1n2 dc1n4 dc1n6 dc2n2 dc2n4 dc2n6

    Excluding nodes from nodeset

        $ cluset -f node[32-159] -x node33
    node[32,34-159]

    Computing nodesets intersection

        $ cluset -f node[32-159] -i node[0-7,20-21,32,156-159]
    node[32,156-159]

    Computing nodesets symmetric difference (xor)

        $ cluset -f node[33-159] --xor node[32-33,156-159]
    node[32,34-155]

    Splitting nodes into several nodesets (expanding results)

        $ cluset --split=3 -e node[1-9]
    node1 node2 node3
    node4 node5 node6
    node7 node8 node9

    Splitting non-contiguous nodesets (folding results)

        $ cluset --contiguous -f node2 node3 node4 node8 node9
    node[2-4]
    node[8-9]

        $ cluset --contiguous -f dc[1,3]n[1-2,4-5]
    dc1n[1-2]
    dc1n[4-5]
    dc3n[1-2]
    dc3n[4-5]

HISTORY

cluset was added in 1.7.3 to avoid a conflict with xCAT's nodeset command and also to conform with ClusterShell's "clu*" command nomenclature.

SEE ALSO

clubak(1), clush(1), nodeset(1), groups.conf(5).

https://clustershell.readthedocs.io/

BUG REPORTS

    Use the following URL to submit a bug report or feedback:
        https://github.com/clustershell/clustershell/issues

AUTHOR
Stephane Thiell

COPYRIGHT
GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)