From dde74232f251434715cb76664426d9c1e1c91bd8 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Thu, 20 Feb 2020 02:05:27 -0800 Subject: [PATCH] Clearly document all template-engine-enabled options (#8770) --- builder/amazon/common/ami_config.go | 6 +-- builder/cloudstack/config.go | 2 +- builder/hyperone/config.go | 32 ++++++++++----- builder/lxc/config.go | 2 +- builder/lxd/config.go | 3 +- builder/qemu/builder.go | 4 ++ builder/virtualbox/iso/builder.go | 7 ++-- builder/vmware/iso/config.go | 7 +++- common/bootcommand/config.go | 2 +- .../source/docs/builders/cloudstack.html.md | 12 +++--- .../docs/builders/oracle-classic.html.md | 5 ++- .../post-processors/alicloud-import.html.md | 5 ++- .../post-processors/amazon-import.html.md | 4 +- .../docs/post-processors/checksum.html.md | 7 +++- .../docs/post-processors/compress.html.md | 11 ++++- .../digitalocean-import.html.md | 5 ++- .../googlecompute-import.html.md | 4 +- .../docs/post-processors/manifest.html.md | 6 +-- .../docs/post-processors/shell-local.html.md | 6 ++- .../post-processors/ucloud-import.html.md | 5 ++- .../post-processors/vagrant-cloud.html.md | 11 +++-- .../docs/post-processors/vagrant.html.md | 16 +++++--- .../docs/provisioners/ansible.html.md.erb | 10 +++-- .../docs/provisioners/chef-client.html.md.erb | 3 ++ .../docs/provisioners/converge.html.md.erb | 15 ++++--- .../docs/provisioners/powershell.html.md.erb | 41 +++++++++++-------- .../puppet-masterless.html.md.erb | 28 ++++++++++--- .../provisioners/puppet-server.html.md.erb | 25 +++++++++-- .../docs/provisioners/shell.html.md.erb | 6 +-- .../provisioners/windows-shell.html.md.erb | 9 ++-- .../common/_AMIConfig-not-required.html.md | 6 +-- .../cloudstack/_Config-not-required.html.md | 2 +- .../hyperone/_Config-not-required.html.md | 18 ++++++-- .../builder/lxc/_Config-not-required.html.md | 2 +- .../builder/lxd/_Config-not-required.html.md | 3 +- .../builder/qemu/_Config-not-required.html.md | 4 ++ .../iso/_Config-not-required.html.md | 7 ++-- .../vmware/iso/_Config-not-required.html.md | 7 +++- .../common/bootcommand/_BootConfig.html.md | 2 +- 39 files changed, 243 insertions(+), 107 deletions(-) diff --git a/builder/amazon/common/ami_config.go b/builder/amazon/common/ami_config.go index 28ddfdfa5..8a5b83a67 100644 --- a/builder/amazon/common/ami_config.go +++ b/builder/amazon/common/ami_config.go @@ -19,9 +19,9 @@ type AMIConfig struct { // engine](../templates/engine.html) for more info). AMIName string `mapstructure:"ami_name" required:"true"` // The description to set for the resulting - // AMI(s). By default this description is empty. This is a template - // engine, see Build template - // data for more information. + // AMI(s). By default this description is empty. This is a + // [template engine](/docs/templates/engine.html), see [Build template + // data](#build-template-data) for more information. AMIDescription string `mapstructure:"ami_description" required:"false"` // The type of virtualization for the AMI // you are building. This option is required to register HVM images. Can be diff --git a/builder/cloudstack/config.go b/builder/cloudstack/config.go index c3487afba..2640e7a56 100644 --- a/builder/cloudstack/config.go +++ b/builder/cloudstack/config.go @@ -120,7 +120,7 @@ type Config struct { // provisioners should connect to the local IP address of the instance. UseLocalIPAddress bool `mapstructure:"use_local_ip_address" required:"false"` // User data to launch with the instance. This is a - // template engine see User Data bellow for + // template engine; see "User Data" bellow for // more details. Packer will not automatically wait for a user script to // finish before shutting down the instance this must be handled in a // provisioner. diff --git a/builder/hyperone/config.go b/builder/hyperone/config.go index 603651bfc..9c6a4144f 100644 --- a/builder/hyperone/config.go +++ b/builder/hyperone/config.go @@ -91,17 +91,29 @@ type Config struct { // Can be useful when using custom api_url. Defaults to public. PublicNetAdpService string `mapstructure:"public_netadp_service" required:"false"` - ChrootDisk bool `mapstructure:"chroot_disk"` - ChrootDiskSize float32 `mapstructure:"chroot_disk_size"` - ChrootDiskType string `mapstructure:"chroot_disk_type"` - ChrootMountPath string `mapstructure:"chroot_mount_path"` - ChrootMounts [][]string `mapstructure:"chroot_mounts"` - ChrootCopyFiles []string `mapstructure:"chroot_copy_files"` - ChrootCommandWrapper string `mapstructure:"chroot_command_wrapper"` + ChrootDisk bool `mapstructure:"chroot_disk"` + ChrootDiskSize float32 `mapstructure:"chroot_disk_size"` + ChrootDiskType string `mapstructure:"chroot_disk_type"` + ChrootMountPath string `mapstructure:"chroot_mount_path"` + ChrootMounts [][]string `mapstructure:"chroot_mounts"` + ChrootCopyFiles []string `mapstructure:"chroot_copy_files"` + // How to run shell commands. This defaults to {{.Command}}. This may be + // useful to set if you want to set environmental variables or perhaps run + // it with sudo or so on. This is a configuration template where the + // .Command variable is replaced with the command to be run. Defaults to + // {{.Command}}. + ChrootCommandWrapper string `mapstructure:"chroot_command_wrapper"` - MountOptions []string `mapstructure:"mount_options"` - MountPartition string `mapstructure:"mount_partition"` - PreMountCommands []string `mapstructure:"pre_mount_commands"` + MountOptions []string `mapstructure:"mount_options"` + MountPartition string `mapstructure:"mount_partition"` + // A series of commands to execute after attaching the root volume and + // before mounting the chroot. This is not required unless using + // from_scratch. If so, this should include any partitioning and filesystem + // creation commands. The path to the device is provided by {{.Device}}. + PreMountCommands []string `mapstructure:"pre_mount_commands"` + // As pre_mount_commands, but the commands are executed after mounting the + // root device and before the extra mount and copy steps. The device and + // mount path are provided by {{.Device}} and {{.MountPath}}. PostMountCommands []string `mapstructure:"post_mount_commands"` // List of SSH keys by name or id to be added // to the server on launch. diff --git a/builder/lxc/config.go b/builder/lxc/config.go index fbbd0e117..592c2a5e4 100644 --- a/builder/lxc/config.go +++ b/builder/lxc/config.go @@ -28,7 +28,7 @@ type Config struct { ContainerName string `mapstructure:"container_name" required:"false"` // Allows you to specify a wrapper command, such // as ssh so you can execute packer builds on a remote host. Defaults to - // Empty. + // `{{.Command}}`; i.e. no wrapper. CommandWrapper string `mapstructure:"command_wrapper" required:"false"` // The timeout in seconds to wait for the the // container to start. Defaults to 20 seconds. diff --git a/builder/lxd/config.go b/builder/lxd/config.go index 220c47ca0..25d70fa52 100644 --- a/builder/lxd/config.go +++ b/builder/lxd/config.go @@ -20,7 +20,8 @@ type Config struct { OutputImage string `mapstructure:"output_image" required:"false"` ContainerName string `mapstructure:"container_name"` // Lets you prefix all builder commands, such as - // with ssh for a remote build host. Defaults to "". + // with ssh for a remote build host. Defaults to "{{.Command}}"; i.e. no + // wrapper. CommandWrapper string `mapstructure:"command_wrapper" required:"false"` // The source image to use when creating the build // container. This can be a (local or remote) image (name or fingerprint). diff --git a/builder/qemu/builder.go b/builder/qemu/builder.go index 473f356b0..c42d27b70 100644 --- a/builder/qemu/builder.go +++ b/builder/qemu/builder.go @@ -281,6 +281,10 @@ type Config struct { // This will also work with WinRM, just change the port forward in // `qemuargs` to map to WinRM's default port of `5985` or whatever value // you have the service set to listen on. + // + // This is a template engine and allows access to the following variables: + // `{{ .HTTPIP }}`, `{{ .HTTPPort }}`, `{{ .HTTPDir }}`, + // `{{ .OutputDir }}`, `{{ .Name }}`, and `{{ .SSHHostPort }}` QemuArgs [][]string `mapstructure:"qemuargs" required:"false"` // The name of the Qemu binary to look for. This // defaults to qemu-system-x86_64, but may need to be changed for diff --git a/builder/virtualbox/iso/builder.go b/builder/virtualbox/iso/builder.go index f8743ff0b..eaba33bce 100644 --- a/builder/virtualbox/iso/builder.go +++ b/builder/virtualbox/iso/builder.go @@ -57,8 +57,8 @@ type Config struct { // The path on the guest virtual machine where the VirtualBox guest // additions ISO will be uploaded. By default this is // VBoxGuestAdditions.iso which should upload into the login directory of - // the user. This is a configuration template where the Version variable is - // replaced with the VirtualBox version. + // the user. This is a configuration template where the `{{ .Version }}` + // variable is replaced with the VirtualBox version. GuestAdditionsPath string `mapstructure:"guest_additions_path" required:"false"` // The SHA256 checksum of the guest additions ISO that will be uploaded to // the guest VM. By default the checksums will be downloaded from the @@ -69,7 +69,8 @@ type Config struct { // URL if the ISO is at a local path. By default, the VirtualBox builder // will attempt to find the guest additions ISO on the local file system. // If it is not available locally, the builder will download the proper - // guest additions ISO from the internet. + // guest additions ISO from the internet. This is a template engine, and you + // have access to the variable `{{ .Version }}`. GuestAdditionsURL string `mapstructure:"guest_additions_url" required:"false"` // The interface type to use to mount guest additions when // guest_additions_mode is set to attach. Will default to the value set in diff --git a/builder/vmware/iso/config.go b/builder/vmware/iso/config.go index f08a51bc9..596ce26ea 100644 --- a/builder/vmware/iso/config.go +++ b/builder/vmware/iso/config.go @@ -108,8 +108,11 @@ type Config struct { VMXDiskTemplatePath string `mapstructure:"vmx_disk_template_path"` // Path to a [configuration template](/docs/templates/engine.html) that - // defines the contents of the virtual machine VMX file for VMware. This is - // for **advanced users only** as this can render the virtual machine + // defines the contents of the virtual machine VMX file for VMware. The + // engine has access to the template variables `{{ .DiskNumber }}` and + // `{{ .DiskName }}`. + // + // This is for **advanced users only** as this can render the virtual machine // non-functional. See below for more information. For basic VMX // modifications, try `vmx_data` first. VMXTemplatePath string `mapstructure:"vmx_template_path" required:"false"` diff --git a/common/bootcommand/config.go b/common/bootcommand/config.go index 607ee6f9e..aa7d8c74d 100644 --- a/common/bootcommand/config.go +++ b/common/bootcommand/config.go @@ -76,7 +76,7 @@ import ( // `http_directory` configuration parameter. If `http_directory` isn't // specified, these will be blank! // -// - `Name` - The name of the VM. +// - `{{ .Name }}` - The name of the VM. // // Example boot command. This is actually a working boot command used to start an // CentOS 6.4 installer: diff --git a/website/source/docs/builders/cloudstack.html.md b/website/source/docs/builders/cloudstack.html.md index 07e65bec1..7185a7905 100644 --- a/website/source/docs/builders/cloudstack.html.md +++ b/website/source/docs/builders/cloudstack.html.md @@ -111,14 +111,14 @@ builder. - `hypervisor` (string) - The target hypervisor (e.g. `XenServer`, `KVM`) for the new template. This option is required when using `source_iso`. -- `eject_iso` (boolean) - If `true` make a call to the CloudStack API, after - loading image to cache, requesting to check and detach ISO file (if any) - currently attached to a virtual machine. Defaults to `false`. This option +- `eject_iso` (boolean) - If `true` make a call to the CloudStack API, after + loading image to cache, requesting to check and detach ISO file (if any) + currently attached to a virtual machine. Defaults to `false`. This option is only available when using `source_iso`. - `eject_iso_delay` (time.Duration) - Configure the duration time to wait, making - sure virtual machine is able to finish installing OS before it ejects safely. - Requires `eject_iso` set to `true` and this option is only available when + sure virtual machine is able to finish installing OS before it ejects safely. + Requires `eject_iso` set to `true` and this option is only available when using `source_iso`. - `keypair` (string) - The name of the SSH key pair that will be used to @@ -203,7 +203,7 @@ The available variables are: - `HTTPIP` and `HTTPPort` - The IP and port, respectively of an HTTP server that is started serving the directory specified by the `http_directory` configuration parameter. If `http_directory` isn't specified, these will be - blank. + blank. Example: "{{.HTTPIP}}:{{.HTTPPort}}/path/to/a/file/in/http_directory" ## Basic Example diff --git a/website/source/docs/builders/oracle-classic.html.md b/website/source/docs/builders/oracle-classic.html.md index 0d64e584a..6e81c6bb4 100644 --- a/website/source/docs/builders/oracle-classic.html.md +++ b/website/source/docs/builders/oracle-classic.html.md @@ -176,7 +176,10 @@ If this is set, a few more options become available. - `builder_upload_image_command` (string) - The command to run to upload the image to Object Storage Classic. This is for advanced users only, and you should consult the default in code to decide on the changes to make. For - most users the default should suffice. + most users the default should suffice. If you choose to write your own, + this command is a template engine and can make use of the following + variables: `{{ .Username }}`, `{{ .Password }}`, `{{ .AccountID }}`, + `{{ .ImageFile }}`, and `{{ .SegmentPath }}`. ## Basic Example diff --git a/website/source/docs/post-processors/alicloud-import.html.md b/website/source/docs/post-processors/alicloud-import.html.md index fb28f6163..d50e7677b 100644 --- a/website/source/docs/post-processors/alicloud-import.html.md +++ b/website/source/docs/post-processors/alicloud-import.html.md @@ -64,7 +64,10 @@ are two categories: required and optional parameters. disk image after importing it to the cloud. Defaults to false. - `oss_key_name` (string) - The name of the object key in `oss_bucket_name` - where the RAW or VHD file will be copied to for import. + where the RAW or VHD file will be copied to for import. This is treated as + a [template engine](/docs/templates/engine.html), and you may access any of + the variables stored in the generated data using the + [build](/docs/templates/engine.html) template function. - `skip_clean` (boolean) - Whether we should skip removing the RAW or VHD file uploaded to OSS after the import process has completed. `true` means diff --git a/website/source/docs/post-processors/amazon-import.html.md b/website/source/docs/post-processors/amazon-import.html.md index 21f24eeea..39a2c0f5a 100644 --- a/website/source/docs/post-processors/amazon-import.html.md +++ b/website/source/docs/post-processors/amazon-import.html.md @@ -138,7 +138,9 @@ Optional: - `s3_key_name` (string) - The name of the key in `s3_bucket_name` where the OVA file will be copied to for import. If not specified, this will default to "packer-import-{{timestamp}}.ova". This key (i.e., the uploaded OVA) - will be removed after import, unless `skip_clean` is `true`. + will be removed after import, unless `skip_clean` is `true`. This is + treated as a [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. - `skip_clean` (boolean) - Whether we should skip removing the OVA file uploaded to S3 after the import process has completed. "true" means that we diff --git a/website/source/docs/post-processors/checksum.html.md b/website/source/docs/post-processors/checksum.html.md index e95a280d9..672f69424 100644 --- a/website/source/docs/post-processors/checksum.html.md +++ b/website/source/docs/post-processors/checksum.html.md @@ -51,8 +51,11 @@ Optional parameters: - `output` (string) - Specify filename to store checksums. This defaults to `packer_{{.BuildName}}_{{.BuilderType}}_{{.ChecksumType}}.checksum`. For example, if you had a builder named `database`, you might see the file - written as `packer_database_docker_md5.checksum`. The following variables - are available to use in the output template: + written as `packer_database_docker_md5.checksum`. This is treated as a + [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. + The following special variables are also available to use in the output + template: - `BuildName`: The name of the builder that produced the artifact. - `BuilderType`: The type of builder used to produce the artifact. diff --git a/website/source/docs/post-processors/compress.html.md b/website/source/docs/post-processors/compress.html.md index f908612ae..ae97b75cd 100644 --- a/website/source/docs/post-processors/compress.html.md +++ b/website/source/docs/post-processors/compress.html.md @@ -27,8 +27,15 @@ you will need to specify the `output` option. tarball. `.zip` will be a zip file. If the extension can't be detected packer defaults to `.tar.gz` behavior but will not change the filename. - You can use `{{.BuildName}}` and `{{.BuilderType}}` in your output path. If - you are executing multiple builders in parallel you should make sure + This is treated as a + [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. + The following special variables are also available to use in the output + template: + - `{{.BuildName}}` + - `{{.BuilderType}}` + + If you are executing multiple builders in parallel you should make sure `output` is unique for each one. For example `packer_{{.BuildName}}.zip`. - `format` (string) - Disable archive format autodetection and use provided diff --git a/website/source/docs/post-processors/digitalocean-import.html.md b/website/source/docs/post-processors/digitalocean-import.html.md index 48a757a76..732b9b8fb 100644 --- a/website/source/docs/post-processors/digitalocean-import.html.md +++ b/website/source/docs/post-processors/digitalocean-import.html.md @@ -76,7 +76,10 @@ Optional: Defaults to `false`. - `space_object_name` (string) - The name of the key used in the Space where - the image file will be copied to for import. If not specified, this will default to "packer-import-{{timestamp}}". + the image file will be copied to for import. This is treated as a + [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. + If not specified, this will default to "packer-import-{{timestamp}}". - `timeout` (number) - The length of time in minutes to wait for individual steps in the process to successfully complete. This includes both importing diff --git a/website/source/docs/post-processors/googlecompute-import.html.md b/website/source/docs/post-processors/googlecompute-import.html.md index c7ff21f09..67d193759 100644 --- a/website/source/docs/post-processors/googlecompute-import.html.md +++ b/website/source/docs/post-processors/googlecompute-import.html.md @@ -50,7 +50,9 @@ for details. ### Optional - `gcs_object_name` (string) - The name of the GCS object in `bucket` where - the RAW disk image will be copied for import. Defaults to + the RAW disk image will be copied for import. This is treated as a + [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. Defaults to "packer-import-{{timestamp}}.tar.gz". - `image_description` (string) - The description of the resulting image. diff --git a/website/source/docs/post-processors/manifest.html.md b/website/source/docs/post-processors/manifest.html.md index 8be57af1d..d8077d7e1 100644 --- a/website/source/docs/post-processors/manifest.html.md +++ b/website/source/docs/post-processors/manifest.html.md @@ -38,9 +38,9 @@ post-processors such as Docker and Artifice. to `packer-manifest.json`. - `strip_path` (boolean) Write only filename without the path to the manifest file. This defaults to false. -- `custom_data` (map of strings) Arbitrary data to add to the manifest. This - is a [template engine](/docs/templates/engine.html); see - [Build template data](#build-template-data) for more information. +- `custom_data` (map of strings) Arbitrary data to add to the manifest. + This is a [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. - `keep_input_artifact` (boolean) - Unlike most other post-processors, the keep_input_artifact option will have no effect for the manifest post-processor. We will always retain the input artifact for manifest, diff --git a/website/source/docs/post-processors/shell-local.html.md b/website/source/docs/post-processors/shell-local.html.md index 6989c0fd3..cc97b145b 100644 --- a/website/source/docs/post-processors/shell-local.html.md +++ b/website/source/docs/post-processors/shell-local.html.md @@ -81,9 +81,11 @@ Optional parameters: ``` This is treated as a [template engine](/docs/templates/engine.html). - There are two available variables: `Script`, which is the path to the + There are several available variables: `Script`, which is the path to the script to run, and `Vars`, which is the list of `environment_vars`, if - configured. If you choose to set this option, make sure that the first + configured. In addition, you may access any of the variables stored in the + generated data using the [build](/docs/templates/engine.html) template + function. If you choose to set this option, make sure that the first element in the array is the shell program you want to use (for example, "sh" or "/usr/local/bin/zsh" or even "powershell.exe" although anything other than a flavor of the shell command language is not explicitly diff --git a/website/source/docs/post-processors/ucloud-import.html.md b/website/source/docs/post-processors/ucloud-import.html.md index bdf778ce0..4d2987ffd 100644 --- a/website/source/docs/post-processors/ucloud-import.html.md +++ b/website/source/docs/post-processors/ucloud-import.html.md @@ -47,7 +47,10 @@ are two categories: required and optional parameters. - `base_url` - (string) This is the base url. (Default: `https://api.ucloud.cn`). -- `ufile_key_name` (string) - The name of the object key in `ufile_bucket_name` where the RAW, VHD, VMDK, or qcow2 file will be copied to import. +- `ufile_key_name` (string) - The name of the object key in + `ufile_bucket_name` where the RAW, VHD, VMDK, or qcow2 file will be copied + to import. This is a [template engine](/docs/templates/engine.html). + Therefore, you may use user variables and template functions in this field. - `skip_clean` (boolean) - Whether we should skip removing the RAW, VHD, VMDK, or qcow2 file uploaded to UFile after the import process has completed. Possible values are: `true` to leave it in the UFile bucket, `false` to remove it. (Default: `false`). diff --git a/website/source/docs/post-processors/vagrant-cloud.html.md b/website/source/docs/post-processors/vagrant-cloud.html.md index f3ba90b3c..6a47addbf 100644 --- a/website/source/docs/post-processors/vagrant-cloud.html.md +++ b/website/source/docs/post-processors/vagrant-cloud.html.md @@ -68,7 +68,7 @@ on Vagrant Cloud, as well as authentication and version information. can be generated on your [tokens page](https://app.vagrantup.com/settings/security). If not specified, the environment will be searched. First, `VAGRANT_CLOUD_TOKEN` is checked, and - if nothing is found, finally `ATLAS_TOKEN` will be used. This is required + if nothing is found, finally `ATLAS_TOKEN` will be used. This is required unless you are using a private hosting solution (i.e. `vagrant_cloud_url` has been populated). @@ -76,8 +76,8 @@ on Vagrant Cloud, as well as authentication and version information. - `vagrant_cloud_url` (string) - Override the base URL for Vagrant Cloud. This is useful if you're using Vagrant Private Cloud in your own network. - Defaults to `https://vagrantcloud.com/api/v1`. If this value is set to something - other than the default then `access_token` can be left blank and no + Defaults to `https://vagrantcloud.com/api/v1`. If this value is set to something + other than the default then `access_token` can be left blank and no `Authorization` header will be added to requests sent by this post-processor. @@ -102,6 +102,11 @@ on Vagrant Cloud, as well as authentication and version information. - `box_download_url` (string) - Optional URL for a self-hosted box. If this is set the box will not be uploaded to the Vagrant Cloud. + This is a [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. + The following extra variables are also avilable in this engine: + * `Provider`: The Vagrant provider the box is for + * `ArtifactId`: The ID of the input artifact. ## Use with the Vagrant Post-Processor diff --git a/website/source/docs/post-processors/vagrant.html.md b/website/source/docs/post-processors/vagrant.html.md index 862f20017..f1b8b7229 100644 --- a/website/source/docs/post-processors/vagrant.html.md +++ b/website/source/docs/post-processors/vagrant.html.md @@ -78,12 +78,16 @@ more details about certain options in following sections. `"keep_input_artifact":false` - `output` (string) - The full path to the box file that will be created by - this post-processor. This is a [configuration - template](/docs/templates/engine.html). The variable `Provider` is replaced - by the Vagrant provider the box is for. The variable `ArtifactId` is - replaced by the ID of the input artifact. The variable `BuildName` is - replaced with the name of the build. By default, the value of this config - is `packer_{{.BuildName}}_{{.Provider}}.box`. + this post-processor. This is a + [template engine](/docs/templates/engine.html). Therefore, you may use user + variables and template functions in this field. The following extra + variables are also avilable in this engine: + * `Provider`: The Vagrant provider the box is for + * `ArtifactId`: The ID of the input artifact. + * `BuildName`: The name of the build. + + By default, the value of this config is + `packer_{{.BuildName}}_{{.Provider}}.box`. - `vagrantfile_template` (string) - Path to a template to use for the Vagrantfile that is packaged with the box. diff --git a/website/source/docs/provisioners/ansible.html.md.erb b/website/source/docs/provisioners/ansible.html.md.erb index ff2608cca..35a3cfa5b 100644 --- a/website/source/docs/provisioners/ansible.html.md.erb +++ b/website/source/docs/provisioners/ansible.html.md.erb @@ -77,11 +77,13 @@ Optional Parameters: ``` json "ansible_env_vars": [ "ANSIBLE_HOST_KEY_CHECKING=False", "ANSIBLE_SSH_ARGS='-o ForwardAgent=yes -o ControlMaster=auto -o ControlPersist=60s'", "ANSIBLE_NOCOLOR=True" ] ``` + This is a [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. - If you are running a Windows build on AWS, Azure, Google Compute, or OpenStack - and would like to access the auto-generated password that Packer uses to - connect to a Windows instance via WinRM, you can use the template variable - {{.WinRMPassword}} in this option. For example: + For example, if you are running a Windows build on AWS, Azure, + Google Compute, or OpenStack and would like to access the auto-generated + password that Packer uses to connect to a Windows instance via WinRM, you + can use the template variable {{.WinRMPassword}} in this option. Example: ``` json "ansible_env_vars": [ "WINRM_PASSWORD={{.WinRMPassword}}" ], diff --git a/website/source/docs/provisioners/chef-client.html.md.erb b/website/source/docs/provisioners/chef-client.html.md.erb index 264432c8c..b71f31abd 100644 --- a/website/source/docs/provisioners/chef-client.html.md.erb +++ b/website/source/docs/provisioners/chef-client.html.md.erb @@ -50,6 +50,9 @@ configuration is actually required. `accept-silent` and `accept-no-persist`. For details see [Accepting the Chef License](https://docs.chef.io/chef_license_accept.html). + This is a [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. + - `config_template` (string) - Path to a template that will be used for the Chef configuration file. By default Packer only sets configuration it needs to match the settings set in the provisioner configuration. If you need to diff --git a/website/source/docs/provisioners/converge.html.md.erb b/website/source/docs/provisioners/converge.html.md.erb index 6c79e8db0..fd9b47a34 100644 --- a/website/source/docs/provisioners/converge.html.md.erb +++ b/website/source/docs/provisioners/converge.html.md.erb @@ -56,16 +56,21 @@ Optional parameters: - `params` (maps of string to string) - parameters to pass into the root module. -- `execute_command` (string) - the command used to execute Converge. This has - various [configuration template variables](/docs/templates/engine.html) - available. +- `execute_command` (string) - the command used to execute Converge. This is a + [configuration template variables](/docs/templates/engine.html). + See below for detailed usage instructions. - `prevent_sudo` (boolean) - stop Converge from running with administrator privileges via sudo - `bootstrap_command` (string) - the command used to bootstrap Converge. This - has various [configuration template variables](/docs/templates/engine.html) - available. + is a [template engine](/docs/templates/engine.html). Therefore, you may use + user variables and template functions in this field. The following extra + variables are also avilable in this engine: + * `Version`: The version of Converge to use. + * `Sudo`: Boolean; intended to say whether to use sudo or not. + + By default, this is `"curl -s https://get.converge.sh | {{if .Sudo}}sudo {{end}}sh {{if ne .Version \"\"}}-s -- -v {{.Version}}{{end}}"` - `prevent_bootstrap_sudo` (boolean) - stop Converge from bootstrapping with administrator privileges via sudo diff --git a/website/source/docs/provisioners/powershell.html.md.erb b/website/source/docs/provisioners/powershell.html.md.erb index 60a715ca5..e6ae52868 100644 --- a/website/source/docs/provisioners/powershell.html.md.erb +++ b/website/source/docs/provisioners/powershell.html.md.erb @@ -39,17 +39,20 @@ The example below is fully functional. ``` powershell powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" ``` - - The value of this is treated as [configuration - template](/docs/templates/engine.html). There are two available variables: - `Path`, which is the path to the script to run, and `Vars`, which is the - location of a temp file containing the list of `environment_vars`, if - configured. + This is a [template engine](/docs/templates/engine.html). 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. - `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. If you are + environment, as well, which are covered in the section below. + + This is a [template engine](/docs/templates/engine.html). 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 generated password that Packer uses to connect to the instance via WinRM, you can use the template variable `{{.WinRMPassword}}` to set this as an @@ -70,12 +73,14 @@ The example below is fully functional. powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }" ``` - The value of this is treated as [configuration - template](/docs/templates/engine.html). There are two available variables: - `Path`, which is the path to the script to run, and `Vars`, which is the - location of a temp file containing the list of `environment_vars`. The - value of both `Path` and `Vars` can be manually configured by setting the - values for `remote_path` and `remote_env_var_path` respectively. + This is a [template engine](/docs/templates/engine.html). 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. + The value of both `Path` and `Vars` can be manually configured by setting + the values for `remote_path` and `remote_env_var_path` respectively. 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 @@ -84,10 +89,14 @@ The example below is fully functional. - `elevated_user` and `elevated_password` (string) - If specified, the PowerShell script will be run with elevated privileges using the given - Windows user. If you are running a build on AWS, Azure, Google Compute, + Windows user. + + This is a [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. If you are + running a build on AWS, Azure, Google Compute, or OpenStack and would like to run using the generated password that Packer - uses to connect to the instance via WinRM, you may do so by using the template - variable {{.WinRMPassword}}. For example: + uses to connect to the instance via WinRM, you may do so by using the + template variable {{.WinRMPassword}}. For example: ``` json "elevated_user": "Administrator", diff --git a/website/source/docs/provisioners/puppet-masterless.html.md.erb b/website/source/docs/provisioners/puppet-masterless.html.md.erb index bca789e90..feaae00e4 100644 --- a/website/source/docs/provisioners/puppet-masterless.html.md.erb +++ b/website/source/docs/provisioners/puppet-masterless.html.md.erb @@ -54,12 +54,27 @@ Required parameters: Optional parameters: -- `execute_command` (string) - The command-line to execute Puppet. This also - has various [configuration template variables](/docs/templates/engine.html) - available. +- `execute_command` (string) - The command-line to execute Puppet. This is a + [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. In addition, + you may use the following extra variables: + * FacterVars: Additional facts to set when executing Puppet, joined for + use in a command. This is internal and not settable by the user. + * HieraConfigPath: Path to a hiera configuration file to upload and use; + set in the template option hiera_config_path + * ManifestDir: The directory of the manifest file on the remote machine. + * ManifestFile: The manifest file on the remote machine. + * ModulePath: The module_paths, combined into one path variable. + * ModulePathJoiner: A colon `:` on posix systems and a semicolon `;` on + Windows. + * PuppetBinDir: The directory that the Puppet binary is in. + * Sudo: Returns false when PreventSudo is set, and true when it is not. + * WorkingDir: The value provided in the `working_directory` option. + See below for `execute_command`'s default value. + - `extra_arguments` (array of strings) - Additional options to pass to the - Puppet command. This allows for customization of + Puppet command. This allows for customization of `execute_command` without having to completely replace or subsume its contents, making forward-compatible customizations much easier to maintain. @@ -119,7 +134,10 @@ multiple manifests you should use `manifest_file` instead. - `elevated_user` and `elevated_password` (string) - If specified, Puppet will be run with elevated privileges using the given Windows user. See the [powershell](/docs/provisioners/powershell.html) provisioner for the full - details. + details. This is a [template engine](/docs/templates/engine.html). + Therefore, you may use user variables and template functions in this + field, including ```{{ build `Password`}}``` to use the password being used + by the communicator to connect to your instance. <%= partial "partials/provisioners/common-config" %> diff --git a/website/source/docs/provisioners/puppet-server.html.md.erb b/website/source/docs/provisioners/puppet-server.html.md.erb index 6f4789509..778e1ab23 100644 --- a/website/source/docs/provisioners/puppet-server.html.md.erb +++ b/website/source/docs/provisioners/puppet-server.html.md.erb @@ -50,9 +50,23 @@ listed below: that contains the client private key for the node. This defaults to nothing, in which case a client private key won't be uploaded. -- `execute_command` (string) - The command-line to execute Puppet. This also - has various [configuration template variables](/docs/templates/engine.html) - available. +- `execute_command` (string) - The command-line to execute Puppet. This is a + [template engine](/docs/templates/engine.html). Therefore, you + may use user variables and template functions in this field. In addition, + you may use the following extra variables: + * ClientCertPath: The value set in the template option + `client_cert_path`. + * ClientPrivateKeyPath: The value set in the template option + `client_private_key_path`. + * FacterVars: Additional facts to set when executing Puppet, joined for + use in a command. This is internal and not settable by the user. + * PuppetNode: The hostname of the Puppet node, set in `puppet_node`. + * PuppetServer: The hostname of the Puppet server, set in `puppet_server` + * PuppetBinDir: The directory that the Puppet binary is in. + * Sudo: Returns false when PreventSudo is set, and true when it is not. + * WorkingDir: The value provided in the `working_directory` option. + See below for `execute_command`'s default value. + - `extra_arguments` (array of strings) - Additional options to pass to the Puppet command. This allows for customization of `execute_command` without @@ -104,7 +118,10 @@ listed below: - `elevated_user` and `elevated_password` (string) - If specified, Puppet will be run with elevated privileges using the given Windows user. See the [powershell](/docs/provisioners/powershell.html) provisioner for the full - details. + details. This is a [template engine](/docs/templates/engine.html). + Therefore, you may use user variables and template functions in this + field, including ```{{ build `Password`}}``` to use the password being used + by the communicator to connect to your instance. <%= partial "partials/provisioners/common-config" %> diff --git a/website/source/docs/provisioners/shell.html.md.erb b/website/source/docs/provisioners/shell.html.md.erb index 7c17f4437..eb57a927e 100644 --- a/website/source/docs/provisioners/shell.html.md.erb +++ b/website/source/docs/provisioners/shell.html.md.erb @@ -58,9 +58,9 @@ The example below is fully functional. default this is `chmod +x {{ .Path }}; {{ .Vars }} {{ .Path }}`, unless the user has set `"use_env_var_file": true` -- in that case, the default `execute_command` is `chmod +x {{.Path}}; . {{.EnvVarFile}} && {{.Path}}`. - The value of this is treated as a [configuration - template](/docs/templates/engine.html). There are three available - variables: + This is a [template engine](/docs/templates/engine.html). Therefore, you may + use user variables and template functions in this field. In addition, there + are three available extra variables: - `Path` is the path to the script to run - `Vars` is the list of `environment_vars`, if configured. - `EnvVarFile` is the path to the file containing env vars, if diff --git a/website/source/docs/provisioners/windows-shell.html.md.erb b/website/source/docs/provisioners/windows-shell.html.md.erb index 06f7e8e82..bdd4bacda 100644 --- a/website/source/docs/provisioners/windows-shell.html.md.erb +++ b/website/source/docs/provisioners/windows-shell.html.md.erb @@ -36,9 +36,12 @@ The example below is fully functional. - `execute_command` (string) - The command to use to execute the script. By default this is `{{ .Vars }}"{{ .Path }}"`. The value of this is treated as - [template engine](/docs/templates/engine.html). There are two available - variables: `Path`, which is the path to the script to run, and `Vars`, - which is the list of `environment_vars`, if configured. + [template engine](/docs/templates/engine.html). This is a + [template engine](/docs/templates/engine.html). Therefore, you may + use user variables and template functions in this field. In addition, there + are two available extra variables: + - `Path` is the path to the script to run + - `Vars` is the list of `environment_vars`, if configured. - `remote_path` (string) - The path where the script will be uploaded to in the machine. This defaults to "c:/Windows/Temp/script.bat". This value must diff --git a/website/source/partials/builder/amazon/common/_AMIConfig-not-required.html.md b/website/source/partials/builder/amazon/common/_AMIConfig-not-required.html.md index d6b77c62c..6cd6c65ff 100644 --- a/website/source/partials/builder/amazon/common/_AMIConfig-not-required.html.md +++ b/website/source/partials/builder/amazon/common/_AMIConfig-not-required.html.md @@ -1,9 +1,9 @@ - `ami_description` (string) - The description to set for the resulting - AMI(s). By default this description is empty. This is a template - engine, see Build template - data for more information. + AMI(s). By default this description is empty. This is a + [template engine](/docs/templates/engine.html), see [Build template + data](#build-template-data) for more information. - `ami_virtualization_type` (string) - The type of virtualization for the AMI you are building. This option is required to register HVM images. Can be diff --git a/website/source/partials/builder/cloudstack/_Config-not-required.html.md b/website/source/partials/builder/cloudstack/_Config-not-required.html.md index bcb74665e..c652ab09f 100644 --- a/website/source/partials/builder/cloudstack/_Config-not-required.html.md +++ b/website/source/partials/builder/cloudstack/_Config-not-required.html.md @@ -72,7 +72,7 @@ provisioners should connect to the local IP address of the instance. - `user_data` (string) - User data to launch with the instance. This is a - template engine see User Data bellow for + template engine; see "User Data" bellow for more details. Packer will not automatically wait for a user script to finish before shutting down the instance this must be handled in a provisioner. diff --git a/website/source/partials/builder/hyperone/_Config-not-required.html.md b/website/source/partials/builder/hyperone/_Config-not-required.html.md index 7e2eb5245..89bb59ca7 100644 --- a/website/source/partials/builder/hyperone/_Config-not-required.html.md +++ b/website/source/partials/builder/hyperone/_Config-not-required.html.md @@ -47,11 +47,23 @@ - `chroot_mount_path` (string) - Chroot Mount Path - `chroot_mounts` ([][]string) - Chroot Mounts - `chroot_copy_files` ([]string) - Chroot Copy Files -- `chroot_command_wrapper` (string) - Chroot Command Wrapper +- `chroot_command_wrapper` (string) - How to run shell commands. This defaults to {{.Command}}. This may be + useful to set if you want to set environmental variables or perhaps run + it with sudo or so on. This is a configuration template where the + .Command variable is replaced with the command to be run. Defaults to + {{.Command}}. + - `mount_options` ([]string) - Mount Options - `mount_partition` (string) - Mount Partition -- `pre_mount_commands` ([]string) - Pre Mount Commands -- `post_mount_commands` ([]string) - Post Mount Commands +- `pre_mount_commands` ([]string) - A series of commands to execute after attaching the root volume and + before mounting the chroot. This is not required unless using + from_scratch. If so, this should include any partitioning and filesystem + creation commands. The path to the device is provided by {{.Device}}. + +- `post_mount_commands` ([]string) - As pre_mount_commands, but the commands are executed after mounting the + root device and before the extra mount and copy steps. The device and + mount path are provided by {{.Device}} and {{.MountPath}}. + - `ssh_keys` ([]string) - List of SSH keys by name or id to be added to the server on launch. diff --git a/website/source/partials/builder/lxc/_Config-not-required.html.md b/website/source/partials/builder/lxc/_Config-not-required.html.md index e81ce2657..e972a039d 100644 --- a/website/source/partials/builder/lxc/_Config-not-required.html.md +++ b/website/source/partials/builder/lxc/_Config-not-required.html.md @@ -9,7 +9,7 @@ - `command_wrapper` (string) - Allows you to specify a wrapper command, such as ssh so you can execute packer builds on a remote host. Defaults to - Empty. + `{{.Command}}`; i.e. no wrapper. - `init_timeout` (duration string | ex: "1h5m2s") - The timeout in seconds to wait for the the container to start. Defaults to 20 seconds. diff --git a/website/source/partials/builder/lxd/_Config-not-required.html.md b/website/source/partials/builder/lxd/_Config-not-required.html.md index d0e837e73..072ff2848 100644 --- a/website/source/partials/builder/lxd/_Config-not-required.html.md +++ b/website/source/partials/builder/lxd/_Config-not-required.html.md @@ -5,7 +5,8 @@ - `container_name` (string) - Container Name - `command_wrapper` (string) - Lets you prefix all builder commands, such as - with ssh for a remote build host. Defaults to "". + with ssh for a remote build host. Defaults to "{{.Command}}"; i.e. no + wrapper. - `profile` (string) - Profile - `init_sleep` (string) - The number of seconds to sleep between launching diff --git a/website/source/partials/builder/qemu/_Config-not-required.html.md b/website/source/partials/builder/qemu/_Config-not-required.html.md index 7c4b56b02..7836b7e4a 100644 --- a/website/source/partials/builder/qemu/_Config-not-required.html.md +++ b/website/source/partials/builder/qemu/_Config-not-required.html.md @@ -179,6 +179,10 @@ `qemuargs` to map to WinRM's default port of `5985` or whatever value you have the service set to listen on. + This is a template engine and allows access to the following variables: + `{{ .HTTPIP }}`, `{{ .HTTPPort }}`, `{{ .HTTPDir }}`, + `{{ .OutputDir }}`, `{{ .Name }}`, and `{{ .SSHHostPort }}` + - `qemu_binary` (string) - The name of the Qemu binary to look for. This defaults to qemu-system-x86_64, but may need to be changed for some platforms. For example qemu-kvm, or qemu-system-i386 may be a diff --git a/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md b/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md index c636ed567..510376ec3 100644 --- a/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md +++ b/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md @@ -14,8 +14,8 @@ - `guest_additions_path` (string) - The path on the guest virtual machine where the VirtualBox guest additions ISO will be uploaded. By default this is VBoxGuestAdditions.iso which should upload into the login directory of - the user. This is a configuration template where the Version variable is - replaced with the VirtualBox version. + the user. This is a configuration template where the `{{ .Version }}` + variable is replaced with the VirtualBox version. - `guest_additions_sha256` (string) - The SHA256 checksum of the guest additions ISO that will be uploaded to the guest VM. By default the checksums will be downloaded from the @@ -26,7 +26,8 @@ URL if the ISO is at a local path. By default, the VirtualBox builder will attempt to find the guest additions ISO on the local file system. If it is not available locally, the builder will download the proper - guest additions ISO from the internet. + guest additions ISO from the internet. This is a template engine, and you + have access to the variable `{{ .Version }}`. - `guest_additions_interface` (string) - The interface type to use to mount guest additions when guest_additions_mode is set to attach. Will default to the value set in diff --git a/website/source/partials/builder/vmware/iso/_Config-not-required.html.md b/website/source/partials/builder/vmware/iso/_Config-not-required.html.md index f223b9e2c..772dfd424 100644 --- a/website/source/partials/builder/vmware/iso/_Config-not-required.html.md +++ b/website/source/partials/builder/vmware/iso/_Config-not-required.html.md @@ -74,8 +74,11 @@ - `vmx_disk_template_path` (string) - VMX Disk Template Path - `vmx_template_path` (string) - Path to a [configuration template](/docs/templates/engine.html) that - defines the contents of the virtual machine VMX file for VMware. This is - for **advanced users only** as this can render the virtual machine + defines the contents of the virtual machine VMX file for VMware. The + engine has access to the template variables `{{ .DiskNumber }}` and + `{{ .DiskName }}`. + + This is for **advanced users only** as this can render the virtual machine non-functional. See below for more information. For basic VMX modifications, try `vmx_data` first. \ No newline at end of file diff --git a/website/source/partials/common/bootcommand/_BootConfig.html.md b/website/source/partials/common/bootcommand/_BootConfig.html.md index fec7504e9..d578ab5f2 100644 --- a/website/source/partials/common/bootcommand/_BootConfig.html.md +++ b/website/source/partials/common/bootcommand/_BootConfig.html.md @@ -65,7 +65,7 @@ command, they will be replaced by the proper key: `http_directory` configuration parameter. If `http_directory` isn't specified, these will be blank! -- `Name` - The name of the VM. +- `{{ .Name }}` - The name of the VM. Example boot command. This is actually a working boot command used to start an CentOS 6.4 installer: