staprun - systemtap runtime




   The  staprun program is the back-end of the Systemtap tool.  It expects
   a kernel module produced by the front-end stap tool.

   Splitting the systemtap tool into a front-end and a back-end  allows  a
   user  to  compile  a systemtap script on a development machine that has
   the kernel development tools (needed to compile the  script)  and  then
   transfer  the  resulting  kernel  module  to  a production machine that
   doesn't have any development tools installed.

   Please refer to stappaths (7) for the version number,  or  run  rpm  -q
   systemtap (fedora/red hat) apt-get -v systemtap (ubuntu)


   The  staprun  program supports the following options.  Any other option
   prints a list of supported options.

   -v     Verbose mode.  The  level  of  verbosity  is  also  set  in  the
          SYSTEMTAP_VERBOSE environment variable.

   -V     Print version number and exit.

   -w     Suppress warnings from the script.

   -u     Load the uprobes.ko module.

   -c CMD Command  CMD  will be run and the staprun program will exit when
          CMD does.  The '_stp_target' variable will contain the  pid  for

   -x PID The '_stp_target' variable will be set to PID.

   -o FILE
          Send  output  to  FILE. If the module uses bulk mode, the output
          will be in percpu files FILE_x(FILE_cpux in background and  bulk
          mode)  where  'x'  is  the cpu number. This supports strftime(3)
          formats for FILE.

          The systemtap module will specify a buffer  size.   Setting  one
          here  will  override  that value. The value should be an integer
          between 1 and 4095 which be assumed to be the buffer size in MB.
          That value will be per-cpu if bulk mode is used.

   -L     Load  module  and  start  probes,  then  detach  from the module
          leaving the probes running.  The module can be attached to later
          by using the -A option.

   -A     Attach to loaded systemtap module.

   -C WHEN
          Control coloring of error messages. WHEN must be either "never",
          "always", or "auto" (i.e. enable only if at a terminal). If  the
          option  is  missing,  then  "auto"  is  assumed.  Colors  can be
          modified using the SYSTEMTAP_COLORS  environment  variable.  See
          the  stap(1)  manual  page  for  more  information on syntax and

   -d     Delete a module.  Only detached or unused modules the  user  has
          permission to access will be deleted. Use "*" (quoted) to delete
          all unused modules.

   -D     Run staprun in background as a daemon and show it's pid.

   -R     Rename the module to a unique name before inserting it.

   -r N:URI
          Pass the given number and  URI  data  to  the  tapset  functions
          remote_id() and remote_uri().

   -S size[,N]
          Sets  the  maximum size of output file and the maximum number of
          output files.  If the size of output file  will  exceed  size  ,
          systemtap  switches  output  file  to  the next file. And if the
          number of output files exceed N , systemtap removes  the  oldest
          output file. You can omit the second argument.

   -T timeout
          Sets  maximum  time reader thread will wait before dumping trace
          buffer. Value is in ms, default is 200ms. Setting this to a high
          value decreases number of stapio wake-ups, allowing deeper sleep
          for embedded platforms. But it impacts interactivity on terminal
          as  traces  are  dumped  less  often  in case of low throughput.
          There  is  no  interactivity  or  performance  impact  for  high
          throughput  as  trace is dumped when buffer is full, before this
          timeout expires.

          Sets the value of global variable var1 to val. Global  variables
          contained  within a module are treated as module options and can
          be set from the staprun command line.


   MODULE is either a module path or a module name.  If  it  is  a  module
   name,  the  module will be looked for in the following directory (where
   'VERSION' is the output of "uname -r"):


   Any additional arguments on the command line are passed to the  module.
   One  use  of  these  additional module arguments is to set the value of
   global variables declared within the module.

    $ stap -p4 -m mod1 -e 'global var1="foo";  probe  begin{printf("%s\n",
   var1); exit()}'

   Running this with an additional module argument:

    $ staprun mod1.ko var1="HelloWorld"

   Spaces  and  exclamation  marks  currently cannot be passed into global
   variables this way.


   See the stapex(3stap) manual page for a collection of sample scripts.

   Here is a very basic example of how to use staprun.  First, use stap to
   compile  a  script.   The  stap program will report the pathname to the
   resulting module.

    $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'

   Run staprun with the pathname to the module as an argument.

    $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
    Hello World!


   After the staprun program installs a Systemtap kernel module, users can
   detach  from the kernel module and reattach to it later.  The -L option
   loads the module and automatically detaches.   Users  can  also  detach
   from the kernel module interactively by sending the SIGQUIT signal from
   the keyboard (typically by typing Ctrl-\).

   To reattach to a kernel module, the staprun -A option would be used.


   After staprun launched the stapio program,  users  can  command  it  to
   switch  output  file  to  next file when it outputs to file(s) (running
   staprun with -o option) by sending  a  SIGUSR2  signal  to  the  stapio
   process.  When  it  receives SIGUSR2, it will switch output file to new
   file with suffix .N where N is the sequential number.  For example,

    $ staprun -o foo ...

   outputs trace logs to  foo  and  if  it  receives  SIGUSR2  signal,  it
   switches output to foo.1 file. And receiving SIGUSR2 again, it switches
   to foo.2 file.


   Systemtap,  in  the  default  kernel-module   runtime   mode,   is   an
   administrative  tool.   It  exposes kernel internal data structures and
   potentially private user information.  See the stap(1) manual page  for
   additional information on safety and security.

   To increase system security, users of systemtap must be root, or in the
   staprun group in order to execute this setuid staprun program.  A  user
   may  select  a  particular  privilege  level with the stap --privilege=
   option, which staprun will later enforce.

          Members of the stapdev group can write and load  script  modules
          with  root-equivalent  privileges,  without  particular security
          constraints.  (Many safety constraints remain.)

          Members of the stapsys group have almost all the  privileges  of
          stapdev, except for guru mode constructs.

          Members  only  of  the  stapusr group may any-privileged modules
          placed into the  /lib/modules/VERSION/systemtap  by  the  system

          Members  only  of the stapusr group may also write and load low-
          privilege  script  modules,  which  are  normally   limited   to
          manipulating  their  own processes (and not the kernel nor other
          users' processes).

   Part of the privilege enforcement mechanism may require using  a  stap-
   server  and  administrative  trust in its cryptographic signer; see the
   stap-server(8) manual page for a for more information.

   On a kernel with FIPS mode enabled, staprun normally refuses to attempt
   to  load  systemtap-generated  kernel modules.  This is because on some
   kernels, this results in a panic.  If your kernel includes  corrections
   such  as  linux  commit  #002c77a48b47,  then  you can force staprun to
   attempt  module  loads  anyway,  by  setting   the   STAP_FIPS_OVERRIDE
   environment variable to any value.


          If  MODULE  is  a  module name, the module will be looked for in
          this directory.  Users who are only in the 'stapusr'  group  can
          install  modules located in this directory.  This directory must
          be owned by the root user and not be world writable.


   stap(1), stapprobes(3stap), stap-server(8), stapdyn(8), stapex(3stap)


   Use the Bugzilla link of the project web  page  or  our  mailing  list., <>.



Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.