Jenkins: Startup Configuration Options

Table of Contents

• Jenkins Startup Settings
• JVM Options
  • Recommended Production Settings
  • Memory Configuration
  • Garbage Collection
• System Properties
  • Core Jenkins Properties
  • Performance Tuning
  • Security Settings
• Environment Variables
  • Essential Variables
  • Agent Configuration
  • Plugin Settings
• Configuration Files
  • Systemd Service File
  • Docker Configuration
• Startup Options
  • Command Line Arguments
  • Common Startup Arguments
• Performance Optimization
  • Memory Recommendations
  • GC Tuning for Different Workloads
• Logging Configuration
  • Enable Debug Logging
  • GC Logging
• Troubleshooting
  • Common Issues
• Security Hardening
  • Recommended Security Options
• Monitoring
  • JMX Configuration
  • Metrics Endpoint
• Resources

Jenkins Startup Settings

Configuration options for Jenkins server startup, including JVM settings, system properties, and environment variables.

JVM Options

Recommended Production Settings

JENKINS_JAVA_OPTIONS="-Djava.awt.headless=true -XX:MaxRAMPercentage=50.0 -XX:InitialRAMPercentage=50.0 -XX:+UseG1GC"

Memory Configuration

Set memory limits as percentage of available RAM:

# Use 50% of available RAM
-XX:MaxRAMPercentage=50.0
-XX:InitialRAMPercentage=50.0

# Or set explicit heap size
-Xmx2048m
-Xms1024m

Garbage Collection

Use G1GC for better performance:

# Enable G1 Garbage Collector
-XX:+UseG1GC

# Tune G1GC parameters
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:ParallelGCThreads=20 \
-XX:ConcGCThreads=5 \
-XX:InitiatingHeapOccupancyPercent=45

Alternative collectors:

# ZGC (for large heaps, Java 11+)
-XX:+UseZGC

# Shenandoah (low pause times, Java 12+)
-XX:+UseShenandoahGC

System Properties

Core Jenkins Properties

# Jenkins home directory
-Dhudson.model.DirectoryBrowserSupport.CSP="sandbox; default-src 'self';"

# Disable DNS multicast
-Dhudson.DNSMultiCast.disabled=true

# Set Jenkins root URL
-Djenkins.model.Jenkins.slaveAgentPort=50000

# Increase form post size limit (default is 2MB)
-Dorg.apache.commons.jelly.tags.fmt.timeZone=America/New_York

Performance Tuning

# Increase executor timeout
-Dhudson.model.LoadStatistics.decay=0.7

# Reduce workspace cleanup overhead
-Dhudson.model.WorkspaceCleanupThread.recurrencePeriodHours=24

# Speed up plugin loading
-Dhudson.PluginManager.workDir=/var/lib/jenkins/pluginWorkDir

# Disable usage statistics
-Dhudson.model.UsageStatistics.disabled=true

Security Settings

# Disable CLI over remoting
-Djenkins.CLI.disabled=true

# Enable CSRF protection
-Dhudson.security.csrf.DefaultCrumbIssuer.EXCLUDE_SESSION_ID=true

# Set Content Security Policy
-Dhudson.model.DirectoryBrowserSupport.CSP="default-src 'self'; script-src 'self' 'unsafe-inline';"

Environment Variables

Essential Variables

# Jenkins home directory
export JENKINS_HOME=/var/lib/jenkins

# HTTP port
export JENKINS_PORT=8080

# HTTPS configuration
export JENKINS_HTTPS_PORT=8443
export JENKINS_HTTPS_KEYSTORE=/path/to/keystore
export JENKINS_HTTPS_KEYSTORE_PASSWORD=password

# Listen address
export JENKINS_LISTEN_ADDRESS=0.0.0.0

Agent Configuration

# Agent port (for JNLP agents)
export JENKINS_SLAVE_AGENT_PORT=50000

# Agent connection timeout
export JENKINS_AGENT_TIMEOUT=60

Plugin Settings

# Plugin download URL
export JENKINS_UC=https://updates.jenkins.io

# Plugin install directory
export JENKINS_PLUGIN_DIR=/var/lib/jenkins/plugins

# Disable plugin install wizard
export JENKINS_OPTS="--sessionTimeout=1440"

Configuration Files

Systemd Service File

/etc/systemd/system/jenkins.service:

