README.security

   1 Systemtap builds kernel modules.  To insert a kernel module on a
   2 system, root access is needed.
   3
   4 SECURITY MODEL
   5 ==============
   6
   7 Originally sudo(8) was used to grant root access.  After compiling a
   8 new kernel module, stap ran "sudo staprun module_path".  This worked,
   9 but required all systemtap users to have root access.  Many sysadmins
  10 on enterprise systems do not have root access.
  11
  12 So, a new security model was developed.  To run the staprun program
  13 (which installs systemtap kernel modules), a user must be one of the
  14 following:
  15
  16  * the root user;
  17
  18  * a member of both 'stapdev' and 'stapusr' groups; or
  19
  20  * a member of the 'stapusr' group.  Members of the stapusr group can
  21    only use modules located in the /lib/modules/VERSION/systemtap
  22    directory (where VERSION is the output of "uname -r").  This
  23    directory must be owned by root and not be world writable.
  24
  25 So, there are two classes of users: systemtap developers (the root user
  26 and members of the stapdev/stapusr groups) and systemtap users (members of
  27 only the stapusr group).  Systemtap developers can compile and run any
  28 systemtap script.  Systemtap users can only run "approved"
  29 pre-compiled modules located in /lib/modules/VERSION/systemtap.
  30
  31 USAGE
  32 =====
  33
  34 Here's the usage case.  A systemtap developer hears of a problem on a
  35 production machine (which doesn't have a compiler or kernel debuginfo
  36 installed).  So, he write a systemtap script to probe certain areas of
  37 the kernel that will give him a better idea of what is going on.  He
  38 develops the script on a development machine (that has the compiler
  39 and kernel debuginfo installed).  Once he is satisfied with the
  40 systemtap script, he creates the systemtap kernel module and copies it
  41 to /lib/modules/VERSION/systemtap on the target production machine.
  42 He then asks a systemtap user on that machine to run the module and
  43 report the results.
  44
  45 The above usage case would look something like this:
  46
  47 On the development machine:
  48 # vi pmod.stp
  49 (The systemtap developer writes the systemtap script.)
  50
  51 # stap -m pmod pmod.stp
  52 (The systemtap developer compiles and runs the script.  If necessary,
  53 the script may need to be edited to fix any errors.)
  54
  55 # scp pmod.ko prod_machine:/lib/modules/`uname -r`/systemtap
  56 (The systemtap developer copies the compiled kernel module to the proper
  57 directory on the production machine.  Of course other methods - ftp,
  58 nfs, etc. could be used to transfer the module.)
  59
  60 On the production machine:
  61 $ staprun pmod
  62 (The systemtap user runs the newly developed systemtap kernel module.)
  63
  64 There are (at least) 2 different usage scenarios for the
  65 /lib/modules/VERSION/systemtap directory.
  66
  67 1) Most restrictive usage.  If only root should be able to add
  68 "approved" systemtap modules to /lib/modules/VERSION/systemtap, the
  69 permissions should be 755, like this:
  70
  71 drwxr-xr-x 2 root root 4096 2007-08-07 13:54 systemtap/
  72
  73 2) More permissive usage.  If all systemtap developers should be able
  74 to add "approved" systemtap modules to /lib/modules/VERSION/systemtap,
  75 its permissions should be 775 (and be owned by root, group stapdev),
  76 like this:
  77
  78 drwxrwxr-x 2 root stapdev 4096 2007-08-07 13:54 systemtap/
  79
  80 INTERNALS
  81 =========
  82
  83 To accomplish the new security model, staprun has been split into two
  84 programs: staprun and stapio.
  85
  86 Here is a description of a typical systemtap session.  The staprun
  87 program is a setuid program that does some system setup, loads the
  88 kernel module, then runs stapio (and waits for it to finish).  The
  89 stapio program runs as the invoking user and is responsible for all
  90 communication with the kernel module.  After the script runs to
  91 completion, stapio fork/execs staprun -d to unload the kernel module.
  92
  93 staprun is a setuid program.  It holds on to the root privileges only
  94 for the least amount of time (as required to verify/load compiled
  95 kernel module files).  It invokes only stapio, and only as the
  96 original (unprivileged) user.
  97