Install Rudder agent on Windows systems

Windows agents are only available with a subscription and can be downloaded on https://download.rudder.io/misc/windows/.

The Windows agent can only work if the DSC plugin installed on the Rudder server. You can find the documentation about how to install a plugin here

Note that even if properties' name is case-sensitive, collision can occur, on nodes based on Windows agent. We strongly recommend to use distinct strings for property’s name, in particular on Windows node.

Installation for Windows server 2012R2 and later

The agent is currently distributed as an msi installer which both support graphical and cli based installations.

An inventory will be run after the installation to send an up-to-date inventory to the policy-server after each installation/upgrade.

The agent comes without digital signature, you may need to allow Powershell to execute remote signed source code to be able to properly install the agent. In some environment, this policy change can lead to security issues, please read the dedicated Microsoft Windows documentation. This can be done in Powershell by executing the following command:

Set-ExecutionPolicy RemoteSigned

CLI Installation

Use msiexec with the /quiet switch to make the installation in silent mode. You need to run this command as administrator.

# When done manually
msiexec /i <absolute path to rudder agent>.msi /quiet POLICYSERVER=my.rudder.server /L*v C:\install.log

# When scripted
$errCode = (Start-Process "msiexec" -ArgumentList "/i", "<absolute path to rudder agent>", "POLICYSERVER=my.rudder.server", "/quiet", "/L*v", "C:\install.log" -Wait -Passthru).ExitCode

Installer options

POLICYSERVER (optional)

Hostname or ip of the policy server to overwrite the policy-server.conf file.

SCHEDULEDTASKUSER (optional)

Overwrite the user that will be used to run the scheduled task responsible of running the agent every 5minutes. If left empty, the task will run as the SYSTEM account.

SCHEDULEDTASKPASSWORD (optional)

Only used with the SCHEDULEDTASKPASSWORD option. Password of the user.

/L*v <path to logfile>

MSI verbose installation log.

/quiet

MSI non graphical installation.

The SCHEDULEDTASK* options are only available through the CLI, and when used, the agent will not try to modify the defined task afterward without manual intervention. The scheduled tasks can be manually modified using the rudder command rudder agent check-scheduled-tasks.

Configuration

The policy server configuration can be provisioned prior to the installation by writing its hostname or IP in the file:

C:\Program Files\Rudder\etc\policy-server.conf

Proxy options for the agent can be pre-configured if needed, see next section.

Proxy settings

Agent supports configuration through proxy. Proxy can be configured in the file C:\Program Files\Rudder\etc\agent.conf which exists by default. It is a key-value based file, currently only supporting the https_proxy option.

Correct value formats for the https_proxy key are listed below:

https_proxy =

https_proxy = "192.168.2.4"

https_proxy = "192.168.2.4:3128"

# For authenticated proxy
https_proxy = "user:password@192.168.2.4:3128"

# To use the system defined proxy
https_proxy = "system"

Logs

To get install logs, use msiexec’s option /L*V C:\MyLogFile.txt, other verbose log files are available in C:\Program Files\Rudder\logs. You can also get the rudder agent run logs by running this command: rudder agent run -v -LogFile C:\debug.txt

The MSI install log file is a binary data file, some usual text editors may not be able to read it.

Requirements for non server or server version older than 2012R2

Desktop versions are not officially supported but should be mostly compatible as long as the requirements listed below are filled.

Powershell

version 4 or later

.NET

version 4.5 or later

PSDesiredStateConfiguration

installed

For Windows Server 2008R2 and Windows Server 2012 you can upgrade the PowerShell version by following for instance, this guide.

On desktop or old Windows versions you may need to activate the DSC features and WinRM features. Please note that older desktop versions (Windows 7 and 8), you will need to install PowerShell 4 and make sure WinRM is activated with the following command:

Set-WSManQuickConfig DSC

Versioning policy

The agent version follows the rudder version schema for its first three digits. As MSI requires a four digit based versioning, the fourth is used to describe the release type. Timestamps are calculated from the 1 January 2020.

alpha

x.y.z.0000000000<timestamp>

beta

x.y.z.0<patch version>0000000

rc

x.y.z.1<patch version>0000000

release

x.y.z.2000000000

nightly

x.y.z.109<timestamp>

alpha-nightly

x.y.z.000<timestamp>

beta-nightly

x.y.z.0<patch version><timestamp>

rc-nightly

x.y.z.1<patch version><timestamp>


← on SLES on Debian/Ubuntu →