Remoting Update. Protocols deprecation, Java 8 requirement and plans

Published on 2017-08-11 by Oleg Nenashev
Updated on Jan 10, 2019: The deprecated protocols were removed in Remoting 3.40+ and Jenkins 2.214+. See JENKINS-60381: Remove old for more information and links.

There are upcoming changes in Jenkins "core" which may require extra steps when upgrading Jenkins. If you use configuration management for Jenkins agents, please read this announcement carefully.

If you have ever seen messages like "Channel is already closed" or "Remote call failed" in your build logs, you have already met Jenkins Remoting.

Remoting is an agent executable and a library implementing the communication layer between Jenkins controllers and their agents (including communication protocols, distributed calls and classloading). It is also used in several other cases: Maven Integration Plugin, Remoting-based CLI, etc.

In order to make it clear what’s changing in Jenkins Remoting, I have documented the various components on the Remoting’s sub-project page, and will try to publish regular updates about the status of Remoting to this site and the developer mailing list.

In this post I would like to provide an update on the Remoting roadmap and to announce two major incoming changes: deprecation of old protocols and upgrade to Java 8. Both changes will take place in one of the next Weekly releases. ETA is Jenkins 2.75 on Aug 20, 2017.

Below are details on the incoming changes and compatibility notes.

Old Remoting Protocols Deprecation

It has been almost one year since the release of JNLP4-connect protocol in Remoting 3.0. This protocol has been enabled by default since 2.46.x, and so far it demonstrates good stability being compared to JNLP2 and JNLP3 protocols.

At the governance meeting we decided to disable old Remoting protocols (JNLP/JNLP2 + CLI1) in new installations by default. There are 3 reasons for it:

  1. Maintenance of multiple protocols takes a lot of extra effort. The JNL2 NIO engine is complex and barely diagnosable.

  2. There are known issues in JNLP2 connection management (see the protocol’s Errata). In many cases update to JNLP4 was a resolution

  3. JNLP1/JNLP2/CLI1 are unencrypted, and it is not something Jenkins users may expect in 2017

It is tracked as JENKINS-45841 in Jenkins JIRA.

How?

  • When Jenkins is started in the new installation mode with enabled Installation Wizard, old protocols will be disabled

  • Jenkins shows an administrative warning when obsolete protocols are enabled

Compatibility notes

Older instances won’t be affected by the disabling of the older JNLP1/JNLP2 protocols, which will still be enabled for them. Newly created instances which skip, or disable, the Setup Wizard will not be affected either.

"New" Jenkins instances installed via setup wizard may be affected in edge cases. For example:

  • Agents with Remoting older than 3.0 will be unable to connect.

    • Mitigation: Before updating make sure Remoting is not bundled custom Docker images, AMIs, etc.

  • Swarm Plugin: old versions of Swarm Client (before 3.3) will be unable to connect to Jenkins, because Remoting 2.x is bundled

    • Mitigation: Update Swarm Client

  • Very old jenkins-cli.jar without CLI2 support will be unable to connect.

    • Mitigation: Do not use Remoting-based CLI on new instances (see this blogpost)

Upgrade to Java 8

Starting with version 2.54, Jenkins requires Java 8 to run (announcement blog post). This version is also required for Jenkins LTS 2.60.1.

Remoting continued to support Java 7 for a while for backporting purposes, but it will be also upgraded to Java 8 in the Remoting 3.11 release. This Rremoting version is expected to be available in Jenkins 2.75 (ETA: Aug 20, 2017). This change is tracked as JENKINS-43985.

Compatibility notes

The update does not cause compatibility issues in common use-cases. However, there may be issues in custom Jenkins core builds and packaging. There are several examples below.

  • Jenkins instances with built-in Remoting versions will NOT be affected, Java 8 is already required there

  • Users of community-provided Docker packages (docker-agent, docker-inbound-agent) will NOT be affected, Java 8 is already required there

  • Custom Jenkins WAR file builds targeting Java 7 may fail to build/run if they bundle Remoting 3.11 or later

  • Custom Jenkins agent instances (manually installed hosts, VM snapshots, Docker packages, AMIs, etc.) may fail if they download the latest Remoting version and use Java 7

Java 9 support

As with Jenkins core, Java 9 not supported and not tested in Remoting. It may work in some configurations, but it is not guaranteed.

As a consequence, it is not recommended to run Remoting with Java 9 right now. It is also not recommended to use Maven Integration Plugin to run builds on Java 9.

What’s next?

There are some ongoing activities in the Remoting sub-project:

  1. Stability and Diagnosability improvements (JENKINS-38833)

    • Why? When it comes to Remoting issues, it is really hard to diagnose them

    • Recently I have published some slides about preventing and diagnosing issues, but I want the behavior to be more stable by default

    • This Epic lists my plans about Remoting issues and papercuts I would like to fix this year

  2. Remoting Work Directories (JENKINS-44108)

    • For a long time logging was disabled by default in Java Web Start (JNLP) and SSH agents, because Remoting had no option to determine where to store such data before connecting to the controller

    • The new Remoting Work Directory feature (since Remoting 3.8) offers such storage, which is also used for storing JAR caches and for checking workspace writeability before accepting builds.

    • This Epic is about enabling Remoting work directories by default in common Agent launcher types.

  3. Remoting Upgradeability (JENKINS-44099)

    • Right now Remoting is not being upgraded automatically on JNLP agents, it is supported only for Windows service agents starting from Jenkins 2.50

    • On the Jenkins controller side it is required to upgrade the Jenkins core in order to pick Remoting fixes.

    • This Epic aims simplifying the upgrade procedure for most common cases.

If you are interested in contributing to these tasks, or others in the Remoting sub-project, please feel free to reach out via the issue tracker or #jenkins IRC channel.

If you are coming to Jenkins World, you can also find me at the "Ask the Experts" booth there. See more info about Ask the Experts here.

About the Author
Oleg Nenashev

Jenkins core maintainer and board member, open source software and open hardware advocate, TOC chair in the Continuous Delivery Foundation. Oleg started using Hudson for Hardware/Embedded projects in 2008 and became an active Jenkins contributor in 2012. Nowadays he maintains Jenkinsfile Runner, contributes to several Jenkins SIGs and outreach programs (Google Summer of Code, Hacktoberfest) and organizes Jenkins meetups in Switzerland and Russia. Oleg works on open source programs and Keptn at the Dynatrace, Open Source Program Office.