GIVERTCAP
=========

NOTE: This utility is only needed on older Linux systems. If your system
already has rtlimit or the realtime-lsm module then it is no longer necessary
to patch your kernel, and you should use those facilities instead.

This directory contains Tommi Ilmonen's givertcap utility which enables a
program to enjoy realtime scheduling under Linux without having to be run as
root. This is provided as a temporary workaround until the Linux file systems
provide POSIX.1e capability support; once this is implemented this utility
will no longer be necessary.

Givertcap now comes bundled with the Q distribution for your convenience, but
it is not installed by default. Installation instructions can be found below.

Please note that you do not have to run givertcap yourself; once givertcap is
installed, a givertcap-aware software (like the clib module) will invoke it
automatically.

You'll notice that I made some trivial cosmetic changes to the sources (watch
out for -AG). The original sources of givertcap are available under the GPL
from the following website:

	http://www.tml.hut.fi/~tilmonen/givertcap/

Please refer to this site for further information.

KERNEL REQUIREMENTS
====== ============

To make givertcap work, you'll need a recent kernel and the libcap library (I
tested it with 2.4.19 on a SuSE 8.1 system). You also have to build a custom
kernel with a patched version of /usr/src/linux/include/linux/capability.h. On
my system the relevant lines in linux/capability.h look as follows:

#define CAP_INIT_EFF_SET    to_cap_t(~0 & ~CAP_TO_MASK(CAP_SETPCAP))
#define CAP_INIT_INH_SET    to_cap_t(0)

You'll have to change these to something like the following:

#define CAP_INIT_EFF_SET    to_cap_t(~0)
#define CAP_INIT_INH_SET    to_cap_t(~0)

Rebuild the modified kernel and install it on your system. See your distro's
manual on how to accomplish this. It goes without saying that you should only
try this if you are a seasoned Linux hacker. If you messed up your system
following these instructions, don't tell me. YOU HAVE BEEN WARNED. ;-)

INSTALLATION
============

THIS PROGRAM IS FOR LINUX ONLY! You can compile and install the program on
your system as follows:

$ make; make install

This requires that you have the libcap library on your system. The program
will be installed under /usr/local/bin. The installed program will be owned by
user root, group users, will have the setuid bit set, and will be executable
by owner and group, but not by others.

You can uninstall the program as follows:

$ make uninstall

Please note that the givertcap program *NEEDS TO BE SETUID ROOT* to make it
work. As with all setuid programs, this is a *POTENTIAL SECURITY RISK*. If you
are concerned about security, you might want to set up a special "rtusers"
group on your system and change the group ownership of givertcap accordingly:

$ chgrp rtusers /usr/local/bin/givertcap

This way only users in the rtusers group will be able to execute the program.

If you want to rename givertcap or move it to another directory, you need to
specify the full path in an environment variable, like so:

$ export GIVERTCAP=/some/path/here/givertcap


Good luck!
March 2003, Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de