Windows

This plugins allows to manage Windows systems, using Microsoft Powershell DSC. Rudder Windows agent is available with a annual subscription, read more about it on our website.

Install Windows DSC plugin on the server

Prerequisite

The Windows DSC plugin requires zip on the Rudder server, you need to install it prior to installing the plugin.

Installing and Upgrading

The installation and upgrade processes are exactly the same. Download the rpkg file, and run, on the Rudder server:

rudder package install-file rudder-plugin-dsc-<Rudder version>-<plugin version>.rpkg

It will add:

  • The ability to generate policies for Windows Nodes

  • New generic methods in the technique editor

  • New techniques

Install Windows DSC agent

The installation and upgrade processes are exactly the same.

Supported version of Microsoft Windows

The Rudder agent needs PowerShell 4 or later, which is built-in on:

  • Windows Server 2012 R2 and later

PowerShell 4 may also be installed on the following platforms, following this procedure: https://social.technet.microsoft.com/wiki/contents/articles/20623.step-by-step-upgrading-the-powershell-version-4-on-2008-r2.aspx

  • Windows Server 2008 R2

  • Windows Server 2012

Desktop version of Microsoft Windows

There is no official support of Rudder agent on desktop versions of Microsoft Windows. However, the agent can be installed on the following platforms:

  • Windows 7 (you will need to upgrade to PowerShell 4 first, and activate WinRM)

  • Windows 8 (you will need to upgrade to PowerShell 4 first, and activate WinRM)

  • Windows 8.1

  • Windows 10

Plase note that prior to the installation on Windows 7 and 8, you will need to install PowerShell 4 and make sure WinRM is activated with the following command:

Set-WSManQuickConfig DSC

Moreover, the Windows DSC agent comes without digital signature, you need to allow the unsigned source code execution on the Windows node. In some environment, this policy change can lead to security issues, please read the Microsoft Windows doc associated. This can be done in powershell by executing the following command:

Set-ExecutionPolicy RemoteSigned

Installation procedure

Download the exe file, and run, on your node:

rudder-agent-dsc-<Rudder version>-<plugin version>.exe

The installer will ask the IP address or DNS name of the policy server to use. If a policy server is already configured (for example during upgrade or an unattended installation), you can leave this field empty.

The installer will install the agent files and create the scheduled tasks to run the agent and the inventory. Rudder does not come as a Windows Service but as a scheduled PowerShell task, managed by schtasks.exe.

Unattended installation

For an automated unattended installation, you can pre-configure the policy server in the file:

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

Then the installer need to be executed with the following command:

rudder-agent-dsc-<Rudder version>-<plugin version>.exe /S /POLICYSERVER=xxx.xxx.xxx.xxx

This will install the agent in silent mode.

Technique editor with DSC

DSC Generic Methods are shipped with the Rudder dsc plugin. Some are specific for Windows managed systems (like the Registry management), and the others are the DSC version of existing generic methods.

A filter is available in the Technique Editor to select either all generic methods, generic methods available for classic agent, and generic method available for DSC agent, so that you can choose relevant methods for the type of nodes you need to manage

Technique editor filter

You can get more information about building your own Windows techniques with the Rudder By Example article: Manage Windows Registry keys

DSC Techniques

Techniques compatible with DSC agent appear, in the Directives and Techniques trees, with a DSC symbol, as shown in the screenshot below.

Unfortunately, not all Techniques are compatible with DSC agent, as some are deprecated, or some will be completely rewritten, but the coverage is increasing regularly.

DSC compatible Techniques

There is a detailed walk-through example of the Windows Software technique in Install software from a .exe or .msi installer Rudder By Example article.

DSC Agent CLI

The Rudder agent CLI is available as a Powershell module, by running, in a Powershell terminal

rudder agent <action>

where action can be one of the following

  • disable: Disable the agent, and prevent its execution

  • enable: Enable the agent

  • info: Show information about the agent and the node (hostname, Rudder ID, policy server, etc)

  • inventory: Generate an inventory, and send it to the server

  • run: Run the agent (see example output below)

  • update: Update agent policy from the Rudder Server

  • version: Show the version of the DSC Rudder agent

Example of a Rudder DSC agent output on Windows

Agent logs

Rudder logs are visible in the output of the agent. You can get more details about what is done with the -Verbose option:

rudder agent run -v

You can also explore all agent logs (including those from unattended runs) in the Windows Event Viewer. Before Windows plugin version 4.2-1.6 Rudder used the windows system eventlog and was logging in the Windows Logs → Application view, with the Rudder source and the 101 Event ID.

Since the Windows plugin version 4.2-1.6 Rudder will report in a dedicated windows journal named Rudder and its logs are saved on different verbosity:

  • classic Rudder reports will have the Event ID 101, they are the reports sent to the server.

  • Information logs will have the Event ID 102 and will only be local logs.

If you had an old plugin version installed Rudder will not try to install the new journal reference because it needs a complete reboot of the host system. See the last note on the Microsoft doc: https://msdn.microsoft.com/en-us/library/2awhba7a%28v=vs.110%29.aspx.

If you want to change manually the Rudder eventlog use the following process, keep in mind that it will need a machine restart to avoid any reporting issues. First identify the current eventlog for Rudder by running in the powershell console

[System.Diagnostics.EventLog]::LogNameFromSourceName("Rudder", ".")

If it does not suit you, remove the Rudder source from it and create a new logger for Rudder

Remove-Eventlog -Source "Rudder"
New-Eventlog -Source "Rudder" -LogName "Rudder"

Then reboot the system.

Proxy settings

Starting 6.2-1.26 the agent support communications through proxy. The proxy can be configured in the file C:\Program Files\Rudder\etc\agent.conf which does exist by default. It is a key-value based file, currently only supporting the https_proxy key.

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"

Known issues

  • On Windows, Rudder can only manage user password in clear text.

  • Mustache templating on Windows does not support the exact same syntax than Linux, see the documentation see the documentation.

  • The Technique File download (Rudder server) technique can not share folders with a Windows agent, only files can be shared.

  • If you have a file explorer opened on a Rudder folder while executing the command rudder agent update there is a chance that the agent fails and raise an error like :

    Get-ChildItem : Access to the path 'C:\Program Files\Rudder\tmp\dsc\ncf' is denied.

    This may broke agents prior to 6.2. If it happens, please rename the folder C:\Program Files\Rudder\Policy.swap in C:\Program Files\Rudder\Policy, close all Windows File Explorer and try again to update.


← Vault Zabbix →