From f19a1ef476349c42861cfecf6dc5afdbedc9191f Mon Sep 17 00:00:00 2001 From: Jonathan Lebon 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 - -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/.stp - - Systemtap scripts stored in the script directory must have ".stp" suffix. - -3.4 Cache directory - /var/cache/systemtap// - - Systemtap initscript stores compiled scripts in this directory. - -3.4.1 Compiled scripts (or script caches) - /var/cache/systemtap//.ko - /var/cache/systemtap//.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/ - -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 _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 _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 - -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 - And package the compiled scripts and configuration file. - # tar czf stap-scripts-.tar.gz \ - /var/cache/systemtap/ /etc/systemtap/conf.d/ - 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-.tar.gz -C /var/cache/systemtap/ - # mv /var/cache/systemtap/ /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