Managing systemd services

Beginning with Jenkins 2.332.1 and Jenkins 2.335, the Linux package installers use systemd to manage services. The RPM and deb package installers migrate configuration settings from System V init to systemd overrides.

Viewing service configurations

The current service configuration of the Jenkins service as configured by the package installers and any overrides can be viewed with:

$ systemctl cat jenkins
# /etc/systemd/system/jenkins.service
#
# This file is managed by systemd(1). Do NOT edit this file manually!
# To override these settings, run:
#
#     systemctl edit jenkins
#
# For more information about drop-in files, see:
#
#     https://www.freedesktop.org/software/systemd/man/systemd.unit.html
#

[Unit]
Description=Jenkins Continuous Integration Server
Requires=network.target
After=network.target

[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/bin/jenkins
Restart=on-failure
SuccessExitStatus=143

# /etc/systemd/system/jenkins.service.d/override.conf
[Service]
Environment="JAVA_OPTS=-Djava.awt.headless=true"

Overriding service configurations

When installed on a modern Linux distribution running systemd(1), the systemd(1) service unit is delivered to:

Debian

/lib/systemd/system/jenkins.service

Red Hat

/usr/lib/systemd/system/jenkins.service

openSUSE

/usr/lib/systemd/system/jenkins.service

The main service unit is read-only and not intended to be edited manually. It contains a large notice at the top of the file reminding the user that it is read-only.

Values may be overridden in the drop-in unit (override.conf file) for the service. Edit the drop-in unit with:

# systemctl edit jenkins

The override.conf file is stored at /etc/systemd/system/jenkins.service.d/override.conf and can be used to customize the service. Note that such customizations must be done in a [Service] section in order to take effect. Example content of the override.conf file might include:

[Unit]
Description=My Company Jenkins Controller

[Service]
# Add JVM configuration options
Environment="JAVA_OPTS=-Djava.awt.headless=true -XX:+UseStringDeduplication"

# Arbitrary additional arguments to pass to Jenkins.
# Full option list: java -jar jenkins.war --help
Environment="JENKINS_OPTS=--prefix=/jenkins --javaHome=/opt/jdk-11"

# Configuration as code directory
Environment="CASC_JENKINS_CONFIG=/var/lib/jenkins/configuration-as-code/"
systemctl edit jenkins creates the drop-in unit as root with 0644 (-rw-r—​r--) permissions. The migration logic, on the other hand, creates the drop-in unit as root with 0600 (-rw-------) permissions. This might be of consequence if you store an HTTPS keystore location and/or password in the drop-in unit and also run jobs directly on the controller, a practice which the Jenkins project explicitly discourages. When in doubt, secure the drop-in unit by setting its permissions to 0600 with chmod(1).

The drop-in unit unifies configuration across all three distributions: Debian, Red Hat, and openSUSE. Also note that the drop-in unit is not overwritten on upgrades.

Unlike the System V init(8) configuration, the override.conf file only contains customizations, not the original defaults. Users who are accustomed to editing an existing set of defaults must refer to the (read-only) service unit side-by-side when editing the drop-in unit or use a command like systemctl edit jenkins --full, which copies the original service unit instead of creating a drop-in unit.

Editing the drop-in unit with systemctl edit jenkins will automatically reload the systemd(1) configuration. The settings will take effect the next time Jenkins is restarted. If you edit the drop-in unit without systemctl(1), you need to run systemctl daemon-reload for the changes to take effect.

A final point to mention about the service unit is its use of specifiers, which may be unfamiliar to some users. The drop-in unit does not perform shell expansion. Specifiers can insert contextual information (like system hostname, unit name, and operating system kernel release) into the drop-in unit. The systemd(1) documentation contains a table of specifiers available in unit files.

Starting services

Once the Jenkins systemd service has been defined, it can be started with:

# systemctl start jenkins

If Jenkins does not signal startup completion within a configured time, the service will be considered failed and will be shut down again. As each initialization milestone (i.e., "Started initialization", "Listed all plugins", "Prepared all plugins", "Started all plugins", "Augmented all extensions", "System config loaded", "System config adapted", "Loaded all jobs", "Configuration for all jobs updated", and "Completed initialization") is attained, the timeout is extended by the value of the jenkins.model.Jenkins.extendTimeoutSeconds system property (by default, 15 seconds). The timeout can be configured with the TimeoutStartSec directive in the service unit.

Stopping services

The Jenkins systemd service can be stopped with:

# systemctl stop jenkins

Restarting services

The Jenkins systemd service can be restarted with:

# systemctl restart jenkins

Reloading service definitions

After changes to configuration files, the service definition may need to be reloaaded with:

# systemctl daemon-reload

Reading service logs

Logs for the Jenkins service can be read with the command:

$ journalctl -u jenkins

Pruning service logs

Log files retained by systemd are commonly configured to automatically rotate. If the log files need to be reduced in size, use the command:

$ journalctl --vacuum-size=500M

Viewing service status

The Jenkins systemd service status can be viewed with systemctl status jenkins. Some examples are shown below.

After upgrading plugins:

$ systemctl status jenkins
● jenkins.service - Jenkins Continuous Integration Server
     Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/jenkins.service.d
             └─override.conf
     Active: active (running) […]
   Main PID: […] (java)
     Status: "Restart in 10 seconds"

As Jenkins is being brought down:

$ systemctl status jenkins
● jenkins.service - Jenkins Continuous Integration Server
     Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/jenkins.service.d
             └─override.conf
     Active: deactivating (stop-sigterm) since […]
   Main PID: […] (java)
     Status: "Stopping Jenkins"

As Jenkins is starting up:

$ systemctl status jenkins
● jenkins.service - Jenkins Continuous Integration Server
     Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/jenkins.service.d
             └─override.conf
     Active: activating (start) since […]
   Main PID: […] (java)

After successful startup:

$ systemctl status jenkins
● jenkins.service - Jenkins Continuous Integration Server
     Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/jenkins.service.d
             └─override.conf
     Active: active (running) since […]
   Main PID: […] (java)

Going further

Some recommended readings on this subject: