CONDOR_USERPRIO(1)

NAME
condor_userprio - HTCondor Manual

Manage submitter priorities.

SYNOPSIS

condor_userprio [-help]

condor_userprio [-name negotiatorname] [-inputfile filename] [-pool hostname[:port]] [Edit Option | Display Options [submitter]]

DESCRIPTION

Modify or display priority information for submitters and/or groups from HTCondor's accounting. By default, only display active submitters (i.e. submitters whose usage was recorded in the last 24 hours).

NOTE: For the purposes of accounting and fair share, HTCondor "charges" usage to a submitter. A submitter, by default, is the same as the operating system user. This means one user of HTCondor, such as Taylor, may have multiple submitter accounts on different Access Points i.e. taylor@ap1.chtc.wisc.edu and taylor@ap2.chtc.wisc.edu.

OPTIONS

  General

-debug[:level]
    Causes debugging information to be sent to stderr, based on the value of the configuration variable TOOL_DEBUG. Optional debug levels can be specified.

-help
    Display tool usage information.

-inputfile filename
    Read priority information from filename.

-name negotiatorname
    Send the command to a machine identified by negotiatorname.

-pool hostname[:port]
    Specify a pool by giving the central manager's host name and an optional port number.

  Edit Options

-delete submitter
    Remove the specified submitter from HTCondor's accounting.

-resetall
    Reset the accumulated usage of all the submitters to zero.

-resetusage submitter
    Reset the accumulated usage of the submitter specified by submitter to zero.

-setaccum submitter value
    Set the accumulated usage of the submitter specified by submitter to the specified floating point value.

-setbegin submitter value
    Set the begin usage time of the submitter specified by submitter to the specified value.

-setlast submitter value
    Set the last usage time of the submitter specified by submitter to the specified value.

-setfactor submitter value
    Set the priority factor of the submitter specified by submitter to the specified value. When combined with -duration, the priority factor is set as a temporary lease: at the next negotiation cycle on or after seconds have elapsed, the priority factor is automatically restored to its prior value. Lease state is persistent across a condor_negotiator restart. It is an error to set a lease while one is already in effect for the same submitter; cancel the existing lease first with -cancelfactorlease.

-setprio submitter value
    Set the real priority of the submitter specified by submitter to the specified value.

-setceiling submitter value
    Set the ceiling for the submitter specified by submitter to the specified value. Where value is the sum of the SlotWeight of all running jobs (See SLOT_WEIGHT). Setting the ceiling to -1 clears any previously set ceiling, and sets the effective ceiling to unlimited. When combined with -duration, the ceiling is set as a temporary lease: at the next negotiation cycle on or after seconds have elapsed, the ceiling is automatically restored to its prior value. Lease state is persistent, so it survives a condor_negotiator restart. It is an error to set a lease while one is already in effect for the same submitter; cancel the existing lease first with -cancelceilinglease.

-duration seconds
    Only valid with -setceiling, -setfloor, or -setfactor. Make the corresponding value a lease that expires after seconds seconds, at which point the prior value is restored.

-cancelceilinglease submitter
    Cancel an in-effect ceiling lease for submitter, immediately restoring the ceiling value that was in effect before the lease was set. It is an error if no lease is in effect.

-cancelfloorlease submitter
    Cancel an in-effect floor lease for submitter, immediately restoring the floor value that was in effect before the lease was set. It is an error if no lease is in effect.

-cancelfactorlease submitter
    Cancel an in-effect priority-factor lease for submitter, immediately restoring the priority factor that was in effect before the lease was set. It is an error if no lease is in effect.

-setfloor submitter value
    Set the floor for the submitter specified by submitter to the specified value. Where value is the sum of the SlotWeight of all running jobs (See SLOT_WEIGHT). Setting the floor to 0 clears any previously set floor. When combined with -duration, the floor is set as a temporary lease: at the next negotiation cycle on or after seconds have elapsed, the floor is automatically restored to its prior value. Lease state is persistent across a condor_negotiator restart. It is an error to set a lease while one is already in effect for the same submitter; cancel the existing lease first with -cancelfloorlease.

  Display Options

-activefrom month day year
    Display information for submitters who have some recorded accumulated usage since the specified date.

-all
    Display all available fields about each group or submitters (active).

-allusers
    Display information for all the submitters (active and inactive) who have some recorded accumulated usage.

-collector
    Force the query to come from the collector.

-negotiator
    Force the query to come from the negotiator instead of the collector.

-af/-autoformat[:jlhVr,tng] Attribute [Attribute ...]
    Display attribute(s) or expression(s) formatted in a default way depending on the type of each Attribute specified after the option. It is assumed that no Attributes begin with a dash character so that the next word that begins with a dash is considered another option. This option may be followed by a colon character and formatting qualifiers to deviate the output formatting from the default:

