flux-hostlist(1)

SYNOPSIS

flux hostlist [OPTIONS] [SOURCES]

DESCRIPTION

flux hostlist takes zero or more SOURCES of host lists on the command line and concatenates them by default into a single RFC 29 Hostlist.

SOURCES can optionally be combined by various set operations, for example to find the intersection, difference, or to subtract hostlists.

SOURCES

Valid SOURCES of hostlist information include:

instance: hosts from the broker hostlist attribute
jobid: hosts assigned to a job.
local: jobid from FLUX_JOB_ID environment variable if set, otherwise instance
avail[able]: instance hostlist minus those nodes down or drained
stdin or -: read a list of hosts on stdin
hosts: a literal RFC 29 Hostlist

The default source is local.

OPTIONS

-e, --expand: Expand hostlist result using the defined output delimiter. Default is space-delimited.

-d, --delimiter=S: Set the delimiter for --expand to string S.

-c, --count: Emit the number of hosts in the result hostlist instead of the hostlist itself.

-n, --nth=N: Output only the host at index N (-N to index from the end). The command will fail if N is not a valid index.

-L, --limit=N: Output at most N hosts (-N to output the last N hosts).

-S, --sort: Display sorted result.

-u, --union, --unique: Return only unique hosts. This implies --sort. Without any other manipulation options, this is equivalent to returning the set union of all provided hosts. (By default, all inputs are concatenated).

-x, --exclude=HOSTS: Exclude all occurrences of HOSTS form the result.

-i, --intersect: Return the set intersection of all hostlists.

-m, --minus: Subtract all hostlists from the first.

-X, --xor: Return the symmetric difference of all hostlists.

-f, --fallback

If an argument to flux-hostlist is a single hostname, and the hostname can be interpreted as a valid Flux jobid (e.g. starts with f and otherwise contains valid base58 characters like fuzzy or foo1), then the command may fail with:

flux-hostlist: ERROR: job foo1 not found

With the --fallback option arguments that appear to be jobids that are not found are treated as hostnames, e.g.:

$ flux hostlist --fallback foo1 foo2
foo[1-2]

-q, --quiet: Suppress output and exit with a nonzero exit code if the hostlist is empty.

EXAMPLES

Create host file for the current job or instance if running in an initial program:

$ flux hostlist -ed'\n' >hostfile

Launch an MPI program using mpiexec.hydra from within a batch script:

#!/bin/sh
mpiexec.hydra -launcher ssh -hosts "$(flux hostlist -e)" mpi_hello

List the hosts for one job: (Note: this is the same as flux jobs -no {nodelist} JOBID)

$ flux hostlist JOBID
host[1-2]

List the unordered, unique hosts for multiple jobs:

$ flux hostlist -u JOBID1 JOBID2 JOBID3
host[1-2,4]

Determine if any failed jobs shared common nodes:

$ flux hostlist --intersect $(flux jobs -f failed -no {id})
host4

Determine if a given host appeared the last submitted job:

if flux hostlist -q -i $(flux job last) host1; then
    echo host1 was part of your last job
fi

Count the number of currently available hosts:

$ flux hostlist --count avail
4

List all the hosts on which a job named 'myapp' ran:

$ flux hostlist --union $(flux pgrep myapp)
host[2,4-5]

List all hosts in the current instance which haven't had a job assigned in the last 100 jobs:

$ flux hostlist --minus instance $(flux jobs -c 100 -ano {id})
host0

EXIT STATUS

0: Successful operation
1: One or more SOURCES were invalid, an invalid index was specified to --nth, or --quiet was used and the result hostlist was empty.
2: Invalid option specified or other command line error

RESOURCES

Flux: http://flux-framework.org

Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc

FLUX RFC

29/Hostlist Format