Jenkins Features Controlled with System Properties

Jenkins has several "hidden" features that can be enabled with system properties. This page describes how to configure them on your instance.

Usage

System properties are defined by passing -Dproperty=value to the java command line to start Jenkins. Make sure to pass all of these arguments before the -jar argument, otherwise they will be ignored. Example:

java -Dhudson.footerURL=http://example.org -jar jenkins.war

The following table lists the properties and the version of Jenkins they were introduced in.

  • Property - Java property name

  • Default - Default value if not explicitly set

  • Version - The version of Jenkins the property was introduced in

  • Notes - Other notes

Compatibility notice

We do NOT guarantee compatibility for system properties. These switches are often experimental in nature, and subject to change without notice. If you find some of those useful, please file a ticket to promote it to the official feature.

Properties in Jenkins Core

hudson.ClassicPluginStrategy.useAntClassLoader

Default: false
Since: 1.316
Description:

hudson.cli.CLI.pingInterval

Default: 3000
Since: 2.199
Description: Client-side HTTP CLI ping interval in milliseconds. Set on the CLI client (java -jar jenkins-cli.jar), not Jenkins server process.

hudson.ConsoleNote.INSECURE

Default: false
Since: 2.44 / 2.32.2
Description: Whether to load unsigned console notes (see SECURITY-382 on Jenkins Security Advisory 2017-02-01)

hudson.consoleTailKB

Default: 150
Since: Actually works since 2.98/2.89.3
Description: How many KB of console log to show in default console view

hudson.diagnosis.HudsonHomeDiskUsageChecker.freeSpaceThreshold

Default: 1073741824 (1 GB, up to 2.39), 10737418240 (10 GB, from 2.40)
Since: 1.339
Description: If there’s less than this amount of free disk space, in bytes, on the disk with the Jenkins home directory, and the disk is 90% or more full, a warning will be shown to administrators

hudson.diyChunking

Default: false
Since: n/a
Description: Set to true if the servlet container doesn’t support chunked encoding

hudson.DNSMultiCast.disabled

Default: false
Since: 1.359
Description: Set to true to disable DNS multicast

hudson.FilePath.VALIDATE_ANT_FILE_MASK_BOUND

Default: 10000
Since: 1.592
Description: Max. number of operations to validate a file mask (e.g. pattern to archive artifacts).

hudson.footerURL

Default: https://jenkins.io
Since: 1.416
Description: Allows tweaking the URL displayed at the bottom of Jenkins' UI

hudson.Functions.autoRefreshSeconds

Default: 10
Since: 1.365
Description: Number of seconds between reloads when Auto Refresh is enabled

hudson.lifecycle

Default: n/a
Since: n/a
Description: Specify full class name for Lifecycle implementation to override default

hudson.logging.LogRecorderManager.skipPermissionCheck

Default: false
Since: 2.121.3 and 2.138
Description: Disable security hardening for LogRecorderManager Stapler access. Possibly unsafe, see 2018-12-05 security advisory.

hudson.matrix.MatrixConfiguration.useShortWorkspaceName

Default: false
Since: n/a
Description: Use shorter but cryptic names in matrix build workspace directories. Avoids problems with 256 character limit on paths in Cygwin, path depths problems on Windows, and shell metacharacter problems with label expressions on most platforms. See JENKINS-25783.

hudson.model.AbstractItem.skipPermissionCheck

Default: false
Since: 2.121.3 / 2.138
Description: Disable security hardening related to Stapler routing for AbstractItem. Possibly unsafe, see 2018-12-05 security advisory.

hudson.model.AsyncAperiodicWork.logRotateMinutes

Default: 1440
Since: 1.651
Description: The number of minutes after which to try and rotate the log file used by any AsyncAperiodicWork extension. For fine-grained control of a specific extension you can use the FullyQualifiedClassName.logRotateMinutes system property to only affect a specific extension. It is not anticipated that you will ever need to change these defaults

hudson.model.AsyncAperiodicWork.logRotateSize

