How to install Windows agents as a service?

Issue

I would like to connect Windows agents, and have them installed as a Windows service.

Environment

Resolution

There are multuple possible ways to connect a Windows agent to a controller:

  1. Using SSH
  2. Using WebSocket transport and creating the service using WinSW
  3. Using the Java Web start service install (not possible with WebSocket until JENKINS-64144 is fixed)

1. Use SSH

You can use ssh to connect the agent by following Configuring Windows agents
Note: This solution does not actually use a Windows service, as the agent launch is handeled by your controller automatically.

2. Use WebSocket transport and creating the service using WinSW

a) Create the agent and ensure Use WebSocket is checked:

websocket agent

b) Logon to your Windows agent machine and create a new directory (eg C:\AgentWorkspace), the next steps are based upon https://github.com/winsw/winsw/blob/master/doc/installation.md#winsw-installation-guide

c) Download WinSW from https://github.com/winsw/winsw/releases/tag/v2.11.0 (or latest version) to the service directory. (WinSW-64x.exe)

d) Optionally, rename WinSW-64x.exe to a name of your choice such as C:\AgentWorkspace\jenkinsAgentService.exe

e) Use the xml file from https://github.com/winsw/winsw/blob/v3/samples/jenkins.xml as a template for your service and save it as an XML file named after the exe file from step d (eg C:\AgentWorkspace\jenkinsAgentService.xml)

f) Downlaod the agent.jar from JENKINS_URL/jnlpJars/agent.jar or clicking on agent.jar at JENKINS_URL/computer/<my-node>/, save it to C:\AgentWorkspace\agent.jar.

g) View the launch command at JENKINS_URL/computer/<my-node>/ to find the Java arguments to use, and paste those arguments into the <arguments> section of the C:\AgentWorkspace\jenkinsAgentService.xml.

node-launcher

h) Update C:\AgentWorkspace\jenkinsAgentService.xml with the correct path to the the agent.jar (eg C:\AgentWorkspace\agent.jar).

i) Update C:\AgentWorkspace\jenkinsAgentService.xml with the correct path to Java inside of the <executable> xml element.

j) Open a Windows cmd or PowerShell window “As Administrator”

k) CD into the service directory: cd C:\AgentWorkspace

l) Run jenkinsAgentService.exe install, the expected output will be similar to:

2021-08-02 18:20:59,119 INFO  - Installing service 'JenkinsAgent (jenkinsAgent)'...
2021-08-02 18:20:59,172 INFO  - Service 'JenkinsAgent (jenkinsAgent)' was installed successfully.

m) Start the service from the Windows services application, or run jenkinsAgentService.exe start (it will also start automatically after the agent restarts).

n) Open JENKINS_URL to validate that the Agent is showing as connected.

3. Using the Java Web start service install

Note: this method is not possible when using WebSocket transport until JENKINS-64144 is fixed.

a) Create an agent and ensure Use WebSocket is unchecked:

node-config

b) There are different ways to launch the agent:

  • The easiest way is to open a web browser and access the JENKINS_URL from the agent machine, go to the node page JENKINS_URL/computer/<my-node>/ and click on the Launch button. This downloads the file jenkins-agent.jnlp and runs it.
    • Another way is to run the command java -jar agent.jar -jnlpUrl JENKINS_URL/computer/<my-node>/jenkins-agent.jnlp -secret <my-secret> described at JENKINS_URL/computer/<my-node>/
    • You can download jenkins-agent.jnlp from the controller, copy it to the agent machine and run javaws jenkins-agent.jnlp

node-launcher

c) Once the agent is launched, you will see a Windows application open. To install this agent as a service, click on File/Install as a service.

install-service

Further Information

Further documentation can be found on the Jenkins wiki regarding Windows agents:

https://wiki.jenkins-ci.org/display/JENKINS/Installing+Jenkins+as+a+Windows+service
https://wiki.jenkins-ci.org/display/JENKINS/Step+by+step+guide+to+set+up+master+and+slave+machines
https://wiki.jenkins-ci.org/display/JENKINS/Launch+Java+Web+Start+slave+agent+via+Windows+Scheduler

Have more questions?

3 Comments

  • 0
    Avatar
    Harsh Sarode

    awesome !! can you please help me about how to launch slave agent automatically via Launch method "Let Jenkins control this Windows slave as a Windows service" with using admin user credentials.as i tried varied attempts for this but doesn't work.my Jenkins server is Linux machine and slave node is Windows Server 2012 r2. i will be glad if i get solution.Thanks in advance.

  • 0
    Avatar
    Denys Digtiar

    Hi Harsh,

    This article is not related to the Launch method you are trying to use.

    Have you gone through the troubleshooting guide? https://wiki.jenkins.io/display/JENKINS/Windows+slaves+fail+to+start+via+DCOM

    If it didn't help you can request help on Users Mailing list or IRC. If you are a CloudBees customer feel free to raise a support ticket.

  • 0
    Avatar
    Radjammin Radjammin

    Step 2 , 3rd bullet. Creating a service is an administrator right.

    Edited by Radjammin Radjammin
Please sign in to leave a comment.