[JENKINS-41218] Provide native systemd unit

[jenkins-infra-bot]

Currently debian packages (and presumably redhat/suse/etc) ship with old style SysV init.d file.

Most distributions are now systemd based, and to be able to make use of it's additional features it would be useful have /lib/systemd/system/jenkins.service file.

This would allow features like systemd's restart functionality to work (useful when Jenkins occasionally crashes, etc). See discussion around this here: http://serverfault.com/questions/760552/how-to-use-automatic-restart-with-jenkins-on-systemd

Details of how provide both systemd unit file and SysV init file are detailed here:
https://wiki.debian.org/Teams/pkg-systemd/Packaging

This should be applicable to all distro, and systemd unit most likely the same across them all, as it's much more standardised than each distros SysV init infrastructure.

https://github.com/jenkinsci/packaging

---

Originally reported by nickbrown, imported from: Provide native systemd unit

• assignee: basil
• status: Closed
• priority: Critical
• component(s): packaging
• resolution: Fixed
• resolved: 2022-02-16T18:48:24+00:00
• votes: 14
• watchers: 27
• imported: 2025-11-26

Raw content of original issue

Currently debian packages (and presumably redhat/suse/etc) ship with old style SysV init.d file.

Most distributions are now systemd based, and to be able to make use of it's additional features it would be useful have /lib/systemd/system/jenkins.service file.

This would allow features like systemd's restart functionality to work (useful when Jenkins occasionally crashes, etc). See discussion around this here: http://serverfault.com/questions/760552/how-to-use-automatic-restart-with-jenkins-on-systemd

Details of how provide both systemd unit file and SysV init file are detailed here:
https://wiki.debian.org/Teams/pkg-systemd/Packaging

This should be applicable to all distro, and systemd unit most likely the same across them all, as it's much more standardised than each distros SysV init infrastructure.

https://github.com/jenkinsci/packaging

[jenkins-infra-bot]

• Remote link associated with this issue:

  • jenkinsci/packaging#​266

[jenkins-infra-bot]

axmetishe:

• Original comment link
• Raw content of original comment:

  I'll leave the unit template here for Jenkins within multi-instance tomcat installation, maybe this will be helpful.
  
  Only one thing - the internal restart commands like safeRestart or restart cause service to be unavailable since restart command is not correct in such case.
  
  #/lib/systemd/system/tomcat@.service 
  [Unit]
  Description=Apache Tomcat service for "%i"
  After=syslog.target network-online.target
  
  [Service]
  SyslogIdentifier=%i
  
  User=%i
  Group=%i
  PermissionsStartOnly=true
  
  EnvironmentFile=-/etc/sysconfig/%i
  Environment='CATALINA_PID=$MAINPID'
  
  ExecStartPre=/bin/bash -c 'systemctl set-environment JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:/bin/java::")'
  ExecStartPre=/bin/bash -c 'systemctl set-environment CATALINA_HOME=$(readlink -f /usr/bin/tomcat)'
  
  ExecStart=@/usr/bin/java \
  $JAVA_OPTS \
  $JMX_OPTS \
  $INSTANCE_OPTS \
  $CATALINA_OPTS \
  -Djava.endorsed.dirs=${CATALINA_HOME}/endorsed \
  -Djava.io.tmpdir=${CATALINA_BASE}/temp \
  -Dcatalina.base=${CATALINA_BASE} \
  -Dcatalina.home=${CATALINA_HOME} \
  -classpath ${CATALINA_HOME}/bin/bootstrap.jar:${CATALINA_HOME}/bin/tomcat-juli.jar \
  org.apache.catalina.startup.Bootstrap start
  
  SuccessExitStatus=143
  
  [Install]
  WantedBy=multi-user.target
  Alias=%i.service
  
  
  
  UPD:
  Example config file for tomcat@jenkins instance:
  
  #/etc/sysconfig/jenkins
  CATALINA_BASE="/opt/jenkins/app"
  
  CATALINA_OPTS="-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
  
  JAVA_OPTS="-Xms189M -Xmx1514M -XX:MaxDirectMemorySize=378M -XX:-UseConcMarkSweepGC -XX:+UseSerialGC"
  
  JMX_OPTS=""
  
  INSTANCE_OPTS="-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv4Addresses=true -Djenkins.install.runSetupWizard=false"
  
  JENKINS_HOME="/opt/jenkins/data"
  
  
  
   
  Regards.
  

