From f19a1ef476349c42861cfecf6dc5afdbedc9191f Mon Sep 17 00:00:00 2001
From: Jonathan Lebon <jlebon@redhat.com>
Date: Mon, 10 Feb 2014 10:20:56 -0500
Subject: [PATCH] man/systemtap.8.in: new man page to replace README

This man page replaces the README.systemtap text file. The content is
almost the same. A lot of rephrasing, some restructuring, and some
clarifications that weren't present in the original document.

- man/systemtap.8.in: new man page
- initscript/README.systemtap: remove it
- initscript/systemtap.in: add hint to man page

- configure.ac: add man/systemtap.8.in in AC_CONFIG_FILES macro
- man/Makefile.am: add systemtap.8 to man_MANS
- systemtap.spec: replace README by man page in systemtap-initscript pkg
  $files list
---
 configure.ac                |   2 +-
 initscript/README.systemtap | 447 --------------------------------------------
 initscript/systemtap.in     |   4 +-
 man/Makefile.am             |   2 +-
 man/systemtap.8.in          | 439 +++++++++++++++++++++++++++++++++++++++++++
 systemtap.spec              |   2 +-
 6 files changed, 445 insertions(+), 451 deletions(-)
 delete mode 100644 initscript/README.systemtap
 create mode 100644 man/systemtap.8.in

diff --git a/configure.ac b/configure.ac
index 3f22549..9cc1e50 100644
--- a/configure.ac
+++ b/configure.ac
@@ -682,7 +682,7 @@ AC_SUBST(STAP_PREFIX, "$stap_prefix")
 AC_CONFIG_HEADERS([config.h:config.in])
 AC_CONFIG_FILES([Makefile doc/Makefile man/Makefile \
 doc/beginners/Makefile doc/SystemTap_Tapset_Reference/Makefile \
-man/stappaths.7 \
+man/stappaths.7 man/systemtap.8 \
 initscript/config.systemtap initscript/config.stap-server \
 initscript/systemtap initscript/stap-server \
 initscript/99stap/module-setup.sh ])
