From d42c3ab0f448c9ca90fab4c3fbac0fc47bb5f090 Mon Sep 17 00:00:00 2001 From: Dave Brolley Date: Wed, 6 Jul 2011 10:26:52 -0400 Subject: [PATCH] PR 12955 - unprivileged mode elaboration in man pages etc Document the actual restrictions enforced at translation time and at run time for unprivileged users. --- README.unprivileged | 2 +- stap.1 | 217 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 215 insertions(+), 4 deletions(-) diff --git a/README.unprivileged b/README.unprivileged index 8fc7f7f6f..4afdf0bc2 100644 --- a/README.unprivileged +++ b/README.unprivileged @@ -207,7 +207,7 @@ 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 compile systemtap scripts correctly. +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 diff --git a/stap.1 b/stap.1 index 1b887d18d..b64082e5a 100644 --- a/stap.1 +++ b/stap.1 @@ -300,7 +300,8 @@ seems to be misbehaving. .TP .BI \-\-unprivileged This option instructs \fIstap\fR to examine the script looking for constructs -which are not allowed for unprivileged users. Compilation fails if any such +which are not allowed for unprivileged users (see \fIUNPRIVILEGED USERS\fR). +Compilation fails if any such constructs are used. If this option is specified when using a compile server (see \fI\-\-use\-server\fR), @@ -1348,7 +1349,7 @@ and groups can build and run any systemtap script. Members of the .I stapusr -group can only use pre-built modules under the following conditions: +group can only use pre\-built modules under the following conditions: .IP \(bu 4 The module is located in the /lib/modules/VERSION/systemtap directory. This directory @@ -1358,7 +1359,7 @@ The module has been signed by a trusted signer. Trusted signers are normally systemtap compile\-servers which sign modules when the \-\-unprivileged option is specified by the client. See the .IR stap\-server (8) -manual page for a for more information. +manual page for more information. .PP The kernel modules generated by .I stap @@ -1507,6 +1508,216 @@ By default, overload processing is turned on for all modules. If you would like to disable overload processing, define STP_NO_OVERLOAD (or its alias STAP_NO_OVERLOAD). +.SH UNPRIVILEGED USERS + +Systemtap exposes kernel internal data +structures and potentially private user information. Because of this, use of +systemtap's full capabilities are restricted to root and to users who are +members of the groups stapdev and stapusr. + +However, a restricted set of systemtap's features can be made available to +trusted, unprivileged users. These users are members of the group stapusr +only. These users can load systemtap modules which have been compiled and +certified by a trusted systemtap compile\-server. See the descriptions of the +options \fI\-\-unprivileged\fR and \fI\-\-use\-server\fR. See +\fIREADME.unprivileged\fR in the systemtap source code for information about +setting up a trusted compile server. + +The restrictions enforced when \fI\-\-unprivileged\fR is specified are designed +to prevent unprivileged users from: +.RS +.IP \(bu 4 +harming the system maliciously. +.IP \(bu 4 +gaining access to information which would not normally be available to an +unprivileged user. +.IP \(bu 4 +disrupting the performance of processes owned by other users of the system. +Some overhead to the system in general is unavoidable since the +unprivileged user's probes +will be triggered at the appropriate times. What we would like to avoid is +targeted interruption of another user's processes which would not normally be +possible by an unprivileged user. +.RE + +.SS PROBE RESTRICTIONS +An unprivileged user may only use the following probes: + +.RS +.IP \(bu 4 +begin, begin(n) +.IP \(bu 4 +end, end(n) +.IP \(bu 4 +error(n) +.IP \(bu 4 +never +.IP \(bu 4 +process.*, where the target process is owned by the user. +.IP \(bu 4 +timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)* +.IP \(bu 4 +timer.hz(n) +.RE + +.SS SCRIPTING LANGUAGE RESTRICTIONS +The following scripting language features are unavailable to unprivileged users: + +.RS +.IP \(bu 4 +any feature enabled by the Guru Mode (-g) option. +.IP \(bu 4 +embedded C code. +.RE + +.SS RUNTIME RESTRICTIONS +The following runtime restrictions are placed upon unprivileged users: + +.RS +.IP \(bu 4 +Only the default runtime code (see \fI-R\fR) may be used. +.IP \(bu 4 +Probing of processes owned by other users is not permitted. +.IP \(bu 4 +Access of kernel memory (read and write) is not permitted. +.RE + +.SS COMMAND LINE OPTION RESTRICTIONS +Some command line options provide access to features which must not be available +to unprivileged users: + +.RS +.IP \(bu 4 +-g may not be specified. +.IP \(bu 4 +The following options may not be used by the compile-server client: +.SAMPLE + -a, -B, -D, -I, -r, -R +.ESAMPLE +.RE + +.SS ENVIRONMENT RESTRICTIONS +The following environment variables must not be set: +.SAMPLE + +SYSTEMTAP_RUNTIME +SYSTEMTAP_TAPSET +SYSTEMTAP_DEBUGINFO_PATH +.ESAMPLE + +.SS TAPSET RESTRICTIONS +The following built-in tapset functions are unconditionally available to unprivileged +users: +.SAMPLE + +_ehostunreach:long () +_enetunreach:long () +_icmp_dest_unreach:long () +_icmp_exc_fragtime:long () +_icmp_prot_unreach:long () +_icmp_time_exceeded:long () +_MM_ANONPAGES:long() +_MM_FILEPAGES:long() +_net_rx_drop:long () +_rtn_broadcast:long () +_rtn_multicast:long () +_rtn_unspec:long () +_sys_pipe2_flag_str:string (f:long) +AF_INET:long() +cpu:long () +cputime_to_msecs:long (cputime:long) +egid:long () +error (msg:string) +euid:long () +execname:string () +exit () +get_cycles:long () +gettimeofday_ns:long () +GFP_KERNEL:long() +gid:long () +HZ:long () +is_myproc:long () +isdigit:long(str:string) +isinstr:long(s1:string,s2:string) +jiffies:long () +log (msg:string) +mem_page_size:long () +module_name:string () +pexecname:string () +pgrp:long () +pid:long () +pn:string () +pp:string () +ppid:long () +randint:long(n:long) +registers_valid:long () +sid:long () +str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) +stringat:long(str:string, pos:long) +strlen:long(s:string) +strtol:long(str:string, base:long) +substr:string(str:string,start:long, length:long) +target:long () +task_utime:long () +task_stime:long () +text_str:string(input:string) +text_strn:string(input:string, len:long, quoted:long) +tid:long () +tokenize:string(input:string, delim:string) +tz_gmtoff() { +tz_name() { +uid:long () +user_mode:long () +warn (msg:string) +.ESAMPLE + +The following built-in tapset functions are available to unprivileged users +within their own processes. Scripts written by unprivileged users must test the +result of the tapset function \fIis_myproc\fR and only call these functions if +the result is 1. The script will exit immediately if any of these functions is +called by an unprivileged user within a probe within a process which is not +owned by that user. +.SAMPLE + +_utrace_syscall_nr:long () +_utrace_syscall_arg:long (n:long) +_utrace_syscall_return:long () +print_ubacktrace () +print_ubacktrace_brief () +print_ustack(stk:string) +sprint_ubacktrace:string () +uaddr:long () +ubacktrace:string () +umodname:string (addr:long) +user_char:long (addr:long) +user_char_warn:long (addr:long) +user_int:long (addr:long) +user_int_warn:long (addr:long) +user_int16:long (addr:long) +user_int32:long (addr:long) +user_int64:long (addr:long) +user_int8:long (addr:long) +user_long:long (addr:long) +user_long_warn:long (addr:long) +user_short:long (addr:long) +user_short_warn:long (addr:long) +user_string_quoted:string (addr:long) +user_string_n_quoted:string (addr:long, n:long) +user_string_n_warn:string (addr:long, n:long) +user_string_n2:string (addr:long, n:long, err_msg:string) +user_string_warn:string (addr:long) +user_string2:string (addr:long, err_msg:string) +user_uint16:long (addr:long) +user_uint32:long (addr:long) +user_uint8:long (addr:long) +user_ushort:long (addr:long) +user_ushort_warn:long (addr:long) +usymdata:string (addr: long) +usymname:string (addr: long) +.ESAMPLE + +No other built-in tapset functions may be used by unprivileged users. + .\" PR6864: disable temporarily .\".SH MAKING DO WITH SYMBOL TABLES .\"Systemtap performs best when it has access to the debugging information -- 2.43.5