•   j print the ClassAds associated JobID as the first field.

•   l label each field.

•   h print column headings before the first line of output.

•   V use %V rather than %v for formatting (string values are quoted).

•   r print "raw", or unevaluated values.

•   , add a comma character after each field.

•   t add a tab character before each field instead of the default space character.

•   n add a newline character after each field.

•   g add a newline character between ClassAds, and suppress spaces before each field.

    WARNING: The n and , qualifiers may not be used together.

    The l and h qualifiers may not be used together.

-constraint expr
    Display submitters and groups that satisfy the expression.

-flat
    Display information such that submitters within hierarchical groups are not listed with their group.

-groupid
    Display group ID.

-getreslist submitter
    Display all the resources currently allocated to the submitter specified by submitter.

-grouporder
    Display submitter information with accounting group entries at the top of the list, and in breadth-first order within the group hierarchy tree.

-grouprollup
    For hierarchical groups, the display shows sums as computed for groups, and these sums include sub groups.

-hierarchical
    Display information such that submitters within hierarchical groups are listed with their group.

-legacy
    For use with the -long option, displays attribute names and values as a single ClassAd.

-long
    Display ClassAds in long format.

-modular
    Modifies the display when using the -long option, such that attribute names and values are shown as distinct ClassAds.

-order
    Display group order.

-priority
    Display fields with submitter priority information.

-most
    Display fields considered to be the most useful. This is the default set of fields displayed.

-quotas
    Display fields relevant to hierarchical group quotas.

-sortkey
    Display group sort key.

-surplus
    Display usage surplus.

-usage
    Display usage information for each group or submitter.

submitter
    Display information only for the specified submitter.

GENERAL REMARKS

The default tool output will display the following information for each active submitter
Field | Description
Effective Priority | The effective priority value of the submitter, which is used to calculate the submitter's share when allocating resources. A lower value means a higher priority, and the minimum value (highest priority) is 0.5. The effective priority is calculated by multiplying the real priority by the priority factor.
Priority Factor | The system administrator can set this value for each submitter, thus controlling a submitter's effective priority relative to other submitters. This can be used to create different classes of submitters.
Weighted In Use | The number of resources currently used.
Total Usage (Weighted hours) | The accumulated number of resource-hours used by the submitter since the usage start time.
Time Since Last Usage | Elapsed time since the specific submitter last had claimed resources.
Submitter Floor | The minimum guaranteed number of CPU cores assigned to the specific submitter.
Submitter Ceiling | Maximum number of CPU cores assigned to the specific submitter.

When executed with the -all option, the following additional columns of information will be displayed
Field | Description
Real Priority | The value of the real priority of the submitter. This value follows the submitter's resource usage.
Usage Start Time | The time since when usage has been recorded for the submitter. This time is set when a submitter job runs for the first time. It is reset to the present time when the usage for the submitter is reset.
Last Usage Time | The most recent time a resource usage has been recorded for the submitter.

For security purposes of authentication and authorization, specifying an Edit Option requires the ADMINISTRATOR level of access.

EXIT STATUS

0 - Success

1 - Failure has occurred

EXAMPLES

Display default information about active submitters

$ condor_userprio

Display all information about active submitters

$ condor_userprio -all

Display default information for active submitters Bill and Ted associated with Access Point excellent.host.machine

$ condor_userprio bill@excellent.host.machine ted@excellent.host.machine

Display default information for every submitter

$ condor_userprio -allusers

Display usage information for all active submitters

$ condor_userprio -usage

Remove submitter taylor@ap2.chtc.wisc.edu from HTCondor's accounting

$ condor_userprio -delete taylor@ap2.chtc.wisc.edu

Reset accumulated usages for all submitters to zero

$ condor_userprio -resetall

Reset accumulated usage for submitter jfk@white.house.gov to zero

$ condor_userprio -resetusage jfk@white.house.gov

Set submitter frodo@mount.doom.mordor accumulated usage to 6.0

$ condor_userprio -setaccum frodo@mount.doom.mordor 6.0

Set submitter taylor@ap1.cthc.wisc.edu priority to 100

$ condor_userprio -setprio taylor@ap1.cthc.wisc.edu 100

Set submitter taylor@ap1.cthc.wisc.edu usage ceiling to 50

$ condor_userprio -setceiling taylor@ap1.cthc.wisc.edu 50

Set submitter taylor@ap1.cthc.wisc.edu usage floor floor to 5

$ condor_userprio -setfloor taylor@ap1.cthc.wisc.edu 5

SEE ALSO

None.

AVAILABILITY

Linux, MacOS, Windows

AUTHOR
HTCondor Team

COPYRIGHT
1990-2026, Center for High Throughput Computing, Computer Sciences Department, University of Wisconsin-Madison, Madison, WI, US. Licensed under the Apache License, Version 2.0.