jenkinsci / windows-slave-installer-module

Windows Agent Installer module for Jenkins

This module is a part of the Jenkins core, which provides features for managing agents as Windows services.

Provided features:

• Installation agents as Windows services, powered by the Windows Service Wrapper (WinSW).
• GUI option for the JNLP agents, which adds the Install as a service menu option.
• Automatic upgrade of Windows service wrapper versions to keep them aligned with the version from this module.

Changelog

See the changelog here.

Installation

System requirements

• Starting from version 2.0, .NET Framework 4.0 or higher is required to install Jenkins agents as Windows services.
• Jenkins System Requirements apply to agents installed by this module
  • Windows Support Policy
  • Java requirements
  • Hardware requirements

Automatic

Once you start a JNLP agents on Windows in the GUI mode (e.g. via Java WebStart), It will display the Install as a service menu option once the Jenkins master finishes the agent configuration.

• The agent will be installed if your Windows account has enough permissions to install Windows Services and to access the System and Application event logs.
• If the current account does not have enough permissions, the installer will prompt for permission elevation.

Manual

You can setup the agent service manually by following the WinSW Installation Guide.

More info

See also the old installation guide on Jenkins Wiki (link).

Upgrading old agents

This section provides information about upgrading Jenkins agents installed as Windows services. In order to apply the new features, you may need to...

• Upgrade the WinSW executable (manually or automatically)
• Upgrade the WinSW configuration (manually)

Upgrading Windows Service Wrapper

Windows Agent Installer module may be able to automatically upgrade the agent in particular cases.

Automatic upgrade

1. Upgrade Jenkins to the version, which provides this module
2. Jenkins is expected to automatically upgrade jenkins-slave.exe executables if...

• The agent is connected to the Jenkins master
• If the agent is not connected, the update will be postponed till the agent connects to the master
• WinSW executable is located in REMOTE_ROOT_DIR/jenkins-slave.exe and writable by the agent
• WinSW executable is writable as well as REMOTE_ROOT_DIR/jenkins-slave.exe.new and REMOTE_ROOT_DIR/jenkins-slave.exe.bak files

3. If the upgrade happens, you should be able to see the message in the Agent log in Jenkins Web UI
4. Once upgrade is done, the changes will be applied on the next Windows service restart

Enabling Automatic upgrade

Windows Service Wrapper

The wrapper automatic upgrade is enabled by default.

Remoting executable (slave.jar)

Automatic upgrade is enabled for all newly created agents connected via HTTPs. You may need to enable automatic upgrades manually for agents installed as a service before Jenkins 2.50 OR for agents connected to the master over HTTP. In this case, open jenkins-slave.xml and add the following line to enable automatic upgrades:

<download from="${JENKINS_URL}/jnlpJars/slave.jar" to="%BASE%\slave.jar"/>

Disabling Automatic upgrade

Windows Service Wrapper

In some cases Jenkins administrators may want to update WinSW to a version higher than the version provided by this module. By default it is not possible if the executable is named as jenkins-slave.exe, because the module performs automatic update.

Starting from version 2.9 (Jenkins 2.60), it is possible to disable such automatic upgrades by setting the org.jenkinsci.modules.windows_slave_installer.disableAutoUpdate System Property to true.

Remoting executable (slave.jar)

To disable the automatic Remoting executable upgrade, open jenkins-slave.xml and remove the following line:

<download from="${JENKINS_URL}/jnlpJars/slave.jar" to="%BASE%\slave.jar"/>

Manual upgrade

Manual upgrade may be required if the agent does not comply with the requirements mentioned above.

Please note that Jenkins master may override the WinSW executable if it is located in REMOTE_ROOT_DIR/jenkins-slave.exe. It possible to disable the automatic upgrade only by using another path or by making the executable non-writable by the Windows agent.

1. Download the new WinSW release from GitHub Releases or NuGet.

• Depending on the .NET Framework version in your system, you can use WinSW.NET2.exe or WinSW.NET4.exe executable.
• If you need to run the WinSW.NET2.exe executable on .NET 4 or above, see this guide.

2. Replace the WinSW executable on your agent machines by the new version.

Upgrading agent configuration

Windows Agent Installer module never updates WinSW configuration files, but these files enable particular features on new agent installations. For example 1.7 introduces Runaway Process Killer and Automatic JNLP agent upgrade. It is advised to keep configurations up to date on all agents.

In order to update the configurations you, need to edit the XML configuration files (e.g. jenkins-slave.xml).

• The default configuration of agents can be found here.
• All available options are described in the WinSW XML config file specification.