Puppet uses the same exec
resource type on both *nix and Windows systems, and there are a few Windows-specific best practices and tips to keep in mind.
Puppet can run binary files (such as exe
, com
, or bat
), and can log the child process output and exit status. To ensure the resource is idempotent, specify one of the creates
, onlyif
, or unless
attributes.
Command extensions
If a file extension for the command is not specified (for example, ruby
instead of ruby.exe
), Puppet will use the PATHEXT
environment variable to resolve the appropriate binary. PATHEXT
is a Windows-specific variable that lists the valid file extensions for executables.
Exit codes
On Windows, most exit codes are integers between 0 and 2147483647.
Larger exit codes on Windows behave inconsistently across different tools. The Win32 APIs define exit codes as 32-bit unsigned integers, but both the cmd.exe shell and the .NET runtime cast them to signed integers. This means some tools will report negative numbers for exit codes above 2147483647. For example, cmd.exe reports 4294967295 as -1.
Because Puppet uses the GetExitCodeProcess Win32 API, it reports the very large number instead of the negative number, which might not be what you expect if you got the exit code from a cmd.exe session.
Microsoft recommends against using negative or very large exit codes, so avoid them.
Shell built-ins
Puppet does not support a shell provider for Windows, so if you want to execute shell built-ins (such as echo
), you must provide a complete cmd.exe
invocation as the command. For example, command => 'cmd.exe /c echo "hello"'
.
When using cmd.exe
and specifying a file path in the command line, be sure to use backslashes. For example, 'cmd.exe /c type c:\path\to\file.txt'
. If you use forward slashes, cmd.exe
returns an error.
Optional PowerShell exec
provider
An optional PowerShell exec
provider is available as a plug-in and is helpful if you need to run PowerShell commands from within Puppet. To use it, install puppetlabs/powershell.
Inline PowerShell scripts
If you choose to execute PowerShell scripts using the default Puppet exec
provider on Windows, you must specify the remotesigned
execution policy as part of the powershell.exe
invocation:
exec { 'test':
command => 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -executionpolicy remotesigned -file C:\test.ps1',
}