Provided by: systemtap-doc_4.6-2_amd64 bug

NAME

       systemtap-service - SystemTap initscript and systemd service

SYNOPSIS

       systemtap-service COMMAND [OPTIONS] [SCRIPT...]

       service systemtap COMMAND [OPTIONS] [SCRIPT...]

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 systemtap-service  command.  On
       systemd-based  systems,  the  initscript  is controlled by systemctl with the service file
       systemtap.service.

       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  /etc/systemtap/config.  Acceptable
       parameters are detailed in the GLOBAL PARAMETERS section.

       Scripts  must  be  placed  in  the  /etc/systemtap/script.d directory and must have a .stp
       extension. When referring to them on the command-line however, there in no need to include
       the  .stp  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.

COMMANDS

       One of the commands below must be specified:

       start  Start  SCRIPTs.  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:

              - The compiled cache file does not exist.

              - The mtime (modified timestamp) of the original script file is newer than the time
                of the compiled script cache.

              - The specified stap options used to compile the script has been changed (see  also
                the SCRIPT PARAMETERS section).

              - The result of `uname -a` has been changed.

       stop   Stop  SCRIPTs.  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).

       restart
              Stop and start SCRIPTs.

       status Show the state of SCRIPTs and their dependencies.

       compile
              Compile  SCRIPTs  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 -r option.

       onboot Make SCRIPTs 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 -r option. The path of  the  created  initramfs  defaults  to  /boot/initramfs-
              KVER.img,  where  KVER  is the output of `uname -r`. The bootloader is also updated
              (using new-kernel-pkg(8)) to make the kernel entry use the new initramfs file.  Use
              the -o option to specify a different path (the bootloader will not be updated).

              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.   However,
              if there is already a .bak version of the file, the backup will not be overwritten.

              WARNING: do not use the -o option of stap(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.

       cleanup
              Delete  the  compiled  SCRIPTs  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  -r option. Prompt for confirmation before
              deleting.

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:

       -c CONFIG_FILE
              Specify a different configuration file in place of the default one.

       -R     When using the start and stop commands,  also  include  the  scripts'  dependencies
              (recursively).

       -r KERNEL_RELEASE
              When  using  the  compile,  onboot, and cleanup commands, specify the target kernel
              version rather than using the current one. Must be in the  same  format  as  `uname
              -r`.

       -y     Answer yes for all prompts.

       -o PATH.IMG
              When  using  the  onboot command, specify the output path of the created initramfs.
              When specified, the bootloader configuration is not updated.

       -b     When using the onboot command, backup an existing initramfs image by adding a  .bak
              extension  rather  than  overwriting  it.  Without  this  option,  the initramfs is
              overwritten.

GLOBAL PARAMETERS

       These parameters affect the general behaviour of the SystemTap  initscript  service.  They
       can be specified in the configuration file.

       SCRIPT_PATH
              Specify  the  absolute path of the script directory. These are the scripts on which
              the initscript can operate. Scripts must have the .stp extension.  The default path
              is /etc/systemtap/script.d.

       CONFIG_PATH
              Specify   the   absolute   path   of  the  script  configuration  directory.  These
              configuration files contain options for specific scripts. They must have the  .conf
              extension. The default path is /etc/systemtap/conf.d.

       CACHE_PATH
              Specify   the   absolute   path  of  the  cache  directory.  The  default  path  is
              /var/cache/systemtap.

       TEMP_PATH
              Specify the absolute path of the  temporary  directory  in  which  SystemTap  makes
              temporary directories to compile scripts. The default path is /tmp.

       STAT_PATH
              Specify  the  absolute path of the directory containing PID files used to track the
              status of SystemTap scripts. The default path is /var/run/systemtap.

       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
              /var/log/systemtap.log.

       PASSALL
              If this is set yes, 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 no, only a warning is emitted. The default is yes.

       RECURSIVE
              If this  is  set  yes,  the  initscript  will  always  follow  script  dependencies
              recursively.  This means that there is no need to specify the -R option.  This flag
              is effective only if you specify script(s) from the command-line.  The  default  is
              no.

       AUTOCOMPILE
              If this is set yes, 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 yes.

       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 "".

       ALLOW_CACHEONLY
              If this is set yes, the initscript will also allow operating on  scripts  that  are
              located in the cache directory, but not in the script directory. The default is no.

              WARNING:  the initscript may load unexpected obsolete caches with this option.  The
              cache directory should be checked before enabling this option.

       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  yes.  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 no.

       Here is a global configuration file example:

              SCRIPT_PATH=/var/systemtap/script.d/
              PASSALL=yes
              RECURSIVE=no

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.

       <SCRIPT>_OPT
              Specify  options  passed to the stap(1) command for the SCRIPT. Here, SCRIPT is the
              name of the script file without the .stp extension. Note  that  the  -F  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.

       <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

              foo_REQ="bar"

              Specify multiple scripts by separating their names by spaces.

       Here is a script configuration file example:

              script1_OPT="-o /var/log/script1.out"
              script2_OPT="-o /var/log/script2.out"
              script2_REQ="script1"

EXAMPLES

       INSTALLING SCRIPTS
              We first copy a SystemTap script (e.g. "script1.stp") into the script directory:

              # cp script1.stp /etc/systemtap/script.d/

              We can then set any script options, for example:

              # vi /etc/systemtap/conf.d/group1.conf
              script1_OPT="-o /var/log/group1.out"

              We  then install a script (e.g. "script2.stp") which needs to run after script1. In
              this case, we can do the following:

              # cp script2.stp /etc/systemtap/script.d/
              # vi /etc/systemtap/conf.d/group1.conf
              script2_OPT="-o /var/log/group2.out"
              script2_REQ="script1"

              This way, if stap(1) fails to run script1, the initscript will not even try to  run
              script2.

       TESTING
              After installing scripts, we can test that they work by simply doing:

              # systemtap-service start
              # systemtap-service stop

              We could be more specific as well, for example:

              # systemtap-service start script1
              # systemtap-service stop script1

              If there were no errors, we are ready to use it.

       ENABLING SERVICE
              After we're satisfied with the scripts and their tests, we can enable the SystemTap
              initscript service:

              # chkconfig systemtap on

       DELETING SCRIPTS
              Scripts are deleted by simply removing them from the script directory and  removing
              any configuration lines specific to them:

              # rm /etc/systemtap/script.d/script2.stp
              # vi /etc/systemtap/conf.d/group1.conf

              If the script is still running, we also need to stop it:

              # systemtap-service stop script2

              We can then also remove the cache associated with the script:

              # systemtap-service cleanup script2

       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 -r option:

              # systemtap-service compile myscript -r <NEW_KERNEL_VERSION>

       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:

              # systemtap-service compile myscript -r \
              >   <KERNEL_VERSION_OF_TARGET_MACHINE>
              # tar czf stap-scripts-<kernel-version>.tar.gz \
              >   /var/cache/systemtap/<kernel-version> \
              >   /etc/systemtap/conf.d/<configfile>

              And then copy this package to the target machine and extract it.

       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:

              # cp myscript.stp /etc/systemtap/script.d
              # vi /etc/systemtap/conf.d/myscript.conf

              To add the script to the initramfs, we use the onboot command:

              # systemtap-service onboot myscript

              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 -b
              option to ensure that the existing initramfs is backed up. We can then restart  the
              system.

       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 -o option to  specify  a  different  initramfs  output
              file:

              # systemtap-service onboot myscript \
              >   -o /boot/special_initramfs.img

              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.

       CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
              Just like the compile command, we can use the -r 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:

              # systemtap-service onboot myscript \
              >   -r 3.12.6-200.fc19.x86_64

       REMOVING SCRIPTS FROM THE INITRAMFS
              Finally, to remove all script from the initramfs, we simple run the onboot  command
              without specifying any scripts:

              # systemtap-service onboot

              This  will  simply  create  a  standard  initramfs  without  any  SystemTap modules
              inserted.

       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 yes.

SEE ALSO

       stap(1) dracut(8) new-kernel-pkg(8)

BUGS

       Use   the   Bugzilla   link   of   the   project   web   page   or   our   mailing   list.
       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.

                                                                                     SYSTEMTAP(8)