Search code examples
windowsjenkinsjenkins-agent

JNLP Connections are deprecated in Jenkins what is the new recommended way connecting a windows agent to jenkins?


As the title already states JNLP connections are deprecated. Jenkins also gives a message and a hyperlink to https://en.wikipedia.org/wiki/Java_Web_Start#Deprecation.

So what's the recommended way to attach a Windows agent to Jenkins now? There seems to be no real good guide on https://jenkins.io covering that topic.


Solution

  • There are two options: Either use an open source alternative for Java Web Start or use the Jenkins service wrapper instead. The latter gives you the most control.

    Open Source Alternative to Java Web Start

    There is an open source replacement called OpenWebStart which is based on IcedTeaWeb.

    More information: Java Web Start is dead - long live OpenWebStart!

    OpenWebStart is an open source implementation of the WebStart and JNLP standards (JSR-56).

    [...]

    In IcedTeaWeb we are currently working on mapping the JNLP spec and supporting its functions to the greatest extent possible. In addition to OpenWebStart, which uses IcedTeaWeb as its core, IcedTeaWeb is also used within AdoptOpenJDK to provide minimal WebStart in the Java 8 releases of AdoptOpenJDK. However, these are limited compared to OpenWebStart because they can only use the current JVM to run JNLP-based applications.

    Using the Jenkins Service Wrapper

    When installing Jenkins service through the service wrapper (winsw-*.exe), Java Web Start is no longer required. It seems that JNLP protocol is still used behind the scenes, so it may still have some deprecation issue in the future.

    Steps (assuming you have already set up the node in Jenkins master):

    1. Download latest service wrapper from http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/ (e. g. "winsw-2.2.0-net4.exe")
      Place it in the Custom WorkDir path and rename it to "jenkins-agent.exe"

    2. Download "agent.jar": http://YourJenkinsServer:8080/jnlpJars/agent.jar
      Place it in the Custom WorkDir path and rename it to "agent.jar"

    3. Create "jenkins-agent.xml" in the same directory:

       <service>
         <id>YourJenkinsAgentServiceId</id>
         <name>Your Jenkins Agent Service Name</name>
         <description>This service runs an agent for Jenkins automation server.</description>
         <executable>C:\Program Files\Java\bin\java.exe</executable>
         <arguments>-Xrs -jar "%BASE%\agent.jar" -jnlpUrl http://YourJenkinsServer:8080/manage/computer/YourNodeName/jenkins-agent.jnlp -secret YourSecretStringConsistingOfHexadecimalCharacters -workDir=C:\YourNodeWorkDir</arguments>
         <logmode>rotate</logmode>
         <onfailure action="restart" />
         <download from="http://YourJenkinsServer:8080/jnlpJars/agent.jar" to="%BASE%\agent.jar"/>
         <extensions>
           <extension enabled="true" className="winsw.Plugins.RunawayProcessKiller.RunawayProcessKillerExtension" id="killOnStartup">
             <pidfile>%BASE%\jenkins_agent.pid</pidfile>
             <stopTimeout>5000</stopTimeout>
             <stopParentFirst>false</stopParentFirst>
           </extension>
         </extensions>
       </service>
      
    4. Adjust "jenkins-agent.xml" according to your environment. The java.exe should be the same version as used by Jenkins. Make sure to adjust all strings I prefixed with "Your" and also the path to "java.exe". You'll find the secret string and correct jnlpUrl on the node configuration page of Jenkins master (e. g. http://YourJenkinsServer:8080/manage/computer/YourNodeName/).
      Official documentation

    5. Create "jenkins-agent.exe.conf" file to prevent the executable from running on an earlier version of the .NET Framework.

       <configuration>
         <startup>
           <supportedRuntime version="v4.0"/>
         </startup>
       </configuration>
      
    6. Launch "cmd.exe" as administrator and navigate to directory of "jenkins-agent.exe".

    7. Install the service:
      jenkins-agent.exe install

    8. Launch the service:
      sc start YourJenkinsAgentServiceId

    Notes:

    • For simplicity I have used http protocol only. When the connection is working, I recommend to switch to https for improved security.
      • If you are using a self-signed certificate on the Jenkins server (typically in a LAN), you have to install the certificate on the agent into the Java certificate store (as the Windows certificate store is ignored by Java). This can be done using Java's keytool (more information).