I'll leave the unit template here for Jenkins within multi-instance tomcat installation, maybe this will be helpful.

Only one thing - the internal restart commands like safeRestart or restart cause service to be unavailable since restart command is not correct in such case.

#/lib/systemd/system/tomcat@​.service 
[Unit]
Description=Apache Tomcat service for "%i"
After=syslog.target network-online.target

[Service]
SyslogIdentifier=%i

User=%i
Group=%i
PermissionsStartOnly=true

EnvironmentFile=-/etc/sysconfig/%i
Environment='CATALINA_PID=$MAINPID'

ExecStartPre=/bin/bash -c 'systemctl set-environment JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:/bin/java::")'
ExecStartPre=/bin/bash -c 'systemctl set-environment CATALINA_HOME=$(readlink -f /usr/bin/tomcat)'

ExecStart=@/usr/bin/java \
$JAVA_OPTS \
$JMX_OPTS \
$INSTANCE_OPTS \
$CATALINA_OPTS \
-Djava.endorsed.dirs=${CATALINA_HOME}/endorsed \
-Djava.io.tmpdir=${CATALINA_BASE}/temp \
-Dcatalina.base=${CATALINA_BASE} \
-Dcatalina.home=${CATALINA_HOME} \
-classpath ${CATALINA_HOME}/bin/bootstrap.jar:${CATALINA_HOME}/bin/tomcat-juli.jar \
org.apache.catalina.startup.Bootstrap start

SuccessExitStatus=143

[Install]
WantedBy=multi-user.target
Alias=%i.service

UPD:

Example config file for tomcat@​jenkins instance:

#/etc/sysconfig/jenkins

CATALINA_BASE="/opt/jenkins/app"
CATALINA_OPTS="-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
JAVA_OPTS="-Xms189M -Xmx1514M -XX:MaxDirectMemorySize=378M -XX:-UseConcMarkSweepGC -XX:+UseSerialGC"
JMX_OPTS=""
INSTANCE_OPTS="-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv4Addresses=true -Djenkins.install.runSetupWizard=false"
JENKINS_HOME="/opt/jenkins/data"

 

Regards.

[jenkins-infra-bot]

ieugen:

• Original comment link
• Raw content of original comment:

  Hello,
  
  What can I/we do to have this fix applied? Systemd has become the defacto service manager across major / all distributions.
  
  There are new releases in Debian and RHEL that use systemd. There are great benefits to have apps managed by systemd. 
  
  It would be great to have this upstream. Even if it is disabled and we need to `systemctl enable ` it manually.
  
   
  
  Looking forward for your feedback.
  
   
  
  Thanks
  

Hello,

What can I/we do to have this fix applied? Systemd has become the defacto service manager across major / all distributions.

There are new releases in Debian and RHEL that use systemd. There are great benefits to have apps managed by systemd.

It would be great to have this upstream. Even if it is disabled and we need to `systemctl enable ` it manually.

 

Looking forward for your feedback.

 

Thanks

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  The above is for running Jenkins in Tomcat, isn't it? It also seems to be RedHat specific (/etc/sysconfig). When running apps in Tomcat, one usually just need to start Tomcat itself, which in turn takes care of starting all the webapps deployed to it. So setting up a "tomcat@.service" for single webapps doesn't seem to be necessary at all (and also feels wrong given that this would mean to start one Tomcat instance for each webapp configured this way).
  
  OTOH, this ticket is about a "native" systemd unit, which I think means: One that starts Jenkins standalone, just like the current sys-v init script does.
  