Default: -1
Since: 1.651
Description: When starting a new run of any AsyncAperiodicWork extension, if this value is non-negative and the existing log file is larger than the specified number of bytes then the log file will be rotated. For fine-grained control of a specific extension you can use the FullyQualifiedClassName.logRotateSize system property to only affect a specific extension. It is not anticipated that you will ever need to change these defaults

hudson.model.AsyncPeriodicWork.logRotateMinutes

Default: 1440
Since: 1.651
Description: The number of minutes after which to try and rotate the log file used by any AsyncPeriodicWork extension. For fine-grained control of a specific extension you can use the FullyQualifiedClassName.logRotateMinutes system property to only affect a specific extension. It is not anticipated that you will ever need to change these defaults

hudson.model.AsyncPeriodicWork.logRotateSize

Default: -1
Since: 1.651
Description: When starting a new run of any AsyncPeriodicWork extension, if this value is non-negative and the existing log file is larger than the specified number of bytes then the log file will be rotated. For fine-grained control of a specific extension you can use the FullyQualifiedClassName.logRotateSize system property to only affect a specific extension. It is not anticipated that you will ever need to change these defaults

hudson.model.DirectoryBrowserSupport.CSP

Default: sandbox; default-src 'none'; image-src 'self'; style-src 'self';
Since: 1.625.3, 1.641
Description: Determines the Content Security Policy header sent for static files served by Jenkins. See Configuring Content Security Policy for more details.

hudson.model.DownloadService.never

Default: false
Since: n/a
Description: Suppress the periodic download of data files for plugins

hudson.model.Hudson.flyweightSupport

Default: false before 1.337; true from 1.337; unused since 1.598
Since: 1.318
Description: Matrix parent job and other flyweight tasks (e.g. Build Flow plugin) won’t consume an executor when true. Unused since 1.598, flyweight support is now always enabled.

hudson.model.Hudson.killAfterLoad

Default: false
Since: n/a
Description: Exit Jenkins right after loading

hudson.model.Hudson.parallelLoad

Default: true
Since: n/a
Description: Loads job configurations in parallel on startup

hudson.model.LoadStatistics.clock

Default: 10000
Since: n/a
Description: Load statistics clock cycle in milliseconds

hudson.model.LoadStatistics.decay

Default: 0.9
Since: n/a
Description: Decay ratio for every clock cycle in node utilization charts

hudson.model.MultiStageTimeSeries.chartFont

Default: SansSerif-10
Since: 1.562
Description: Font used for load statistics (see Java documentation on how the value is decoded)

hudson.model.ParametersAction.keepUndefinedParameters

Default: undefined
Since: 1.651.2 / 2.3
Description: If true, not discard parameters for builds that are not defined on the job. Enabling this can be unsafe Since Jenkins 2.40, if set to false, will not log a warning message that parameters were defined but ignored.

hudson.model.ParametersAction.safeParameters

Default: undefined
Since: 1.651.2 / 2.3
Description: Comma-separated list of additional build parameter names that should not be discarded even when not defined on the job.

hudson.model.Queue.cacheRefreshPeriod

Default: 1000
Since: 1.577 up to 1.647
Description: Defines the refresh period for the internal queue cache (in milliseconds). The greater period workarounds web UI delays on large installations, which may be caused by locking of the build queue by build executors. Downside - builds appear in the queue with a noticeable delay.

hudson.model.Queue.Saver.DELAY_SECONDS

Default: 60
Since: 2.109
Description: Maximal delay of a save operation when content of Jenkins queue changes. This works as a balancing factor between queue consistency guarantee in case of Jenkins crash (short delay) and decreasing IO activity based on Jenkins load (long delay).

hudson.model.Run.ArtifactList.listCutoff

Default: 16
Since: 1.330
Description: More artifacts than this will use tree view or simple link rather than listing out artifacts

hudson.model.Run.ArtifactList.treeCutoff

Default: 40
Since: 1.330
Description: More artifacts than this will show a simple link to directory browser rather than showing artifacts in tree view

hudson.model.Slave.workspaceRoot

Default: workspace
Since: 1.341?
Description: name of the folder within the slave root directory to contain workspaces

hudson.model.UpdateCenter.className

Default: n/a
Since: 2.4
Description: Allow overriding the implementation class for update center. Useful for custom war distributions with a different update center implementation. Cannot be used for plugins.

hudson.model.UpdateCenter.defaultUpdateSiteId

Default: default
Since: 2.4
Description: Configure a different ID for the default update site. Useful for custom war distributions or externally provided UC data files

hudson.model.UpdateCenter.never

Default: false
Since: n/a
Description: When true, don’t automatically check for new versions

hudson.model.UpdateCenter.skipPermissionCheck

Default: false
Since: 2.121.3 / 2.138
Description: Disable security hardening related to Stapler routing for UpdateCenter. Possibly unsafe, see 2018-12-05 security advisory.

hudson.model.UsageStatistics.disabled

Default: false
Since: 1.312 or so?
Description: Set to true to opt out of usage statistics collection, independent of UI option.

hudson.model.User.allowNonExistentUserToLogin

Default: false
Since: 1.602
Description: When true, does not check auth realm for existence of user if there’s a record in Jenkins. Unsafe, but may be used on some instances for service accounts

hudson.model.User.allowUserCreationViaUrl

Default: false
Since: 2.44 / 2.32.2
Description: Whether admins accessing /user/example creates a user record (see SECURITY-406 on Jenkins Security Advisory 2017-02-01)

hudson.model.User.SECURITY_243_FULL_DEFENSE

Default: true
Since: 1.651.2 / 2.3
Description: When false, skips part of the fix that tries to determine whether a given user ID exists, and if so, doesn’t consider users with the same full name during resolution.

hudson.model.User.skipPermissionCheck

Default: false
Since: 2.121.3 / 2.138
Description: Disable security hardening related to Stapler routing for User. Possibly unsafe, see 2018-12-05 security advisory.

hudson.model.WorkspaceCleanupThread.disabled

Default: false
Since: n/a
Description: Don’t clean up old workspaces on slave nodes

hudson.model.WorkspaceCleanupThread.recurrencePeriodHours

Default: 24
Since: 1.608
Description: How often workspace cleanup should run, in hours.

hudson.model.WorkspaceCleanupThread.retainForDays

Default: 30
Since: 1.608
Description: Unused workspaces are retained for this many days before qualifying for deletion.

hudson.os.solaris.ZFSInstaller.disabled

Default: false
Since: n/a
Description: True to disable ZFS monitor on Solaris

hudson.PluginManager.CHECK_UPDATE_ATTEMPTS

Default: 1
Since: 2.152
Description: Number of attempts to check the updates sites.

hudson.PluginManager.checkUpdateSleepTimeMillis

Default: 1000
Since: 2.152
Description: Time (milliseconds) elapsed between retries to check the updates sites.

hudson.PluginManager.skipPermissionCheck

Default: false
Since: 2.121.3 / 2.138
Description: Disable security hardening related to Stapler routing for PluginManager. Possibly unsafe, see 2018-12-05 security advisory.

hudson.PluginManager.workDir

Default: undefined
Since: 1.649
Description: Location of the base directory for all exploded .hpi/.jpi plugins. By default the plugins will be extracted under $JENKINS_HOME/plugins/.

hudson.PluginStrategy

Default: n/a
Since: n/a
Description: Allow plugins to be loaded into a different environment, such as an existing DI container like Plexus; specify full class name here to override default ClassicPluginStrategy

hudson.PluginWrapper.dependenciesVersionCheck.enabled

Default: true
Since: 2.0
Description: Set to false to skip the version check for plugin dependencies.

hudson.ProxyConfiguration.DEFAULT_CONNECT_TIMEOUT_MILLIS

Default: 20000
Since: 2.0
Description: Connection timeout applied to connections e.g. to the update site.

hudson.scheduledRetention

Default: false
Since: Up to 1.354
Description: Control a slave based on a schedule

hudson.scm.CVSSCM.skipChangeLog

Default: false
Since: n/a
Description: Useful with ancient versions of CVS that don’t support the -d option in the log command

hudson.search.Search.skipPermissionCheck

Default: false
Since: 2.121.3 / 2.138
Description: Disable security hardening related to Stapler routing for Search. Possibly unsafe, see 2018-12-05 security advisory.

