Upgrading to Jenkins LTS 2.249.x

Each section covers the upgrade from the previous LTS release, the section on 2.249.1 covers the upgrade from 2.235.5.

Upgrading to Jenkins 2.249.3

No notable changes requiring upgrade notes.

Upgrading to Jenkins 2.249.2

No notable changes requiring upgrade notes.

Upgrading to Jenkins 2.249.1

Microsoft .NET Framework 2.0 support removed

winsw logo
Figure 1. WinSW Logo

Starting from this release, we won’t support .NET Framework 2.0 for launching the Jenkins controller or agents as Windows services. Microsoft.NET Framework 4.0 or above is now required for using the default service management features.

This release also upgrades Windows Service Wrapper (WinSW) from 2.3.0 to 2.9.0 and replaces the bundled binary from .NET Framework 2.0 to 4.0. There are many improvements and fixes in these versions, big thanks to NextTurn and all other contributors. You can find the full WinSW changelog here, just a few highlights important to Jenkins users:

  • Prompt for permission elevation when administrative access is required. Now Jenkins users do not need to run the agent process as Administrator to install the agent as a service from GUI.

  • Enable TLS 1.1/1.2 in .NET Framework 4.0 packages on Windows 7 and Windows Server 2008 R2.

  • Enable strong cryptography when running .NET Framework 4.0 binaries on .NET 4.6.

  • Support security descriptor string in the Windows service definition.

  • Support 'If-Modified-Since' and proxy settings for automatic downloads.

  • Fix Runaway Process Killer extension so that it does not kill wrong processes with the same PID on startup.

  • Fix the default domain name in the serviceaccount parameter (JENKINS-12660)

  • Fix archiving of old logs in the roll-by-size-time mode.

As you may see, there are many improvements available with this version, and we hope that it will make Windows service installation even more reliable. Some of the changes in WinSW also replaced old workarounds in the Jenkins core, making the code more maintainable.

Use-cases affected by .NET Framework 2.0 support removal

If you use .NET Framework 2.0 to run the Jenkins Windows services, the following use-cases are likely to be affected:

  • Installing the Jenkins controller as a Windows service from Web UI. The official MSI Installer supports .NET Framework 2.0 for the moment, but it will be changed in future versions.

  • Installing agents as Windows services from GUI. This feature is provided by in Windows Agent Installer Module from the Jenkins core.

  • Installing agents over Windows Management Instrumentation (WMI) via the WMI Windows Agents plugin

  • Auto-updating of Windows service wrappers on agents installed from GUI.

Upgrade guidelines

If all of your Jenkins controller and agent instances already use .NET Framework 4.0 or above, there are no special upgrade steps required. Please enjoy the new features!

If you run the Jenkins controller as a Windows Service with .NET Framework 2.0, this instance will require an upgrade of .NET Framework to version 4.0 or above. We recommend running with .NET Framework 4.6.1 or above, because this .NET version provides many platform features by default (e.g. TLS 1.2 encryption and strong cryptography), and Windows Service Wrapper does not have to apply custom workarounds.

If you want to continue running some of your agents with .NET Framework 2.0, the following extra upgrade steps are required:

  1. Disable auto-upgrade of Windows Service Wrapper on agents by setting the -Dorg.jenkinsci.modules.windows_slave_installer.disableAutoUpdate=true flag on the Jenkins controller side.

  2. Upgrade agents with .NET Framework 4.0+ by downloading the recent Windows Service Wrapper 2.x version from WinSW GitHub Releases and manually replacing the wrapper ".exe" files in the agent workspaces.

WMI Windows agents plugin

The WMI Windows Agents plugin version 1.7 has been released for Jenkins 2.249.1 and later. Prior versions of the plugin will report a null pointer exception and the agent will fail to connect to Jenkins 2.249.1.

Jenkins 2.249.1 users of the WMI Windows Agents plugin should upgrade to version 1.7.

View job status filter

As part of a performance improvement for list views, the statusFilter key is now an optional, separate item in the Jenkins view configuration.

The job status filter has been moved to be a Job View Filter. The order of this filter matters as its interaction with various other filters will affect what jobs are shown in the view. If the status filter is the first filter (filtering only enabled jobs) and a later filter adds a disabled job. the disabled job will be visible. If the status filter is last in the same scenario, the disabled job will not be visible.

The job status filter defined on views from previous Jenkins versions is not migrated in Jenkins 2.249.1 Refer to JENKINS-62661.
Configuration as code statusFilter

The statusFilter key in configuration as code view definitions must be removed or replaced with a new entry as part of the upgrade to Jenkins 2.249.1.

Previous configuration

The previous configuration looked like this:

  views:
  - list:
      columns:
      - "status"
      - "weather"
      - "jobName"
      description: "Jobs failing recently"
      jobFilters:
      - jobStatusFilter:
          aborted: true
          failed: true
          includeExcludeTypeString: "includeMatched"
      name: "Failed Jobs"
      statusFilter: true # This must be removed
New configuration

The new configuration looks like this:

  views:
  - list:
      columns:
      - "status"
      - "weather"
      - "jobName"
      description: "Jobs failing recently"
      jobFilters:
      - jobStatusFilter:
          aborted: true
          failed: true
          includeExcludeTypeString: "includeMatched"
      - statusFilter: # This is the replacement section
          statusFilter: true
      name: "Failed Jobs"

If the statusFilter key is not updated or removed from the YAML file, Jenkins halts during startup with a stack trace. The initial section of the failure stack trace looks like this:

Configuration as code stack trace
SEVERE  jenkins.InitReactorRunner$1#onTaskFailed: Failed ConfigurationAsCode.init
io.jenkins.plugins.casc.ConfiguratorException: 'statusFilter' is deprecated
        at io.jenkins.plugins.casc.BaseConfigurator.configure(BaseConfigurator.java:321)
        at io.jenkins.plugins.casc.BaseConfigurator.configure(BaseConfigurator.java:270)
        ...

Alternate URL removed from inbound agent

Jenkins 2.249.1 no longer provides a fallback URL in the inbound agent launch file (the slave-agent.jnlp file). Prior releases included an alternate URL in the inbound agent launch file when the launch file was requested through a URL that is not the Jenkins root URL. If the Jenkins root URL was unreachable by the agent, the alternate URL was used.

The alternate URL must be provided as an argument to the agent.jar command for Jenkins 2.249.1 and later. The inbound agent can connect to the alternate URL using commands like this:

$ WORKDIR=<work-dir-from-agent-definition-page>
$ ALTERNATE_URL=<alternate-url-used-to-access-Jenkins>
$ SECRET_STRING=<secret-from-agent-definition-page>
$ AGENT_NAME=<agent-name-from-agent-definition-page>
$ java -cp agent.jar hudson.remoting.jnlp.Main \
  -headless \
  -workDir $WORKDIR \
  -url $ALTERNATE_URL \
  $SECRET_STRING \
  $AGENT_NAME