homebloghow to avoid common windows gotchas puppet

How To Avoid Common Windows Gotchas with Puppet

“Does Puppet work with Windows? How well does Puppet work with Windows?”

This is a common question I’m asked by friends and other people who have heard the term “Puppet,” but have never looked into it much. Indeed, both open source Puppet and Puppet Enterprise work with Windows. We’ve had support for Windows since 2011, and it’s only gotten better over time. We support all versions of Windows Server, from Windows Server 2003 forward, and all consumer versions of Windows from Windows Vista forward.

James Sweeny gave a great talk at PuppetConf 2013, Managing Windows with Puppet. He addresses what you can manage, plus some of the gotchas we are going to talk about below. It’s a great talk — I won’t be offended if you go watch it now.

In this post, 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, management of services, etc.

All these are listed on Windows Core Resource Types, along with specific examples.

In addition to the built-in supported types and providers, there are 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. We have an upcoming ACL module that will give you fine-grained control over permissions, so keep your eye on the Forge for that.

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 Runs as a 32-bit Application

Puppet runs with 32-bit Ruby, although recently Ruby x64 has been released for Windows. What does this mean? It means that we tend to run into fun Windows-y things that folks without significant Windows experience may not be expecting. In fact, we have over 80 related posts about this in the Puppet Users Google Group.

Microsoft has documentation on MSDN about running 32-bit applications — it’s a good read with good links.

File System Redirection

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:

The output?

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 Microsoft’s 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.

Registry Redirection

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:

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 Microsoft’s MSDN Reference.

UAC (User Account Control) aka Security Context

Windows does not have sudo, but it does have UAC. Unlike sudo, there is no command line call to assert more privileges. Something that catches folks here is that, by default, the installed agent 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:

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

You will find more information here: http://docs.puppetlabs.com/windows/writing.html#file-paths-on-windows and http://docs.puppetlabs.com/windows/troubleshooting.html#path-separator.


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 know Puppet works well on Windows, 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

Rob Reynolds is a software engineer at Puppet Labs.

Learn More

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.