hudson.security.AccessDeniedException2.REPORT_GROUP_HEADERS

Default: false
Since: 2.46 / 2.32.3
Description: If set to true, restore pre-2.46 behavior of sending HTTP headers on "access denied" pages listing group memberships.

hudson.security.ArtifactsPermission

Default: false
Since: 1.374
Description: The Artifacts permission allows to control access to artifacts; When this property is unset or set to false, access to artifacts is not controlled

hudson.security.csrf.requestfield

Default: .crumb (Jenkins 1.x), Jenkins-Crumb (Jenkins 2.0)
Since: 1.310
Description: Parameter name that contains a crumb value on POST requests

hudson.security.ExtendedReadPermission

Default: false
Since: 1.324
Description: The ExtendedReadPermission allows read-only access to "Configure" pages; can also enable with extended-read-permission plugin

hudson.security.HudsonPrivateSecurityRealm.ID_REGEX

Default: [a-zA-Z0-9_-]+
Since: 2.121 and 2.107.3
Description: Regex for legal user names in Jenkins user database. See SECURITY-786.

hudson.security.LDAPSecurityRealm.groupSearch

Default: TBD
Since: n/a
Description: LDAP filter to look for groups by their names

hudson.security.WipeOutPermission

Default: false
Since: 1.416
Description: The WipeOut permission allows to control access to the "Wipe Out Workspace" action, which is normally available as soon as the Build permission is granted

hudson.slaves.ChannelPinger.pingInterval

Default: 5
Since: 1.405
Description: (Deprecated since 2.37) Frequency (in minutes) of pings between the master and slaves

hudson.slaves.ChannelPinger.pingIntervalSeconds

Default: 300
Since: 2.37
Description: Frequency of pings between the master and slaves, in seconds

hudson.slaves.ChannelPinger.pingTimeoutSeconds

Default: 240
Since: 2.37
Description: Timeout for each ping between the master and slaves, in seconds

hudson.slaves.WorkspaceList

Default: @
Since: 1.424
Description: When concurrent builds is enabled, a unique workspace directory name is required for each concurrent build. To create this name, this token is placed between project name and a unique ID, e.g. "my-project@123".

hudson.tasks.ArtifactArchiver.warnOnEmpty

Default: false
Since: n/a
Description: When true, builds don’t fail when there is nothing to archive

hudson.tasks.Fingerprinter.enableFingerprintsInDependencyGraph

Default: false
Since: 1.430
Description: When true, jobs associated through fingerprints are added to the dependency graph, even when there is no configured upstream/downstream relationship between them.

hudson.tasks.MailSender.maxLogLines

Default: 250
Since: n/a
Description: Number of lines of console output to include in emails

hudson.TcpSlaveAgentListener.hostName

Default: n/a
Since: n/a
Description: Host name that Jenkins advertises to its clients. Especially useful when running Jenkins behind a reverse proxy.

hudson.TcpSlaveAgentListener.port

Default: n/a
Since: n/a
Description: Port that Jenkins advertises to its clients. Especially useful when running Jenkins behind a reverse proxy.

hudson.TreeView

Default: false
Since: n/a
Description: Experimental nested views feature

hudson.triggers.SafeTimerTask.logsTargetDir

Default: $JENKINS_HOME/logs
Since: 2.114
Description: Allows to move the logs usually found under $JENKINS_HOME/logs to another location. Beware that no migration is handled if you change it on an existing instance.

hudson.triggers.SCMTrigger.starvationThreshold

Default: 1 hour
Since: n/a
Description: Milliseconds waiting for polling executor before trigger reports it is clogged

hudson.udp

Default: 33848
Since: n/a
Description: Port for UDP multicast broadcast (set to -1 to disable)

hudson.upstreamCulprits

Default: false
Since: 1.327
Description: Pass blame information to downstream jobs

hudson.Util.deletionRetryWait

Default: 100
Since: 2.2
Description: The time (in milliseconds) to wait between attempts to delete files when retrying. This has no effect unless hudson.Util.maxFileDeletionRetries is greater than 1. If zero, there will be no delay between attempts. If negative, the delay will be a (linearly) increasing multiple of this value between attempts.

