It is time to review this article. “How to Install Jenkins Slave as Windows Service” has been one of the most popular blog articles 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.
OpenJDK or Oracle Java (We’ll use OpenJDK in this article)
- 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.
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\jenkinsand 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
- Place the executable under
C:\Users\hiriu\jenkinsand rename it as
- 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 "%BASE%\slave.jar" -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.
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
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.
- Open terminal.
openssl s_client -showcerts -connect hoge.com:443 < /dev/null
| openssl x509 -outform DER > hoge.com.cer
- 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.
- Once you get the .cer file, it’s time to tell Java to trust the certificate. For that, we use keytool.
- 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"
- You will be prompted to enter “yes”. Once you enter yes, you are ready to start the Jenkins agent Windows Service.
- Navigate to Windows Service console (services.msc) and start the Jenkins agent Windows service.
- 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.