The above is for running Jenkins in Tomcat, isn't it? It also seems to be RedHat specific (/etc/sysconfig). When running apps in Tomcat, one usually just need to start Tomcat itself, which in turn takes care of starting all the webapps deployed to it. So setting up a "tomcat@​.service" for single webapps doesn't seem to be necessary at all (and also feels wrong given that this would mean to start one Tomcat instance for each webapp configured this way).

OTOH, this ticket is about a "native" systemd unit, which I think means: One that starts Jenkins standalone, just like the current sys-v init script does.

[jenkins-infra-bot]

axmetishe:

• Original comment link
• Raw content of original comment:

  dhs
  The above is for running Jenkins in Tomcat, isn't it?
  Yes. The example provided based on [Advanced Configuration - Multiple Tomcat Instances|https://tomcat.apache.org/tomcat-8.0-doc/RUNNING.txt] - e.g. single installation and "n" - Tomcat Server instances, which allow to run NOT multiple applications within single server(which is also possible by default), but multiple Tomcat Server instances.
  This is widely used technique when you desire to split up different application servers but share binaries between them.
  Unit template "tomcat@.service" follow the described flow above:
  
  	
  Determines current default Tomcat binaries(configured via alternatives) directory and expose required variable 
  ExecStartPre=/bin/bash -c 'systemctl set-environment CATALINA_HOME=$(readlink -f /usr/bin/tomcat)'
  	
  Retrieves server instance configuration(RedHat or Debian makes no difference here, just replace 'sysconfig' to 'default' on deb packaging stage)
  EnvironmentFile=-/etc/sysconfig/%i
  	
  Starts dedicated Tomcat Instance for Jenkins
  
  
  
  This kind of configuration provides flexibility on Servlet container configuration, protocols configuration used for proxy communication, simple server and java versions updates, and simplicity for multiple server configuration(dev/int/stage/prod instances) when you are on bare-metal/virtual machines.
  
  
  So setting up a "tomcat@.service" for single webapps doesn't seem to be necessary at all
  
  For the configuration when the single app should have its own server.
  
   
  
  One that starts Jenkins standalone, just like the current sys-v init script does.
  
  I'd left this advanced java app deployment configuration here for someone who tried to find systemd solution from the maintainers. Feel free to switch this unit to the internal winstone(jetty) servlet container used at Jenkins war/jar binaries.
  
  Regards.
  

dhs
The above is for running Jenkins in Tomcat, isn't it?
Yes. The example provided based on [Advanced Configuration - Multiple Tomcat Instances|https://tomcat.apache.org/tomcat-8.0-doc/RUNNING.txt] - e.g. single installation and "n" - Tomcat Server instances, which allow to run NOT multiple applications within single server(which is also possible by default), but multiple Tomcat Server instances.
This is widely used technique when you desire to split up different application servers but share binaries between them.
Unit template "tomcat@​.service" follow the described flow above:

1. Determines current default Tomcat binaries(configured via alternatives) directory and expose required variable 
   ExecStartPre=/bin/bash -c 'systemctl set-environment CATALINA_HOME=$(readlink -f /usr/bin/tomcat)'
2. Retrieves server instance configuration(RedHat or Debian makes no difference here, just replace 'sysconfig' to 'default' on deb packaging stage)
   EnvironmentFile=-/etc/sysconfig/%i
3. Starts dedicated Tomcat Instance for Jenkins

This kind of configuration provides flexibility on Servlet container configuration, protocols configuration used for proxy communication, simple server and java versions updates, and simplicity for multiple server configuration(dev/int/stage/prod instances) when you are on bare-metal/virtual machines.

So setting up a "tomcat@​.service" for single webapps doesn't seem to be necessary at all

For the configuration when the single app should have its own server.

 

One that starts Jenkins standalone, just like the current sys-v init script does.

I'd left this advanced java app deployment configuration here for someone who tried to find systemd solution from the maintainers. Feel free to switch this unit to the internal winstone(jetty) servlet container used at Jenkins war/jar binaries.

Regards.

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  axmetishe, but still, this way of starting Jenkins should not be part of the Jenkins package, but the Tomcat one, right? Also, the "EnvironmentFile" entry is there for providing some kind of backwards compatibility with system v. In a pure systemd setup they shouldn't be used anymore as environment variables can be added directly via "Environment" entries. Customizations should then go into /etc/systemd/system/myservice.service.d/*.conf. This completely eliminates the need for ANY distribution specific files.
  
  I'll try to write a native service file for standalone Jenkins, I already have one for starting swarm agents which I can use as a starting point...
  

axmetishe, but still, this way of starting Jenkins should not be part of the Jenkins package, but the Tomcat one, right? Also, the "EnvironmentFile" entry is there for providing some kind of backwards compatibility with system v. In a pure systemd setup they shouldn't be used anymore as environment variables can be added directly via "Environment" entries. Customizations should then go into /etc/systemd/system/myservice.service.d/*.conf. This completely eliminates the need for ANY distribution specific files.

I'll try to write a native service file for standalone Jenkins, I already have one for starting swarm agents which I can use as a starting point...

[jenkins-infra-bot]

axmetishe:

• Original comment link
• Raw content of original comment:

  dhs
  not be part of the Jenkins package, but the Tomcat one, right?
  
  not Jenkins, nor Tomcat - environment specific configuration
  
   
  
  Also, the "EnvironmentFile" entry is there for providing some kind of backwards compatibility with system v
  
  wrong - this is not a backward compatibility level, but conscious way to pass basic deployment configuration instead of large unit file with tons of Environment definitions which will not be updated from place to place
  
   
  
  In a pure systemd setup they shouldn't be used anymore as environment variables
  
  wrong again - it's a just two different methods for environment configuration for 'pure' systemd setup
  
   
  
  Customizations should then go into /etc/systemd/system/myservice.service.d/*.conf
  
  customization will still be applied even using EnvironmentFile which is related to general configuration - https://www.freedesktop.org/software/systemd/man/systemd.exec.html
  
   
  
  This completely eliminates the need for ANY distribution specific files
  
  You will still have to do some customization with deb/rpm packaging at pre-inst/post-inst for example and string replacement will be the lesser problem
  
   
  
  I'll try to write a native service file for standalone Jenkins, I already have one for starting swarm agents which I can use as a starting point
  
  Glad to hear that.
  
   
  
  Regards.
  

dhs
not be part of the Jenkins package, but the Tomcat one, right?

not Jenkins, nor Tomcat - environment specific configuration

 

Also, the "EnvironmentFile" entry is there for providing some kind of backwards compatibility with system v

wrong - this is not a backward compatibility level, but conscious way to pass basic deployment configuration instead of large unit file with tons of Environment definitions which will not be updated from place to place

 

In a pure systemd setup they shouldn't be used anymore as environment variables

wrong again - it's a just two different methods for environment configuration for 'pure' systemd setup

 

Customizations should then go into /etc/systemd/system/myservice.service.d/*.conf

customization will still be applied even using EnvironmentFile which is related to general configuration - https://www.freedesktop.org/software/systemd/man/systemd.exec.html

 

This completely eliminates the need for ANY distribution specific files

You will still have to do some customization with deb/rpm packaging at pre-inst/post-inst for example and string replacement will be the lesser problem

 

I'll try to write a native service file for standalone Jenkins, I already have one for starting swarm agents which I can use as a starting point

Glad to hear that.

 

Regards.

[jenkins-infra-bot]

ieugen:

• Original comment link
• Raw content of original comment:

  HI,
  
  dhs : You are correct, I am talking about the standalone application.
  axmetishe : Jenkins is not using tomcat installation from Debian. It's running on embedded Tomcat and it should stay like this. It's fine. I believe creating dependencies between packages is a bad practice that complicates a lot of things. 
  
   
  
  I am running Jenkins 2.222 from pkg.jenkins.io and it is running as a standalone application on Debian:
  
  ```
  
  jenkins 1397 0.0 0.0 20244 172 ? S 07:35 0:00 /usr/bin/daemon --name=jenkins --inherit --env=JENKINS_HOME=/var/lib/jenkins --output=/var/log/jenkins/jenkins.log --pidfile=/var/run/jenkins/jenkins.pid – /usr/bin/java -Djava.awt.headless=true -Djava.util.logging=DEBUG -jar /usr/share/jenkins/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080
  jenkins 1398 4.9 14.2 4762984 1138044 ? Sl 07:35 9:42 /usr/bin/java -Djava.awt.headless=true -Djava.util.logging=DEBUG -jar /usr/share/jenkins/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080
  
  ```
  
  I am using Debian. I do believe we should keep things simple and leave out detection and automation stuff. We should avoid assumptions.
  
  Having the following should solve the problem easily IMO
  
  	
  systemd unit delivered as part of the package
  	
  documentation that the user can enable it
  	
  a `systemctl enable` command with the path see https://www.freedesktop.org/software/systemd/man/systemctl.html
  
  
  
   
  
  The behavior of the package does not even have to change IMO. We can add the files, allow people to test them out and change the defaults a few months later.
  
  Both Debian and RHEL systemd files can be provided in case one is not enough.
  
  No fiddling with alternatives or other stuff.
  
   As a final note: 
  
  I am willing to provide patches however I would like to do the work if it has a chance to get merged. Otherwise it makes no sense to spend time on this. 
  
  Waiting for an ok on the solution. 
  
   
  

HI,

dhs : You are correct, I am talking about the standalone application.
axmetishe : Jenkins is not using tomcat installation from Debian. It's running on embedded Tomcat and it should stay like this. It's fine. I believe creating dependencies between packages is a bad practice that complicates a lot of things.

 

I am running Jenkins 2.222 from pkg.jenkins.io and it is running as a standalone application on Debian:

```

jenkins 1397 0.0 0.0 20244 172 ? S 07:35 0:00 /usr/bin/daemon --name=jenkins --inherit --env=JENKINS_HOME=/var/lib/jenkins --output=/var/log/jenkins/jenkins.log --pidfile=/var/run/jenkins/jenkins.pid – /usr/bin/java -Djava.awt.headless=true -Djava.util.logging=DEBUG -jar /usr/share/jenkins/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080
jenkins 1398 4.9 14.2 4762984 1138044 ? Sl 07:35 9:42 /usr/bin/java -Djava.awt.headless=true -Djava.util.logging=DEBUG -jar /usr/share/jenkins/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080

```

I am using Debian. I do believe we should keep things simple and leave out detection and automation stuff. We should avoid assumptions.

Having the following should solve the problem easily IMO

• systemd unit delivered as part of the package
• documentation that the user can enable it
• a `systemctl enable` command with the path see https://www.freedesktop.org/software/systemd/man/systemctl.html

 

The behavior of the package does not even have to change IMO. We can add the files, allow people to test them out and change the defaults a few months later.

Both Debian and RHEL systemd files can be provided in case one is not enough.

No fiddling with alternatives or other stuff.

 As a final note:

I am willing to provide patches however I would like to do the work if it has a chance to get merged. Otherwise it makes no sense to spend time on this.

Waiting for an ok on the solution.

 

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  Sorry, did not find the time yet to create a service file.
  

Sorry, did not find the time yet to create a service file.

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  Here you are:
  
  [Unit]
  Description=Standalone Jenkins Master server
  Documentation=https://www.jenkins.io/doc
  
  Wants=network-online.target
  After=network-online.target
  
  [Service]
  User=jenkins
  Group=jenkins
  Environment=HTTP_PORT=8080
  Environment=JAVA_ARGS=-Djava.awt.headless=true
  Environment=JENKINS_HOME=/var/lib/jenkins
  Environment=JENKINS_WAR=/usr/share/jenkins/jenkins.war
  Environment=LISTEN_ADDRESS=0.0.0.0
  Environment=WEBROOT=/var/cache/jenkins/war
  WorkingDirectory=/var/lib/jenkins
  LimitNOFILE=8192
  ExecStart=/usr/bin/java ${JAVA_ARGS} -jar ${JENKINS_WAR} --webroot=${WEBROOT} --httpPort=${HTTP_PORT} --httpListenAddress=${LISTEN_ADDRESS}
  
  [Install]
  WantedBy=multi-user.target
  
  An example overlay file (to overwrite the defaults) could look like this:
  
  [Service]
  Environment=JENKINS_HOME=/srv/jenkins
  Environment=LISTEN_ADDRESS=127.0.0.1
  
  and should be placed into /etc/systemd/system/jenkins.service.d/ as *.conf by the system admin.
  I also use this for some services to grant them access to the OpenAFS network filesystem, which requires Kerberos authentication, by overwriting the ExecStart= line. Something that's not possible with an environment file in /etc/default.
  

Here you are:

[Unit]
Description=Standalone Jenkins Master server
Documentation=https://www.jenkins.io/doc

Wants=network-online.target
After=network-online.target

[Service]
User=jenkins
Group=jenkins
Environment=HTTP_PORT=8080
Environment=JAVA_ARGS=-Djava.awt.headless=true
Environment=JENKINS_HOME=/var/lib/jenkins
Environment=JENKINS_WAR=/usr/share/jenkins/jenkins.war
Environment=LISTEN_ADDRESS=0.0.0.0
Environment=WEBROOT=/var/cache/jenkins/war
WorkingDirectory=/var/lib/jenkins
LimitNOFILE=8192
ExecStart=/usr/bin/java ${JAVA_ARGS} -jar ${JENKINS_WAR} --webroot=${WEBROOT} --httpPort=${HTTP_PORT} --httpListenAddress=${LISTEN_ADDRESS}

[Install]
WantedBy=multi-user.target

An example overlay file (to overwrite the defaults) could look like this:

[Service]
Environment=JENKINS_HOME=/srv/jenkins
Environment=LISTEN_ADDRESS=127.0.0.1

and should be placed into /etc/systemd/system/jenkins.service.d/ as *.conf by the system admin.

I also use this for some services to grant them access to the OpenAFS network filesystem, which requires Kerberos authentication, by overwriting the ExecStart= line. Something that's not possible with an environment file in /etc/default.

[jenkins-infra-bot]

ieugen:

• Original comment link
• Raw content of original comment:

  Thanks dhs, I hope the files get added to the jenkins package and are distributed with it so people can use them instead of the scripts. 
  After some time, it can be installed by default instead of the scripts. 
  

Thanks dhs, I hope the files get added to the jenkins package and are distributed with it so people can use them instead of the scripts.
After some time, it can be installed by default instead of the scripts.

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  You're welcome. Forgot to mention: While this works for me, it doesn't mean it works for others, too. But it should make a good starting point  (and should as well be distribution independent).
  

You're welcome. Forgot to mention: While this works for me, it doesn't mean it works for others, too. But it should make a good starting point (and should as well be distribution independent).

[jenkins-infra-bot]

axmetishe:

• Original comment link
• Raw content of original comment:

  Good job dhs, thank you.
  
  By the way, it will be better to set dependency on network-online.target in order to be sure that we can create network socket.
  

Good job dhs, thank you.

By the way, it will be better to set dependency on network-online.target in order to be sure that we can create network socket.

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  Good point axmetishe. Changed it.
  

Good point axmetishe. Changed it.

[jenkins-infra-bot]

dhs:

• Original comment link
• Raw content of original comment:

  Since more than a year has passed and 2.303.1 STILL ships a SysV init script instead of a systemd service file, I'd like to ask what's the status here? All the major distributions default to systemd nowadays, so it's about time...
  
   
  

Since more than a year has passed and 2.303.1 STILL ships a SysV init script instead of a systemd service file, I'd like to ask what's the status here? All the major distributions default to systemd nowadays, so it's about time...