hudson.Util.maxFileDeletionRetries

Default: 3
Since: 2.2
Description: The number of times to attempt to delete files/directory trees before giving up and throwing an exception. Specifying a value less than 1 is invalid and will be treated as if a value of 1 (i.e. one attempt, no retries) was specified. See JENKINS-10113 and JENKINS-15331.

hudson.Util.noSymLink

Default: false
Since: n/a
Description: True to disable creation of symbolic links in job/builds directories

hudson.Util.performGCOnFailedDelete

Default: false
Since: 2.2
Description: If this flag is set to true then we will request a garbage collection after a deletion failure before we next retry the delete. It is ignored unless hudson.Util.maxFileDeletionRetries is greater than 1.
Setting this flag to true may resolve some problems on Windows, and also for directory trees residing on an NFS share, but it can have a negative impact on performance and may have no effect at all (GC behavior is JVM-specific). Warning: This should only ever be used if you find that your builds are failing because Jenkins is unable to delete files, that this failure is because Jenkins itself has those files locked "open", and even then it should only be used on slaves with relatively few executors (because the garbage collection can impact the performance of all job executors on that slave). Setting this flag is a act of last resort - it is not recommended, and should not be used on your main Jenkins server unless you can tolerate the performance impact.

hudson.util.ProcessTree.disable

Default: false
Since: n/a
Description: True to disable cleanup of child processes

hudson.util.RingBufferLogHandler.defaultSize

Default: 256
Since: 1.563
Description: Number of log entries in loggers available on the UI at /log/

hudson.util.Secret.provider

Default: n/a
Since: 1.360
Description: Force a particular crypto provider; with Glassfish Enterprise set value to SunJCE to workaround a known issue.

hudson.Util.symlinkEscapeHatch

Default: false
Since: n/a
Description: True to use exec of "ln" binary to create symbolic links instead of native code

hudson.Util.useNativeChmodAndMode

Default: false
Since: 2.93
Description: True to use native (JNA/JNR) implementation to set file permissions instead of NIO

jenkins.CLI.disabled

Default: false
Since: 2.32 and 2.19.3
Description: true to disable Jenkins CLI via JNLP and HTTP (SSHD can still be enabled)

jenkins.InitReactorRunner.concurrency

Default: 2x of CPU
Since: n/a
Description: During start of Jenkins, loading of jobs in parallel have a fixed number of threads by default (twice the CPU). To make Jenkins load time 8x faster, increase it to 8x. For example, 24 CPU Jenkins Master host use this: -Dhudson.InitReactorRunner.concurrency=192

jenkins.install.runSetupWizard

Default: undefined
Since: 2.0
Description: Set to false to skip install wizard. Note that this leaves Jenkins unsecured by default. Development-mode only: Set to true to not skip showing the setup wizard during Jenkins development. This property is only effective the first time you run Jenkins in given JENKINS_HOME.

jenkins.model.Jenkins.buildsDir

Default: ${ITEM_ROOTDIR}/builds
Since: 2.119
Description: The configuration of a given job is located under $JENKINS_HOME/jobs/[JOB_NAME]/config.xml and its builds are under $JENKINS_HOME/jobs/[JOB_NAME]/builds by default. This option allows you to store builds elsewhere, which can be useful with finer-grained backup policies, or to store the build data on a faster disk such as an SSD. The following placeholders are supported for this value:

  • ${JENKINS_HOME}  – Resolves to the Jenkins home directory.

  • ${ITEM_ROOTDIR} – The directory containing the job metadata within Jenkins home.

  • ${ITEM_FULL_NAME} – The full name of the item, with file system unsafe characters replaced by others.

  • ${ITEM_FULLNAME} – See above, but does not replace unsafe characters. This is a legacy option and should not be used.

For instance, if you would like to store builds outside of Jenkins home, you can use a value like the following: /some_other_root/builds/${ITEM_FULL_NAME} This used to be a UI setting, but was removed in 2.119 as it did not support migration of existing build records and could lead to build-related errors until restart.

jenkins.model.Jenkins.crumbIssuerProxyCompatibility

Default: false
Since: 2.119
Description: true to enable crumb proxy compatibility when running the Setup Wizard for the first time.

