Skip to content

Commit 803dfc6

Browse files
committed
DOC-1497:Grammar, markdown, and format to match current styleguide
1 parent 8b69a66 commit 803dfc6

File tree

1 file changed

+65
-43
lines changed

1 file changed

+65
-43
lines changed

README.md

Lines changed: 65 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
1. [Overview](#overview)
66
2. [Module Description - What the module does and why it is useful](#module-description)
77
3. [Setup - The basics of getting started with powershell](#setup)
8+
* [Setup requirements](#setup-requirements)
89
* [Beginning with powershell](#beginning-with-powershell)
910
4. [Usage - Configuration options and additional functionality](#usage)
1011
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
@@ -17,95 +18,116 @@ This module adds a new exec provider capable of executing PowerShell commands.
1718

1819
##Module Description
1920

20-
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 all of the `exec` parameters, such as `creates`, `onlyif`, `unless`, etc. This module is particularly helpful if you need to run PowerShell commands but don't know the details about how PowerShell is executed, since you can technically run PowerShell commands in Puppet without the module.
21+
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, since you can technically run PowerShell commands in Puppet without the module.
2122

2223
##Setup
2324

25+
###Setup Requirements
26+
This module requires PowerShell to be installed and the `powershell.exe` to be available in the system PATH.
27+
2428
###Beginning with powershell
2529

26-
The powershell module adapts the Puppet
27-
[exec](http://docs.puppetlabs.com/references/stable/type.html#exec)
28-
resource to run PowerShell commands. To get started with the module, simply install it and declare 'powershell' in `provider` with the applicable command.
30+
The powershell module adapts the Puppet [exec](http://docs.puppetlabs.com/references/stable/type.html#exec) resource to run PowerShell commands. To get started, simply install the module and declare 'powershell' in `provider` with the applicable command.
2931

30-
```
32+
~~~
3133
exec { 'RESOURCENAME':
3234
command => '$(SOMECOMMAND)',
3335
provider => powershell,
3436
}
35-
```
37+
~~~
3638

3739
##Usage
3840

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

41-
For instance, if you wanted to rename the Guest account
43+
For instance, if you wanted to rename the Guest account:
4244

43-
```
45+
~~~
4446
exec { 'rename-guest':
4547
command => '$(Get-WMIObject Win32_UserAccount -Filter "Name=\'guest\'").Rename("new-guest")',
4648
unless => 'if (Get-WmiObject Win32_UserAccount -Filter "Name=\'guest\'") { exit 1 }',
4749
provider => powershell,
4850
}
49-
```
51+
~~~
5052

51-
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
52-
`unless` returning 0.
53+
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.
5354

54-
**Note:** PowerShell variables, e.g. `$_`, must be escaped in puppet manifests either using backslashes or single quotes.
55+
**Note:** PowerShell variables (e.g. `$_`), must be escaped in Puppet manifests either using backslashes or single quotes.
5556

5657
Alternatively, you can put the PowerShell code for the `command`, `onlyif`, and `unless` parameters into separate templates and then invoke the template function in the resource.
5758

58-
```
59+
~~~
5960
exec { 'rename-guest':
6061
command => template('guest/rename-guest.ps1'),
6162
onlyif => template('guest/guest-exists.ps1'),
6263
provider => powershell,
6364
logoutput => true,
6465
}
65-
```
66-
Each template is a PowerShell script,
66+
~~~
67+
68+
Each template is a PowerShell script.
6769

68-
```
70+
~~~
6971
$obj = $(Get-WMIObject Win32_UserAccount -Filter "Name='Guest'")
7072
$obj.Rename("OtherGuest")
71-
```
73+
~~~
7274

7375
This has the added benefit of not requiring escaping '$' in the PowerShell code.
7476

7577
##Reference
7678

77-
Since the powershell module is a provider for `exec` it enables the same parameters as [`exec`](http://docs.puppetlabs.com/references/stable/type.html#exec) for PowerShell.
78-
79-
###Provider: powershell
79+
####Provider
80+
* powershell - Adapts the Puppet `exec` resource to run PowerShell commands.
8081

8182
####Parameters
83+
All parameters are optional.
8284

83-
* **command** - The actual PowerShell command to execute. Must either be fully qualified or a search path for the command must be provided.
84-
* **creates** - The file to look for before running the command. The command will only run if the file doesn’t exist. *Note:* This parameter will not create a file, it will simply look for one.
85-
* **cwd** - The directory from which to run the command.
86-
* **environment** - Additional environment variables to set for a command. Multiple entries should be in an array.
87-
* **group** - The group to run the command as.
88-
* **logoutput** - Whether to log command output in addition to logging the exit code. Valid values are 'true', 'false', and 'on_failure'. Defaults to 'on_failure, which only logs the output when the command has an exit code that does not match any value specified by the returns attribute.
89-
* **onlyif** - Only run the exec if the command returns 0.
90-
* **path** - The search path used for command execution.
91-
* **refresh** - How to refresh the command.
92-
* **refreshonly** - Used with `subscribe` and `notify` [metaparameters](http://docs.puppetlabs.com/references/latest/metaparameter.html) to refresh the command only when a dependent object is changed. Valid values are 'true' and 'false'.
93-
* **returns** - The expected return code(s). An error will be returned if the executed command returns something else. Defaults to 0. Can be specified as an array of acceptable return codes or a single value.
94-
* **timeout** - The maximum time the command should take.
95-
* **tries** - The number of times execution of the command should be tried. Defaults to '1'.
96-
* **try_sleep** - The time to sleep in seconds between `tries`.
97-
* **umask** - The umask to be used while executing the command.
98-
* **unless** - The `exec` will run unless the command returns 0.
85+
#####`creates`
86+
Specifies the file to look for before running the command. The command will only run if the file doesn't exist. **Note: This parameter will not create a file, it will simpy look for one.** Valid options: A string of the path to the file. Default: Undefined.
9987

100-
##Limitations
88+
#####`cwd`
89+
Sets the directory from which to run the command. Valid options: A string of the directory path. Default: Undefined.
10190

102-
* This module requires PowerShell to be installed and the `powershell.exe` to be available in the system PATH.
103-
* Only supported on Windows Server 2003 and above, and Windows 7 and 8
91+
#####`command`
92+
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.
10493

105-
##Development
94+
#####`environment`
95+
Sets additional environment variables to set for a command. Valid options: String, or an array of multiple options. Default: Undefined.
96+
97+
#####`logoutput`
98+
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'.
99+
100+
#####`onlyif`
101+
Runs the exec only if the command returns 0. Valid options: String. Default: Undefined.
102+
103+
#####`path`
104+
Specifies the search path used for command execution. Valid options: String of the path, an array, or a semicolon-separated list. Default: Undefined.
105+
106+
#####`refresh`
107+
Refreshes the command. Valid options: String. Default: Undefined.
106108

107-
Puppet Labs 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 of hardware, software, and deployment configurations that Puppet is intended to serve.
109+
#####`refreshonly`
110+
Refreshes the command only when a dependent object is changed. Used with `subscribe` and `notify` [metaparameters](http://docs.puppetlabs.com/references/latest/metaparameter.html). Valid options: 'true', 'false'. Default: 'false'.
108111

109-
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.
112+
#####`returns`
113+
Lists the expected return code(s). An error will be returned if the executed command returns something else. Valid options: An array of acceptable return codes or a single value. Default: 0.
114+
115+
#####`timeout`
116+
Sets the maximum time in seconds that the command should take. Valid options: Number or string representation of a number. Default: 300.
117+
118+
#####`tries`
119+
Determines the number of times execution of the command should be attempted. Valid options: Number or a string representation of a number. Default: '1'.
120+
121+
#####`try_sleep`
122+
Specifies the time to sleep in seconds between `tries`. Valid options: Number or a string representation of a number. Default: Undefined.
123+
124+
#####`unless`
125+
Runs the `exec`, unless the command returns 0. Valid options: String. Default: Undefined.
126+
127+
##Limitations
128+
129+
* Only supported on Windows Server 2003 and above, and Windows 7 and above.
130+
131+
##Development
110132

111-
You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
133+
Puppet Labs 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.puppetlabs.com/forge/contributing.html)

0 commit comments

Comments
 (0)