Edit File: 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.