diff --git a/initscript/README.systemtap b/initscript/README.systemtap
deleted file mode 100644
index 9dd1ee6..0000000
--- a/initscript/README.systemtap
+++ /dev/null
@@ -1,447 +0,0 @@
-Systemtap initscript
-Version 0.2.1
-Author: Masami Hiramatsu <mhiramat@redhat.com>
-
-INDEX
-=====
-1. Introduction
-2. Usage
-3. Files
-4. Configuration Format
-5. How to use
-
-1. Introduction
-===============
-Systemtap initscript aims to provide
-- running systemtap script as a service with dependency.
-- easy way to control(start/stop) those scripts individually.
-The dependency means that which user-defined systemtap script is required by
-other script (Here the scripts don't include tapsets). This dependency
-will be useful for users who use -DRELAY_HOST and -DRELAY_GUEST.
-
-2. Usage
-========
-2.1 Synopsis
-
-/sbin/service systemtap {start|stop|restart|status|compile|onboot|cleanup} \
-   [-r kernelrelease] [-o path.img] [-b] [-c config] [-R] [-y] [script(s)]
-
-2.2 Commands
- You have to specify one of the below commands.
-
-2.2.1 start
- Run script(s). If the script(s) is already started, the command will be
- ignored. If it fails to start, return FAIL. If AUTOCOMPILE option is 'yes'
- (see 4.1.9), this will try to compile or update the specified script when
- one of the below condition is true.
- - compiled cache file does not exist.
- - mtime (modified time stamp) of original script file is newer than compiled
-   script cache.
- - script options which is used when compiling(see 4.2.1) has been changed.
- - result of `uname -a` has been changed.
- If no scripts specified from command line, it starts all scripts in the script
- directory or the scripts specified by DEFAULT_START in config (see 4.1.10).
-
-2.2.2 stop
- Stop script(s). If the script(s) is already stopped, this will be ignored.
- If it fails to stop, return FAIL.
- If no scripts specified from command line, it stops all running scripts.
-
-2.2.3 restart
- Stop and start script(s) again.
-
-2.2.4 status
- Show running script(s) status and dependency.
-
-2.2.5 compile
- Compile script(s) on the specified kernel. This command takes '-r' option
- which specifies the release of the kernel(see 2.3.4) on which you would
- like to compile script(s). This command asks user whether it can overwrite
- existing caches.
-
-2.2.6 onboot
- Make script(s) part of the initramfs so that they are started earlier during
- the boot process. Only works on dracut-based systems. This command also takes
- the '-r' option. If '-r' is omitted, the initramfs is created for the running
- kernel. If '-o path.img' is given, the initramfs is created at 'path.img' (must
- be an absolute path).  Otherwise, defaults to '/boot/initramfs-KVER.img', where
- KVER is `uname -r` if the '-r' option is omitted, or the given kernel version
- otherwise.
-
- If the output file already exists, it is overwritten, unless the -b switch is
- given, in which case the file is appended '.bak' rather than overwritten. Note
- however that if a '.bak' version already exists, it will not be overwritten.
-
- If no scripts are specified on the command-line, the initramfs will be created
- without including any scripts at all (i.e. no extra systemtap files added).
-
- Warning: do not use the stap -o option with onboot scripts because the
- script is started before the root filesystem is even mounted. Increase the
- buffer size if more space is needed.
-
-2.2.7 cleanup
- Cleanup compiled script(s) from cache directory(see 3.4). This command also
- takes '-r' option. If '-r' option is omitted, cleanup all caches for running
- kernel. This command asks user whether it can remove caches.
-
-2.3 Options
- Systemtap initscript can have some options. However, since user can't pass
- these options on boot, these options are only for testing or managing scripts
- after booting.
-
-2.3.1 -c config_path
- You can specify configuration path of this initscript.
-
-2.3.2 script(s)
- You can specify individual scripts to the commands. If you omit to specify
- any script, systemtap initscript will execute the command with all scripts
- in the script directory (except 'start', 'stop', and 'onboot' commands, see
- 2.2.1, 2.2.2, and 2.2.6).
-
-2.3.3 -R
- If this option is specified, systemtap initscript will try to solve
- dependency of specified script(s). This option is always set if you don't
- specify any script(s) from command line.
-
-2.3.4 -r kernelrelease
- You can specify release version of the kernel(e.g. 2.6.26.1). This option
- is valid only with compile, onboot, and cleanup commands.
-
-2.3.5 -y
- Answer yes for all questions.
-
-2.3.6 -o path.img
- Specify the path of the initramfs image. Otherwise, the default is
- '/boot/initramfs-KVER.img', where KVER is `uname -r` if the '-r' option is
- omitted, or the given kernel version otherwise. This option is only valid with
- the onboot command.
-
-2.3.7 -b
- If present, will backup an existing initramfs image by renaming it with a
- '.bak' extension. Otherwise, the initramfs is overwritten without backing up.
- This option is only valid with the onboot command.
-
-2.4 Misc
-2.4.1 Service Priority
- Each initscript has execution priority. Since user would like to trace
- other services by using systemtap, systemtap initscript should have the
- highest priority.
-
-3. Files
-========
-3.1 initscript
- /etc/init.d/systemtap
-
- This file is an executable bash script.
-
-3.2 Configurations
- Configuration files are written in bash script.
-
-3.2.1 Global config file
- /etc/systemtap/config
-
- This config file is for global parameters(see 4.1).
-
-3.2.2 Script config files
- /etc/systemtap/conf.d/*.conf
-
- The config files under this directory are for each scripts or script groups
- (see 4.2).
-
-3.3 Script directory
- /etc/systemtap/script.d/
-
- Systemtap initscript finds systemtap scripts from this directory.
-
-3.3.1 Scripts in the directory
- /etc/systemtap/script.d/<script-name>.stp
-
- Systemtap scripts stored in the script directory must have ".stp" suffix.
-
-3.4 Cache directory
- /var/cache/systemtap/<kernel-version>/
-
- Systemtap initscript stores compiled scripts in this directory.
-
-3.4.1 Compiled scripts (or script caches)
- /var/cache/systemtap/<kernel-version>/<script-name>.ko
- /var/cache/systemtap/<kernel-version>/<script-name>.opts
-
- *.ko file is the compiled script, and *.opts is the file which stores
- stap options and uname -a.
-
-3.5 Message Log
- /var/log/systemtap.log
-
- All messages including compilation errors and detailed messages are sent
- to this file.
- Some error and warning messages are also sent to console and syslogd (syslog
- output is optional, because this service will start before syslog).
-
-3.6 Status files
- /var/run/systemtap/<script-name>
-
-3.7 Dracut
- Files related to dracut/initramfs creation
-
-3.7.1 Dracut stap module directory
- /usr/lib/dracut/modules.d/99stap
-
- These files permit SystemTap modules to be included in the initramfs.
-
-4. Configuration Format
-=======================
-Configuration file allows us
-- specifying options for each script
-- supporting flight recorder mode (on file or memory)
-
-4.1 Global Parameters
-
-4.1.1 SCRIPT_PATH
- Specify the absolute path of the script directory.
- (default: /etc/systemtap/script.d)
-
-4.1.2 CONFIG_PATH
- Specify the absolute path of the script config directory.
- (default: /etc/systemtap/conf.d)
-
-4.1.3 CACHE_PATH
- Specify the absolute path of the parent directory of the cache directory.
- (default: /var/cache/systemtap)
-
-4.1.4 TEMP_PATH
- Specify the absolute path of the temporary directory on which systemtap
- initscript make temporary directories to compile scripts.
- (default: /tmp)
-
-4.1.5 STAT_PATH
- Specify the absolute path of the running status directory.
- (default: /var/run/systemtap)
-
-4.1.6 LOG_FILE
- Specify the absolute path of the log file
- (default: /var/log/systemtap.log)
-
-4.1.7 PASSALL
- If this is set 'yes', systemtap initscript will fail when it fails
- to run one of the scripts. If not, systemtap initscript will not
- fail(just warn).
- (default: yes)
-
-4.1.8 RECURSIVE
- If this is set 'yes', systemtap initscript will always follow script
- dependencies. This means, you don't need to specify '-R' option. This flag is
- effective only if you specify script(s) from command line.
- (default: no)
-
-4.1.9 AUTOCOMPILE
- If this is set 'yes', systemtap initscript automatically tries to compile
- specified script if there is no valid cache. Otherwise, it just fails to
- run script(s).
- (default: yes)
-
-4.1.10 DEFAULT_START
- Specify scripts which will be started by default. If omitted (or empty),
- all scripts in the script directory will be started.
- (default: "")
-
-4.1.11 ALLOW_CACHEONLY
- If this is set 'yes', systemtap initscript list up cache-only scripts too.
- *NOTE*: systemtap initscript will load unexpected obsolete caches with this
- option. You should check cache directory before enabling this option.
- (default: no)
-
-4.1.12 LOG_BOOT_ERR
- Because boot-time scripts are run before the root filesystem is mounted,
- staprun's stderr cannot be logged to the LOG_FILE as usual (see 4.1.6).
- However, the log can instead be output to /var/run/systemtap/$script.log (which
- is accessible at boot-time) by setting LOG_BOOT_ERR to 'yes'. If STAT_PATH is
- different from the default, the log files will be moved there upon executing
- any of the initscript commands.
-
-4.2 Script Parameters
-
-4.2.1 <script-name>_OPT
- Specify options passed to stap command for each script. "script-name" is the
- name of the script file without the suffix extension(.stp).
- Some options are just ignored. And even if you don't specify -F option,
- systemtap initscript always add it for flight recorder mode.
- - Below options are ignored when compiling script.
-   -p,-m,-r,-c,-x,-e,-s,-o,-h,-V,-k
- - Below options are ignored when starting script.
-   -h,-V,-v,-t,-p,-I,-e,-R,-r,-m,-k,-g,-P,-D,-b,-u,-q,-w,-l,-d,-L,-F, and
-   other long options.
-
-4.2.2 <script-name>_REQ
- Specify script dependency(which script this script requires).
- For example, "foo.stp" script requires(or run after) "bar.stp" script, set
-
- foo_REQ="bar"
-
- If the script requires many scripts, set all scripts separated by spaces.
-
- foo_REQ="bar baz"
-
-4.3 Configuration Example
-
-4.3.1 Global Config Example
----
-SCRIPT_PATH=/var/systemtap/script.d/
-PASSALL=yes
-RECURSIVE=no
----
-
-4.3.2 Script Config Example
----
-script1_OPT="-o /var/log/script1.out -DRELAYHOST=group1"
-script2_OPT="-DRELAYGUEST=group1"
-script2_REQ=script1
----
-
-5. How to use
-=============
-
-5.1 Package Installation
- After installing systemtap package, install systemtap-initscript package.
- # yum install systemtap-initscript
- This package will include initscript and default configuration file and
- other files.
-
-5.2 Script installation
-5.2.1 Installing script files
- Copy a systemtap script ("script1.stp") into script directory.
- # cp script1.stp /etc/systemtap/script.d/
-
-5.2.2 Configuration script options
- Add configuration file to specify options.
- # vi /etc/systemtap/conf.d/group1
- script1_OPT="-o /var/log/group1.log -DRELAYHOST=group1"
-
-5.2.3 Installing script file with dependency
- For example, a script("script2.stp") which shares buffer with another
- script("script1.stp"), there is a dependency. In this case, you just do
- as following.
-
- # cp script2.stp /etc/systemtap/script.d/
- # vi /etc/systemtap/conf.d/group1
- script2_OPT="-DRELAYGUEST=group1"
- script2_REQ=script1
-
- In this case, if stap fails to run script1.stp, systemtap initscript will
- not run script2.stp.
-
-5.3 Testing
- After installing all scripts, please make sure to run service successfully.
- # service systemtap start
- # service systemtap stop
- If there is no error, we are ready to use it.
-
-5.4 Service Enabling
- After all test passed, enable systemtap initscript.
- # chkconfig systemtap on
-
-5.5 Adding script
-5.5.1 Installing and configuring new scripts
- Copy new systemtap script("script3.stp") into script directory.
- # cp script3.stp /etc/systemtap/script.d/
- and configure it.
- # vi /etc/systemtap/conf.d/group1
- script3_OPT="-DRELAYGUEST=group1"
- script3_REQ="script1"
-
-5.5.2 Start new script
- If you've already started systemtap initscript, just start new script.
- # service systemtap start script3
-
-5.6 Deleting script
-5.6.1 Deleting old script
- Remove old script ("script2.stp") and remove configure lines
- # rm /etc/systemtap/script.d/script2.stp
- # vi /etc/systemtap/conf.d/group1
- (delete script2_OPT and script2_REQ)
-
-5.6.2 Stopping old script and cleanup
- Stop old script.
- # service systemtap stop script2
- And cleanup the script caches.
- # service systemtap cleanup script2
-
-5.7 Updating kernel
- Usually, you don't need to do anything. Systemtap initscript checks the
- kernel version when starting the service, and compile scripts.
- (If you would like to use compiled scripts due to lack of compiler or
-  debuginfo on the system, see 5.8)
- However, if you want to avoid compiling when booting system, you can prepare
- script caches for new kernel.
- # service systemtap compile -r <new kernel version>
-
-5.8 Using with compiled scripts
- Sometimes, production systems don't have any compilation environment. Even
- though, you can use systemtap initscript with compiled scripts as script
- caches, which are compiled on other machine (but same software environment).
-
-5.8.1 Preparing compiled scripts
- As described in 5.2, installing scripts and configure it on the compiling
- machine (which has compilation environment).
- After that, compile those scripts.
- # service systemtap compile -r <kernel-version>
- And package the compiled scripts and configuration file.
- # tar czf stap-scripts-<kernel-version>.tar.gz \
-   /var/cache/systemtap/<kernel-version> /etc/systemtap/conf.d/<config>
- And copy this package to the target machine.
-
-5.8.2 Installing pre-compiled scripts
- On the target machine, unpackage the compiled scripts into cache
- directory.
- # tar xzf stap-scripts-<kernel-version>.tar.gz -C /var/cache/systemtap/
- # mv /var/cache/systemtap/<config> /etc/systemtap/conf.d/
- At last, set AUTOCOMPILE=no and ALLOW_CACHEONLY=yes in config file.
- # vi /etc/systemtap/config
- AUTOCOMPILE=no
- ALLOW_CACHEONLY=yes
-
-5.9 Starting scripts during early-boot
- The initscript also allows you to start scripts earlier during the boot
- process by creating an initramfs containing the script's module. Your system
- must be dracut-based for this to work. Starting at this stage gives access to
- information otherwise very hard to obtain.
-
-5.9.1 Preparing the script
- As usual, place the script in /etc/systemtap/script.d and any configuration
- settings in /etc/systemtap/conf.d. (Note however that -o and -c are not
- supported).
-
-5.9.2 Adding to initramfs
- Simply run the command:
- # service systemtap onboot my_script
- If the script is not already compiled and cached, it will be done at this
- point.  A new initramfs will then be created at the default location. You can
- specify the '-b' option to make sure that your current initramfs is backed up.
- You can then restart your system. See 2.2.6 for more information regarding the
- onboot command.
-
-5.9.3 Adding to a different initramfs
- Rather than taking the spot of the default initramfs, you may want to create a
- different initramfs for a one-time boot. You can do this using the -o option:
- # service systemtap onboot -o /boot/special_initramfs.img
- Once the initramfs is created, you can change the command-line options at
- boot-time so that the new image is used rather than the usual one.
-
-5.9.4 Creating an initramfs for a different kernel
- Just like the compile command, you can use the -r option to specify the kernel
- for which you would like to create the initramfs. This is useful when you are
- about to upgrade and would like to prepare in advance. For example:
- # service systemtap onboot -r 3.12.6-200.fc19.x86_64 my_script
-
-5.9.5 Removing from initramfs
- To remove all scripts from the initramfs, you can run:
- # service systemtap onboot
- (That is, without any scripts explicitly mentioned). This will simply create
- a standard initramfs without any SystemTap modules inserted.
-
-5.9.6 Troubleshooting
- There can be many reasons for which the module didn't insert or did not work as
- expected. It may be useful to turn on dracut debugging by adding 'rdinitdebug' to
- the kernel command-line and checking dmesg/journalctl -ae. Also, you can
- capture the stderr output of staprun by setting LOG_BOOT_ERR to 'yes' (see
- 4.1.12).
diff --git a/initscript/systemtap.in b/initscript/systemtap.in
index 5290f56..21f9018 100755
--- a/initscript/systemtap.in
+++ b/initscript/systemtap.in
@@ -83,7 +83,7 @@ INITRAMFS=
 BACKUP_INITRAMFS=
 
 echo_usage () {
-  echo $"Usage: $prog {start|stop|status|restart|compile|onboot|cleanup|condrestart|try-restart|reload|force-reload} [option]"
+  echo $"Usage: $prog {start|stop|status|restart|compile|onboot|cleanup|condrestart|try-restart|reload|force-reload} [OPTIONS] [SCRIPTS]"
   echo $"Options:"
   echo $"	-b		: backup initramfs before overwriting"
   echo $"	-c configfile	: specify config file"
@@ -92,6 +92,8 @@ echo_usage () {
   echo $"	-R 		: recursively dependency checking"
   echo $"	-y 		: answer yes for all questions"
   echo $"	script(s)	: specify systemtap scripts"
+  echo $""
+  echo $"See systemtap(8) for full documentation"
 }
 
 #-----------------------------------------------------------------
diff --git a/man/Makefile.am b/man/Makefile.am
index b626481..ef0892e 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -4,7 +4,7 @@
 AUTOMAKE_OPTIONS = no-dist foreign
 
 man_MANS = stapprobes.3stap stapfuncs.3stap stapvars.3stap stapex.3stap \
-	dtrace.1 stap-merge.1 stappaths.7 stapsh.8
+	dtrace.1 stap-merge.1 stappaths.7 stapsh.8 systemtap.8
 
 # NB: this doesn't work, apparently because make doesn't like
 # file names with :: in them, misinterpreting them as some kind
diff --git a/man/systemtap.8.in b/man/systemtap.8.in
new file mode 100644
index 0000000..cea3868
--- /dev/null
+++ b/man/systemtap.8.in
@@ -0,0 +1,439 @@
+.\" -*- nroff -*-
+.TH SYSTEMTAP 8
+.SH NAME
+systemtap \- SystemTap initscript service
+
+.\" macros
+.de SAMPLE
+
+.nr oldin \\n(.i
+.br
+.RS
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+.in \\n[oldin]u
+
+..
+
+.SH SYNOPSIS
+.B service systemtap
+.IR COMMAND " [" OPTIONS "] [" SCRIPT ...]
+
+.SH DESCRIPTION
+The SystemTap initscript aims to provide a way to run scripts as a service and
+easily control them individually. Scripts can be configured to start upon manual
+request, or during system startup. On dracut-based systems, it is also possible
+to integrate scripts in the initramfs and have them start during early-boot.
+
+There are various parameters and options available to modify global behaviour,
+as well as script behaviour. Dependencies between scripts can be established so
+that starting one starts others (especially convenient when using the
+-DRELAY_HOST and -DRELAY_GUEST options of \fIstap\fR(1)).
+
+The configuration file of the initscript is located at
+\fB@sysconfdir@/systemtap/config\fR. Acceptable parameters are detailed in the
+GLOBAL PARAMETERS section.
+
+Scripts must be placed in the \fB@sysconfdir@/systemtap/script.d\fR directory
+and must have a \fB.stp\fR extension. When referring to them on the command-line
+however, there in no need to include the \fB.stp\fR extension. The scripts
+directory may be changed by setting the SCRIPT_PATH parameter in the
+configuration file.
+
+.SH COMMANDS
+One of the commands below must be specified:
+
+.TP
+.B start
+Start \fISCRIPT\fRs. If no scripts are specified, start the scripts specified by
+the DEFAULT_START configuration. If DEFAULT_START is not set, start all scripts
+in the script directory. For scripts already started, the command is ignored.
+The command will fail if the scripts fail to start (see also the PASSALL
+configuration).
+
+If the AUTOCOMPILE configuration is on, the command will try to compile or
+update the specified scripts when one of the below conditions is true:
+.RS
+.IP - 2
+The compiled cache file does not exist.
+.IP -
+The mtime (modified timestamp) of the original script file is newer than the
+time of the compiled script cache.
+.IP -
+The specified stap options used to compile the script has been changed (see
+also the SCRIPT PARAMETERS section).
+.IP -
+The result of `uname -a` has been changed.
+.RE
+
+.TP
+.B stop
+Stop \fISCRIPT\fRs. If no scripts are specified, stop all running scripts. For
+scripts already stopped, the command is ignored. The command will fail if the
+scripts fail to stop (see also the PASSALL configuration).
+
+.TP
+.B restart
+Stop and start \fISCRIPT\fRs.
+
+.TP
+.B status
+Show the state of \fISCRIPT\fRs and their dependencies.
+
+.TP
+.B compile
+Compile \fISCRIPT\fRs but do not start them. If the scripts have already been
+compiled, prompt for confirmation before overwriting cache. Compile for the
+current kernel, or the kernel release specified by the \fB-r\fR option.
+
+.TP
+.B onboot
+Make \fISCRIPT\fRs part of the initramfs so that they are started earlier during
+the boot process. This command is only available on dracut-based systems. If no
+scripts are specified, create a normal initramfs devoid of any SystemTap files.
+
+The initramfs is created for the current kernel, or the kernel release specified
+by the \fB-r\fR option. The path of the created initramfs defaults
+to \fB/boot/initramfs-KVER.img\fR, where KVER is the output of `uname -r`. Use
+the \fB-o\fR option to specify a different path.
+
+If the output file already exists, it is overwritten, unless the \fB-b\fR switch
+is given, in which case the file is appended \fB.bak\fR rather than overwritten.
+However, if there is already a \fB.bak\fR version of the file, the backup will
+not be overwritten.
+
+WARNING: do not use the \fB-o\fR option of \fIstap\fR(1) with onboot scripts
+because the script is started before the root filesystem is even mounted.
+Increase the buffer size if more space is needed.
+
+.TP
+.B cleanup
+Delete the compiled \fISCRIPT\fRs from cache. If no scripts are specified, then
+all compiled scripts are deleted. Only the cache for the current kernel is
+deleted, or the kernel release specified by the \fB-r\fR option. Prompt for
+confirmation before deleting.
+
+.SH OPTIONS
+Many of the commands can also take options. However, since users can't pass
+these options on boot, they are only meant for managing scripts after boot and
+for testing. Available options are:
+
+.TP
+.BI "-c " CONFIG_FILE
+Specify a different configuration file in place of the default one.
+
+.TP
+.B -R
+When using the \fBstart\fR and \fBstop\fR commands, also include the scripts'
+dependencies (recursively).
+
+.TP
+.BI "-r " KERNEL_RELEASE
+When using the \fBcompile\fR, \fBonboot\fR, and \fBcleanup\fR commands, specify
+the target kernel version rather than using the current one. Must be in the same
+format as `uname -r`.
+
+.TP
+.B -y
+Answer yes for all prompts.
+
+.TP
+.BI "-o " PATH.IMG
+When using the \fBonboot\fR command, specify the output path of the created
+initramfs.
+
+.TP
+.B -b
+When using the \fBonboot\fR command, backup an existing initramfs image by
+adding a \fB.bak\fR extension rather than overwriting it. Without this option,
+the initramfs is overwritten.
+
+.SH GLOBAL PARAMETERS
+These parameters affect the general behaviour of the SystemTap initscript
+service. They can be specified in the configuration file.
+
+.TP
+.B SCRIPT_PATH
+Specify the absolute path of the script directory. These are the scripts on
+which the initscript can operate. Scripts must have the \fB.stp\fR extension.
+The default path is \fB@sysconfdir@/systemtap/script.d\fR.
+
+.TP
+.B CONFIG_PATH
+Specify the absolute path of the script configuration directory. These
+configuration files contain options for specific scripts. They must have the
+\fB.conf\fR extension. The default path is \fB@sysconfdir@/systemtap/conf.d\fR.
+
+.TP
+.B CACHE_PATH
+Specify the absolute path of the cache directory. The default path is
+\fB@localstatedir@/cache/systemtap\fR.
+
+.TP
+.B TEMP_PATH
+Specify the absolute path of the temporary directory in which SystemTap
+makes temporary directories to compile scripts. The default path is \fB/tmp\fR.
+
+.TP
+.B STAT_PATH
+Specify the absolute path of the directory containing PID files used to track
+the status of SystemTap scripts. The default path is
+\fB@localstatedir@/run/systemtap\fR.
+
+.TP
+.B LOG_FILE
+Specify the absolute path of the log file. All messages are sent to this file,
+including compilation and runtime errors. The default path is
+\fB@localstatedir@/log/systemtap.log\fR.
+
+.TP
+.B PASSALL
+If this is set \fByes\fR, initscript commands that operate on multiple scripts
+will report as failed when the action could not be performed on at least one
+script. If set to \fBno\fR, only a warning is emitted. The default is \fByes\fR.
+
+.TP
+.B RECURSIVE
+If this is set \fByes\fR, the initscript will always follow script dependencies
+recursively. This means that there is no need to specify the \fB-R\fR option.
+This flag is effective only if you specify script(s) from the command-line. The
+default is \fBno\fR.
+
+.TP
+.B AUTOCOMPILE
+If this is set \fByes\fR, the initscript automatically tries to compile
+specified scripts when needed if there is no valid cache. Otherwise, the related
+command simply fails. The default is \fByes\fR.
+
+.TP
+.B DEFAULT_START
+Specify scripts which will be started by default. If omitted (or empty), all
+scripts in the script directory will be started. The default is \fB""\fR.
+
+.TP
+.B ALLOW_CACHEONLY
+If this is set \fByes\fR, the initscript will also allow operating on scripts
+that are located in the cache directory, but not in the script directory. The
+default is \fBno\fR.
+
+WARNING: the initscript may load unexpected obsolete caches with this option.
+The cache directory should be checked before enabling this option.
+
+.TP
+.B LOG_BOOT_ERR
+Because boot-time scripts are run before the root filesystem is mounted,
+staprun's stderr cannot be logged to the LOG_FILE as usual. However, the log
+can instead be output to /var/run/systemtap/$script.log by setting LOG_BOOT_ERR
+to \fByes\fR. If STAT_PATH is different from the default, the log files will be
+moved there upon executing any of the initscript commands. The default is
+\fBno\fR.
+
+.PP
+Here is a global configuration file example:
+.SAMPLE
+SCRIPT_PATH=/var/systemtap/script.d/
+PASSALL=yes
+RECURSIVE=no
+.ESAMPLE
+
+.SH SCRIPT PARAMETERS
+These parameters affect the compilation or runtime behaviour of specific
+SystemTap scripts. They must be placed in config files located in the
+CONFIG_PATH directory.
+
+.TP
+.B <SCRIPT>_OPT
+Specify options passed to the \fIstap\fR(1) command for the SCRIPT. Here, SCRIPT
+is the name of the script file without the \fB.stp\fR extension. Note that the
+\fB-F\fR option is always added.
+
+The following options are ignored when compiling scripts: -p, -m, -r, -c, -x,
+-e, -s, -o, -h, -V, -k.
+
+The following options are ignored when running starting scripts: -h, -V, -v, -t,
+-p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F, and all
+long options.
+
+.TP
+.B <SCRIPT>_REQ
+Specify script dependencies (i.e. which script this script requires). For
+example, if foo.stp requires (or needs to run after) bar.stp, set
+.SAMPLE
+foo_REQ="bar"
+.ESAMPLE
+Specify multiple scripts by separating their names by spaces.
+
+.PP
+Here is a script configuration file example:
+.SAMPLE
+script1_OPT="-o /var/log/script1.out -DRELAY_HOST=group1"
+script2_OPT="-DRELAY_GUEST=group1"
+script2_REQ="script1"
+.ESAMPLE
+
+.SH EXAMPLES
+
+.TP
+.B INSTALLING SCRIPTS
+We first copy a SystemTap script (e.g. "script1.stp") into the script directory:
+.SAMPLE
+\fB#\fR cp script1.stp /etc/systemtap/script.d/
+.ESAMPLE
+We can then set any script options, for example:
+.SAMPLE
+\fB#\fR vi /etc/systemtap/conf.d/group1
+script1_OPT="-o /var/log/group1.out -DRELAY_HOST=group1"
+.ESAMPLE
+If we then install a script (e.g. "script2.stp") which shares a buffer with
+script1, there is a dependency. In this case, we can do the following:
+.SAMPLE
+\fB#\fR cp script2.stp /etc/systemtap/script.d/
+\fB#\fR vi /etc/systemtap/conf.d/group1
+script2_OPT="-DRELAY_GUEST=group1"
+script2_REQ="script1"
+.ESAMPLE
+This way, if \fIstap\fR(1) fails to run script1, the initscript will not even
+try to run script2.
+
+.TP
+.B TESTING
+After installing scripts, we can test that they work by simply doing:
+.SAMPLE
+\fB#\fR service systemtap start
+\fB#\fR service systemtap stop
+.ESAMPLE
+We could be more specific as well, for example:
+.SAMPLE
+\fB#\fR service systemtap start script1
+\fB#\fR service systemtap stop script1
+.ESAMPLE
+If there were no errors, we are ready to use it.
+
+.TP
+.B ENABLING SERVICE
+After we're satisfied with the scripts and their tests, we can enable the
+SystemTap initscript service:
+.SAMPLE
+\fB#\fR chkconfig systemtap on
+.ESAMPLE
+
+.TP
+.B DELETING SCRIPTS
+Scripts are deleted by simply removing them from the script directory and
+removing any configuration lines specific to them:
+.SAMPLE
+\fB#\fR rm /etc/systemtap/script.d/script2.stp
+\fB#\fR vi /etc/systemtap/conf.d/group1
+.ESAMPLE
+If the script is still running, we also need to stop it:
+.SAMPLE
+\fB#\fR service systemtap stop script2
+.ESAMPLE
+We can then also remove the cache associated with the script:
+.SAMPLE
+\fB#\fR service systemtap cleanup script2
+.ESAMPLE
+
+.TP
+.B PREPARING FOR KERNEL UPDATES
+Usually, there is nothing to do when booting into a new kernel. The initscript
+will see that the kernel version is different and will compile the scripts. The
+compilation can be done beforehand as well to avoid having to compile during
+boot by using the \fB-r\fR option:
+.SAMPLE
+\fB#\fR service systemtap compile myscript -r <NEW_KERNEL_VERSION>
+.ESAMPLE
+
+.TP
+.B IMPORTING COMPILED SCRIPTS
+For environments which lack compilation infrastructure (e.g. no compilers or
+debuginfo), such as a production system, the scripts can be compiled on another
+(development) machine and then transferred over to the production system:
+.SAMPLE
+\fB#\fR service systemtap compile myscript -r \\
+.br
+>   <KERNEL_VERSION_OF_TARGET_MACHINE>
+\fB#\fR tar czf stap-scripts-<kernel-version>.tar.gz \\
+.br
+>   /var/cache/systemtap/<kernel-version> \\
+.br
+>   /etc/systemtap/conf.d/<configfile>
+.ESAMPLE
+And then copy this package to the target machine and extract it.
+
+.TP
+.B STARTING SCRIPTS DURING EARLY-BOOT
+The initscript also allows us to start scripts earlier during the boot process
+by creating an initramfs containing the script's module. The system must be
+dracut-based for this to work. Starting a script at this stage gives access to
+information otherwise very hard to obtain.
+
+We first install the script by copying it into the script directory as usual and
+setting whatever options we'd like:
+.SAMPLE
+\fB#\fR cp myscript.stp /etc/systemtap/script.d
+\fB#\fR vi /etc/systemtap/conf.d/myscript.conf
+.ESAMPLE
+To add the script to the initramfs, we use the \fBonboot\fR command:
+.SAMPLE
+\fB#\fR service systemtap onboot myscript
+.ESAMPLE
+If the script is not already compiled and cached, it will be done at this point.
+A new initramfs will then be created at the default location. We can use the
+\fB-b\fR option to ensure that the existing initramfs is backed up. We can then
+restart the system.
+
+.TP
+.B USING A DIFFERENT INITRAMFS
+If we would prefer to only start the script for one boot and not others, it
+might be easier to instead use the \fB-o\fR option to specify a different
+initramfs output file:
+.SAMPLE
+\fB#\fR service systemtap onboot myscript \\
+>   -o /boot/special_initramfs.img
+.ESAMPLE
+Once the initramfs is created, it's simply a matter of changing the command-line
+options at boot-time so that the new image is used rather than the usual one.
+
+.TP
+.B CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
+Just like the compile command, we can use the \fB-r\fR option to specify the
+kernel for which we want to create the initramfs. This is useful when we are
+about to upgrade and would like to prepare in advance. For example:
+.SAMPLE
+\fB#\fR service systemtap onboot myscript \\
+>   -r 3.12.6-200.fc19.x86_64
+.ESAMPLE
+
+.TP
+.B REMOVING SCRIPTS FROM THE INITRAMFS
+Finally, to remove all script from the initramfs, we simple run the \fBonboot\fR
+command without specifying any scripts:
+.SAMPLE
+\fB#\fR service systemtap onboot
+.ESAMPLE
+This will simply create a standard initramfs without any SystemTap modules
+inserted.
+
+.TP
+.B TROUBLESHOOTING EARLY-BOOT ISSUES
+There can be many reasons for which the module didn't insert or did not work as
+expected. It may be useful to turn on dracut debugging by adding 'rdinitdebug'
+to the kernel command-line and checking dmesg/journalctl -ae. Also, the stderr
+output of staprun can be captured by setting the LOG_BOOT_ERR option to
+\fByes\fR.
+
+.SH SEE ALSO
+.IR stap (1)
+
+.SH BUGS
+Use the Bugzilla link of the project web page or our mailing list.
+.nh
+.BR http://sourceware.org/systemtap/ ", " <systemtap@sourceware.org> .
+.hy
+
diff --git a/systemtap.spec b/systemtap.spec
index 41945bd..41c746d 100644
--- a/systemtap.spec
+++ b/systemtap.spec
@@ -940,7 +940,7 @@ done
 %config(noreplace) %{_sysconfdir}/systemtap/config
 %dir %{_localstatedir}/cache/systemtap
 %ghost %{_localstatedir}/run/systemtap
-%doc initscript/README.systemtap
+%{_mandir}/man8/systemtap.8*
 %if %{with_dracut}
    %dir %{dracutstap}
    %{dracutstap}/*
-- 
1.8.3.1