JENKINS_HOME, Filesystem Layout, Controller Configuration, System Settings, Tools, and Global Properties: Configuration, Design Choices, and Tradeoffs

1. The governing design question: who owns this state?

Jenkins can persist a setting through the UI, load supported configuration from JCasC, generate jobs from Job DSL, discover repositories from SCM, download tools, archive build outputs, and invoke external systems. These mechanisms are not interchangeable. A maintainable controller gives each important state one accountable source.

2. UI-managed versus configuration-as-code state

Chapter 26 teaches JCasC in depth. Here, the important point is architectural: JCasC is a configuration source for supported controller/plugin state, not a substitute for plugin binaries, all job/build history, encrypted credential records, or validated backups.

3. Globally configured tools versus agent/container-local tools

Manage Jenkins → Tools can define JDK, Git, Maven, and other plugin-provided tools. That can be convenient, but the build still executes on an agent. The agent must be able to receive/use the tool, and its OS/architecture/network policy matter.

For production reproducibility, record both the logical Jenkins tool configuration and the actual tool version observed on the executing agent. A name like “Maven-3” is intent; mvn --version on the agent is execution evidence.

4. Full-home versus selective backups

A full JENKINS_HOME snapshot is straightforward and minimizes the chance of omitting obscure plugin state. It can also be large because build records, artifacts, tools, caches, and plugin expansions accumulate. Selective strategies reduce size but increase the burden of proving the restore recipe.

RPO and RTO drive the choice. If build history is audit evidence, it has recovery value. If archived release artifacts are also published immutably to a repository, Jenkins copies may be lower priority. Document these assumptions explicitly.

5. Controller-local files versus external durable services

Jenkins frequently stores a reference to an external thing: an SCM URL, credential ID, registry endpoint, artifact repository, Kubernetes cluster, cloud account, or SonarQube server. The external system owns its own data and availability.

flowchart TD
  A[JENKINS_HOME: job + credential reference] --> B[Jenkins build]
  B --> C[SCM commit]
  B --> D[Artifact repository package/digest]
  B --> E[Cloud/Kubernetes deployment]
  A --> F[Controller backup]
  C --> G[SCM backup/retention]
  D --> H[Repository retention/DR]
  E --> I[Provider state/DR]

A Jenkins restore can recover the job that says “deploy package X,” but it cannot recreate package X if the artifact repository lost it. Recovery plans must therefore map cross-system dependencies.

6. Restart, reload, and live state are different operations

A controller restart stops the process and rebuilds runtime state from disk and external sources. Some configuration mechanisms can reload selected state, while plugins may have their own semantics. Raw filesystem edits while Jenkins is running are dangerous because in-memory objects may later serialize over those edits, or Jenkins may not notice them until a reload/restart.

Later chapters cover JCasC reload and upgrade/restart planning. In this chapter, choose the least surprising rule: change through supported interfaces; if low-level filesystem repair is unavoidable, stop the controller, snapshot first, edit only documented state, preserve the original, and validate startup on an isolated copy.

7. Worked decisions

8. Security and least-privilege implications

• Filesystem read access to JENKINS_HOME is highly privileged; it can expose job configuration, tokens, keys, histories, and plugin data.
• Backup systems become part of the Jenkins trust boundary. Encrypt them, restrict readers, and separate recovery keys.
• Tool auto-installation expands network and supply-chain dependencies; pin versions and trusted sources where practical.
• Do not grant agents broad controller filesystem access. Controller isolation is a security boundary, not a performance preference.
• Document who may change System, Tools, plugin versions, configuration code, and restore procedures.

9. Design challenge

A team has one controller, 80 repositories, ephemeral Kubernetes agents, a Nexus repository, and JCasC in Git. Build logs must be retained 90 days; release packages must be retained seven years. Propose which state belongs in:

1. JCasC/SCM,
2. controller backup,
3. agent image/template,
4. Nexus,
5. separate secret-key recovery storage.

For each choice, state the source of truth, the minimum recovery evidence, and what a Jenkins restore cannot recover automatically.

10. Summary

• Configuration ownership matters more than configuration location.
• UI, JCasC, Job DSL, tools, agent images, and external repositories solve different problems.
• Backup scope trades storage/consistency cost against recovery complexity.
• External systems retain their own durable state; Jenkins stores references and automation around them.
• Low-level filesystem repair should be exceptional, stopped-controller work with snapshots and validation.

Knowledge check

Official references and version notes

• Configuring the System — current Jenkins home-directory and global system-configuration guidance.
• Managing Jenkins — current administrative surfaces for System, Tools, Plugins, status, and troubleshooting.
• System Information — controller system properties, environment variables, plugins, memory information, and diagnostics.
• Managing Tools — built-in tool-provider concepts and global tool configuration.
• Backing-up/Restoring Jenkins — backup scope, controller-key separation, and restore validation.
• Credentials security — why Jenkins secret-key material needs protection and separation from ordinary backups.
• Storing Secrets — technical description of Jenkins encryption keys under $JENKINS_HOME/secrets.
• Controller Isolation — current guidance for keeping routine builds off the built-in controller node.
• Jenkins LTS changelog and Java Support Policy — version/runtime assumptions for this chapter.