NAME

set_rlimits - allow non-privileged per-application access to elevated resource limits (including realtime scheduling priorities)

SYNOPSIS

set_rlimits [options] program [<program options>]

Available options: [-dhv] [-l[=<memlock limit>]] [-n[=<nice priority limit>]] [-r[=<realtime priority limit>]]

program must include an absolute path or be the name of a binary without any path components. In the latter case, the program to be executed will include the absolute path in the configuration file entry whose filename component matches program. If a relative path is given set_rlimits will exit with an error.

DESCRIPTION

set_rlimits allows controlled access to realtime scheduling for selected users and programs under kernel 2.6.12 or later, along with elevated settings for other selected resource limits. The set_rlimits binary needs to be installed setuid root, but it only runs with elevated privileges to set the resource limits.

When set_rlimits is run it first sets the resource limits as requested. The given program is then executed via exec(3) with these resource limits.

The users allowed to utilise this service (and the programs/priorities they can request with set_rlimits) are specified in the set_rlimits.conf configuration file, usually found in /etc/set_rlimits.conf. See the CONFIGURATION FILE section below for more details on this file. Note that failure to find or access the configuration file causes set_rlimits to abort.

By default, all resources with maximums defined in the configuration file for the requested program will be set to those maximums. The options -l , -n or -r can be used to modify this behaviour; the argument is either a limit to use in place of the maximum or -1 (which disables setting of that resource limit). If no resource limits have been altered (either due to an error or because all settings have been turned off) a warning will be printed but set_rlimits will continue to run.

OPTIONS

-d

Turn on debugging output which might assist in tracking down problems.

-h

Display brief usage information.

-l[=<mlock>]

Set the maximum locked memory size to mlock kB. If mlock is omitted it defaults to the maximum size specified for program in the configuration file.

-n[=<limit>]

Set the nice priority resource limit enforced for program. If limit is not specified, the maximum limit specified for program in the configuration file is used. Note that limit is a priority, not a nice level. The possible priorities are 0 to 39, corresponding to nice levels 19 to -20 respectively but the maximum valid priority may be less than 39 due to configuration file restrictions (see the CONFIGURATION FILE section below).

-r[=<limit>]

Set the realtime priority resource limit enforced for program. If limit is not specified, a default limit (reported in the -h output) is used. Possible values for limit range from 0 to 100 inclusive, but the maximum valid value for a given user and/or program may be less than 100 due to restrictions enfored in the configuration file (see the CONFIGURATION FILE section below).

-v

Print the program version and exit.

CONFIGURATION FILE

The configuration file (usually /etc/set_rlimits.conf) defines which users or groups have access to the functionality in set_rlimits, and to which programs and priorities this access extends. set_rlimits will exit with an error if the configuration file does not exist or is otherwise inaccessible by the user. The file consists of a series of entries, one per line. There are two possible formats for the lines: the original set_rtlimits format and an enhanced format which is easier to use when a larger number of rlimits are being set. In both cases, set_rlimits will print a warning if errors are detected in the configuration file and that line will be ignored. A hash (#) starts a comment; everything beyond it is ignored to the end of the line. Lines are limited to 1023 characters (including comment portions) and the presence of longer lines constitutes an error condition.

The original set_rtlimits entry format has the following form:

while the enhanced configuration entry has the form:

The fields and/or <key>=<value> constructs are separated by arbitary whitespace. Each line must be complete or else an error is flagged and set_rlimits refuses to run. The meaning of the fields is outlined below. Note that whitespace cannot occur between a <key>/<value> and the associated `=' sign.

name

The username or groupname which this entry relates to. To specify a groupname, the first character of name should be a @ sign; otherwise name is assumed to be a username. When considering a group specification a user's supplementary group list is scanned for a match in addition to the user's primary group. Numerical IDs are not interpreted. The special name ALL can be specified to include all users on the system. Any name which does not map to a valid user or group is flagged with a warning and the entry ignored.

program

The full absolute path and name of the program to execute with the elevated nice and/or realtime priority resource limits. If a relative path is given set_rlimits will exit with an error.

max_nice_priority

(old format only) The maximum nice priority the specified user (or group) is allowed to request when running the given program. Note that this is a priority, not a nice level. Priorities 0 to 39 correspond to nice levels 19 to -20 respectively. Specifying priorities outside this range effectively allows the user to request any nice priority. A negative value disables the setting of any nice priority for this program by the given user (or group).

max_rt_priority

(old format only) The maximum realtime priority the specified user (or group) is allowed to request when running the given program. Valid values are 0 to 100 inclusive. If a value outside this range is specified it effectively allows the user access to all realtime priority levels. A negative value disables the setting of any realtime priority for this program by the given user (or group).

<key>=<value>

(new format only) Configure a maximum resource limit setting for the given program using the new format. Possible <key> values are

nice - <value> is the maximum nice limit. Useful values are 0 to 39, corresponding to nice levels 19 to -20. A negative value prevents set_rlimits from setting the nice limit for the given program, while a value greater than 39 is treated as if 39 had been specified.

rtprio - <value> is the maximum realtime priority. Useful values are 0 to 100 inclusive. A negative value forces the program to have no effect on the realtime priority while a value greater than 100 is treated as if 100 had been given.

memlock - <value> is the maximum locked memory size in kB. The (arbitary) hard upper limit imposed by the program is reported in the output generated by the `-h' option.

If the configuration file contains more than one line (entry) which matches a given invocation, the first matching entry will be used and the others silently ignored.

RETURN VALUE AND DIAGNOSTICS

On success, set_rlimits returns the exit status of the called program. If set_rlimits itself encountered an error condition 255 is returned.

set_rlimits prints reasonably verbose error messages to assist with diagnosis. If these messages prove insufficient, try running set_rlimits in debug mode using the -d command line option. This activates further output to stderr; it's not as nicely formatted as the main error messages but it may contain information which will assist in the diagnosis of a faulty installation or configuration.

SECURITY NOTES

set_rlimits is believed to be as safe as a program such as this can be, but it has not undergone an extensive security audit and is not guaranteed to be free of bugs. Because elevated priviledges are used for only a small portion of the code the scope for problems is thought to be minimal. However, even in the absence of program bugs the user is reminded that using this program allows ordinary unpriviledged users to request realtime priorities for processes they run, which can potentially compromise system stability and security.

set_rlimits has been structured to maximise the amount of control an administrator has over who can run realtime processes, what those processes are and the maximum priorities allowed for those processes. A fixed configuration file (usually in the system /etc area) contains all the access details and the programs executed by set_rlimits are limited to those specified in the configuration file using absolute paths. This again minimises the scope for problems, but this guarantee is only as good as the realtime programs themselves and the care with which the configuration file has been set up with.

In short, the user of set_rlimits should be aware of the potential security and stability issues when using programs such as set_rlimits and to deploy it accordingly. set_rlimits comes with no warranty and no guarantee of any kind; it is deployed and used at the user's risk.

NOTES

This page describes set_rlimits as found in the original set_rlimits 1.2.0 distribution; other versions may differ slightly. Mail bug reports, corrections and additions to jwoithe@physics.adelaide.edu.au.

SEE ALSO

getrlimit(2), setrlimit(2)