How to Install Jenkins Slave as Windows Service

It is time to review this article. “How to Install Jenkins Slave as Windows Service” has been one of the most popular blog article on this site. I just went through the steps because I needed to have a permanent Windows slave and I found myself trip over some steps because of some lack of information.

Here I am going to review and enhance the article.

Prerequisites

OpenJDK or Oracle Java (We’ll use OpenJDK in this article)

  • Java
  • Windows

Install OpenJDK

  • Download OpenJDK 17 (the latest one did not work).
  • Download the zip for Windows.
  • Unzip the contents and place all the files under C:\Users\[your username]\jdk (or it could be placed somewhere else if you want to)
  • From the Windows menu, enter “env” to show “Edit the system environment variables” menu and select it.
  • Click “Environment Variables” button.
  • Under System Variables, click New… button and enter JAVA_HOME for Variable name and the path to the JDK root path.
  • Click OK and close Environment Variables dialogue.
  • Open command line and make sure you can get an output from java.
    %JAVA_HOME%\bin\java --version

Create a Node

  • Logon to Jenkins with an administrative account.
  • Go to Manage Jenkins.
  • Click Manage Nodes and Clouds.
  • Click New Node.
  • Enter node name like “win-bld01” and click Permanent Agent and then click OK.
  • Enter a name like win-bld01 (or whatever you like) and enter the path to the directory where you plan to have Jenkins slave executable. In this example, I choose C:\Users\hiriu\jenkins and enter the same path for Custom WorkDir Path.
  • Click OK to save the setting. We’ll revisit it afterwards.

Jenkins Slave Download and Install

  • Download the latest Windows Service wrapper executable from https://repo.jenkins-ci.org/ui/native/releases/com/sun/winsw/winsw/
  • In this example, we will get winsw-2.9.0-net461.exe
  • Place the executable under C:\Users\hiriu\jenkins and rename it as jenkins-slave.exe
  • Create jenkins-slave.xml in the same directory with the following XML. Make sure to change the values in the XML according to your environment. You can get the jnlpUrl from the Configure page of the node.
<service>
  <id>JenkinsSlave</id>
  <name>Jenkins agent</name>
  <description>This service runs an agent for Jenkins automation server.</description>
  <executable>%JAVA_HOME%\bin\java.exe</executable>
  <arguments>-Xrs -jar &quot;%BASE%\slave.jar&quot; -jnlpUrl https://hoge.com/computer/win-bld01/jenkins-agent.jnlp -secret 18f9c0c497c0997e9f65buhie743868ae6d5e2e78a6ba77 -workDir "C:\Users\hiriu\jenkins"</arguments>
  <logmode>rotate</logmode>
  <onfailure action="restart">
    <download from="https://hoge.com/jnlpJars/slave.jar" to="%BASE%\slave.jar">
      <extensions>
        <extension className="winsw.Plugins.RunawayProcessKiller.RunawayProcessKillerExtension" enabled="true" id="killOnStartup">
          <pidfile>%BASE%\jenkins_agent.pid</pidfile>
          <stopTimeout>5000</stopTimeout>
          <stopParentFirst>false</stopParentFirst>
        </extension>
      </extensions>
    </download>
  </onfailure>
</service>

For more options, please refer to the official documentation.

Also make sure to create jenkins-slave.exe.config file with the following XML cotent to prevent the executable from running on the earlier version of the .NET Framework.

<configuration>
	<startup>
		<supportedruntime version="v4.0"/>
	</startup>
</configuration>

Execute the following command to install the Jenkins slave as Windows Service.

jenkins-slave.exe install

Once the installation is successful, you should see the output like below.

Also, you should be able to see “Jenkins agent” item in Windows Services console. You can open the Windows Services console by entering services.msc

Trust the SSL Certificate

The HTTP connection between your client computer and your Jenkins instance may be protected by SSL. When you try to connect your Jenkins slave via HTTPS (SSL) connection, it may fail with the following error.

Exception in thread "main" java.io.IOException: Failed to validate a server certificate. If you are using a self-signed certificate, you can use the -noCertificateCheck option to bypass this check.

It is optional to add -noCertificateCheck option in your jenkins-slave.xml file, but it is better for your Java process to trust the certificate and use the SSL connection to protect the data. To accomplish that, please follow the steps below.

  1. Open terminal.
  2. Execute openssl s_client -showcerts -connect hoge.com:443 < /dev/null | openssl x509 -outform DER > hoge.com.cer
  3. You obviously have to have openssl on your machine. Install Cygwin if you are on Windows and that will give you an ability to execute openssl. Or you could use Linux Subsystem for Windows.
  4. Once you get the .cer file, it’s time to tell Java to trust the certificate. For that, we use keytool.
  5. Execute the following command. If you are on Linux Subsystem, you may want to go back to the normal command prompt.
    %JAVA_HOME%\bin\keytool -trustcacerts -keystore "%JAVA_HOME%\lib\security\cacerts" -storepass changeit -alias ppd -import -file "C:\Users\hiriu\Downloads\hoge.com.cer"
  6. You will be prompted to enter “yes”. Once you enter yes, you are ready to start the Jenkins agent Windows Service.
  7. Navigate to Windows Service console (services.msc) and start the Jenkins agent Windows service.
  8. Once the communication between Jenkins slave and the Jenkins master is successful, you should see the node icon turning to normal like the image below.

Author: admin

A software engineer in greater Seattle area

4 thoughts on “How to Install Jenkins Slave as Windows Service”

  1. Thank you for this guide 🙂

    You need to modify classname @ line 11 of jenkins-slave.xml as className as described here: https://stackoverflow.com/a/60836612

    If not, it complains like this:

    “Service cannot be started. System.IO.InvalidDataException: Attribute is missing in configuration XML”

    Even after fixing this, I still fail to get the service started. I get this error:

    “The requested PID file ‘C:\jenkins-slave\jenkins_agent.pid’ does not exist. The runaway process won’t be checked”

    (I’ve replaced “C:\Users\hiriu\jenkins” as “C:\jenkins-slave” in my environment.)

    Regards.

    1. Hi, Umut. Thank you very much for your comment! I thought I fixed className but I still had it wrong. I edited the blog post and fixed the case. Again, thank you for pointing it out! 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *