diff --git a/provisioner/powershell/provisioner.go b/provisioner/powershell/provisioner.go index 70b7105da..bd2d91509 100644 --- a/provisioner/powershell/provisioner.go +++ b/provisioner/powershell/provisioner.go @@ -1,3 +1,4 @@ +//go:generate struct-markdown //go:generate mapstructure-to-hcl2 -type Config // This package implements a provisioner for Packer that executes powershell @@ -50,6 +51,15 @@ type Config struct { // The command used to execute the elevated script. The '{{ .Path }}' // variable should be used to specify where the script goes, {{ .Vars }} // can be used to inject the environment_vars into the environment. + // ```powershell + // powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" + // ``` + // This is a [template engine](/docs/templates/engine). Therefore, you + // may use user variables and template functions in this field. In addition, + // you may use two extra variables: + // - `Path`: The path to the script to run + // - `Vars`: The location of a temp file containing the list of + // `environment_vars`, if configured. ElevatedExecuteCommand string `mapstructure:"elevated_execute_command"` // Whether to clean scripts up after executing the provisioner. @@ -59,9 +69,10 @@ type Config struct { // value set for `skip_clean`. SkipClean bool `mapstructure:"skip_clean"` - // The timeout for retrying to start the process. Until this timeout is - // reached, if the provisioner can't start a process, it retries. This - // can be set high to allow for reboots. + // The amount of time to attempt to _start_ + // the remote process. By default this is "5m" or 5 minutes. This setting + // exists in order to deal with times when SSH may restart, such as a system + // reboot. Set this to a higher value if reboots take a longer amount of time. StartRetryTimeout time.Duration `mapstructure:"start_retry_timeout"` // This is used in the template generation to format environment variables @@ -74,6 +85,11 @@ type Config struct { ElevatedUser string `mapstructure:"elevated_user"` ElevatedPassword string `mapstructure:"elevated_password"` + // To run ps scripts on windows packer defaults this to + // "bypass" and wraps the command to run. Setting this to "none" will prevent + // wrapping, allowing to see exit codes on docker for windows. Possible values + // are "bypass", "allsigned", "default", "remotesigned", "restricted", + // "undefined", "unrestricted", "none". ExecutionPolicy ExecutionPolicy `mapstructure:"execution_policy"` remoteCleanUpScriptPath string diff --git a/website/pages/docs/provisioners/powershell.mdx b/website/pages/docs/provisioners/powershell.mdx index 928886ec2..b6a50e083 100644 --- a/website/pages/docs/provisioners/powershell.mdx +++ b/website/pages/docs/provisioners/powershell.mdx @@ -46,42 +46,16 @@ provisioner "powershell" { ## Configuration Reference -@include 'provisioners/shell-config.mdx' - -- `debug_mode` - If set, sets PowerShell's [PSDebug mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/set-psdebug?view=powershell-7) - in order to make script debugging easier. For instance, setting the value to 1 results in adding this to the execute command: - - ```powershell - Set-PSDebug -Trace 1 - ``` - -- `elevated_execute_command` (string) - The command to use to execute the - elevated script. By default this is as follows: +### Required - ```powershell - powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" - ``` - - This is a [template engine](/docs/templates/engine). Therefore, you - may use user variables and template functions in this field. In addition, - you may use two extra variables: +@include 'provisioners/shell-config.mdx' - - `Path`: The path to the script to run - - `Vars`: The location of a temp file containing the list of - `environment_vars`, if configured. +### Optional +@include 'provisioner/powershell/Config-not-required.mdx' -- `environment_vars` (array of strings) - An array of key/value pairs to - inject prior to the execute_command. The format should be `key=value`. - Packer injects some environmental variables by default into the - environment, as well, which are covered in the section below. +@include 'provisioners/common-config.mdx' - This is a [template engine](/docs/templates/engine). Therefore, you - may use user variables and template functions in this field. If you are - running on AWS, Azure, Google Compute, or OpenStack and would like to access - the autogenerated password that Packer uses to connect to the instance via - WinRM, you can use the `build` template engine to inject it using - `{{ build `Password`}}`. In HCL templates, you can do the same thing by - accessing the `build` variables For example: +## Default Environmental Variables @@ -107,39 +81,29 @@ provisioner "powershell" { -- `execute_command` (string) - The command to use to execute the script. By - default this is as follows: - - ```powershell - powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" - ``` +In addition to being able to specify custom environmental variables using the +`environment_vars` configuration, the provisioner automatically defines certain +commonly useful environmental variables: - This is a [template engine](/docs/templates/engine). Therefore, you - may use user variables and template functions in this field. In addition, - you may use two extra variables: +- `PACKER_BUILD_NAME` is set to the [name of the + build](/docs/templates/builders#named-builds) that Packer is running. + This is most useful when Packer is making multiple builds and you want to + distinguish them slightly from a common provisioning script. - - `Path`: The path to the script to run - - `Vars`: The location of a temp file containing the list of - `environment_vars`, if configured. - The value of both `Path` and `Vars` can be manually configured by setting - the values for `remote_path` and `remote_env_var_path` respectively. +- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create + the machine that the script is running on. This is useful if you want to + run only certain parts of the script on systems built with certain + builders. - If you use the SSH communicator and have changed your default shell, you - may need to modify your `execute_command` to make sure that the command is - valid and properly escaped; the default assumes that you have not changed - the default shell away from cmd. +- `PACKER_HTTP_ADDR` If using a builder that provides an http server for file + transfer (such as hyperv, parallels, qemu, virtualbox, and vmware), this + will be set to the address. You can use this address in your provisioner to + download large files over http. This may be useful if you're experiencing + slower speeds using the default file provisioner. A file provisioner using + the `winrm` communicator may experience these types of difficulties. -- `elevated_user` and `elevated_password` (string) - If specified, the - PowerShell script will be run with elevated privileges using the given - Windows user. - This is a [template engine](/docs/templates/engine). Therefore, you - may use user variables and template functions in this field. If you are - running on AWS, Azure, Google Compute, or OpenStack and would like to access - the autogenerated password that Packer uses to connect to the instance via - WinRM, you can use the `build` template engine to inject it using - `{{ build `Password`}}`. In HCL templates, you can do the same thing by - accessing the `build` variables For example: +## Setting Elevated User and Password @@ -194,69 +158,6 @@ provisioner "powershell" { -- `execution_policy` - To run ps scripts on windows packer defaults this to - "bypass" and wraps the command to run. Setting this to "none" will prevent - wrapping, allowing to see exit codes on docker for windows. Possible values - are "bypass", "allsigned", "default", "remotesigned", "restricted", - "undefined", "unrestricted", "none". - -- `remote_path` (string) - The path where the PowerShell script will be - uploaded to within the target build machine. This defaults to - `C:/Windows/Temp/script-UUID.ps1` where UUID is replaced with a dynamically - generated string that uniquely identifies the script. - - This setting allows users to override the default upload location. The - value must be a writable location and any parent directories must already - exist. - -- `remote_env_var_path` (string) - Environment variables required within the - remote environment are uploaded within a PowerShell script and then enabled - by 'dot sourcing' the script immediately prior to execution of the main - command or script. - - The path the environment variables script will be uploaded to defaults to - `C:/Windows/Temp/packer-ps-env-vars-UUID.ps1` where UUID is replaced with a - dynamically generated string that uniquely identifies the script. - - This setting allows users to override the location the environment variable - script is uploaded to. The value must be a writable location and any parent - directories must already exist. - -- `skip_clean` (bool) - Whether to clean scripts up after executing the provisioner. - Defaults to false. When true any script created by a non-elevated Powershell - provisioner will be removed from the remote machine. Elevated scripts, - along with the scheduled tasks, will always be removed regardless of the - value set for `skip_clean`. - -- `start_retry_timeout` (string) - The amount of time to attempt to _start_ - the remote process. By default this is "5m" or 5 minutes. This setting - exists in order to deal with times when SSH may restart, such as a system - reboot. Set this to a higher value if reboots take a longer amount of time. - -@include 'provisioners/common-config.mdx' - -## Default Environmental Variables - -In addition to being able to specify custom environmental variables using the -`environment_vars` configuration, the provisioner automatically defines certain -commonly useful environmental variables: - -- `PACKER_BUILD_NAME` is set to the [name of the - build](/docs/templates/builders#named-builds) that Packer is running. - This is most useful when Packer is making multiple builds and you want to - distinguish them slightly from a common provisioning script. - -- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create - the machine that the script is running on. This is useful if you want to - run only certain parts of the script on systems built with certain - builders. - -- `PACKER_HTTP_ADDR` If using a builder that provides an http server for file - transfer (such as hyperv, parallels, qemu, virtualbox, and vmware), this - will be set to the address. You can use this address in your provisioner to - download large files over http. This may be useful if you're experiencing - slower speeds using the default file provisioner. A file provisioner using - the `winrm` communicator may experience these types of difficulties. ## Combining the PowerShell Provisioner with the SSH Communicator diff --git a/website/pages/partials/provisioner/powershell/Config-not-required.mdx b/website/pages/partials/provisioner/powershell/Config-not-required.mdx new file mode 100644 index 000000000..87bf5342f --- /dev/null +++ b/website/pages/partials/provisioner/powershell/Config-not-required.mdx @@ -0,0 +1,52 @@ + + +- `remote_env_var_path` (string) - The remote path where the file containing the environment variables + will be uploaded to. This should be set to a writable file that is in a + pre-existing directory. + +- `elevated_execute_command` (string) - The command used to execute the elevated script. The '{{ .Path }}' + variable should be used to specify where the script goes, {{ .Vars }} + can be used to inject the environment_vars into the environment. + ```powershell + powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" + ``` + This is a [template engine](/docs/templates/engine). Therefore, you + may use user variables and template functions in this field. In addition, + you may use two extra variables: + - `Path`: The path to the script to run + - `Vars`: The location of a temp file containing the list of + `environment_vars`, if configured. + +- `skip_clean` (bool) - Whether to clean scripts up after executing the provisioner. + Defaults to false. When true any script created by a non-elevated Powershell + provisioner will be removed from the remote machine. Elevated scripts, + along with the scheduled tasks, will always be removed regardless of the + value set for `skip_clean`. + +- `start_retry_timeout` (duration string | ex: "1h5m2s") - The amount of time to attempt to _start_ + the remote process. By default this is "5m" or 5 minutes. This setting + exists in order to deal with times when SSH may restart, such as a system + reboot. Set this to a higher value if reboots take a longer amount of time. + +- `elevated_env_var_format` (string) - This is used in the template generation to format environment variables + inside the `ElevatedExecuteCommand` template. + +- `elevated_user` (string) - Instructs the communicator to run the remote script as a Windows + scheduled task, effectively elevating the remote user by impersonating + a logged-in user + +- `elevated_password` (string) - Elevated Password + +- `execution_policy` (ExecutionPolicy) - To run ps scripts on windows packer defaults this to + "bypass" and wraps the command to run. Setting this to "none" will prevent + wrapping, allowing to see exit codes on docker for windows. Possible values + are "bypass", "allsigned", "default", "remotesigned", "restricted", + "undefined", "unrestricted", "none". + +- `debug_mode` (int) - If set, sets PowerShell's [PSDebug mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/set-psdebug?view=powershell-7) + in order to make script debugging easier. For instance, setting the + value to 1 results in adding this to the execute command: + + ``` powershell + Set-PSDebug -Trace 1 + ```