<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.3. Running SystemTap Scripts</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css" /><meta name="generator" content="publican 1.6" /><meta name="package" content="Systemtap-SystemTap_Beginners_Guide-1.0-en-US-2.0-2" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="using-systemtap.html" title="Chapter 2. Using SystemTap" /><link rel="prev" href="cross-compiling.html" title="2.2. Generating Instrumentation for Other Computers" /><link rel="next" href="understanding-how-systemtap-works.html" title="Chapter 3. Understanding How SystemTap Works" /></head><body class=""><p id="title"><a class="left" href="http://www.fedoraproject.org"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="http://docs.fedoraproject.org"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="cross-compiling.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="understanding-how-systemtap-works.html"><strong>Next</strong></a></li></ul><div class="section" title="2.3. Running SystemTap Scripts"><div class="titlepage"><div><div><h2 class="title" id="using-usage">2.3. Running SystemTap Scripts</h2></div></div></div><a id="id2797922" class="indexterm"></a><a id="id2922776" class="indexterm"></a><a id="id3036408" class="indexterm"></a><a id="id3112439" class="indexterm"></a><a id="id3804799" class="indexterm"></a><a id="id2828427" class="indexterm"></a><div class="para">
SystemTap scripts are run through the command <code class="command">stap</code>. <code class="command">stap</code> can run SystemTap scripts from standard input or from file.
</div><a id="id2936396" class="indexterm"></a><div class="para">
Running <code class="command">stap</code> and <code class="command">staprun</code> requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine.
</div><div class="para">
To allow ordinary users to run SystemTap without root access, add them to one of these user groups:
</div><div class="variablelist"><dl><dt><span class="term">stapdev</span></dt><dd><a id="id2957540" class="indexterm"></a><a id="id2726430" class="indexterm"></a><div class="para">
Members of this group can use <code class="command">stap</code> to run SystemTap scripts, or <code class="command">staprun</code> to run SystemTap instrumentation modules.
</div><div class="para">
Running <code class="command">stap</code> involves compiling SystemTap scripts into kernel modules and loading them into the kernel. This requires elevated privileges to the system, which are granted to <code class="command">stapdev</code> members. Unfortunately, such privileges also grant effective root access to <code class="command">stapdev</code> members. As such, you should only grant <code class="command">stapdev</code> group membership to users whom you can trust root access.
</div></dd><dt><span class="term">stapusr</span></dt><dd><a id="id3031035" class="indexterm"></a><a id="id2725735" class="indexterm"></a><div class="para">
Members of this group can only run <code class="command">staprun</code> to run SystemTap instrumentation modules. In addition, they can only run those modules from <code class="filename">/lib/modules/<em class="replaceable"><code>kernel_version</code></em>/systemtap/</code>. Note that this directory must be owned only by the root user, and must only be writable by the root user.
</div></dd></dl></div><div class="para">
Below is a list of commonly used <code class="command">stap</code> options:
</div><a id="id4379600" class="indexterm"></a><a id="id2729169" class="indexterm"></a><div class="variablelist"><a id="id3007364" class="indexterm"></a><dl><dt><span class="term">-v</span></dt><dd><div class="para">
Makes the output of the SystemTap session more verbose. You can repeat this option (for example, <code class="command">stap -vvv script.stp</code>) to provide more details on the script's execution. This option is particularly useful if you encounter any errors in running the script.
</div><div class="para">
For more information about common SystemTap script errors, refer to <a class="xref" href="errors.html" title="Chapter 5. Understanding SystemTap Errors">Chapter 5, <i>Understanding SystemTap Errors</i></a>.
</div></dd><dt><span class="term">-o <em class="replaceable"><code>filename</code></em></span></dt><dd><div class="para">
Sends the standard output to file (<em class="replaceable"><code>filename</code></em>).
</div></dd><dt><span class="term">-x <em class="replaceable"><code>process ID</code></em></span></dt><dd><div class="para">
Sets the SystemTap handler function <code class="command">target()</code> to the specified process ID. For more information about <code class="command">target()</code>, refer to <a class="xref" href="systemtapscript-handler.html#systemtapscript-functions" title="SystemTap Functions">SystemTap Functions</a>.
</div></dd><dt><span class="term">-c <em class="replaceable"><code>command</code></em></span></dt><dd><div class="para">
Sets the SystemTap handler function <code class="command">target()</code> to the specified command. Note that you must use the full path to the specified command; for example, instead of specifying <code class="command">cp</code>, use <code class="command">/bin/cp</code> (as in <code class="command">stap <em class="replaceable"><code>script</code></em> -c /bin/cp</code>). For more information about <code class="command">target()</code>, refer to <a class="xref" href="systemtapscript-handler.html#systemtapscript-functions" title="SystemTap Functions">SystemTap Functions</a>.
</div></dd><dt><span class="term">-e '<em class="replaceable"><code>script</code></em>'</span></dt><dd><div class="para">
Use <code class="command"><em class="replaceable"><code>script</code></em></code> string rather than a file as input for systemtap translator.
</div></dd></dl></div><div class="para">
You can also instruct <code class="command">stap</code> to run scripts from standard input using the switch <code class="command">-</code>. To illustrate:
</div><a id="id2691549" class="indexterm"></a><a id="id2983576" class="indexterm"></a><a id="id3068476" class="indexterm"></a><div class="example" id="stdinstap"><div class="example-contents"><pre class="programlisting">
echo "probe timer.s(1) {exit()}" | stap -
</pre></div><h6>Example 2.1. Running Scripts From Standard Input</h6></div><br class="example-break" /><div class="para">
<a class="xref" href="using-usage.html#stdinstap" title="Example 2.1. Running Scripts From Standard Input">Example 2.1, “Running Scripts From Standard Input”</a> instructs <code class="command">stap</code> to run the script passed by <code class="command">echo</code> to standard input. Any <code class="command">stap</code> options you wish to use should be inserted before the <code class="command">-</code> switch; for instance, to make the example in <a class="xref" href="using-usage.html#stdinstap" title="Example 2.1. Running Scripts From Standard Input">Example 2.1, “Running Scripts From Standard Input”</a> more verbose, the command would be:
</div><div class="para">
<code class="command">echo "probe timer.s(1) {exit()}" | stap -v -</code>
</div><div class="para">
For more information about <code class="command">stap</code>, refer to <code class="command">man stap</code>.
</div><div class="para">
To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use <code class="command">staprun</code> instead. For more information about <code class="command">staprun</code> and cross-instrumentation, refer to <a class="xref" href="cross-compiling.html" title="2.2. Generating Instrumentation for Other Computers">Section 2.2, “Generating Instrumentation for Other Computers”</a>.
</div><div class="note"><h2>Note</h2><div class="para">
The <code class="command">stap</code> options <code class="command">-v</code> and <code class="command">-o</code> also work for <code class="command">staprun</code>. For more information about <code class="command">staprun</code>, refer to <code class="command">man staprun</code>.
</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="cross-compiling.html"><strong>Prev</strong>2.2. Generating Instrumentation for Other Compute...</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="understanding-how-systemtap-works.html"><strong>Next</strong>Chapter 3. Understanding How SystemTap Works</a></li></ul></body></html>
