<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="using-systemtap">
	<title>Using SystemTap</title>
	<remark>
		short intro, contents of chapter
	</remark>
	<indexterm>
		<primary>Using SystemTap</primary>
	</indexterm>
	

	<para>
		This chapter instructs users how to install SystemTap, and provides an introduction on how to run SystemTap scripts.
	</para>	
	<xi:include href="Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="CrossInstrumenting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
	<section id="using-usage">
		<title>Running SystemTap Scripts</title>
		<remark>
			- basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter)
		</remark>
		
		<remark>
			- running systemtap scripts
		</remark>
<!--		
		<remark>- Tapsets: short intro on usage</remark>
		-->
<indexterm>
<primary>Usage</primary>
<secondary>running SystemTap scripts</secondary>
</indexterm>

<indexterm>
<primary>running SystemTap scripts</primary>
<secondary>Usage</secondary>
</indexterm>

<indexterm>
	<primary>Usage</primary>
	<secondary>stap</secondary>
</indexterm>

<indexterm>
	<primary>stap</primary>
	<secondary>Usage</secondary>
</indexterm>
<!-- next 2 indexterms for staprun -->

<indexterm>
	<primary>Usage</primary>
	<secondary>staprun</secondary>
</indexterm>

<indexterm>
	<primary>staprun</primary>
	<secondary>Usage</secondary>
</indexterm>
		<para>
			SystemTap scripts are run through the command <command>stap</command>. <command>stap</command> can run SystemTap scripts from standard input or from file.
		</para>
<!--		
<important>
	<title>Important</title>
<para>Running SystemTap requires root privileges. As such, you need to either log in as root or configure <command>sudo</command> accordingly for specific users who need to run SystemTap (refer to <command>man sudo</command> or <command>man visudo</command> for more information.</para> 

</important>
		-->

<!--<formalpara>
	<title>stapdev and stapusr</title>-->

<indexterm>
<primary>SystemTap scripts, how to run</primary>
</indexterm>
	<para>Running <command>stap</command> and <command>staprun</command> 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.</para>
<!-- </formalpara> -->

<para>To allow ordinary users to run SystemTap without root access, add them to one of these user groups:</para>

<variablelist>
	
<varlistentry>
	<term>stapdev</term>
	<listitem>
<indexterm>
<primary>Usage</primary>
<secondary>stapdev</secondary>
</indexterm>

<indexterm>
<primary>stapdev</primary>
<secondary>Usage</secondary>
</indexterm>
<para>
	Members of this group can use <command>stap</command> to run SystemTap scripts, or <command>staprun</command> to run SystemTap instrumentation modules. 
</para>	
	

<para>
	Running <command>stap</command> involves compiling SystemTap scripts into kernel modules and 
	loading them into the kernel. This requires elevated privileges to the system, which are granted 
	to <command>stapdev</command> members. Unfortunately, such privileges also grant effective root 
	access to <command>stapdev</command> members. As such, you should only grant  
	<command>stapdev</command> group membership to users whom you can trust root access.
</para>
	
	</listitem>
</varlistentry>

<varlistentry>
	<term>stapusr</term>
	<listitem>
<indexterm>
<primary>Usage</primary>
<secondary>stapusr</secondary>
</indexterm>

<indexterm>
<primary>stapusr</primary>
<secondary>Usage</secondary>
</indexterm>
<para>
	Members of this group can only run <command>staprun</command> to run SystemTap instrumentation modules. In addition, they can only run those modules from <filename>/lib/modules/<replaceable>kernel_version</replaceable>/systemtap/</filename>. Note that this directory must be owned only by the root user, and must only be writable by the root user.
</para>
</listitem>
</varlistentry>
</variablelist>		



		<para> Below is a list of commonly used <command>stap</command> options: </para>
<indexterm>
<primary>Usage</primary>
<secondary>options, stap</secondary>
</indexterm>

<indexterm>
<primary>options, stap</primary>
<secondary>Usage</secondary>
</indexterm>		
<variablelist>

<indexterm>
<primary>stap options</primary>
</indexterm>

<varlistentry>
	<term>-v</term>
	<listitem>
		<para>Makes the output of the SystemTap session more
		verbose. You can repeat this option (for example, <command>stap
		-vvv script.stp</command>) to provide more details on the script's execution. This option is particularly useful if you encounter any errors in running the script.</para>
		
		<para>For more information about common SystemTap script errors, refer to <xref linkend="errors"/>.</para>
	</listitem>	
</varlistentry>	
	
<varlistentry>
	<term>-o <replaceable>filename</replaceable></term>
	<listitem>
		<para>Sends the standard output to file (<replaceable>filename</replaceable>).</para>
	</listitem>	
</varlistentry>	

<varlistentry>
	<term>-x <replaceable>process ID</replaceable></term>
	<listitem>
		<para>Sets the SystemTap handler function <command>target()</command> to the specified process ID. For more information about <command>target()</command>, refer to <xref linkend="systemtapscript-functions"/>.</para>
	</listitem>	
</varlistentry>

<varlistentry>
	<term>-c <replaceable>command</replaceable></term>
	<listitem>
		<para>Sets the SystemTap handler function <command>target()</command> to the specified command. Note that you must use the full path to the specified command; for example, instead of specifying <command>cp</command>, use <command>/bin/cp</command> (as in <command>stap <replaceable>script</replaceable> -c /bin/cp</command>). For more information about <command>target()</command>, refer to <xref linkend="systemtapscript-functions"/>.</para>
	</listitem>	
</varlistentry>	
<!--	
<varlistentry>
	<term></term>
	<listitem>
		<para></para>
	</listitem>	
</varlistentry>	
			-->
<varlistentry>
	<term>-e '<replaceable>script</replaceable>'</term>
	<listitem>
	  <para>Use <command><replaceable>script</replaceable></command>
	    string rather than a file as input for systemtap translator.</para>
	</listitem>
</varlistentry>
</variablelist>

<para>You can also instruct <command>stap</command> to run scripts from standard input using the switch <command>-</command>. To illustrate:</para>
<indexterm>
	<primary>Usage</primary>
	<secondary>standard input, running scripts from</secondary>
</indexterm>

<indexterm>
	<primary>standard input, running scripts from</primary>
	<secondary>Usage</secondary>
</indexterm>
<indexterm>
	<primary>running scripts from standard input</primary>
</indexterm>
<example id="stdinstap">
	<title>Running Scripts From Standard Input</title>
<programlisting>
echo "probe timer.s(1) {exit()}" | stap -
</programlisting>
</example>

<para><xref linkend="stdinstap"/> instructs <command>stap</command> to run the script passed by <command>echo</command> to standard input. Any <command>stap</command> options you wish to use should be inserted before the <command>-</command> switch; for instance, to make the example in <xref linkend="stdinstap"/> more verbose, the command would be:</para>

<para><command>echo "probe timer.s(1) {exit()}" | stap -v -</command></para>

<remark>any other useful options worth noting here for beginners?</remark>

<para>For more information about <command>stap</command>, refer to <command>man stap</command>.</para>

<para>To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use <command>staprun</command> instead. For more information about <command>staprun</command> and cross-instrumentation, refer to <xref linkend="cross-compiling"/>.</para>

<note>
	<title>Note</title>
	<para>The <command>stap</command> options <command>-v</command> and <command>-o</command> also work for <command>staprun</command>. For more information about <command>staprun</command>, refer to <command>man staprun</command>.</para>
</note>	

	</section>

</chapter>