[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

User=jenkins
Group=jenkins

Environment="JENKINS_HOME=/var/lib/jenkins"
Environment="JENKINS_WEBROOT=/var/cache/jenkins/war"
Environment="JENKINS_LOG=/var/log/jenkins/jenkins.log"

Environment="JENKINS_JAVA_OPTIONS=-Djava.awt.headless=true -XX:MaxRAMPercentage=50.0 -XX:+UseG1GC"
Environment="JENKINS_OPTS=--sessionTimeout=1440"

[Install]
WantedBy=multi-user.target

Docker Configuration

docker-compose.yml:

version: "3.8"

services:
  jenkins:
    image: jenkins/jenkins:lts
    container_name: jenkins
    privileged: true
    user: root
    ports:
      - 8080:8080
      - 50000:50000
    volumes:
      - jenkins_home:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - JAVA_OPTS=-Djava.awt.headless=true -XX:MaxRAMPercentage=50.0 -XX:+UseG1GC
      - JENKINS_OPTS=--sessionTimeout=1440

volumes:
  jenkins_home:

Startup Options

Command Line Arguments

# Basic startup
java -jar jenkins.war

# With custom port
java -jar jenkins.war --httpPort=9090

# With HTTPS
java -jar jenkins.war --httpPort=-1 --httpsPort=8443 --httpsKeyStore=keystore --httpsKeyStorePassword=password

# With prefix
java -jar jenkins.war --prefix=/jenkins

# With custom home
java -DJENKINS_HOME=/custom/path -jar jenkins.war

Common Startup Arguments

Argument	Description	Example
--httpPort	HTTP port	--httpPort=8080
--httpsPort	HTTPS port	--httpsPort=8443
--prefix	URL prefix	--prefix=/jenkins
--sessionTimeout	Session timeout (minutes)	--sessionTimeout=60
--logfile	Log file location	--logfile=/var/log/jenkins.log

Performance Optimization

Memory Recommendations

Jenkins Size	Heap Size	Recommended RAM
Small (<100 jobs)	1-2 GB	4 GB
Medium (100-500 jobs)	2-4 GB	8 GB
Large (500-1000 jobs)	4-8 GB	16 GB
Enterprise (>1000 jobs)	8-16 GB	32 GB+

GC Tuning for Different Workloads

For many short builds:

-XX:+UseG1GC \
-XX:MaxGCPauseMillis=100 \
-XX:ParallelGCThreads=8

For long-running builds:

-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:G1ReservePercent=20

For large workspaces:

-XX:+UseG1GC \
-XX:G1HeapRegionSize=16m \
-XX:InitiatingHeapOccupancyPercent=30

Logging Configuration

Enable Debug Logging

-Djava.util.logging.config.file=/path/to/logging.properties

logging.properties:

handlers=java.util.logging.ConsoleHandler
.level=INFO

# Set Jenkins logger to FINE
jenkins.level=FINE
hudson.level=FINE

# Plugin-specific logging
hudson.plugins.git.GitSCM.level=FINE
org.jenkinsci.plugins.workflow.level=FINE

GC Logging

# Java 8
-Xloggc:/var/log/jenkins/gc.log \
-XX:+PrintGCDetails \
-XX:+PrintGCDateStamps \
-XX:+UseGCLogFileRotation \
-XX:NumberOfGCLogFiles=5 \
-XX:GCLogFileSize=20M

# Java 11+
-Xlog:gc*:file=/var/log/jenkins/gc.log:time,level,tags:filecount=5,filesize=20M

Troubleshooting

Common Issues

Out of Memory:

# Increase heap size
-Xmx4096m -Xms2048m

# Add heap dump on OOM
-XX:+HeapDumpOnOutOfMemoryError \
-XX:HeapDumpPath=/var/log/jenkins/heapdump.hprof

Slow Startup:

# Reduce plugin load time
-Dhudson.Main.development=true

# Disable plugin dependency resolution
-Dhudson.PluginStrategy=hudson.ClassicPluginStrategy

Connection Timeouts:

# Increase read timeout
-Dhudson.model.DownloadService.noSignatureCheck=true \
-Dhttp.proxyHost=proxy.example.com \
-Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com \
-Dhttps.proxyPort=8080

Security Hardening

Recommended Security Options

# Disable CLI
-Djenkins.CLI.disabled=true

# Enable agent protocols
-Djenkins.slaves.JnlpSlaveAgentProtocol3.enabled=false

# Set strict CSP
-Dhudson.model.DirectoryBrowserSupport.CSP="sandbox; default-src 'none';"

# Disable insecure features
-Dhudson.model.ParametersAction.keepUndefinedParameters=false

# Enable modern agent protocols only
-Djenkins.install.runSetupWizard=false

Monitoring

JMX Configuration

-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=9999 \
-Dcom.sun.management.jmxremote.authenticate=false \
-Dcom.sun.management.jmxremote.ssl=false

Metrics Endpoint

# Enable metrics
-Djenkins.metrics.api.Metrics.enabled=true

# Access at http://jenkins/metrics/currentUser/

Resources

• Jenkins System Properties
• Jenkins Performance Tuning
• JVM Options Reference