Edit File: README.unprivileged
Unprivileged Mode for Systemtap Users ===================================== Introduction ------------ In order to use the full capabilities of systemtap, one must run it as root or as a member of the groups stapusr and stapdev. For other (unprivileged) users, systemtap does provide support for use of a subset of systemtap's capabilities to perform limited probing. For example, tracing your own applications or polling using timers. The intent is to give unprivileged users capabilities similar to those provided by a debugger. Below are instructions for running systemtap scripts in unprivileged mode. Systemtap Compile Server ------------------------ In order to load the kernel module produced by compiling a systemtap script for an unprivileged user, we must know that the script was compiled correctly and that the script does not do anything dangerous. A systemap compile server provides the trusted compilation environment needed to certify both conditions. NOTE: In order to use a compile server, the nss and nspr packages must be installed on the client host and systemtap must have been built with NSS enabled. Run 'stap -V | grep NSS' to find out if NSS is enabled. NOTE: In order to detect servers on the local network, the avahi package must be installed on the client host and systemtap must have been built with avahi enabled. Run 'stap -V | grep AVAHI' to find out if avahi is enabled. To find out if a suitable server is available on the local network, this command should produce output similar to the following: # stap --list-servers --privileged=stapusr Systemtap Compile Server Status for 'online,trusted,compatible,signer' host=somehost ip=10.15.16.156 port=10913 sysinfo="2.6.34.7-66.fc13.x86_64 x86_64" certinfo="00:93:49:be:2a" NOTE: In order for servers to be detected, the port for mDNS (5353/udp) must be open on the server and client hosts. If no servers are listed, then you must ask your system administrator to make the appropriate compile server available on the local host or on the local network. The server must be trusted as an ssl peer and as a systemtap module signer on the local host. See "Setup and Administration of Unprivileged Users for System Administrators" below for more details. Trust of Unprivileged Users --------------------------- Even with the appropriate compile server available, each unprivileged user must be explicitly trusted. This is done by adding each unprivileged user to the group stapusr and possibly the group stapsys on each host on which they will run systemtap scripts. To see if you are a member of the group stapusr on the local host, this command should produce output similar to the following: # getent group stapusr stapusr:x:483:someuser,anotheruser If your userid is listed, then you are already a member of the group stapusr. If it is not, then you must ask your system administrator to add you to this group. Once added, Try the command newgrp stapusr to activate your membership. If all else fails, logging out and back in again should work. See the manual page for newgrp(1) for details. Using Systemtap in Unprivileged Mode ------------------------------------ Unprivileged users can compile any systemtap script either directly or using a compile server, but systemtap will not load the resulting kernel module for an unprivileged user unless it has been compiled and certified by a trusted compile server. To do this, as an unprivileged user, this command should produce output similar to the following: # stap -e 'probe begin { printf ("Hello\n"); exit (); }' Hello For unprivileged users, stap will automatically add the options --privilege and --use-server (you could also specify them yourself). --use-server tells systemtap to compile the script using a server. --privilege tells the server to check the script to maker sure it doesn't do anything 'dangerous', i.e. nothing that a user with the specified privilege credentials shouldn't be able to do. If the server approves of your script and is able to compile it, systemtap will then load the resulting module for you even though you are an unprivileged user. If you save the resulting module by using the -p4 option of stap, then trusted, unprivileged users can load the module at a later time using staprun: # stap -e 'probe begin { printf ("Hello\n"); exit (); }' -p4 stap_5330.ko # staprun stap_5330.ko Hello Note that the module has already been certified (signed), so no special options are needed. Additional Information ---------------------- o When specifying path names in your script and compiling using a server, you must use a server which has access to those paths (e.g. via nfs, or a server on the local host) and you must specify the paths in full from the servers's point of view. For example, specify probe process("foo").begin() as probe process("/the/full/path/as/seen/by/the/server/to/foo").begin() o You can use '--privilege=[stapusr|stapsys] -pN' (for 1 <= N <= 4) without --use-server to compile and check scripts directly. stap will still check your script for 'dangerous' behavior, but will not load it for an unprivileged user. o When using --privilege, all compile time and run time restrictions are enforced for all users, including root and members of the group stapdev. Setup and Administration of Unprivileged Users for System Administrators ======================================================================== Introduction ------------ In order to use the full capabilities of systemtap, one must run it as root or as a member of the group stapdev. For other (unprivileged) users, systemtap does provide support for use of a subset of systemtap's capabilities to perform limited probing. For example, tracing your own applications or polling using timers. The intent is to give unprivileged users capabilities similar to those provided by a debugger. In order for this to happen, the system administrator must first perform some setup: o Systemtap compile server(s) must be made available on the local network. One server is needed for each kernel version and architecture pair for which users will compile scripts. o The compile server(s) must be trusted as an SSL peer and as a signer of systemtap modules on hosts on which unprivileged users will compile and run their scripts respectively. o Unprivileged users must be added to the group stapusr, and possibly the group stapsys on the host(s) on which they will run their scripts. Below are the necessary steps for the system administrator to setup the above infrastructure. Systemtap Compile Server ------------------------ In order to load the kernel module produced by compiling a systemtap script for an unprivileged user, we must know that the script was compiled correctly and that the script does not do anything dangerous. A systemap compile server provides a trusted environment needed to certify both conditions. In order to make a compile server available on the local network the systemtap-server package and its prerequisites must be installed on the server host. The system administrator then uses the following command: sudo service stap-server start [-r KERNEL-RELEASE] [-a ARCH] For example: # sudo service stap-server start -r 2.6.34.7-61.fc13.x86_64 -a x86_64 Starting stap-server -a "x86_64" -r "2.6.34.7-61.fc13.x86_64" -u "stap-server" [ OK ] This starts a compile server for the specified kernel release and hardware architecture. The kernel and kernel-devel package for the specified release and architecture must be installed on the server host. The kernel-debuginfo package for each kernel release and architecture should also be installed, but is not relevant for unprivileged users. If either one (or both) the kernel release and/or architecture is not specified, the kernel release and/or architecture of the server host will be used: # sudo service stap-server start Starting stap-server -a "x86_64" -r "2.6.34.7-66.fc13.x86_64" -u "stap-server" [ OK ] As a short cut, to start a server for each kernel release and architecture installed on the server host, use the command: # sudo service stap-server start -i Starting stap-server -a "x86_64" -r "2.6.34.7-61.fc13.x86_64" -u "stap-server" [ OK ] Starting stap-server -a "x86_64" -r "2.6.34.7-63.fc13.x86_64" -u "stap-server" [ OK ] Starting stap-server -a "x86_64" -r "2.6.34.7-66.fc13.x86_64" -u "stap-server" [ OK ] NOTE: Only root can start a systemtap server using the service command. Trust of Compile Servers ------------------------ Once systemtap compile servers have been made available on the local network, the system administrator must certify which ones are trusted as SSL peers, as systemtap kernel module signers or both. Certifying a compile server as an SSL peer means what the system administrator trusts that it compiles systemtap scripts correctly. Certifying a compile server as a module signer means that the system administrator trusts it to correctly check a systemtap script for behavior which should not be made available to unprivileged users. When a script is compiled using the --privilege option, the server checks the script for such behavior and cryptographically signs the resulting module if it is safe for use by unprivileged users. Verification of the signature certifies that the module was certified as 'safe' by the server and that it has not been altered since it was certified. Systemtap compile servers started by using the 'service' command are automatically trusted both as SSL peers and as module signers on the server's host. No further setup of the servers is necessary for users (clients) on that same host. Before clients on another host can make use of a server, the system administrator of each client host must certify trust in that server. This is performed in two steps: 1) Identify the server(s) to be trusted. # stap --list-servers=online,compatible Systemtap Compile Server Status for 'online,compatible' host=somehost ip=10.15.16.156 port=26543 sysinfo="2.6.34.7-66.fc13.x86_64 x86_64" certinfo="00:93:49:be:2a" Identify the server(s) to be trusted by examining the host name, ip address and sysinfo (kernel release and architecture). Take note of the 'certinfo' field of each server to be trusted. NOTE: In order for servers to be detected, the port for mDNS (5353/udp) must be open on the server and client hosts. 2) For each server to be trusted for use by unprivileged clients, use the command: sudo stap --trust-servers=ssl,signer,all-users --use-server=CERTINFO1 [--use-server=CERTINFO2 ...] where each CERTINFOn is the value of the 'certinfo' field of a server to be trusted (obtained using the previous command). For example: # sudo stap --trust-servers=ssl,signer,all-users --use-server=00:93:49:be:2a Add trust in the following servers as an SSL peer for all users and as a module signer for all users? host=somehost ip=10.15.16.156 port=26543 sysinfo="2.6.34.7-66.fc13.x86_64 x86_64" certinfo="00:93:49:be:2a" [y/N] y Using the 'certinfo' to specify each server ensures that the exact servers which were intended are the ones which become trusted. Note that only root can certify trust in a server as signer in this way. Now verify the result: # stap --list-servers --privilege=stapusr Systemtap Compile Server Status for 'online,trusted,compatible,signer' host=somehost ip=10.15.16.156 port=26543 sysinfo="2.6.34.7-66.fc13.x86_64 x86_64" certinfo="00:93:49:be:2a" Each of the servers you specified in stap 2 above should be listed. Trust of Unprivileged Users --------------------------- Finally, once compile servers have been set up and are trusted, each unprivileged user must be explicitly trusted. This is done by adding each unprivileged user to the group stapusr, and possibly the group stapsys on each host on which they will run systemtap scripts: sudo usermod -a -G stapusr[,stapsys] USERID If the user is already logged in, they can try using newgrp stapusr to activate their membership. If all else fails, logging out and back in again should work. See newgrp(1) for details.