⇑ Managing Jenkins Index

Configuring the System

Use the Manage Jenkins >> System page to configure many standard aspects of your Jenkins server, including:

  • JDK installations

  • Build tools - Ant and Maven installations

  • Version control tools

  • Email configuration

This page discusses the fields that are present after a standard Jenkins installation using the "Suggested plugins". Plugins installed on your system may add sections to this page.

You can set these configurations using the Jenkins dashboard as described here or you can set them using Configuration as Code, where you define the configuration you want in a YAML file that you then deploy to a server to configure Jenkins. See Configuration as Code for more information.

General system-wide configurations

The top of the System Configuration page sets basic information about the controller:

  • Home Directory — Display the location of the Jenkins home directory. You can change this location by modifying the value of the JENKINS_HOME environment variable.

Details are in the Jenkins home directory section.

  • System Message — Text that is displayed at the top of your Jenkins home page. Use this page to display the name of the server and a short description of its purpose. It is also used to display announcements about scheduled down time and other information of interest to all Jenkins users. This field can include HTML tags or a pointer to a Wiki page and information about who to contact.

Inline help is available for most fields on most Manage Jenkins pages. To access the help, select the ? icon to the right of each field. Click the ? icon again to hide the help text.

Executors on controller

The # of executors field configures the number of executors on the controller. Typically, this should be set to 0 to prevent builds from running on the controller. A detailed explanation of executors on the controller is available in the controller isolation page. We will discuss executors for nodes and agents in a later section.

Quiet period

This field defines an interval to wait before actually starting a build. This can be used to collapse multiple adjacent commits into one build.

Jenkins location

You must configure the Jenkins Location area to identify this particular instance of Jenkins.

Two items must be defined here:

  • Jenkins URL — Replace the localhost:5000 string with information about the actual location people can use to access this Jenkins instance. This information can be:

    • The actual URL that people use to access Jenkins.

    • The host alias as defined by the name service. If your IT people cannot provide this, use dynamic DNS. This makes your instance easier for your users to access and makes your service relocatable.

Invest in a good URL! If your users cannot see Jenkins, much of the benefit is lost. Make the URL easy to remember. For example:

  • Bad: http://tjek-02.int.rev.example.org

  • Good: https://jenkins.example.org

  • System Admin e-mail address — Define the email address to which email about general Jenkins issues are sent. This can be an individual’s email address or an email alias that contains multiple email addresses.

Timestamper

The Timestamper fields define the format used to display timestamp information.

More about system configuration

Jenkins is very flexible and powerful. Default configurations can be used for most fields while you are getting started. As you learn more about how Jenkins works and how your project uses Jenkins, you can modify the values of settings on this page. Use these settings to fine-tune the behavior of your Jenkins instance.

When you are done modifying this screen, scroll to the bottom and click Save to apply your configuration changes.

Tools and actions

Choices in the Tools and actions section focus on service and system operation.

The Reload Configuration from Disk option reads the configuration from $JENKINS_HOME without restarting Jenkins.

The Prepare for Shutdown option prevents new jobs from being started and waits for running jobs to complete. Use this option to ensure a clean job termination before you shut down or restart Jenkins.

The Management page provides Jenkins Upgrade management. If you are running a standalone server, you can perform a one-click upgrade. Otherwise, you have a direct link to the latest WAR.

Troubleshooting

Manage Old Data displays data that may have been stored previously but is no longer applicable. It helps the administrator identify changes after an upgrade.

Jenkins home directory

Jenkins stores its global configuration in files on the Jenkins controller. Administrators and privileged users modify the global configuration from the Jenkins configuration pages.

The JENKINS_HOME directory is the root of the directory structure on disk that Jenkins uses to perform builds and keep archives. The Jenkins home directory is listed in Manage Jenkins > System under the Home directory heading.

Home dir

  • On Windows by default, this is set to C:\ProgramData\Jenkins\.jenkins.

  • On Ubuntu by default, this is set to ~/.jenkins.

But you can change this in one of the following ways:

  • Set the JENKINS_HOME environment variable.

  • Set the JENKINS_HOME Java system property.

You can change this location after you’ve used Jenkins for a while, too. To do this:

  1. Stop Jenkins completely.

  2. Move the contents from the old JENKINS_HOME to the new location.

  3. Set the JENKINS_HOME variable to the new location.

  4. Restart Jenkins.

The directory structure of the JENKINS_HOME tree is often structured as follows:

JENKINS_HOME
 +- builds            (build records)
    +- [BUILD_ID]     (subdirectory for each build)
         +- build.xml      (build result summary)
         +- changelog.xml  (change log)
 +- config.xml         (Jenkins root configuration file)
 +- *.xml              (other site-wide configuration files)
 +- fingerprints       (stores fingerprint records, if any)
 +- identity.key.enc   (RSA key pair that identifies an instance)
 +- jobs               (root directory for all Jenkins jobs)
     +- [JOBNAME]      (sub directory for each job)
         +- config.xml (job configuration file)
     +- [FOLDERNAME]   (sub directory for each folder)
         +- config.xml (folder configuration file)
         +- jobs       (subdirectory for all nested jobs)
 +- plugins            (root directory for all Jenkins plugins)
     +- [PLUGIN]       (sub directory for each plugin)
     +- [PLUGIN].jpi   (.jpi or .hpi file for the plugin)
 +- secret.key         (deprecated key used for some plugins' secure operations)
 +- secret.key.not-so-secret  (used for validating _$JENKINS_HOME_ creation date)
 +- secrets            (root directory for the secret+key for credential decryption)
     +- hudson.util.Secret   (used for encrypting some Jenkins data)
     +- master.key           (used for encrypting the hudson.util.Secret key)
     +- InstanceIdentity.KEY (used to identity this instance)
 +- userContent        (files served under your https://server/userContent/)
 +- workspace          (working directory for the version control system)
⇑ Managing Jenkins Index

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.