powershell

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with powershell
   • Setup requirements
   • Beginning with powershell
4. Usage - Configuration options and additional functionality
   • External files and exit codes
   • Console Error Output
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

Overview

This module adds a new exec provider capable of executing PowerShell commands.

Module Description

Puppet provides a built-in exec type that is capable of executing commands. This module adds a powershell provider to the exec type, which enables exec parameters, listed below. This module is particularly helpful if you need to run PowerShell commands but don't know the details about how PowerShell is executed, because you can run PowerShell commands in Puppet without the module.

Setup

Requirements

This module requires PowerShell to be installed and the powershell.exe to be available in the system PATH.

Beginning with powershell

The powershell module adapts the Puppet exec resource to run PowerShell commands. To get started, install the module and declare 'powershell' in provider with the applicable command.

exec { 'RESOURCENAME':
  command   => '$(SOMECOMMAND)',
  provider  => powershell,
}

Usage

When using exec resources with the powershell provider, the command parameter must be single-quoted to prevent Puppet from interpolating $(..).

For instance, to rename the Guest account:

exec { 'rename-guest':
  command   => '$(Get-WMIObject Win32_UserAccount -Filter "Name=\'guest\'").Rename("new-guest")',
  unless    => 'if (Get-WmiObject Win32_UserAccount -Filter "Name=\'guest\'") { exit 1 }',
  provider  => powershell,
}

Note that the example uses the unless parameter to make the resource idempotent. The command is only executed if the Guest account does not exist, as indicated by unless returning 0.

Note: PowerShell variables (such as $_) must be escaped in Puppet manifests either using backslashes or single quotes.

Alternately, you can put the PowerShell code for the command, onlyif, and unless parameters into separate files, and then invoke the file function in the resource. You could also use templates and the template() function if the PowerShell scripts need access to variables from Puppet.

exec { 'rename-guest':
  command   => file('guest/rename-guest.ps1'),
  onlyif    => file('guest/guest-exists.ps1'),
  provider  => powershell,
  logoutput => true,
}

Each file is a PowerShell script that should be in the module's files/ folder.

For example, here is the script at: guest/files/rename-guest.ps1

$obj = $(Get-WMIObject Win32_UserAccount -Filter "Name='Guest'")
$obj.Rename("OtherGuest")

This has the added benefit of not requiring escaping '$' in the PowerShell code. Note that the files must have DOS linefeeds or they will not work as expected. One tool for converting UNIX linefeeds to DOS linefeeds is unix2dos.

External files and exit codes

If you are calling external files, such as other PowerShell scripts or executables, be aware that the last executed script's exitcode is used by Puppet to determine whether the command was successful.

For example, if the file C:\fail.ps1 contains the following PowerShell script:

& cmd /c EXIT 5
& cmd /c EXIT 1

and we use the following Puppet manifest:

exec { 'test':
  command   => '& C:\fail.ps1',
  provider  => powershell,
}

Then the exec['test'] resource will always fail, because the last exit code from the external file C:\fail.ps1 is 1. This behavior might have unintended consequences if you combine multiple external files.

To stop this behavior, ensure that you use explicit Exit statements in your PowerShell scripts. For example, we changed the Puppet manifest from the above to:

exec { 'test':
  command   => '& C:\fail.ps1; Exit 0',
  provider  => powershell,
}

This will always succeed because the Exit 0 statement overrides the exit code from the C:\fail.ps1 script.

Console Error Output

The PowerShell module internally captures output sent to the .NET [System.Console]::Error stream like:

exec { 'test':
  command   => '[System.Console]::Error.WriteLine("foo")',
  provider  => powershell,
}

However, to produce output from a script, use the Write- prefixed cmdlets such as Write-Output, Write-Debug and Write-Error.

Reference

Provider

• powershell: Adapts the Puppet exec resource to run PowerShell commands.

Parameters

All parameters are optional.

creates

Specifies the file to look for before running the command. The command runs only if the file doesn't exist. Note: This parameter does not create a file, it only looks for one. Valid options: A string of the path to the file. Default: Undefined.

cwd

Sets the directory from which to run the command. Valid options: A string of the directory path. Default: Undefined.

command

Specifies the actual PowerShell command to execute. Must either be fully qualified or a search path for the command must be provided. Valid options: String. Default: Undefined.

environment

Sets additional environment variables to set for a command. Valid options: String, or an array of multiple options. Default: Undefined.

logoutput

Defines whether to log command output in addition to logging the exit code. If you specify 'on_failure', it only logs the output when the command has an exit code that does not match any value specified by the returns attribute. Valid options: true, false, and 'on_failure'. Default: 'on_failure'.

onlyif

Runs the exec only if the command returns 0. Valid options: String. Default: Undefined.

path

Specifies the search path used for command execution. Valid options: String of the path, an array, or a semicolon-separated list. Default: Undefined.

refresh

Refreshes the command. Valid options: String. Default: Undefined.

refreshonly

Refreshes the command only when a dependent object is changed. Used with subscribe and notify metaparameters. Valid options: true, false. Default: false.

returns

Lists the expected return code(s). If the executed command returns something else, an error is returned. Valid options: An array of acceptable return codes or a single value. Default: 0.

timeout

Sets the maximum time in seconds that the command should take. Valid options: Number or string representation of a number. Default: 300.

tries

Determines the number of times execution of the command should be attempted. Valid options: Number or a string representation of a number. Default: '1'.

