{"id":15022675,"url":"https://github.com/puppetlabs/puppetlabs-powershell","last_synced_at":"2025-05-15T06:05:04.774Z","repository":{"id":6589150,"uuid":"7831726","full_name":"puppetlabs/puppetlabs-powershell","owner":"puppetlabs","description":"powershell provider for the Puppet exec resource type","archived":false,"fork":false,"pushed_at":"2025-04-23T12:10:33.000Z","size":22755,"stargazers_count":48,"open_issues_count":3,"forks_count":79,"subscribers_count":171,"default_branch":"main","last_synced_at":"2025-05-03T02:07:55.005Z","etag":null,"topics":["module","supported"],"latest_commit_sha":null,"homepage":"forge.puppetlabs.com/puppetlabs/powershell","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-01-26T01:16:29.000Z","updated_at":"2025-04-23T12:10:36.000Z","dependencies_parsed_at":"2023-11-22T19:26:20.639Z","dependency_job_id":"9ea3c158-cc47-43cf-a64f-352cbac23c18","html_url":"https://github.com/puppetlabs/puppetlabs-powershell","commit_stats":{"total_commits":488,"total_committers":56,"mean_commits":8.714285714285714,"dds":0.8463114754098361,"last_synced_commit":"ca7863577f33dc5f7fafe11205004cd4310eee75"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-powershell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-powershell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-powershell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-powershell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-powershell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043266,"owners_count":22004913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["module","supported"],"created_at":"2024-09-24T19:58:15.627Z","updated_at":"2025-05-15T06:05:04.748Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# powershell\n\n#### Table of Contents\n\n1. [Overview](#overview)\n2. [Module Description - What the module does and why it is useful](#module-description)\n3. [Setup - The basics of getting started with powershell](#setup)\n    * [Setup requirements](#setup-requirements)\n    * [Beginning with powershell](#beginning-with-powershell)\n4. [Usage - Configuration options and additional functionality](#usage)\n    * [External files and exit codes](#external-files-and-exit-codes)\n    * [Console Error Output](#console-error-output)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [License](#license)\n7. [Development - Guide for contributing to the module](#development)\n\n## Overview\n\nThis module adds a new exec provider capable of executing PowerShell commands.\n\n## Module Description\n\nPuppet provides a built-in `exec` type that is capable of executing commands. This module adds a `powershell` and `pwsh` 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 how PowerShell is executed, because you can run PowerShell commands in Puppet without the module.\n\n## Setup\n\n### Requirements\n\nThe `powershell` provider requires you install [Windows PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-5.1) and have `powershell.exe` available in the system PATH. Note that most Windows operating systems already have Windows PowerShell installed.\n\nThe `pwsh` provider requires you install [PowerShell Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-6) and make `pwsh` available either in the system PATH or specified in the `path` parameter.\n\nFor example, when you install PowerShell Core in `/usr/alice/pscore`, you need the following manifest:\n\n~~~ puppet\nexec { 'RESOURCENAME':\n  ...\n  path     =\u003e '/usr/alice/pscore',\n  provider =\u003e pwsh,\n}\n~~~\n\n### Beginning with powershell\n\nThe powershell module adapts the Puppet [exec](http://docs.puppet.com/references/stable/type.html#exec) resource to run PowerShell commands. To get started, install the module and declare 'powershell' in `provider` with the applicable command.\n\n~~~ puppet\nexec { 'RESOURCENAME':\n  command   =\u003e 'SOMECOMMAND',\n  provider  =\u003e powershell,\n}\n~~~\n\n## Usage\n\nWhen using `exec` resources with the `powershell` or `pwsh` provider, the `command` parameter must be single-quoted to prevent Puppet from interpolating `$(..)`.\n\nFor instance, to rename the Guest account:\n\n~~~ puppet\nexec { 'rename-guest':\n  command   =\u003e '(Get-WMIObject Win32_UserAccount -Filter \"Name=\\'guest\\'\").Rename(\"new-guest\")',\n  unless    =\u003e 'if (Get-WmiObject Win32_UserAccount -Filter \"Name=\\'guest\\'\") { exit 1 }',\n  provider  =\u003e powershell,\n}\n~~~\n\nNote 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.\n\n**Note:** PowerShell variables (such as `$_`) must be escaped in Puppet manifests either using backslashes or single quotes.\n\nAlternately, 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.\n\n~~~ puppet\nexec { 'rename-guest':\n  command   =\u003e file('guest/rename-guest.ps1'),\n  onlyif    =\u003e file('guest/guest-exists.ps1'),\n  provider  =\u003e powershell,\n  logoutput =\u003e true,\n}\n~~~\n\nEach file is a PowerShell script that should be in the module's `files/` folder.\n\nFor example, here is the script at: `guest/files/rename-guest.ps1`\n\n~~~ powershell\n$obj = $(Get-WMIObject Win32_UserAccount -Filter \"Name='Guest'\")\n$obj.Rename(\"OtherGuest\")\n~~~\n\nThis 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](http://freecode.com/projects/dos2unix).\n\n### External files and exit codes\n\nIf 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.\n\nFor example, if the file `C:\\fail.ps1` contains the following PowerShell script:\n\n~~~ powershell\n\u0026 cmd /c EXIT 5\n\u0026 cmd /c EXIT 1\n~~~\n\nand we use the following Puppet manifest:\n\n~~~ puppet\nexec { 'test':\n  command   =\u003e '\u0026 C:\\fail.ps1',\n  provider  =\u003e powershell,\n}\n~~~\n\nThen 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.\n\nTo 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:\n\n~~~ puppet\nexec { 'test':\n  command   =\u003e '\u0026 C:\\fail.ps1; Exit 0',\n  provider  =\u003e powershell,\n}\n~~~\n\nThis will always succeed because the `Exit 0` statement overrides the exit code from the `C:\\fail.ps1` script.\n\n### Console Error Output\n\nThe PowerShell module internally captures output sent to the .NET `[System.Console]::Error` stream like:\n\n~~~ puppet\nexec { 'test':\n  command   =\u003e '[System.Console]::Error.WriteLine(\"foo\")',\n  provider  =\u003e powershell,\n}\n~~~\n\nHowever, to produce output from a script, use the `Write-` prefixed cmdlets such as `Write-Output`, `Write-Debug` and `Write-Error`.\n\n## Reference\n\n#### Provider\n\n* `powershell`: Adapts the Puppet `exec` resource to run [Windows PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-5.1) commands.\n\n* `pwsh`: Adapts the Puppet `exec` resource to run [PowerShell Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-6) commands.\n\n#### Parameters\n\nAll parameters are optional.\n\n##### `creates`\n\nSpecifies 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.\n\n##### `cwd`\n\nSets the directory from which to run the command. Valid options: A string of the directory path. Default: Undefined.\n\n##### `command`\n\nSpecifies 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.\n\n##### `environment`\n\nSets additional environment variables to set for a command. Valid options: String, or an array of multiple options. Default: Undefined.\n\n##### `logoutput`\n\nDefines 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'.\n\n##### `onlyif`\n\nRuns the exec only if the command returns 0. Valid options: String. Default: Undefined.\n\n##### `path`\n\nSpecifies the search path used for command execution. Valid options: String of the path, an array, or a semicolon-separated list. Default: Undefined.\n\nThe `pwsh` provider can also use the path to find the pwsh executable.\n\n##### `refresh`\n\nRefreshes the command. Valid options: String. Default: Undefined.\n\n##### `refreshonly`\n\nRefreshes the command only when a dependent object is changed. Used with `subscribe` and `notify` [metaparameters](http://docs.puppet.com/references/latest/metaparameter.html). Valid options: true, false. Default: false.\n\n##### `returns`\n\nLists 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.\n\n##### `timeout`\n\nSets the maximum time in seconds that the command should take. Valid options: Number or string representation of a number. Default: 300. A value of `0` for this property will result in using the default timeout of 300. Inifinite timeout is not supported in this module, but large timeouts are allowed if needed.\n\n##### `tries`\n\nDetermines the number of times execution of the command should be attempted. Valid options: Number or a string representation of a number. Default: '1'.\n\n##### `try_sleep`\n\nSpecifies the time to sleep in seconds between `tries`. Valid options: Number or a string representation of a number. Default: Undefined.\n\n##### `unless`\n\nRuns the `exec`, unless the command returns 0. Valid options: String. Default: Undefined.\n\n## Limitations\n\n* The `powershell` provider is only supported on:\n\n  * Windows Server 2008 and above\n  \n  * Windows 7 and above\n   \n* The `pwsh` provider is supported on:\n\n  * CentOS 7\n\n  * Debian 8.7+, Debian 9\n\n  * Fedora 27, 28\n\n  * MacOS 10.12+\n\n  * Red Hat Enterprise Linux 7\n\n  * Ubuntu 14.04, 16.0.4 and 18.04\n\n  * Windows Desktop 7 and above\n\n  * Windows Server 2008 R2 and above\n\n  Note that this module will not install PowerShell on these platforms. For further information see the [Linux installation instructions](https://docs.microsoft.com/en-us/powershell/scripting/setup/installing-powershell-core-on-linux).\n\n* Only supported on Windows PowerShell 2.0 and above, and PowerShell Core 6.1 and above.\n\n* 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.\n\n  Note that any external .ps1 script file loaded or executed with the call operator `\u0026` 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:\n\n  ```\n  exec { 'external-code':\n    command   =\u003e '\u0026 C:\\external-code.ps1',\n    provider  =\u003e powershell,\n  }\n  ```\n\n## License\n\nThis codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of [AGPL](https://opensource.org/license/agpl-v3/), [BSD-2](https://opensource.org/license/bsd-2-clause/), [BSD-3](https://opensource.org/license/bsd-3-clause/), [GPL2.0](https://opensource.org/license/gpl-2-0/), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.\n\n## Development\n\nPuppet 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.](https://docs.puppet.com/forge/contributing.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-powershell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-powershell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-powershell/lists"}