SBT native packager provides support for different systemloaders in order to register your application as a service on your target system, start it automatically and provide systemloader specific configuration.


You can use systemloaders with the Java Application Archetype or the Java Server Application Archetype!


There is a generic SystemloaderPlugin which configures default settings and requires necessary plugins. It gets triggered automatically, when you enable a specific systemloader plugin. If you want to implement your own loader, you should require the SystemloaderPlugin.

General Settings

Loading system to be used for application start script (SystemV, Upstart, Systemd). This setting can be used to trigger systemloader specific behaviour in your build.
Determines if service will be automatically started after installation. The default value is true.
Sequence of runlevels on which application will start up
Sequence of runlevels on which application will stop
Names of system services that should be provided at application start
Names of system services that should be provided at application stop
Timeout before sigkill on stop (after term)
Timeout before sigterm on stop
Number of retries to start service”
Timeout between retries in seconds


Native packager provides different SysV scripts for rpm (CentOS, RHEL, Fedora) and debian (Debian, Ubuntu) package based systems. Enable SystemV with:


The Java Server Application Archetype provides a daemonStdoutLogFile setting, that you can use to redirect the systemV output into a file.


In order to enable Systemd add this plugin:



Takes a list of exit status definitions that when returned by the main service process will be considered successful termination, in addition to the normal successful exit code 0 and the signals SIGHUP, SIGINT, SIGTERM, and SIGPIPE. Exit status definitions can either be numeric exit codes or termination signal names.
Should file app_name.service be marked as config. Default is true. If it is set to true, file will be marked %config in rpm package for example.


SystemV alternative developed by Ubuntu. Native packager adds support for rpm as well, but we recommend using Systemd if possible.


As a side note Fedora/RHEL/Centos family of linux specifies Default requiretty in its /etc/sudoers file. This prevents the default Upstart script from working correctly as it uses sudo to run the application as the daemonUser . Simply disable requiretty to use Upstart or modify the Upstart template.


Native packager provides general settings to customize the created systemloader scripts.

Start Script Location

In order to change the location of the systemloader script/config file you need to adjust the defaultLinuxStartScriptLocation like this:

Debian / defaultLinuxStartScriptLocation := "/lib/systemd/system"

You may need to change these paths according to your distribution. References are

Customize Start Script

Sbt Native Packager leverages templating to customize various start/stop scripts and pre/post install tasks. As an example, to alter the loader-functions which manage the specific start and stop process commands for SystemLoaders you can to the linuxScriptReplacements map:

import com.typesafe.sbt.packager.archetypes.TemplateWriter

linuxScriptReplacements += {
  val functions = sourceDirectory.value / "templates" / "custom-loader-functions"
  // Nil == replacements. If you want to replace stuff in your script put them in this Seq[(String,String)]
  "loader-functions" -> TemplateWriter.generateScript(functions.toURL, Nil)

which will add the following resource file to use start/stop instead of initctl in the post install script:

startService() {
    start $app_name

stopService() {
    stop $app_name

The debian and redhat pages have further information on overriding distribution specific actions.

Override Start Script

It’s also possible to override the entire script/configuration for your service manager. Create a file src/templates/systemloader/$loader/$template and it will be used instead.

Possible values:

  • $loader - upstart, systemv or systemd
  • $template -
    • systemv - loader-functions, start-debian-template, or start-rpm-template
    • systemd - loader-functions or start-template
    • upstart - loader-functions or start-template


You can use ${{variable_name}} to reference variables when writing your script. The default set of variables is:

  • descr - The description of the server.
  • author - The configured author name.
  • exec - The script/binary to execute when starting the server
  • chdir - The working directory for the server.
  • retries - The number of times to retry starting the server.
  • retryTimeout - The amount of time to wait before trying to run the server.
  • app_name - The name of the application (linux friendly)
  • app_main_class - The main class / entry point of the application.
  • app_classpath - The (ordered) classpath of the application.
  • daemon_user - The user that the server should run as.
  • daemon_log_file - Absolute path to daemon log file.