try_sleep

Specifies the time to sleep in seconds between tries. Valid options: Number or a string representation of a number. Default: Undefined.

unless

Runs the exec, unless the command returns 0. Valid options: String. Default: Undefined.

Limitations

• Only supported on Windows Server 2008 and above, and Windows 7 and above.

• Experimental support added for Ubuntu 16.04, Ubuntu 14.0.4 and, CentOS 7.

  Note that this module will not install PowerShell on these platforms. For further information see the Linux installation instructions.

  Note that on non-Windows platforms the HOME environment variable is not available and can cause PowerShell to raise a The type initializer for 'System.Management.Automation.ConfigPropertyAccessor' threw an exception. error. This is documented in PowerShell GitHub Issue 1794. To workaround this issue, add an environment variable parameter to the Exec resource which specifies the HOME environment variable. For example:

  exec { "CreateTestFile":
    command     => "'puppet' | Set-Content -Path '/tmp/puppet-test'",
    unless      => 'If (Test-Path -Path "/tmp/puppet-test") { exit 0 } else { exit 1}',
    environment => [ 'HOME=/home/username'],
    provider    => powershell,
  }
  

• Only supported on Powershell 2.0 and above.

• When using here-strings in inline or templated scripts executed by this module, you must use the double-quote style syntax that begins with @" and ends with "@. The single-quote syntax that begins with @' and ends with '@ is not supported.

  Note that any external .ps1 script file loaded or executed with the call operator & is not subject to this limitation and can contain any style here-string. For instance, the script file external-code.ps1 can contain any style of here-string:

  exec { 'external-code':
    command   => '& C:\external-code.ps1',
    provider  => powershell,
  }
  

Development

Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our module contribution guide.

2017-07-27 - Supported Release 2.1.2

Summary

Small release with bugs fixes.

Bug Fixes

• Fix Global Warning variable (MODULES-5224)
• Move PowerShell template file to stop conflicts with DSC Module (MODULES-5228)

2017-07-07 - Supported Release 2.1.1

Summary

Small release with bugs fixes and experimental support for non-Windows Operating Systems (CentOS and Ubuntu).

Features

• Added rake tasks for release automation
• Added experimental support for non-Windows Support (CentOS, Ubuntu) (MODULES-3945)

Bug Fixes

• Documentation Update (DOC-2960)
• Update metadata for Puppet 4 and Puppet 5 (MODULES-4528, MODULES-4822, MODULES-5144)
• Dispose runspace on pipe close (MODULES-4754)
• Removed rspec configuration for win32_console (MODULES-4976)
• Provider will now respect the environment parameter (MODULES-4138)
• Return available UI Output on error (MODULES-5145)

2016-11-17 - Supported Release 2.1.0

Summary

Small release with bugs fixes and another speed improvement.

Bug Fixes

• Support Windows 2016/WMF 5.1 using named pipes (MODULES-3690)

Documentation updates

• Document herestring (DOC-2960)

2016-10-05 - Supported Release 2.0.3

Summary

Small release with bugs fixes and another speed improvement.

Bug Fixes

• Miscellaneous fixes which improve reliability
• Capture exit codes when executing external scripts (MODULES-3399)
• Add ability to set current working directory (MODULES-3565)
• Respect user specified timeout (MODULES-3709)
• Improve handling of user code exceptions (MODULES-3443)
• Output line and stacktrace of user code exception (MODULES-3839)
• Improve resilience to failure of PowerShell host (MODULES-3875)
• Fix race condition in threading with PowerShell host (MODULES-3144)
• Modify tests to detect differences in PowerShell error text (MODULES-3442)

Documentation updates

• Document how to handle exit codes (MODULES-3588)

2016-07-12 - Supported Release 2.0.2

Summary

Small release with bugs fixes and another speed improvement.

Features

• Noticable speed increase by reducing the time start a PowerShell command (MODULES-3406)

Bug Fixes

• Fixed minor bugs in tests (MODULES-3347)
• Added tests for try/catch (MODULES-2634)
• Fixed bug with older ruby (1.8)

2016-05-24 - Supported Release 2.0.1

Bug Fixes

• Updated the powershell manager in this module in order to not conflict with the Powershell Manager in the Puppet DSC module

2016-05-17 - Supported Release 2.0.0

Summary

Major release with performance improvements

Removed support for Windows Server 2003

Features

• Major performance improvement by sharing a single powershell session instead of creating a new powershell session per command
• Security improvement as scripts are not stored on the filesystem temporarily

Bug Fixes

• Updated test suites with later versions
• Documentation cleanup

2015-12-08 - Supported Release 1.0.6

Summary

Small release for support of newer PE versions.

2015-07-28 - Supported Release 1.0.5

Summary

Add metadata for Puppet 4 and PE 2015.2.0

Bug Fixes

• Minor testing bug fixes
• Readme cleanup

2014-11-04 - Supported Release 1.0.4

Summary

Fix Issues URL Add Future Parser testing support

2014-08-25 - Supported Release 1.0.3

Summary

This release updates the tests to verify that powershell continues to function on x64-native ruby.

2014-07-15 - Supported Release 1.0.2

Summary

This release merely updates metadata.json so the module can be uninstalled and upgraded via the puppet module command.

2014-07-09 - Release 1.0.1

Summary

Fix issue with metadata and PE version requirement