Systemloaders¶
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.
Tip
You can use systemloaders with the Java Application Archetype or the Java Server Application Archetype!
Overview¶
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¶
serverLoading
- 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.
serviceAutostart
- Determines if service will be automatically started after installation. The default value is true.
startRunlevels
- Sequence of runlevels on which application will start up
stopRunlevels
- Sequence of runlevels on which application will stop
requiredStartFacilities
- Names of system services that should be provided at application start
requiredStopFacilities
- Names of system services that should be provided at application stop
killTimeout
- Timeout before sigkill on stop (after term)
termTimeout
- Timeout before sigterm on stop
retries
- Number of retries to start service”
retryTimeout
- Timeout between retries in seconds
SystemV¶
Native packager provides different SysV scripts for rpm
(CentOS, RHEL, Fedora) and debian
(Debian, Ubuntu)
package based systems. Enable SystemV with:
enablePlugins(SystemVPlugin)
The Java Server Application Archetype provides a daemonStdoutLogFile
setting, that you can use to redirect the systemV
output into a file.
Systemd¶
In order to enable Systemd add this plugin:
enablePlugins(SystemdPlugin)
Settings¶
systemdSuccessExitStatus
- 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 signalsSIGHUP
,SIGINT
,SIGTERM
, andSIGPIPE
. Exit status definitions can either be numeric exit codes or termination signal names.systemdIsServiceFileConfig
- Should file app_name.service be marked as config. Default is
true
. If it is set totrue
, file will be marked%config
in rpm package for example.
Upstart¶
SystemV alternative developed by Ubuntu. Native packager adds support for rpm as well, but we recommend using Systemd if possible.
enablePlugins(UpstartPlugin)
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.
Customization¶
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:
defaultLinuxStartScriptLocation in Debian := "/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() {
app_name=$1
start $app_name
}
stopService() {
app_name=$1
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
orsystemd
$template
-systemv
-loader-functions
,start-debian-template
, orstart-rpm-template
systemd
-loader-functions
orstart-template
upstart
-loader-functions
orstart-template
Syntax
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 serverchdir
- 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.