.\" -*- nroff -*- .TH SYSTEMTAP 8 .SH NAME systemtap-service \- SystemTap initscript and systemd service .\" macros .de SAMPLE .nr oldin \\n(.i .br .RS .nf .nh .. .de ESAMPLE .hy .fi .RE .in \\n[oldin]u .. .SH SYNOPSIS .B systemtap-service .IR COMMAND " [" OPTIONS "] [" SCRIPT ...] .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. The SystemTap initscript can be invoked manually using the .B systemtap-service command. On systemd-based systems, the initscript is controlled by .B systemctl with the service file \fBsystemtap.service\fR. 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. The configuration file of the initscript is located at \fB/etc/systemtap/config\fR. Acceptable parameters are detailed in the GLOBAL PARAMETERS section. Scripts must be placed in the \fB/etc/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. Script names can only contain alphanumeric characters (and '_') and must not start with a number. 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`. The bootloader is also updated (using \fInew-kernel-pkg\fR(8)) to make the kernel entry use the new initramfs file. Use the \fB-o\fR option to specify a different path (the bootloader will not be updated). 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. When specified, the bootloader configuration is not updated. .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/etc/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/etc/systemtap/conf.d\fR. .TP .B CACHE_PATH Specify the absolute path of the cache directory. The default path is \fB/var/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/var/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/var/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