flux-queue(1)

SYNOPSIS

flux queue list [-q QUEUES,...] [-n] [-o FORMAT]

flux queue status [-a] [-v] [QUEUE]

flux queue disable [-a] [-v] [--quiet] [--nocheckpoint] [-m reason] [QUEUE]

flux queue enable [-a] [-v] [--quiet] [QUEUE]

flux queue stop [-a] [-v] [--quiet] [--nocheckpoint] [-m reason] [QUEUE]

flux queue start [-a] [-v] [--quiet] [QUEUE]

flux queue drain [--timeout=DURATION]

flux queue idle [--timeout=DURATION]

DESCRIPTION

The flux queue command operates on Flux job queue(s).

By default, Flux has one anonymous queue. Multiple named queues may be configured - see flux-config-queues(5).

A named queue may be a virtual queue, as described in RFC 33: an alternate submission name for a parent queue's resources with different policy, such as raised limits for a subset of users. Jobs submitted to a virtual queue are scheduled as part of the parent queue. The flux queue administrative commands below operate on a virtual queue's own state without affecting its parent or sibling queues, but note that a virtual queue's jobs are only eligible for scheduling when both the virtual queue and its parent are started.

COMMANDS

flux queue has the following subcommands:

list

List queue status, defaults, and limits. When one or more virtual queues are configured, a PARENT column is also shown, listing each virtual queue's parent queue (blank for a non-virtual queue).

-q, --queue=QUEUE,...: Limit output to specified queues

-n, --no-header: Do not output column headers in list output.

-o, --format=FORMAT: Specify output format in list using Python's string format syntax. See OUTPUT FORMAT below for field names.

status

Report the current queue status.

-q, --queue=NAME: Select a queue by name.

-v, --verbose: Display more detail about internal job manager state.

disable

Prevent jobs from being submitted to the queue, with an optional reason that is shown to submitting users.

-a, --all: Select all queues.

-v, --verbose: Display more detail about internal job manager state.

--quiet: Display only errors.

--nocheckpoint: Do not preserve the new queue disabled state across a Flux instance restart.

enable

Allow jobs to be submitted to the queue.

-q, --queue=NAME: Select a queue by name.

-a, --all: Select all queues.

-v, --verbose: Display more detail about internal job manager state.

--quiet: Display only errors.

stop

Stop allocating resources to jobs. Pending jobs remain enqueued, and running jobs continue to run, but no new jobs are allocated resources.

-a, --all: Select all queues.

-v, --verbose: Display more detail about internal job manager state.

--quiet: Display only errors.

--nocheckpoint: Do not preserve the new queue stop state across a Flux instance restart.

start

Start allocating resources to jobs.

-a, --all: Select all queues.

-v, --verbose: Display more detail about internal job manager state.

--quiet: Display only errors.

drain

Block until all queues become empty. It is sometimes useful to run after flux queue disable, to wait until the system is quiescent and can be taken down for maintenance.

--timeout=FSD: Limit the time that the command` will block.

idle

Block until all queues become idle (no jobs in RUN or CLEANUP state, and no outstanding alloc requests to the scheduler). It may be useful to run after flux queue stop to wait until the scheduler and execution system are quiescent before maintenance involving them.

--timeout=FSD: Limit the time that the command` will block.

OUTPUT FORMAT

The flux queue list --format option can be used to specify an output format using Python's string format syntax or a defined format by name. For a list of built-in and configured formats use -o help. An alternate default format can be set via the FLUX_QUEUE_LIST_FORMAT_DEFAULT environment variable. A configuration snippet for an existing named format may be generated with --format=get-config=NAME. See flux-jobs(1) OUTPUT FORMAT section for a detailed description of this syntax.

If the format string begins with sort:k1[,k2,...], then k1[,k2,...] will be taken to be a comma-separated list of keys on which to sort the displayed output. If a sort key starts with -, then the key will be sorted in reverse order.

Sort keys can be any valid field name. Fields that may be empty or unset will sort before non-empty values. When sorting fields that contain mixed types, the sort order is: empty/None < numbers (including booleans) < strings. Booleans are treated as numeric values (False=0, True=1).

For example, to sort by a numeric field with empty values first:

--format='sort:nnodes {id} {nnodes} {status}'

Or to sort in reverse order (largest first, empty values last):

--format='sort:-nnodes {id} {nnodes} {status}'

Multiple sort keys can be specified, with earlier keys taking precedence:

--format='sort:state,-t_submit {id} {state} {t_submit}'

The following field names can be specified:

queue: queue name
queuem: queue name, but default queue is marked up with an asterisk
parent: parent queue name if this is a virtual queue (RFC 33), otherwise empty. This field is only shown by default if at least one configured queue has a parent.
submission: Description of queue submission status: enabled or disabled
scheduling: Description of queue scheduling status: started, stopped, or, for a virtual queue whose own state is started but whose parent queue is stopped, stopped (parent).
enabled: Single character submission status: ✔ if enabled, ✗ if disabled.
started: Single character scheduling status: ✔ if started, ✗ if stopped. A virtual queue whose own state is started but whose parent queue is stopped shows ⏸ instead: scheduling will resume automatically once the parent is started.
enabled.ascii: Single character submission status: y if enabled, n if disabled.
started.ascii: Single character scheduling status: y if started, n if stopped, or p if started but paused because its parent is stopped (see started above).
defaults.timelimit: default timelimit for jobs submitted to the queue
limits.timelimit: max timelimit for jobs submitted to the queue
limits.range.nnodes: range of nodes that can be requested for this queue
limits.range.ncores: range of cores that can be requested for this queue
limits.range.ngpus: range of gpus that can be requested for this queue
limits.range.effective.nnodes: effective range of nodes that can be requested for this queue. The upper end of the range will display the smaller of the policy limit and the total nodes currently assigned to the queue.
limits.range.effective.ncores: effective range of cores that can be requested for this queue. The upper end of the range will display the smaller of the policy limit and the total cores currently assigned to the queue.
limits.range.effective.ngpus: effective range of gpus that can be requested for this queue. The upper end of the range will display the smaller of the policy limit and the total gpus currently assigned to the queue.
limits.min.nnodes: minimum number of nodes that must be requested for this queue
limits.max.nnodes: maximum number of nodes that can be requested for this queue
limits.min.ncores: minimum number of cores that must be requested for this queue
limits.max.ncores: maximum number of cores that can be requested for this queue
limits.min.ngpus: minimum number of gpus that must be requested for this queue
limits.max.ngpus: maximum number of gpus that can be requested for this queue
resources.{all,free,allocated,up,down}.{nnodes,ncores,ngpus}: Counts of resources in various states (all available, currently free, currently allocated, up, and down) for this queue.