How To Avoid Common Windows Gotchas with Puppet

Originally published at, reposted with permission and adjustments.

I’ve touched on Puppet before – Making Windows Awesome Since 2011Getting Started with Puppet on Windows and Managing Permissions with Access Control Lists.

I’m going to touch on the common things you can do, then show you how to avoid the common gotchas. Throughout the post, I’ll direct you to resources where you can dive in more deeply. When it comes to managing Puppet on Windows, a great resource is our Windows Documentation.

Common Windows Tasks You Can Automate With Puppet

Using Puppet, you can manage:

  • users /groups
  • files and folders
  • scheduled tasks (cron for Windows)
  • installation/upgrade/removal of software
  • permissions
  • windows features
  • management of services
  • IIS
  • management of databases
  • etc

The built-in types are listed on Windows Core Resource Types, along with specific examples. Much of the Windows ecosystem comes from several high-quality modules on the Puppet Forge that you can add in to Puppet to enhance your experience on Windows. Here are just a few specific modules:

There are of course many other modules for Windows, and I encourage you to explore the Forge.

As you can see, you can use Puppet to manage practically anything on Windows.

Common Windows Gotchas

We are always adding common gotchas and their resolutions to the Windows Troubleshooting page. Be sure to check that out if you don’t find what you are looking for here.

Puppet May Run as a 32-bit Application

Before Puppet 3.7.0, there was no 64-bit version of Puppet. This means you would be subject to File System Redirection and Registry Redirection from Windows because Puppet would run under 32-bit Ruby. The next two sections only apply if you are using a 32-bit version of Puppet on an x64 System.

File System Redirection (only when not using Puppet x64 on x64 systems)

Windows reserves the C:\Windows\System32 directory for 64-bit applications. In its great knowledge, Windows will redirect calls to System32 with SysWOW64, which contains the 32-bit equivalents of what is in the native system32 directory. Most of the time with Puppet, users actually want the physical system32 directory — the native system directory. In cases like these, what is wanted is to use the SysNative alias to bypass file system redirection.

To better understand what I mean about redirection, let’s take a simple manifest and execute it:

exec { 'powershell_system32':
  command => 'c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe -NonInteractive -NoProfile -ExecutionPolicy Bypass -Command "get-process powershell* | %{ Write-Host $($_.Path)}"',
  logoutput => true,
} ->
exec { 'powershell_sysnative':
  command => 'c:\windows\sysnative\WindowsPowerShell\v1.0\powershell.exe -NonInteractive -NoProfile -ExecutionPolicy Bypass -Command "get-process powershell* | %{ Write-Host $($_.Path)}"',
  logoutput => true,

The output?

Notice: /Stage[main]/Main/Exec[powershell_system32]/returns: c:\windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe
Notice: /Stage[main]/Main/Exec[powershell_sysnative]/returns: c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe

In this example, we are executing PowerShell and then looking at the path of any running powershell.exe processes (the same process we are running). We told the first exec (named powershell_system32) we wanted c:\windows\system32, but we got c:\windows\SysWOW64. This is how file system redirection works. If we want c:\windows\system32, we need to ask for c:\windows\sysnative, like we did with the second exec (powershell_sysnative).

For more information, see File System Redirection in 64-bit Windows Versions. You should also take a look at the MSDN reference for the File System Redirector.

NOTE: In the unlikely case where you are running Windows Server 2003 x64 (ONLY non-R2), you must apply the KB942589 hotfix to be able bypass file system redirection. And there is no x64 version of Ruby available for Windows Server 2003, so there is no x64 version of Puppet available either.

Registry Redirection (only when not using Puppet x64 on x64 systems)

In most cases, you will want to use the registry module, as it will provide you with the correct calls. In cases where you cannot, like when writing custom facts for Facter, you will want to do something similar to the following:

Facter.add(:myfact) do
  confine :kernel => :windows
  setcode do
    require 'win32/registry'

    value = nil
    hive = Win32::Registry::HKEY_CLASSES_ROOT'SOFTWARE\Somewhere\SomeValue',  Win32::Registry::KEY_READ | 0x100) do |reg|
      value = reg['SomeValue']


The addition of | 0x100 ensures the registry is opened without redirection so you can access the proper keys that you expect to access. For more information, see the MSDN Reference.

UAC (User Account Control) aka Security Context

UAC can bring you into some interesting places with Puppet. The Puppet agent (service) by default runs under an elevated LocalSystem account, which requests a certificate for the machine. If you run Puppet later from the command line in a non-elevated security context, it will attempt to request a second SSL certificate, which usually causes errors. See our documentation on security context.

Case Is Important

Most items on Windows are case-insensitive. Puppet, however, is not, especially when it comes to establishing relationships between resources in the manifests. See our documentation about case insensitivity.

File Paths

The general rule of thumb is to always use forward slash (/) except when specific Windows programs, like msiexec.exe, require backslashes in file paths. In those cases you should use the backslash (\) or a double backslash (\\) when the string is double quoted. The following paths are valid:

file { 'c:/path/to/file.txt': }
file { 'c:\path\to\file.txt': }
file { "c:\\path\\to\\file.txt": }

This is not a valid path due to double quoted single backslashes, which are interpreted as escape sequences:

file { "c:\path\to\file.txt": }

You will find more information here: and


Yes, that’s the thing you have to do sometimes on Windows….it’s crazy, but it works. When you need to reboot, there’s a supported module for that. See Rebooting Windows with Puppet Enterprise.

Parting Thoughts

Now you’ve seen a few common gotchas to avoid and you’ve been introduced to some some stellar modules for enhancing the functionality of Puppet on Windows. Armed with this information, it is my hope that you:

  • Have a better understanding of Puppet and Windows
  • Run into fewer issues when you work with Puppet on Windows
  • Know where to find more Windows resources

About Rob Reynolds

Rob Reynolds has been programming in .NET since the early days of 1.0... [Continue reading... at] On this blog you'll find just about anything I find interesting that has to do with development including Puppet and Chocolatey. Because we are all polyglot programmers in our own way, you may see anything from NHibernate to some custom CSS. Nobody is perfect and occasionally I may post something you find incorrect. Please keep me straight! With your help and interaction the community will benefit.
This entry was posted in howto, puppet and tagged , . Bookmark the permalink. Follow any comments here with the RSS feed for this post.

Comments are closed.