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 stdin.

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=IDS: Output only the hosts at indices IDS (-IDS to index from the end), where IDS is a valid RFC 22 idset (e.g. '0' will return the first host, '0-1' will return the first and second, '-1' returns the last host). The command will fail if any id in IDS is not a valid index.

-F, --find=HOSTS: Output a list of space-separated indices of HOSTS in the result hostlist, where HOSTS should be one or more hosts in hostlist form. The command will fail if any host in HOSTS is not found.

-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|IDS: Exclude all hosts in HOSTS or indices in idset IDS from the result. It is not an error if any hosts or indices do not exist in the target hostlist.

-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]

-l, --local: Change the default input source to "local". This is a shorter way to specify flux hostlist local.

-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 -led'\n' >hostfile

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

#!/bin/sh
mpiexec.hydra -launcher ssh -hosts "$(flux hostlist -le)" 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 hosts for one job, excluding the first node:

$ flux hostlist -x 0 JOBID

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