Introduction
============

set_rlimits is a small wrapper program to allow people to take advantage of
the realtime resource limit extensions available in Linux kernels 2.6.12 and
later without having to resort to using a PAM module.  This is of particular
interest for Slackware users since Slackware doesn't use PAM, but other
users may find this program helpful as well.  In addition, several other
resource limits can be manipulated by the program.

set_rlimits needs to be installed setuid root.  However, it runs at
elevated priviledges only when setting the process resource limits.  This
minimises potential security implications.  Despite this, no security 
guarantee is given; users concerned about the security of this program
should review the source code themselves.  Suggestions on improving security
are welcomed by the author.

The resource limits which set_rlimits is permitted to grant are controlled
by the configuration file (CONFIG_FILE in set_rlimits.c, usually
/etc/set_rlimits.conf).  This file sets the maximum priorities which
set_rlimits can set for a given program when executed by a given user or
group.  The program specified must include an absolute path.  This gives an
administrator fairly fine-grained control over who can execute programs at
elevated priorities and which programs they are.  The enforced specification
of an absolute path in the configuration file means the administrator can
maintain control over exactly which programs may be run with elevated
resource limits.

For further details on the configuration file format, refer to the
samle set_rlimits.conf provided in the source distribution, or
the source itself.


Compilation and installation
============================

This program compiles and runs successfully under Slackware 10.x running a
2.6.12-rc5 kernel and above.  Hopefully there are not too many
distibution-specific assumptions in the source and a simple "make" will be
sufficient for most people.  Please don't complain that autoconf isn't used
or supported; I simply don't have time to do this at the moment.  However,
patches to introduce such functionality would be welcome.

There is also rudimentary "make install" functionality in the Makefile. 
This simply copies the executable to /usr/local/bin/ and makes it setuid
root, copies the manual page to /usr/local/man/man8/, and copies the sample
set_rlimits.conf file to /etc/.  The destination directories can be altered
by editting Makefile and changing PREFIX and/or SYSCONFDIR.  However, note
that if an alternative configuration file location/name is desired, the
CONFIG_FILE define in set_rlimits.c will need to be editted to reflect
this.


Successes
=========

set_rlimits 1.0.0 appears to run as desired with jack 0.99.73 and ardour
0.9beta29.  A realtime priority of 30 appears sufficient for this software
combination.  A realtime priority of 100 is necessary to run all parts of
muse 0.7.2pre1 with no errors.


Known issues
============

muse 0.7.2pre1 appears to require a realtime priorty of at least 80; without
this, realtime scheduling is denied (the watchdog thread actually requests a
realtime priority of 100, but muse appears to run fine without this request
being permitted).  Even with elevated priority, when run through
set_rlimits, a setuid root muse 0.7.2pre1 binary exits on startup:
  muse: Fatal IO error: client killed
The cause is currently not known or understood.  The workaround is to not
have the muse binary setuid root.  This is fine, since running set_rlimits
under kernel 2.6.12 or later should make it unnecessary for muse (and other
low latency audio applications) to be setuid root.


Licence
=======

set_rlimits is released under the GNU General Public License (GNU GPL).
Please refer to the COPYING file in the source distribution for further
details.


Jonathan Woithe
29 May 2005
Updated: 19 December 2005