jenkins.model.Jenkins.disableExceptionOnNullInstance

Default: false
Since: 2.4 only
Description: true to disable throwing an IllegalStateException when Jenkins.getInstance() returns null

jenkins.model.Jenkins.enableExceptionOnNullInstance

Default: false
Since: 2.5
Description: true to enable throwing an IllegalStateException when Jenkins.getInstance() returns null

jenkins.model.Jenkins.exitCodeOnRestart

Default: 5
Since: 2.102
Description: When using the -Dhudson.lifecycle=hudson.lifecycle.ExitLifecycle, exit using this exit code when Jenkins is restarted

jenkins.model.Jenkins.logStartupPerformance

Default: false
Since: n/a
Description: Log startup timing info

jenkins.model.Jenkins.slaveAgentPort

Default: -1 (disabled)
Since: 1.643
Description: Specifies the default TCP slave agent port unless/until configured differently on the UI. -1 to disable, 0 for random port, other values for fixed port. Used to be 0 by default before Jenkins 2.0

jenkins.model.Jenkins.slaveAgentPortEnforce

Default: false
Since: 2.19.4 and 2.24
Description: If true, enforces the specified jenkins.model.Jenkins.slaveAgentPort on startup and will not allow changing it through the UI

jenkins.model.Jenkins.workspacesDir

Default: ${JENKINS_HOME}/workspace/${ITEM_FULL_NAME}
Since: 2.119
Description: Allows to change the directory layout for the job workspaces on the master node. See jenkins.model.Jenkins.buildsDir for supported placeholders.

jenkins.model.JenkinsLocationConfiguration.disableUrlValidation

Default: false
Since: 2.197 / LTS 2.176.4
Description: Disable URL validation intended to prevent an XSS vulnerability. See SECURITY-1471 for details.

jenkins.model.StandardArtifactManager.disableTrafficCompression

Default: false
Since: 2.196
Description: true to disable GZIP compression of artifacts when they’re transferred from slave nodes to master.  Uses less CPU at the cost of increased network traffic.

jenkins.security.ApiTokenProperty.adminCanGenerateNewTokens 

Default: false
Since: 2.129
Description: true to allow users with ADMINISTER permission to create API tokens using the new system for any user. Note that the user will not be able to use that token since it’s only displayed to the creator, once.

jenkins.security.ApiTokenProperty.showTokenToAdmins

Default: false
Since: 1.638
Description: True to show API tokens for users to administrators on the user configuration page. This was set to false as part of SECURITY-200

jenkins.security.FrameOptionsPageDecorator.enabled

Default: true
Since: 1.581
Description: Whether to send X-Frame-Options: sameorigin header, set to false to disable and make Jenkins embeddable

jenkins.security.stapler.StaplerDispatchValidator.disabled

Default: false
Since: 2.186 / 2.176.2
Description: true  to disable the SECURITY-534 fix.

jenkins.slaves.JnlpSlaveAgentProtocol3.enabled

Default: undefined
Since: 1.653
Description: false to disable the JNLP3 agent protocol, true to enable it. Otherwise it’s randomly enabled/disabled to A/B test it.

jenkins.slaves.NioChannelSelector.disabled

Default: false
Since: 1.560
Description: true to disable Nio for JNLP slaves

jenkins.ui.refresh

Default: false
Since: 2.222
Description: true to enable the new experimental UX on Jenkins. See JENKINS-60920. Also see Jenkins UX SIG.

org.jenkinsci.main.modules.sshd.SSHD.idle-timeout

Default: undefined
Since: 2.22
Description: Allows to configure the SSHD client idle timeout (value in milliseconds). Default value is 10min (600000ms).

org.jenkinsci.plugins.workflow.steps.durable_task.DurableTaskStep.REMOTE_TIMEOUT

Default: 20 seconds
Since: workflow-durable-task-step-plugin 2.29
Description: How long to wait for remote calls (see JENKINS-46507).

Properties in plugins

Plugins may define their own system properties. See the plugin documentation for more info.

Properties in other components

Particular Jenkins component have their own release cycle and documentation. In particular cases such components also include System Properties.

References



Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.