github.com/aclaygray/packer@v1.3.2/website/source/docs/provisioners/powershell.html.md (about) 1 --- 2 description: | 3 The PowerShell Packer provisioner runs PowerShell scripts on Windows 4 machines. 5 It assumes that the communicator in use is WinRM. 6 layout: docs 7 page_title: 'PowerShell - Provisioners' 8 sidebar_current: 'docs-provisioners-powershell' 9 --- 10 11 # PowerShell Provisioner 12 13 Type: `powershell` 14 15 The PowerShell Packer provisioner runs PowerShell scripts on Windows machines. 16 It assumes that the communicator in use is WinRM. However, the provisioner 17 can work equally well (with a few caveats) when combined with the SSH 18 communicator. See the [section 19 below](/docs/provisioners/powershell.html#combining-the-powershell-provisioner-with-the-ssh-communicator) 20 for details. 21 22 ## Basic Example 23 24 The example below is fully functional. 25 26 ``` json 27 { 28 "type": "powershell", 29 "inline": ["dir c:\\"] 30 } 31 ``` 32 33 ## Configuration Reference 34 35 The reference of available configuration options is listed below. The only 36 required element is either "inline" or "script". Every other option is 37 optional. 38 39 Exactly *one* of the following is required: 40 41 - `inline` (array of strings) - This is an array of commands to execute. The 42 commands are concatenated by newlines and turned into a single file, so 43 they are all executed within the same context. This allows you to change 44 directories in one command and use something in the directory in the next 45 and so on. Inline scripts are the easiest way to pull off simple tasks 46 within the machine. 47 48 - `script` (string) - The path to a script to upload and execute in 49 the machine. This path can be absolute or relative. If it is relative, it 50 is relative to the working directory when Packer is executed. 51 52 - `scripts` (array of strings) - An array of scripts to execute. The scripts 53 will be uploaded and executed in the order specified. Each script is 54 executed in isolation, so state such as variables from one script won't 55 carry on to the next. 56 57 Optional parameters: 58 59 - `binary` (boolean) - If true, specifies that the script(s) are binary 60 files, and Packer should therefore not convert Windows line endings to Unix 61 line endings (if there are any). By default this is false. 62 63 - `elevated_execute_command` (string) - The command to use to execute the 64 elevated script. By default this is as follows: 65 66 ``` powershell 67 powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" 68 ``` 69 70 The value of this is treated as [configuration 71 template](/docs/templates/engine.html). There are two 72 available variables: `Path`, which is the path to the script to run, and 73 `Vars`, which is the location of a temp file containing the list of 74 `environment_vars`, if configured. 75 76 - `environment_vars` (array of strings) - An array of key/value pairs to 77 inject prior to the execute\_command. The format should be `key=value`. 78 Packer injects some environmental variables by default into the 79 environment, as well, which are covered in the section below. 80 If you are running on AWS, Azure or Google Compute and would like to access the generated 81 password that Packer uses to connect to the instance via 82 WinRM, you can use the template variable `{{.WinRMPassword}}` to set this 83 as an environment variable. For example: 84 85 ```json 86 { 87 "type": "powershell", 88 "environment_vars": "WINRMPASS={{.WinRMPassword}}", 89 "inline": ["Write-Host \"Automatically generated aws password is: $Env:WINRMPASS\""] 90 }, 91 ``` 92 93 - `execute_command` (string) - The command to use to execute the script. By 94 default this is as follows: 95 96 ``` powershell 97 powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" 98 ``` 99 100 The value of this is treated as [configuration 101 template](/docs/templates/engine.html). There are two 102 available variables: `Path`, which is the path to the script to run, and 103 `Vars`, which is the location of a temp file containing the list of 104 `environment_vars`. The value of both `Path` and `Vars` can be 105 manually configured by setting the values for `remote_path` and 106 `remote_env_var_path` respectively. 107 108 If you use the SSH communicator and have changed your default shell, you 109 may need to modify your `execute_command` to make sure that the command is 110 valid and properly escaped; the default assumes that you have not changed 111 the default shell away from cmd. 112 113 - `elevated_user` and `elevated_password` (string) - If specified, the 114 PowerShell script will be run with elevated privileges using the given 115 Windows user. If you are running a build on AWS, Azure or Google Compute and would like to run using 116 the generated password that Packer uses to connect to the instance via 117 WinRM, you may do so by using the template variable {{.WinRMPassword}}. 118 For example: 119 120 ``` json 121 "elevated_user": "Administrator", 122 "elevated_password": "{{.WinRMPassword}}", 123 ``` 124 125 - `remote_path` (string) - The path where the PowerShell script will be 126 uploaded to within the target build machine. This defaults to 127 `C:/Windows/Temp/script-UUID.ps1` where UUID is replaced with a 128 dynamically generated string that uniquely identifies the script. 129 130 This setting allows users to override the default upload location. The 131 value must be a writable location and any parent directories must 132 already exist. 133 134 - `remote_env_var_path` (string) - Environment variables required within 135 the remote environment are uploaded within a PowerShell script and then 136 enabled by 'dot sourcing' the script immediately prior to execution of 137 the main command or script. 138 139 The path the environment variables script will be uploaded to defaults to 140 `C:/Windows/Temp/packer-ps-env-vars-UUID.ps1` where UUID is replaced 141 with a dynamically generated string that uniquely identifies the 142 script. 143 144 This setting allows users to override the location the environment 145 variable script is uploaded to. The value must be a writable location 146 and any parent directories must already exist. 147 148 - `start_retry_timeout` (string) - The amount of time to attempt to *start* 149 the remote process. By default this is "5m" or 5 minutes. This setting 150 exists in order to deal with times when SSH may restart, such as a 151 system reboot. Set this to a higher value if reboots take a longer amount 152 of time. 153 154 - `valid_exit_codes` (list of ints) - Valid exit codes for the script. By 155 default this is just 0. 156 157 ## Default Environmental Variables 158 159 In addition to being able to specify custom environmental variables using the 160 `environment_vars` configuration, the provisioner automatically defines certain 161 commonly useful environmental variables: 162 163 - `PACKER_BUILD_NAME` is set to the 164 [name of the build](/docs/templates/builders.html#named-builds) that Packer is running. 165 This is most useful when Packer is making multiple builds and you want to 166 distinguish them slightly from a common provisioning script. 167 168 - `PACKER_BUILDER_TYPE` is the type of the builder that was used to create 169 the machine that the script is running on. This is useful if you want to 170 run only certain parts of the script on systems built with certain 171 builders. 172 173 - `PACKER_HTTP_ADDR` If using a builder that provides an http server for file 174 transfer (such as hyperv, parallels, qemu, virtualbox, and vmware), this 175 will be set to the address. You can use this address in your provisioner to 176 download large files over http. This may be useful if you're experiencing 177 slower speeds using the default file provisioner. A file provisioner using 178 the `winrm` communicator may experience these types of difficulties. 179 180 ## Combining the PowerShell Provisioner with the SSH Communicator 181 182 The good news first. If you are using the 183 [Microsoft port of OpenSSH](https://github.com/PowerShell/Win32-OpenSSH/wiki) 184 then the provisioner should just work as expected - no extra configuration 185 effort is required. 186 187 Now the caveats. If you are using an alternative configuration, and your SSH 188 connection lands you in a *nix shell on the remote host, then you will most 189 likely need to manually set the `execute_command`; The default 190 `execute_command` used by Packer will not work for you. 191 When configuring the command you will need to ensure that any dollar signs 192 or other characters that may be incorrectly interpreted by the remote shell 193 are escaped accordingly. 194 195 The following example shows how the standard `execute_command` can be 196 reconfigured to work on a remote system with 197 [Cygwin/OpenSSH](https://cygwin.com/) installed. 198 The `execute_command` has each dollar sign backslash escaped so that it is 199 not interpreted by the remote Bash shell - Bash being the default shell for 200 Cygwin environments. 201 202 ```json 203 "provisioners": [ 204 { 205 "type": "powershell", 206 "execute_command": "powershell -executionpolicy bypass \"& { if (Test-Path variable:global:ProgressPreference){\\$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit \\$LastExitCode }\"", 207 "inline": [ 208 "Write-Host \"Hello from PowerShell\"", 209 ] 210 } 211 ] 212 ``` 213 214 215 ## Packer's Handling of Characters Special to PowerShell 216 217 The escape character in PowerShell is the `backtick`, also sometimes 218 referred to as the `grave accent`. When, and when not, to escape characters 219 special to PowerShell is probably best demonstrated with a series of examples. 220 221 ### When To Escape... 222 223 Users need to deal with escaping characters special to PowerShell when they 224 appear *directly* in commands used in the `inline` PowerShell provisioner and 225 when they appear *directly* in the users own scripts. 226 Note that where double quotes appear within double quotes, the addition of 227 a backslash escape is required for the JSON template to be parsed correctly. 228 229 ``` json 230 "provisioners": [ 231 { 232 "type": "powershell", 233 "inline": [ 234 "Write-Host \"A literal dollar `$ must be escaped\"", 235 "Write-Host \"A literal backtick `` must be escaped\"", 236 "Write-Host \"Here `\"double quotes`\" must be escaped\"", 237 "Write-Host \"Here `'single quotes`' don`'t really need to be\"", 238 "Write-Host \"escaped... but it doesn`'t hurt to do so.\"", 239 ] 240 }, 241 ``` 242 243 The above snippet should result in the following output on the Packer console: 244 245 ``` 246 ==> amazon-ebs: Provisioning with Powershell... 247 ==> amazon-ebs: Provisioning with powershell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner508190439 248 amazon-ebs: A literal dollar $ must be escaped 249 amazon-ebs: A literal backtick ` must be escaped 250 amazon-ebs: Here "double quotes" must be escaped 251 amazon-ebs: Here 'single quotes' don't really need to be 252 amazon-ebs: escaped... but it doesn't hurt to do so. 253 ``` 254 255 ### When Not To Escape... 256 257 Special characters appearing in user environment variable values and in the 258 `elevated_user` and `elevated_password` fields will be automatically 259 dealt with for the user. There is no need to use escapes in these instances. 260 261 ``` json 262 { 263 "variables": { 264 "psvar": "My$tring" 265 }, 266 ... 267 "provisioners": [ 268 { 269 "type": "powershell", 270 "elevated_user": "Administrator", 271 "elevated_password": "Super$3cr3t!", 272 "inline": "Write-Output \"The dollar in the elevated_password is interpreted correctly\"" 273 }, 274 { 275 "type": "powershell", 276 "environment_vars": [ 277 "VAR1=A$Dollar", 278 "VAR2=A`Backtick", 279 "VAR3=A'SingleQuote", 280 "VAR4=A\"DoubleQuote", 281 "VAR5={{user `psvar`}}" 282 ], 283 "inline": [ 284 "Write-Output \"In the following examples the special character is interpreted correctly:\"", 285 "Write-Output \"The dollar in VAR1: $Env:VAR1\"", 286 "Write-Output \"The backtick in VAR2: $Env:VAR2\"", 287 "Write-Output \"The single quote in VAR3: $Env:VAR3\"", 288 "Write-Output \"The double quote in VAR4: $Env:VAR4\"", 289 "Write-Output \"The dollar in VAR5 (expanded from a user var): $Env:VAR5\"" 290 ] 291 } 292 ] 293 ... 294 } 295 ``` 296 297 The above snippet should result in the following output on the Packer console: 298 299 ``` 300 ==> amazon-ebs: Provisioning with Powershell... 301 ==> amazon-ebs: Provisioning with powershell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner961728919 302 amazon-ebs: The dollar in the elevated_password is interpreted correctly 303 ==> amazon-ebs: Provisioning with Powershell... 304 ==> amazon-ebs: Provisioning with powershell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner142826554 305 amazon-ebs: In the following examples the special character is interpreted correctly: 306 amazon-ebs: The dollar in VAR1: A$Dollar 307 amazon-ebs: The backtick in VAR2: A`Backtick 308 amazon-ebs: The single quote in VAR3: A'SingleQuote 309 amazon-ebs: The double quote in VAR4: A"DoubleQuote 310 amazon-ebs: The dollar in VAR5 (expanded from a user var): My$tring 311 ```