README.security

Systemtap builds kernel modules.  To insert a kernel module on a
system, root access is needed.

SECURITY MODEL
==============

Originally sudo(8) was used to grant root access.  After compiling a
new kernel module, stap ran "sudo staprun module_path".  This worked,
but required all systemtap users to have root access.  Many sysadmins
on enterprise systems do not have root access.

So, a new security model was developed.  To run the staprun program
(which installs systemtap kernel modules), a user must be one of the
following:

 * the root user;

 * a member of both 'stapdev' and 'stapusr' groups; or

 * a member of the 'stapusr' group.  Members of the stapusr group can
   only use modules located in the /lib/modules/VERSION/systemtap
   directory (where VERSION is the output of "uname -r").  This
   directory must be owned by root and not be world writable.

So, there are two classes of users: systemtap developers (the root user
and members of the stapdev/stapusr groups) and systemtap users (members of
only the stapusr group).  Systemtap developers can compile and run any
systemtap script.  Systemtap users can only run "approved"
pre-compiled modules located in /lib/modules/VERSION/systemtap.

USAGE
=====

Here's the usage case.  A systemtap developer hears of a problem on a
production machine (which doesn't have a compiler or kernel debuginfo
installed).  So, he write a systemtap script to probe certain areas of
the kernel that will give him a better idea of what is going on.  He
develops the script on a development machine (that has the compiler
and kernel debuginfo installed).  Once he is satisfied with the
systemtap script, he creates the systemtap kernel module and copies it
to /lib/modules/VERSION/systemtap on the target production machine.
He then asks a systemtap user on that machine to run the module and
report the results.

The above usage case would look something like this:

On the development machine:
# vi pmod.stp
(The systemtap developer writes the systemtap script.)

# stap -m pmod pmod.stp
(The systemtap developer compiles and runs the script.  If necessary,
the script may need to be edited to fix any errors.)

# scp pmod.ko prod_machine:/lib/modules/`uname -r`/systemtap
(The systemtap developer copies the compiled kernel module to the proper
directory on the production machine.  Of course other methods - ftp,
nfs, etc. could be used to transfer the module.)

On the production machine:
$ staprun pmod
(The systemtap user runs the newly developed systemtap kernel module.)

There are (at least) 2 different usage scenarios for the
/lib/modules/VERSION/systemtap directory.

1) Most restrictive usage.  If only root should be able to add
"approved" systemtap modules to /lib/modules/VERSION/systemtap, the
permissions should be 755, like this:

drwxr-xr-x 2 root root 4096 2007-08-07 13:54 systemtap/

2) More permissive usage.  If all systemtap developers should be able
to add "approved" systemtap modules to /lib/modules/VERSION/systemtap,
its permissions should be 775 (and be owned by root, group stapdev),
like this:

drwxrwxr-x 2 root stapdev 4096 2007-08-07 13:54 systemtap/

INTERNALS
=========

To accomplish the new security model, staprun has been split into two
programs: staprun and stapio.

Here is a description of a typical systemtap session.  The staprun
program is a setuid program that does some system setup, loads the
kernel module, then runs stapio (and waits for it to finish).  The
stapio program runs as the invoking user and is responsible for all
communication with the kernel module.  After the script runs to
completion, stapio fork/execs staprun -d to unload the kernel module.

staprun is a setuid program.  It holds on to the root privileges only
for the least amount of time (as required to verify/load compiled
kernel module files).  It invokes only stapio, and only as the
original (unprivileged) user.