diff --git a/website/source/docs/basics/terminology.html.markdown b/website/source/docs/basics/terminology.html.markdown index e56f48c03..21e3d236b 100644 --- a/website/source/docs/basics/terminology.html.markdown +++ b/website/source/docs/basics/terminology.html.markdown @@ -33,7 +33,7 @@ Packer in the form of plugins. **Commands** are sub-commands for the `packer` program that perform some -job. An example some command is "build", which is invoked as `packer build`. +job. An example command is "build", which is invoked as `packer build`. Packer ships with a set of commands out of the box in order to define its [command-line interface](#). Commands can also be created and added to Packer in the form of plugins. diff --git a/website/source/docs/builders/amazon-chroot.html.markdown b/website/source/docs/builders/amazon-chroot.html.markdown index a2bd21aaf..088304185 100644 --- a/website/source/docs/builders/amazon-chroot.html.markdown +++ b/website/source/docs/builders/amazon-chroot.html.markdown @@ -51,11 +51,11 @@ There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. -Required: +### Required: * `access_key` (string) - The access key used to communicate with AWS. - If not specified, Packer will attempt to read this from environmental - variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order). + If not specified, Packer will use the environment variables + `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. If the environmental variables aren't set and Packer is running on an EC2 instance, Packer will check the instance metadata for IAM role keys. @@ -66,8 +66,8 @@ Required: [configuration templates](/docs/templates/configuration-templates.html) for more info) * `secret_key` (string) - The secret key used to communicate with AWS. - If not specified, Packer will attempt to read this from environmental - variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order). + If not specified, Packer will use the environment variables + `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. If the environmental variables aren't set and Packer is running on an EC2 instance, Packer will check the instance metadata for IAM role keys. @@ -76,37 +76,43 @@ Required: and provisioned on the currently running instance. This must be an EBS-backed AMI with a root volume snapshot that you have access to. -Optional: +### Optional: + +* `ami_description` (string) - The description to set for the resulting + AMI(s). By default this description is empty. + +* `ami_groups` (array of strings) - A list of groups that have access + to launch the resulting AMI(s). By default no groups have permission + to launch the AMI. `all` will make the AMI publicly accessible. + +* `ami_product_codes` (array of strings) - A list of product codes to + associate with the AMI. By default no product codes are associated with + the AMI. + +* `ami_regions` (array of strings) - A list of regions to copy the AMI to. + Tags and attributes are copied along with the AMI. AMI copying takes time + depending on the size of the AMI, but will generally take many minutes. + +* `ami_users` (array of strings) - A list of account IDs that have access + to launch the resulting AMI(s). By default no additional users other than the user + creating the AMI has permissions to launch it. * `ami_virtualization_type` (string) - The type of virtualization for the AMI you are building. This option is required to register HVM images. Can be "paravirtual" (default) or "hvm". -* `ami_description` (string) - The description to set for the resulting - AMI(s). By default this description is empty. - -* `ami_groups` (array of string) - A list of groups that have access - to launch the resulting AMI(s). By default no groups have permission - to launch the AMI. `all` will make the AMI publicly accessible. - -* `ami_product_codes` (array of string) - A list of product codes to - associate with the AMI. By default no product codes are associated with - the AMI. - -* `ami_regions` (array of string) - A list of regions to copy the AMI to. - Tags and attributes are copied along with the AMI. AMI copying takes time - depending on the size of the AMI, but will generally take many minutes. - -* `ami_users` (array of string) - A list of account IDs that have access - to launch the resulting AMI(s). By default no additional users other than the user - creating the AMI has permissions to launch it. - -* `chroot_mounts` (list of list of strings) - This is a list of additional +* `chroot_mounts` (array of array of strings) - This is a list of additional devices to mount into the chroot environment. This configuration parameter requires some additional documentation which is in the "Chroot Mounts" section below. Please read that section for more information on how to use this. -* `copy_files` (list of strings) - Paths to files on the running EC2 instance +* `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. + +* `copy_files` (array of strings) - Paths to files on the running EC2 instance that will be copied into the chroot environment prior to provisioning. This is useful, for example, to copy `/etc/resolv.conf` so that DNS lookups work. @@ -115,12 +121,6 @@ Optional: of the source AMI will be attached. This defaults to "" (empty string), which forces Packer to find an open device automatically. -* `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. - * `mount_path` (string) - The path where the volume will be mounted. This is where the chroot environment will be. This defaults to `packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration diff --git a/website/source/docs/builders/amazon-ebs.html.markdown b/website/source/docs/builders/amazon-ebs.html.markdown index b3fd89e78..885095ada 100644 --- a/website/source/docs/builders/amazon-ebs.html.markdown +++ b/website/source/docs/builders/amazon-ebs.html.markdown @@ -29,11 +29,11 @@ There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. -Required: +### Required: * `access_key` (string) - The access key used to communicate with AWS. - If not specified, Packer will attempt to read this from environmental - variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order). + If not specified, Packer will use the environment variables + `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. * `ami_name` (string) - The name of the resulting AMI that will appear when managing AMIs in the AWS console or via APIs. This must be unique. @@ -47,8 +47,8 @@ Required: to launch the EC2 instance to create the AMI. * `secret_key` (string) - The secret key used to communicate with AWS. - If not specified, Packer will attempt to read this from environmental - variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order). + If not specified, Packer will use the environment variables + `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. * `source_ami` (string) - The initial AMI used as a base for the newly created machine. @@ -56,36 +56,43 @@ Required: * `ssh_username` (string) - The username to use in order to communicate over SSH to the running machine. -Optional: +### Optional: * `ami_block_device_mappings` (array of block device mappings) - Add the block device mappings to the AMI. The block device mappings allow for keys: "device\_name" (string), "virtual\_name" (string), "snapshot\_id" (string), - "volume\_type" (string), "volume\_size" (int), "delete\_on\_termination" - (bool), "no\_device" (bool), and "iops" (int). + "volume\_type" (string), "volume\_size" (integer), "delete\_on\_termination" + (boolean), "no\_device" (boolean), and "iops" (integer). + +* `ami_description` (string) - The description to set for the resulting + AMI(s). By default this description is empty. + +* `ami_groups` (array of strings) - A list of groups that have access + to launch the resulting AMI(s). By default no groups have permission + to launch the AMI. `all` will make the AMI publicly accessible. + +* `ami_product_codes` (array of strings) - A list of product codes to + associate with the AMI. By default no product codes are associated with + the AMI. + +* `ami_regions` (array of strings) - A list of regions to copy the AMI to. + Tags and attributes are copied along with the AMI. AMI copying takes time + depending on the size of the AMI, but will generally take many minutes. + +* `ami_users` (array of strings) - A list of account IDs that have access + to launch the resulting AMI(s). By default no additional users other than the user + creating the AMI has permissions to launch it. * `ami_virtualization_type` (string) - The type of virtualization for the AMI you are building. This option is required to register HVM images. Can be "paravirtual" (default) or "hvm". -* `ami_description` (string) - The description to set for the resulting - AMI(s). By default this description is empty. +* `associate_public_ip_address` (boolean) - If using a non-default VPC, public + IP addresses are not provided by default. If this is toggled, your new + instance will get a Public IP. -* `ami_groups` (array of string) - A list of groups that have access - to launch the resulting AMI(s). By default no groups have permission - to launch the AMI. `all` will make the AMI publicly accessible. - -* `ami_product_codes` (array of string) - A list of product codes to - associate with the AMI. By default no product codes are associated with - the AMI. - -* `ami_regions` (array of string) - A list of regions to copy the AMI to. - Tags and attributes are copied along with the AMI. AMI copying takes time - depending on the size of the AMI, but will generally take many minutes. - -* `ami_users` (array of string) - A list of account IDs that have access - to launch the resulting AMI(s). By default no additional users other than the user - creating the AMI has permissions to launch it. +* `availability_zone` (string) - Destination availability zone to launch instance in. + Leave this empty to allow Amazon to auto-assign. * `iam_instance_profile` (string) - The name of an [IAM instance profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) @@ -105,15 +112,15 @@ Optional: access. Note that if this is specified, you must be sure the security group allows access to the `ssh_port` given below. -* `security_group_ids` (array of string) - A list of security groups as +* `security_group_ids` (array of strings) - A list of security groups as described above. Note that if this is specified, you must omit the security_group_id. -* `ssh_port` (int) - The port that SSH will be available on. This defaults +* `ssh_port` (integer) - The port that SSH will be available on. This defaults to port 22. -* `ssh_private_key_file` - Use this ssh private key file instead of a generated - ssh key pair for connecting to the instance. +* `ssh_private_key_file` (string) - Use this ssh private key file instead of + a generated ssh key pair for connecting to the instance. * `ssh_timeout` (string) - The time to wait for SSH to become available before timing out. The format of this value is a duration such as "5s" @@ -122,10 +129,6 @@ Optional: * `subnet_id` (string) - If using VPC, the ID of the subnet, such as "subnet-12345def", where Packer will launch the EC2 instance. -* `associate_public_ip_address` (bool) - If using a non-default VPC, public - IP addresses are not provided by default. If this is toggled, your new - instance will get a Public IP. - * `tags` (object of key/value strings) - Tags applied to the AMI. * `temporary_key_pair_name` (string) - The name of the temporary keypair @@ -142,9 +145,6 @@ Optional: * `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID in order to create a temporary security group within the VPC. -* `availability_zone` (string) - Destination availability zone to launch instance in. - Leave this empty to allow Amazon to auto-assign. - ## Basic Example Here is a basic example. It is completely valid except for the access keys: diff --git a/website/source/docs/builders/amazon-instance.html.markdown b/website/source/docs/builders/amazon-instance.html.markdown index 71490aa35..5b11bb12f 100644 --- a/website/source/docs/builders/amazon-instance.html.markdown +++ b/website/source/docs/builders/amazon-instance.html.markdown @@ -36,11 +36,11 @@ There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. -Required: +### Required: * `access_key` (string) - The access key used to communicate with AWS. - If not specified, Packer will attempt to read this from environmental - variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order). + If not specified, Packer will use the environment variables + `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. * `account_id` (string) - Your AWS account ID. This is required for bundling the AMI. This is _not the same_ as the access key. You can find your @@ -61,8 +61,8 @@ Required: This bucket will be created if it doesn't exist. * `secret_key` (string) - The secret key used to communicate with AWS. - If not specified, Packer will attempt to read this from environmental - variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order). + If not specified, Packer will use the environment variables + `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. * `source_ami` (string) - The initial AMI used as a base for the newly created machine. @@ -78,37 +78,44 @@ Required: * `x509_key_path` (string) - The local path to the private key for the X509 certificate specified by `x509_cert_path`. This is used for bundling the AMI. -Optional: +### Optional: * `ami_block_device_mappings` (array of block device mappings) - Add the block device mappings to the AMI. The block device mappings allow for keys: "device\_name" (string), "virtual\_name" (string), "snapshot\_id" (string), - "volume\_type" (string), "volume\_size" (int), "delete\_on\_termination" - (bool), "no\_device" (bool), and "iops" (int). + "volume\_type" (string), "volume\_size" (integer), "delete\_on\_termination" + (boolean), "no\_device" (boolean), and "iops" (integer). See [amazon-ebs](/docs/builders/amazon-ebs.html) for an example template. +* `ami_description` (string) - The description to set for the resulting + AMI(s). By default this description is empty. + +* `ami_groups` (array of strings) - A list of groups that have access + to launch the resulting AMI(s). By default no groups have permission + to launch the AMI. `all` will make the AMI publicly accessible. + +* `ami_product_codes` (array of strings) - A list of product codes to + associate with the AMI. By default no product codes are associated with + the AMI. + +* `ami_regions` (array of strings) - A list of regions to copy the AMI to. + Tags and attributes are copied along with the AMI. AMI copying takes time + depending on the size of the AMI, but will generally take many minutes. + +* `ami_users` (array of strings) - A list of account IDs that have access + to launch the resulting AMI(s). By default no additional users other than the user + creating the AMI has permissions to launch it. + * `ami_virtualization_type` (string) - The type of virtualization for the AMI you are building. This option is required to register HVM images. Can be "paravirtual" (default) or "hvm". -* `ami_description` (string) - The description to set for the resulting - AMI(s). By default this description is empty. +* `associate_public_ip_address` (boolean) - If using a non-default VPC, public + IP addresses are not provided by default. If this is toggled, your new + instance will get a Public IP. -* `ami_groups` (array of string) - A list of groups that have access - to launch the resulting AMI(s). By default no groups have permission - to launch the AMI. `all` will make the AMI publicly accessible. - -* `ami_product_codes` (array of string) - A list of product codes to - associate with the AMI. By default no product codes are associated with - the AMI. - -* `ami_regions` (array of string) - A list of regions to copy the AMI to. - Tags and attributes are copied along with the AMI. AMI copying takes time - depending on the size of the AMI, but will generally take many minutes. - -* `ami_users` (array of string) - A list of account IDs that have access - to launch the resulting AMI(s). By default no additional users other than the user - creating the AMI has permissions to launch it. +* `availability_zone` (string) - Destination availability zone to launch instance in. + Leave this empty to allow Amazon to auto-assign. * `bundle_destination` (string) - The directory on the running instance where the bundled AMI will be saved prior to uploading. By default this is @@ -144,15 +151,15 @@ Optional: access. Note that if this is specified, you must be sure the security group allows access to the `ssh_port` given below. -* `security_group_ids` (array of string) - A list of security groups as +* `security_group_ids` (array of strings) - A list of security groups as described above. Note that if this is specified, you must omit the security_group_id. -* `ssh_port` (int) - The port that SSH will be available on. This defaults +* `ssh_port` (integer) - The port that SSH will be available on. This defaults to port 22. -* `ssh_private_key_file` - Use this ssh private key file instead of a generated - ssh key pair for connecting to the instance. +* `ssh_private_key_file` (string) - Use this ssh private key file instead of + a generated ssh key pair for connecting to the instance. * `ssh_timeout` (string) - The time to wait for SSH to become available before timing out. The format of this value is a duration such as "5s" @@ -161,10 +168,6 @@ Optional: * `subnet_id` (string) - If using VPC, the ID of the subnet, such as "subnet-12345def", where Packer will launch the EC2 instance. -* `associate_public_ip_address` (bool) - If using a non-default VPC, public - IP addresses are not provided by default. If this is toggled, your new - instance will get a Public IP. - * `tags` (object of key/value strings) - Tags applied to the AMI. * `temporary_key_pair_name` (string) - The name of the temporary keypair diff --git a/website/source/docs/builders/digitalocean.html.markdown b/website/source/docs/builders/digitalocean.html.markdown index a493de93b..5c00ad6e7 100644 --- a/website/source/docs/builders/digitalocean.html.markdown +++ b/website/source/docs/builders/digitalocean.html.markdown @@ -21,35 +21,43 @@ There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. -Required: +### Required: * `api_key` (string) - The API key to use to access your account. You can retrieve this on the "API" page visible after logging into your account - on DigitalOcean. Alternatively, the builder looks for the environment - variable `DIGITALOCEAN_API_KEY`. + on DigitalOcean. + If not specified, Packer will use the environment variable + `DIGITALOCEAN_API_KEY`, if set. * `client_id` (string) - The client ID to use to access your account. You can find this on the "API" page visible after logging into your account on - DigitalOcean. Alternatively, the builder looks for the environment - variable `DIGITALOCEAN_CLIENT_ID`. + DigitalOcean. + If not specified, Packer will use the environment variable + `DIGITALOCEAN_CLIENT_ID`, if set. -Optional: +### Optional: + +* `droplet_name` (string) - The name assigned to the droplet. DigitalOcean + sets the hostname of the machine to this value. * `image` (string) - The name (or slug) of the base image to use. This is the image that will be used to launch a new droplet and provision it. This defaults to 'ubuntu-12-04-x64' which is the slug for "Ubuntu 12.04.4 x64". See https://developers.digitalocean.com/images/ for the accepted image names/slugs. -* `image_id` (int) - The ID of the base image to use. This is the image that +* `image_id` (integer) - The ID of the base image to use. This is the image that will be used to launch a new droplet and provision it. This setting is deprecated. Use `image` instead. +* `private_networking` (boolean) - Set to `true` to enable private networking + for the droplet being created. This defaults to `false`, or not enabled. + * `region` (string) - The name (or slug) of the region to launch the droplet in. Consequently, this is the region where the snapshot will be available. This defaults to "nyc1", which is the slug for "New York 1". See https://developers.digitalocean.com/regions/ for the accepted region names/slugs. -* `region_id` (int) - The ID of the region to launch the droplet in. Consequently, +* `region_id` (integer) - The ID of the region to launch the droplet in. Consequently, this is the region where the snapshot will be available. This setting is deprecated. Use `region` instead. @@ -57,21 +65,15 @@ Optional: This defaults to "512mb", which is the slug for "512MB". See https://developers.digitalocean.com/sizes/ for the accepted size names/slugs. -* `size_id` (int) - The ID of the droplet size to use. +* `size_id` (integer) - The ID of the droplet size to use. This setting is deprecated. Use `size` instead. -* `private_networking` (bool) - Set to `true` to enable private networking - for the droplet being created. This defaults to `false`, or not enabled. - * `snapshot_name` (string) - The name of the resulting snapshot that will appear in your account. This must be unique. To help make this unique, use a function like `timestamp` (see [configuration templates](/docs/templates/configuration-templates.html) for more info) -* `droplet_name` (string) - The name assigned to the droplet. DigitalOcean - sets the hostname of the machine to this value. - -* `ssh_port` (int) - The port that SSH will be available on. Defaults to port +* `ssh_port` (integer) - The port that SSH will be available on. Defaults to port 22. * `ssh_timeout` (string) - The time to wait for SSH to become available @@ -82,8 +84,8 @@ Optional: over SSH to the running droplet. Default is "root". * `state_timeout` (string) - The time to wait, as a duration string, -for a droplet to enter a desired state (such as "active") before -timing out. The default state timeout is "6m". + for a droplet to enter a desired state (such as "active") before + timing out. The default state timeout is "6m". ## Basic Example diff --git a/website/source/docs/builders/docker.html.markdown b/website/source/docs/builders/docker.html.markdown index 315d5ff63..6b9ee8cd0 100644 --- a/website/source/docs/builders/docker.html.markdown +++ b/website/source/docs/builders/docker.html.markdown @@ -44,7 +44,7 @@ Configuration options are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `export_path` (string) - The path where the final container will be exported as a tar file. @@ -53,9 +53,9 @@ Required: be started. This image will be pulled from the Docker registry if it doesn't already exist. -Optional: +### Optional: -* `pull` (bool) - If true, the configured image will be pulled using +* `pull` (boolean) - If true, the configured image will be pulled using `docker pull` prior to use. Otherwise, it is assumed the image already exists and can be used. This defaults to true if not set. diff --git a/website/source/docs/builders/googlecompute.markdown b/website/source/docs/builders/googlecompute.markdown index bab2ffce3..9c29046dd 100644 --- a/website/source/docs/builders/googlecompute.markdown +++ b/website/source/docs/builders/googlecompute.markdown @@ -69,7 +69,7 @@ files obtained in the previous section. Configuration options are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `bucket_name` (string) - The Google Cloud Storage bucket to store the images that are created. The bucket must already exist in your project. @@ -89,7 +89,7 @@ Required: * `zone` (string) - The zone in which to launch the instance used to create the image. Example: "us-central1-a" -Optional: +### Optional: * `image_name` (string) - The unique name of the resulting image. Defaults to `packer-{{timestamp}}`. @@ -99,6 +99,11 @@ Optional: * `instance_name` (string) - A name to give the launched instance. Beware that this must be unique. Defaults to "packer-{{uuid}}". +* `metadata` (object of key/value strings) + + * `machine_type` (string) - The machine type. Defaults to `n1-standard-1`. * `network` (string) - The Google Compute network to use for the launched @@ -107,7 +112,7 @@ Optional: * `passphrase` (string) - The passphrase to use if the `private_key_file` is encrypted. -* `ssh_port` (int) - The SSH port. Defaults to 22. +* `ssh_port` (integer) - The SSH port. Defaults to 22. * `ssh_timeout` (string) - The time to wait for SSH to become available. Defaults to "1m". @@ -117,6 +122,11 @@ Optional: * `state_timeout` (string) - The time to wait for instance state changes. Defaults to "5m". +* `tags` (array of strings) + + ## Gotchas Centos images have root ssh access disabled by default. Set `ssh_username` to any user, which will be created by packer with sudo access. diff --git a/website/source/docs/builders/null.html.markdown b/website/source/docs/builders/null.html.markdown index c1c6c1ebc..732026d03 100644 --- a/website/source/docs/builders/null.html.markdown +++ b/website/source/docs/builders/null.html.markdown @@ -30,7 +30,7 @@ Configuration options are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `host` (string) - The hostname or IP address to connect to. @@ -42,7 +42,7 @@ Required: * `ssh_username` (string) - The username to be used for the ssh connection. -Optional: +### Optional: -* `port` (int) - port to connect to, defaults to 22. +* `port` (integer) - ssh port to connect to, defaults to 22. diff --git a/website/source/docs/builders/openstack.html.markdown b/website/source/docs/builders/openstack.html.markdown index c6916232c..d4ca59a81 100644 --- a/website/source/docs/builders/openstack.html.markdown +++ b/website/source/docs/builders/openstack.html.markdown @@ -24,7 +24,7 @@ There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. -Required: +### Required: * `flavor` (string) - The ID or full URL for the desired flavor for the server to be created. @@ -32,31 +32,32 @@ Required: * `image_name` (string) - The name of the resulting image. * `password` (string) - The password used to connect to the OpenStack service. - If not specified, Packer will attempt to read this from the - `SDK_PASSWORD` or `OS_PASSWORD` environment variable. + If not specified, Packer will use the environment variables + `SDK_PASSWORD` or `OS_PASSWORD` (in that order), if set. * `provider` (string) - The provider used to connect to the OpenStack service. - If not specified, Packer will attempt to read this from the - `SDK_PROVIDER` environment variable. For Rackspace this should be `rackspace-us` - or `rackspace-uk`. + If not specified, Packer will use the environment variable + `SDK_PROVIDER`, if set. + For Rackspace this should be `rackspace-us` or `rackspace-uk`. * `region` (string) - The name of the region, such as "DFW", in which - to launch the server to create the AMI. If not specified, Packer will - attempt to read this from the `SDK_REGION` or `OS_REGION_NAME` environmental - variables. + to launch the server to create the AMI. + If not specified, Packer will use the environment variables + `SDK_REGION` or `OS_REGION_NAME` (in that order), if set. * `source_image` (string) - The ID or full URL to the base image to use. This is the image that will be used to launch a new server and provision it. * `username` (string) - The username used to connect to the OpenStack service. - If not specified, Packer will attempt to read this from the - `SDK_USERNAME` or `OS_USERNAME` environment variable. + If not specified, Packer will use the environment variables + `SDK_USERNAME` or `OS_USERNAME` (in that order), if set. -Optional: +### Optional: * `api_key` (string) - The API key used to access OpenStack. Some OpenStack - installations require this. If not specified, Packer will attempt to - read this from the `SDK_API_KEY` environmental variable. + installations require this. + If not specified, Packer will use the environment variables + `SDK_API_KEY`, if set. * `floating_ip` (string) - A specific floating IP to assign to this instance. `use_floating_ip` must also be set to true for this to have an affect. @@ -65,20 +66,31 @@ Optional: to allocate a floating IP. `use_floating_ip` must also be set to true for this to have an affect. +* `openstack_provider` (string) + + * `project` (string) - The project name to boot the instance into. Some - OpenStack installations require this. If not specified, Packer will attempt - to read this from the `SDK_PROJECT` or `OS_TENANT_NAME` environmental - variables. + OpenStack installations require this. + If not specified, Packer will use the environment variables + `SDK_PROJECT` or `OS_TENANT_NAME` (in that order), if set. * `provider` (string) - A name of a provider that has a slightly different API model. Currently supported values are "openstack" (default), - and "rackspace". If not specified, Packer will attempt to read this from - the `SDK_PROVIDER` or `OS_AUTH_URL` environmental variables. + and "rackspace". + If not specified, Packer will use the environment variables + `SDK_PROVIDER` or `OS_AUTH_URL` (in that order), if set. + +* `proxy_url` (string) + * `security_groups` (array of strings) - A list of security groups by name to add to this instance. -* `ssh_port` (int) - The port that SSH will be available on. Defaults to port +* `ssh_port` (integer) - The port that SSH will be available on. Defaults to port 22. * `ssh_timeout` (string) - The time to wait for SSH to become available @@ -91,8 +103,8 @@ Optional: * `tenant_id` (string) - Tenant ID for accessing OpenStack if your installation requires this. -* `use_floating_ip` (bool) - Whether or not to use a floating IP for - the instance. +* `use_floating_ip` (boolean) - Whether or not to use a floating IP for + the instance. Defaults to false. ## Basic Example diff --git a/website/source/docs/builders/parallels-iso.html.markdown b/website/source/docs/builders/parallels-iso.html.markdown index e27152731..425f337ce 100644 --- a/website/source/docs/builders/parallels-iso.html.markdown +++ b/website/source/docs/builders/parallels-iso.html.markdown @@ -47,7 +47,7 @@ There are many configuration options available for the Parallels builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO files are so large, this is required and Packer will verify it prior @@ -68,7 +68,7 @@ Required: * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: +### Optional: * `boot_command` (array of strings) - This is an array of commands to type when the virtual machine is first booted. The goal of these commands should @@ -83,22 +83,18 @@ Optional: five seconds and one minute 30 seconds, respectively. If this isn't specified, the default is 10 seconds. -* `disk_size` (int) - The size, in megabytes, of the hard disk to create +* `disk_size` (integer) - The size, in megabytes, of the hard disk to create for the VM. By default, this is 40000 (about 40 GB). -* `floppy_files` (array of strings) - A list of files to put onto a floppy - disk that is attached when the VM is booted for the first time. This is - most useful for unattended Windows installs, which look for an - `Autounattend.xml` file on removable media. By default no floppy will - be attached. The files listed in this configuration will all be put - into the root directory of the floppy disk; sub-directories are not supported. - -* `guest_os_type` (string) - The guest OS type being installed. By default - this is "other", but you can get _dramatic_ performance improvements by - setting this to the proper value. To view all available values for this - run `prlctl create x --ostype list`. Setting the correct value hints to - Parallels Desktop how to optimize the virtual hardware to work best with - that operating system. +* `floppy_files` (array of strings) - A list of files to place onto a floppy + disk that is attached when the VM is booted. This is most useful + for unattended Windows installs, which look for an `Autounattend.xml` file + on removable media. By default, no floppy will be attached. All files + listed in this setting get placed into the root directory of the floppy + and the floppy is attached as the first floppy device. Currently, no + support exists for creating sub-directories on the floppy. Wildcard + characters (*, ?, and []) are allowed. Directory names are also allowed, + which will add all the files found in the directory to the floppy. * `guest_os_distribution` (string) - The guest OS distribution being installed. By default this is "other", but you can get dramatic @@ -107,6 +103,13 @@ Optional: Setting the correct value hints to Parallels how to optimize the virtual hardware to work best with that operating system. +* `guest_os_type` (string) - The guest OS type being installed. By default + this is "other", but you can get _dramatic_ performance improvements by + setting this to the proper value. To view all available values for this + run `prlctl create x --ostype list`. Setting the correct value hints to + Parallels Desktop how to optimize the virtual hardware to work best with + that operating system. + * `hard_drive_interface` (string) - The type of controller that the hard drives are attached to, defaults to "sata". Valid options are "sata", "ide", and "scsi". @@ -119,7 +122,7 @@ Optional: available as variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (int) - These are the minimum and +* `http_port_min` and `http_port_max` (integer) - These are the minimum and maximum port to use for the HTTP server started to serve the `http_directory`. Because Packer often runs in parallel, Packer will choose a randomly available port in this range to run the HTTP server. If you want to force the HTTP @@ -139,21 +142,6 @@ Optional: By default this is "output-BUILDNAME" where "BUILDNAME" is the name of the build. -* `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in - order to further customize the virtual machine being created. The value of - this is an array of commands to execute. The commands are executed in the order - defined in the template. For each command, the command is defined itself as an - array of strings, where each string represents a single argument on the - command-line to `prlctl` (but excluding `prlctl` itself). Each arg is treated - as a [configuration template](/docs/templates/configuration-templates.html), - where the `Name` variable is replaced with the VM name. More details on how - to use `prlctl` are below. - -* `parallels_tools_mode` (string) - The method by which Parallels tools are - made available to the guest for installation. Valid options are "upload", - "attach", or "disable". The functions of each of these should be - self-explanatory. The default value is "upload". - * `parallels_tools_guest_path` (string) - The path on the guest virtual machine where the Parallels tools ISO will be uploaded. By default this is "prl-tools.iso" which should upload into the login directory of the user. @@ -165,6 +153,21 @@ Optional: the Parallels installation: "/Applications/Parallels Desktop.app/Contents/Resources/Tools/prl-tools-other.iso" +* `parallels_tools_mode` (string) - The method by which Parallels tools are + made available to the guest for installation. Valid options are "upload", + "attach", or "disable". The functions of each of these should be + self-explanatory. The default value is "upload". + +* `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in + order to further customize the virtual machine being created. The value of + this is an array of commands to execute. The commands are executed in the order + defined in the template. For each command, the command is defined itself as an + array of strings, where each string represents a single argument on the + command-line to `prlctl` (but excluding `prlctl` itself). Each arg is treated + as a [configuration template](/docs/templates/configuration-templates.html), + where the `Name` variable is replaced with the VM name. More details on how + to use `prlctl` are below. + * `prlctl_version_file` (string) - The path within the virtual machine to upload a file that contains the `prlctl` version that was used to create the machine. This information can be useful for provisioning. By default this is @@ -187,7 +190,7 @@ Optional: * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will be listening on in the guest +* `ssh_port` (integer) - The port that SSH will be listening on in the guest virtual machine. By default this is 22. * `ssh_wait_timeout` (string) - The duration to wait for SSH to become diff --git a/website/source/docs/builders/parallels-pvm.html.markdown b/website/source/docs/builders/parallels-pvm.html.markdown index 0e32ab975..24ca7f439 100644 --- a/website/source/docs/builders/parallels-pvm.html.markdown +++ b/website/source/docs/builders/parallels-pvm.html.markdown @@ -43,7 +43,7 @@ There are many configuration options available for the Parallels builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `source_path` (string) - The path to a PVM directory that acts as the source of this build. @@ -51,7 +51,7 @@ Required: * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: +### Optional: * `floppy_files` (array of strings) - A list of files to put onto a floppy disk that is attached when the VM is booted for the first time. This is @@ -67,21 +67,6 @@ Optional: By default this is "output-BUILDNAME" where "BUILDNAME" is the name of the build. -* `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in - order to further customize the virtual machine being created. The value of - this is an array of commands to execute. The commands are executed in the order - defined in the template. For each command, the command is defined itself as an - array of strings, where each string represents a single argument on the - command-line to `prlctl` (but excluding `prlctl` itself). Each arg is treated - as a [configuration template](/docs/templates/configuration-templates.html), - where the `Name` variable is replaced with the VM name. More details on how - to use `prlctl` are below. - -* `parallels_tools_mode` (string) - The method by which Parallels tools are - made available to the guest for installation. Valid options are "upload", - "attach", or "disable". The functions of each of these should be - self-explanatory. The default value is "upload". - * `parallels_tools_guest_path` (string) - The path on the guest virtual machine where the Parallels tools ISO will be uploaded. By default this is "prl-tools.iso" which should upload into the login directory of the user. @@ -93,6 +78,21 @@ Optional: the Parallels installation: "/Applications/Parallels Desktop.app/Contents/Resources/Tools/prl-tools-other.iso" +* `parallels_tools_mode` (string) - The method by which Parallels tools are + made available to the guest for installation. Valid options are "upload", + "attach", or "disable". The functions of each of these should be + self-explanatory. The default value is "upload". + +* `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in + order to further customize the virtual machine being created. The value of + this is an array of commands to execute. The commands are executed in the order + defined in the template. For each command, the command is defined itself as an + array of strings, where each string represents a single argument on the + command-line to `prlctl` (but excluding `prlctl` itself). Each arg is treated + as a [configuration template](/docs/templates/configuration-templates.html), + where the `Name` variable is replaced with the VM name. More details on how + to use `prlctl` are below. + * `prlctl_version_file` (string) - The path within the virtual machine to upload a file that contains the `prlctl` version that was used to create the machine. This information can be useful for provisioning. By default this is @@ -115,14 +115,13 @@ Optional: * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will be listening on in the guest +* `ssh_port` (integer) - The port that SSH will be listening on in the guest virtual machine. By default this is 22. * `ssh_wait_timeout` (string) - The duration to wait for SSH to become available. By default this is "20m", or 20 minutes. Note that this should be quite long since the timer begins as soon as the virtual machine is booted. - * `vm_name` (string) - This is the name of the virtual machine when it is imported as well as the name of the PVM directory when the virtual machine is exported. By default this is "packer-BUILDNAME", where "BUILDNAME" is diff --git a/website/source/docs/builders/qemu.html.markdown b/website/source/docs/builders/qemu.html.markdown index 9cb78d2e6..882aab816 100644 --- a/website/source/docs/builders/qemu.html.markdown +++ b/website/source/docs/builders/qemu.html.markdown @@ -70,7 +70,7 @@ There are many configuration options available for the Qemu builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO files are so large, this is required and Packer will verify it prior @@ -88,7 +88,7 @@ Required: * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: +### Optional: * `accelerator` (string) - The accelerator type to use when running the VM. This may have a value of either "kvm" or "xen" and you must have that @@ -107,7 +107,7 @@ Optional: five seconds and one minute 30 seconds, respectively. If this isn't specified, the default is 10 seconds. -* `disk_size` (int) - The size, in megabytes, of the hard disk to create +* `disk_size` (integer) - The size, in megabytes, of the hard disk to create for the VM. By default, this is 40000 (about 40 GB). * `disk_interface` (string) - The interface to use for the disk. Allowed @@ -115,9 +115,6 @@ Optional: commands or kickstart type scripts must have proper adjustments for resulting device names. The Qemu builder uses "virtio" by default. -* `format` (string) - Either "qcow2" or "raw", this specifies the output - format of the virtual machine image. This defaults to "qcow2". - * `floppy_files` (array of strings) - A list of files to place onto a floppy disk that is attached when the VM is booted. This is most useful for unattended Windows installs, which look for an `Autounattend.xml` file @@ -128,7 +125,10 @@ Optional: characters (*, ?, and []) are allowed. Directory names are also allowed, which will add all the files found in the directory to the floppy. -* `headless` (bool) - Packer defaults to building virtual machines by +* `format` (string) - Either "qcow2" or "raw", this specifies the output + format of the virtual machine image. This defaults to "qcow2". + +* `headless` (boolean) - Packer defaults to building virtual machines by launching a GUI that shows the console of the machine being built. When this value is set to true, the machine will start without a console. @@ -140,7 +140,7 @@ Optional: available as variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (int) - These are the minimum and +* `http_port_min` and `http_port_max` (integer) - These are the minimum and maximum port to use for the HTTP server started to serve the `http_directory`. Because Packer often runs in parallel, Packer will choose a randomly available port in this range to run the HTTP server. If you want to force the HTTP @@ -157,6 +157,13 @@ Optional: values "ne2k_pci," "i82551," "i82557b," "i82559er," "rtl8139," "e1000," "pcnet" or "virtio." The Qemu builder uses "virtio" by default. +* `output_directory` (string) - This is the path to the directory where the + resulting virtual machine will be created. This may be relative or absolute. + If relative, the path is relative to the working directory when `packer` + is executed. This directory must not exist or be empty prior to running the builder. + By default this is "output-BUILDNAME" where "BUILDNAME" is the name + of the build. + * `qemuargs` (array of array of strings) - Allows complete control over the qemu command line (though not, at this time, qemu-img). Each array of strings makes up a command line switch that overrides matching default @@ -194,13 +201,6 @@ Optional: qemu-system-x86 -m 1024m --no-acpi -netdev user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device virtio-net,netdev=mynet0" -* `output_directory` (string) - This is the path to the directory where the - resulting virtual machine will be created. This may be relative or absolute. - If relative, the path is relative to the working directory when `packer` - is executed. This directory must not exist or be empty prior to running the builder. - By default this is "output-BUILDNAME" where "BUILDNAME" is the name - of the build. - * `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 better @@ -229,7 +229,7 @@ Optional: * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will be listening on in the guest +* `ssh_port` (integer) - The port that SSH will be listening on in the guest virtual machine. By default this is 22. The Qemu builder will map, via port forward, a port on the host machine to the port listed here so machines outside the installing VM can access the VM. @@ -242,6 +242,12 @@ Optional: the new virtual machine, without the file extension. By default this is "packer-BUILDNAME", where "BUILDNAME" is the name of the build. +* `vnc_port_min` and `vnc_port_max` (integer) - The minimum and + maximum port to use for the VNC port on the host machine which is forwarded + to the VNC port on the guest machine. Because Packer often runs in parallel, + Packer will choose a randomly available port in this range to use as the + host port. + ## Boot Command The `boot_command` configuration is very important: it specifies the keys diff --git a/website/source/docs/builders/virtualbox-iso.html.markdown b/website/source/docs/builders/virtualbox-iso.html.markdown index 8e5eaa373..f435250cf 100644 --- a/website/source/docs/builders/virtualbox-iso.html.markdown +++ b/website/source/docs/builders/virtualbox-iso.html.markdown @@ -46,7 +46,7 @@ There are many configuration options available for the VirtualBox builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO files are so large, this is required and Packer will verify it prior @@ -67,7 +67,7 @@ Required: * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: +### Optional: * `boot_command` (array of strings) - This is an array of commands to type when the virtual machine is first booted. The goal of these commands should @@ -82,9 +82,13 @@ Optional: five seconds and one minute 30 seconds, respectively. If this isn't specified, the default is 10 seconds. -* `disk_size` (int) - The size, in megabytes, of the hard disk to create +* `disk_size` (integer) - The size, in megabytes, of the hard disk to create for the VM. By default, this is 40000 (about 40 GB). +* `export_opts` (array of strings) - Additional options to pass to the `VBoxManage export`. + This can be useful for passing product information to include in the resulting + appliance file. + * `floppy_files` (array of strings) - A list of files to place onto a floppy disk that is attached when the VM is booted. This is most useful for unattended Windows installs, which look for an `Autounattend.xml` file @@ -131,7 +135,7 @@ Optional: hard drive is attached to, defaults to "ide". When set to "sata", the drive is attached to an AHCI SATA controller. -* `headless` (bool) - Packer defaults to building VirtualBox +* `headless` (boolean) - Packer defaults to building VirtualBox virtual machines by launching a GUI that shows the console of the machine being built. When this value is set to true, the machine will start without a console. @@ -144,7 +148,7 @@ Optional: available as variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (int) - These are the minimum and +* `http_port_min` and `http_port_max` (integer) - These are the minimum and maximum port to use for the HTTP server started to serve the `http_directory`. Because Packer often runs in parallel, Packer will choose a randomly available port in this range to run the HTTP server. If you want to force the HTTP @@ -173,7 +177,7 @@ Optional: If it doesn't shut down in this time, it is an error. By default, the timeout is "5m", or five minutes. -* `ssh_host_port_min` and `ssh_host_port_max` (uint) - The minimum and +* `ssh_host_port_min` and `ssh_host_port_max` (integer) - The minimum and maximum port to use for the SSH port on the host machine which is forwarded to the SSH port on the guest machine. Because Packer often runs in parallel, Packer will choose a randomly available port in this range to use as the @@ -187,7 +191,7 @@ Optional: * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will be listening on in the guest +* `ssh_port` (integer) - The port that SSH will be listening on in the guest virtual machine. By default this is 22. * `ssh_wait_timeout` (string) - The duration to wait for SSH to become @@ -211,17 +215,13 @@ Optional: * `virtualbox_version_file` (string) - The path within the virtual machine to upload a file that contains the VirtualBox version that was used to create the machine. This information can be useful for provisioning. - By default this is ".vbox_version", which will generally upload it into + By default this is ".vbox_version", which will generally be upload it into the home directory. * `vm_name` (string) - This is the name of the OVF file for the new virtual machine, without the file extension. By default this is "packer-BUILDNAME", where "BUILDNAME" is the name of the build. -* `export_opts` (array of strings) - Additional options to pass to the `VBoxManage export`. - This can be useful for passing product information to include in the resulting - appliance file. - ## Boot Command The `boot_command` configuration is very important: it specifies the keys diff --git a/website/source/docs/builders/virtualbox-ovf.html.markdown b/website/source/docs/builders/virtualbox-ovf.html.markdown index e1a170d4c..4a41021b2 100644 --- a/website/source/docs/builders/virtualbox-ovf.html.markdown +++ b/website/source/docs/builders/virtualbox-ovf.html.markdown @@ -42,7 +42,7 @@ There are many configuration options available for the VirtualBox builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `source_path` (string) - The path to an OVF or OVA file that acts as the source of this build. @@ -50,7 +50,11 @@ Required: * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: +### Optional: + +* `export_opts` (array of strings) - Additional options to pass to the `VBoxManage export`. + This can be useful for passing product information to include in the resulting + appliance file. * `floppy_files` (array of strings) - A list of files to place onto a floppy disk that is attached when the VM is booted. This is most useful @@ -87,11 +91,15 @@ Optional: By default the VirtualBox builder will go and download the proper guest additions ISO from the internet. -* `headless` (bool) - Packer defaults to building VirtualBox +* `headless` (boolean) - Packer defaults to building VirtualBox virtual machines by launching a GUI that shows the console of the machine being built. When this value is set to true, the machine will start without a console. +* `import_opts` (string) - Additional options to pass to the `VBoxManage import`. + This can be useful for passing "keepallmacs" or "keepnatmacs" options for existing + ovf images. + * `output_directory` (string) - This is the path to the directory where the resulting virtual machine will be created. This may be relative or absolute. If relative, the path is relative to the working directory when `packer` @@ -108,7 +116,7 @@ Optional: If it doesn't shut down in this time, it is an error. By default, the timeout is "5m", or five minutes. -* `ssh_host_port_min` and `ssh_host_port_max` (uint) - The minimum and +* `ssh_host_port_min` and `ssh_host_port_max` (integer) - The minimum and maximum port to use for the SSH port on the host machine which is forwarded to the SSH port on the guest machine. Because Packer often runs in parallel, Packer will choose a randomly available port in this range to use as the @@ -122,7 +130,7 @@ Optional: * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will be listening on in the guest +* `ssh_port` (integer) - The port that SSH will be listening on in the guest virtual machine. By default this is 22. * `ssh_wait_timeout` (string) - The duration to wait for SSH to become @@ -146,7 +154,7 @@ Optional: * `virtualbox_version_file` (string) - The path within the virtual machine to upload a file that contains the VirtualBox version that was used to create the machine. This information can be useful for provisioning. - By default this is ".vbox_version", which will generally upload it into + By default this is ".vbox_version", which will generally be upload it into the home directory. * `vm_name` (string) - This is the name of the virtual machine when it is @@ -154,14 +162,6 @@ Optional: exported. By default this is "packer-BUILDNAME", where "BUILDNAME" is the name of the build. -* `import_opts` (string) - Additional options to pass to the `VBoxManage import`. - This can be useful for passing "keepallmacs" or "keepnatmacs" options for existing - ovf images. - -* `export_opts` (array of strings) - Additional options to pass to the `VBoxManage export`. - This can be useful for passing product information to include in the resulting - appliance file. - ## Guest Additions Packer will automatically download the proper guest additions for the diff --git a/website/source/docs/builders/vmware-iso.html.markdown b/website/source/docs/builders/vmware-iso.html.markdown index ce3359140..7e5f3437a 100644 --- a/website/source/docs/builders/vmware-iso.html.markdown +++ b/website/source/docs/builders/vmware-iso.html.markdown @@ -47,7 +47,7 @@ There are many configuration options available for the VMware builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO files are so large, this is required and Packer will verify it prior @@ -68,7 +68,7 @@ Required: * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: +### Optional: * `boot_command` (array of strings) - This is an array of commands to type when the virtual machine is firsted booted. The goal of these commands should @@ -83,7 +83,7 @@ Optional: five seconds and one minute 30 seconds, respectively. If this isn't specified, the default is 10 seconds. -* `disk_size` (int) - The size of the hard disk for the VM in megabytes. +* `disk_size` (integer) - The size of the hard disk for the VM in megabytes. The builder uses expandable, not fixed-size virtual hard disks, so the actual file representing the disk will not use the full size unless it is full. By default this is set to 40,000 (about 40 GB). @@ -114,7 +114,7 @@ Optional: OS type, VMware may perform some optimizations or virtual hardware changes to better support the operating system running in the virtual machine. -* `headless` (bool) - Packer defaults to building VMware +* `headless` (boolean) - Packer defaults to building VMware virtual machines by launching a GUI that shows the console of the machine being built. When this value is set to true, the machine will start without a console. For VMware machines, Packer will output VNC @@ -129,7 +129,7 @@ Optional: available as variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (int) - These are the minimum and +* `http_port_min` and `http_port_max` (integer) - These are the minimum and maximum port to use for the HTTP server started to serve the `http_directory`. Because Packer often runs in parallel, Packer will choose a randomly available port in this range to run the HTTP server. If you want to force the HTTP @@ -149,11 +149,6 @@ Optional: By default this is "output-BUILDNAME" where "BUILDNAME" is the name of the build. -* `remote_type` (string) - The type of remote machine that will be used to - build this VM rather than a local desktop product. The only value accepted - for this currently is "esx5". If this is not set, a desktop product will be - used. By default, this is not set. - * `remote_datastore` (string) - The path to the datastore where the resulting VM will be stored when it is built on the remote machine. By default this is "datastore1". This only has an effect if `remote_type` is enabled. @@ -165,15 +160,14 @@ Optional: access the remote machine. By default this is empty. This only has an effect if `remote_type` is enabled. +* `remote_type` (string) - The type of remote machine that will be used to + build this VM rather than a local desktop product. The only value accepted + for this currently is "esx5". If this is not set, a desktop product will be + used. By default, this is not set. + * `remote_username` (string) - The username for the SSH user that will access the remote machine. This is required if `remote_type` is enabled. -* `skip_compaction` (bool) - VMware-created disks are defragmented - and compacted at the end of the build process using `vmware-vdiskmanager`. - In certain rare cases, this might actually end up making the resulting disks - slightly larger. If you find this to be the case, you can disable compaction - using this configuration value. - * `shutdown_command` (string) - The command to use to gracefully shut down the machine once all the provisioning is done. By default this is an empty string, which tells Packer to just forcefully shut down the machine. @@ -183,21 +177,27 @@ Optional: If it doesn't shut down in this time, it is an error. By default, the timeout is "5m", or five minutes. +* `skip_compaction` (boolean) - VMware-created disks are defragmented + and compacted at the end of the build process using `vmware-vdiskmanager`. + In certain rare cases, this might actually end up making the resulting disks + slightly larger. If you find this to be the case, you can disable compaction + using this configuration value. + +* `ssh_host` (string) - Hostname or IP address of the host. By default, DHCP + is used to connect to the host and this field is not used. + * `ssh_key_path` (string) - Path to a private key to use for authenticating with SSH. By default this is not set (key-based auth won't be used). The associated public key is expected to already be configured on the VM being prepared by some other process (kickstart, etc.). -* `ssh_host` (string) - Hostname or IP address of the host. By default, DHCP - is used to connect to the host and this field is not used. - * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will listen on within the virtual +* `ssh_port` (integer) - The port that SSH will listen on within the virtual machine. By default this is 22. -* `ssh_skip_request_pty` (bool) - If true, a pty will not be requested as +* `ssh_skip_request_pty` (boolean) - If true, a pty will not be requested as part of the SSH connection. By default, this is "false", so a pty _will_ be requested. @@ -223,16 +223,10 @@ Optional: * `vmdk_name` (string) - The filename of the virtual disk that'll be created, without the extension. This defaults to "packer". -* `vmx_data` (object, string keys and string values) - Arbitrary key/values +* `vmx_data` (object of key/value strings) - Arbitrary key/values to enter into the virtual machine VMX file. This is for advanced users who want to set properties such as memory, CPU, etc. -* `vnc_port_min` and `vnc_port_max` (int) - The minimum and maximum port to - use for VNC access to the virtual machine. The builder uses VNC to type - the initial `boot_command`. Because Packer generally runs in parallel, Packer - uses a randomly chosen port in this range that appears available. By default - this is 5900 to 6000. The minimum and maximum ports are inclusive. - * `vmx_template_path` (string) - Path to a [configuration template](/docs/templates/configuration-templates.html) that defines the contents of the virtual machine VMX file for VMware. This is @@ -240,6 +234,12 @@ Optional: non-functional. See below for more information. For basic VMX modifications, try `vmx_data` first. +* `vnc_port_min` and `vnc_port_max` (integer) - The minimum and maximum port to + use for VNC access to the virtual machine. The builder uses VNC to type + the initial `boot_command`. Because Packer generally runs in parallel, Packer + uses a randomly chosen port in this range that appears available. By default + this is 5900 to 6000. The minimum and maximum ports are inclusive. + ## Boot Command The `boot_command` configuration is very important: it specifies the keys diff --git a/website/source/docs/builders/vmware-vmx.html.markdown b/website/source/docs/builders/vmware-vmx.html.markdown index eacaa82c0..2f1ecfa73 100644 --- a/website/source/docs/builders/vmware-vmx.html.markdown +++ b/website/source/docs/builders/vmware-vmx.html.markdown @@ -42,20 +42,14 @@ There are many configuration options available for the VMware builder. They are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described. -Required: +### Required: * `source_path` (string) - Path to the source VMX file to clone. * `ssh_username` (string) - The username to use to SSH into the machine once the OS is installed. -Optional: - -* `boot_wait` (string) - The time to wait after booting the initial virtual - machine before typing the `boot_command`. The value of this should be - a duration. Examples are "5s" and "1m30s" which will cause Packer to wait - five seconds and one minute 30 seconds, respectively. If this isn't specified, - the default is 10 seconds. +### Optional: * `floppy_files` (array of strings) - A list of files to place onto a floppy disk that is attached when the VM is booted. This is most useful @@ -71,7 +65,7 @@ Optional: is "/Applications/VMware Fusion.app" but this setting allows you to customize this. -* `headless` (bool) - Packer defaults to building VMware +* `headless` (boolean) - Packer defaults to building VMware virtual machines by launching a GUI that shows the console of the machine being built. When this value is set to true, the machine will start without a console. For VMware machines, Packer will output VNC @@ -85,12 +79,6 @@ Optional: By default this is "output-BUILDNAME" where "BUILDNAME" is the name of the build. -* `skip_compaction` (bool) - VMware-created disks are defragmented - and compacted at the end of the build process using `vmware-vdiskmanager`. - In certain rare cases, this might actually end up making the resulting disks - slightly larger. If you find this to be the case, you can disable compaction - using this configuration value. - * `shutdown_command` (string) - The command to use to gracefully shut down the machine once all the provisioning is done. By default this is an empty string, which tells Packer to just forcefully shut down the machine. @@ -100,6 +88,12 @@ Optional: If it doesn't shut down in this time, it is an error. By default, the timeout is "5m", or five minutes. +* `skip_compaction` (boolean) - VMware-created disks are defragmented + and compacted at the end of the build process using `vmware-vdiskmanager`. + In certain rare cases, this might actually end up making the resulting disks + slightly larger. If you find this to be the case, you can disable compaction + using this configuration value. + * `ssh_key_path` (string) - Path to a private key to use for authenticating with SSH. By default this is not set (key-based auth won't be used). The associated public key is expected to already be configured on the @@ -108,10 +102,10 @@ Optional: * `ssh_password` (string) - The password for `ssh_username` to use to authenticate with SSH. By default this is the empty string. -* `ssh_port` (int) - The port that SSH will listen on within the virtual +* `ssh_port` (integer) - The port that SSH will listen on within the virtual machine. By default this is 22. -* `ssh_skip_request_pty` (bool) - If true, a pty will not be requested as +* `ssh_skip_request_pty` (boolean) - If true, a pty will not be requested as part of the SSH connection. By default, this is "false", so a pty _will_ be requested. @@ -123,6 +117,6 @@ Optional: machine, without the file extension. By default this is "packer-BUILDNAME", where "BUILDNAME" is the name of the build. -* `vmx_data` (object, string keys and string values) - Arbitrary key/values +* `vmx_data` (object of key/value strings) - Arbitrary key/values to enter into the virtual machine VMX file. This is for advanced users who want to set properties such as memory, CPU, etc. diff --git a/website/source/docs/command-line/build.html.markdown b/website/source/docs/command-line/build.html.markdown index 198bd85b4..ff111b477 100644 --- a/website/source/docs/command-line/build.html.markdown +++ b/website/source/docs/command-line/build.html.markdown @@ -18,16 +18,16 @@ artifacts that are created will be outputted at the end of the build. between each step, waiting for keyboard input before continuing. This will allow the user to inspect state and so on. +* `-except=foo,bar,baz` - Builds all the builds except those with the given + comma-separated names. Build names by default are the names of their builders, + unless a specific `name` attribute is specified within the configuration. + * `-force` - Forces a builder to run when artifacts from a previous build prevent a build from running. The exact behavior of a forced build is left to the builder. In general, a builder supporting the forced build will remove the artifacts from the previous build. This will allow the user to repeat a build without having to manually clean these artifacts beforehand. -* `-except=foo,bar,baz` - Builds all the builds except those with the given - comma-separated names. Build names by default are the names of their builders, - unless a specific `name` attribute is specified within the configuration. - * `-only=foo,bar,baz` - Only build the builds with the given comma-separated names. Build names by default are the names of their builders, unless a specific `name` attribute is specified within the configuration. diff --git a/website/source/docs/other/core-configuration.html.markdown b/website/source/docs/other/core-configuration.html.markdown index 8592b2e08..42705384a 100644 --- a/website/source/docs/other/core-configuration.html.markdown +++ b/website/source/docs/other/core-configuration.html.markdown @@ -25,7 +25,7 @@ The format of the configuration file is basic JSON. Below is the list of all available configuration parameters for the core configuration file. None of these are required, since all have sane defaults. -* `plugin_min_port` and `plugin_max_port` (int) - These are the minimum and +* `plugin_min_port` and `plugin_max_port` (integer) - These are the minimum and maximum ports that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. By default these are 10,000 and 25,000, respectively. Be sure to set a fairly diff --git a/website/source/docs/post-processors/vagrant.html.markdown b/website/source/docs/post-processors/vagrant.html.markdown index ed7f7708b..bffcafddd 100644 --- a/website/source/docs/post-processors/vagrant.html.markdown +++ b/website/source/docs/post-processors/vagrant.html.markdown @@ -59,6 +59,9 @@ below, with more details about certain options in following sections. of the Vagrant box (regardless of their paths). They can then be used from the Vagrantfile. +* `keep_input_artifact` (boolean) - If set to true, do not delete the + `output_directory` on a successful build. Defaults to 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/configuration-templates.html). diff --git a/website/source/docs/post-processors/vsphere.html.markdown b/website/source/docs/post-processors/vsphere.html.markdown index 8dde0e8fb..408d8b327 100644 --- a/website/source/docs/post-processors/vsphere.html.markdown +++ b/website/source/docs/post-processors/vsphere.html.markdown @@ -43,7 +43,7 @@ Optional: * `disk_mode` (string) - Target disk format. See `ovftool` manual for available options. By default, "thick" will be used. -* `insecure` (bool) - Whether or not the connection to vSphere can be done +* `insecure` (boolean) - Whether or not the connection to vSphere can be done over an insecure connection. By default this is false. * `vm_folder` (string) - The folder within the datastore to store the VM. diff --git a/website/source/docs/provisioners/chef-solo.html.markdown b/website/source/docs/provisioners/chef-solo.html.markdown index 5e68d933b..e3852cb20 100644 --- a/website/source/docs/provisioners/chef-solo.html.markdown +++ b/website/source/docs/provisioners/chef-solo.html.markdown @@ -63,15 +63,15 @@ configuration is actually required, but at least `run_list` is recommended. * `json` (object) - An arbitrary mapping of JSON that will be available as node attributes while running Chef. -* `remote_cookbook_paths` (array of string) - A list of paths on the remote - machine where cookbooks will already exist. These may exist from a previous - provisioner or step. If specified, Chef will be configured to look for - cookbooks here. By default, this is empty. - * `prevent_sudo` (boolean) - By default, the configured commands that are executed to install and run Chef are executed with `sudo`. If this is true, then the sudo will be omitted. +* `remote_cookbook_paths` (array of strings) - A list of paths on the remote + machine where cookbooks will already exist. These may exist from a previous + provisioner or step. If specified, Chef will be configured to look for + cookbooks here. By default, this is empty. + * `roles_path` (string) - The path to the "roles" directory on your local filesystem. These will be uploaded to the remote machine in the directory specified by the `staging_directory`. By default, this is empty. diff --git a/website/source/docs/provisioners/puppet-server.html.markdown b/website/source/docs/provisioners/puppet-server.html.markdown index 413e1831e..11a7bbd96 100644 --- a/website/source/docs/provisioners/puppet-server.html.markdown +++ b/website/source/docs/provisioners/puppet-server.html.markdown @@ -54,16 +54,16 @@ required. They are listed below: * `options` (string) - Additional command line options to pass to `puppet agent` when Puppet is ran. +* `prevent_sudo` (boolean) - By default, the configured commands that are + executed to run Puppet are executed with `sudo`. If this is true, + then the sudo will be omitted. + * `puppet_node` (string) - The name of the node. If this isn't set, the fully qualified domain name will be used. * `puppet_server` (string) - Hostname of the Puppet server. By default "puppet" will be used. -* `prevent_sudo` (boolean) - By default, the configured commands that are - executed to run Puppet are executed with `sudo`. If this is true, - then the sudo will be omitted. - * `staging_directory` (string) - This is the directory where all the configuration of Puppet by Packer will be placed. By default this is "/tmp/packer-puppet-server". This directory doesn't need to exist but must have proper permissions so that diff --git a/website/source/docs/provisioners/salt-masterless.html.markdown b/website/source/docs/provisioners/salt-masterless.html.markdown index c0dbead7c..76128a87c 100644 --- a/website/source/docs/provisioners/salt-masterless.html.markdown +++ b/website/source/docs/provisioners/salt-masterless.html.markdown @@ -27,27 +27,27 @@ The reference of available configuration options is listed below. The only requi Optional: -* `local_state_tree` (string) - The path to your local - [state tree](http://docs.saltstack.com/ref/states/highstate.html#the-salt-state-tree). - This will be uploaded to the `/srv/salt` on the remote. - -* `local_pillar_roots` (string) - The path to your local - [pillar roots](http://docs.saltstack.com/ref/configuration/master.html#pillar-configuration). - This will be uploaded to the `/srv/pillar` on the remote. - -* `skip_bootstrap` (boolean) - By default the salt provisioner runs - [salt bootstrap](https://github.com/saltstack/salt-bootstrap) to install - salt. Set this to true to skip this step. - * `bootstrap_args` (string) - Arguments to send to the bootstrap script. Usage is somewhat documented on [github](https://github.com/saltstack/salt-bootstrap), but the [script itself](https://github.com/saltstack/salt-bootstrap/blob/develop/bootstrap-salt.sh) has more detailed usage instructions. By default, no arguments are sent to the script. +* `local_pillar_roots` (string) - The path to your local + [pillar roots](http://docs.saltstack.com/ref/configuration/master.html#pillar-configuration). + This will be uploaded to the `/srv/pillar` on the remote. + +* `local_state_tree` (string) - The path to your local + [state tree](http://docs.saltstack.com/ref/states/highstate.html#the-salt-state-tree). + This will be uploaded to the `/srv/salt` on the remote. + * `minion_config` (string) - The path to your local [minion config](http://docs.saltstack.com/topics/configuration.html). This will be uploaded to the `/etc/salt` on the remote. +* `skip_bootstrap` (boolean) - By default the salt provisioner runs + [salt bootstrap](https://github.com/saltstack/salt-bootstrap) to install + salt. Set this to true to skip this step. + * `temp_config_dir` (string) - Where your local state tree will be copied before moving to the `/srv/salt` directory. Default is `/tmp/salt`. diff --git a/website/source/docs/templates/introduction.html.markdown b/website/source/docs/templates/introduction.html.markdown index 6b11cc851..1bf3bc282 100644 --- a/website/source/docs/templates/introduction.html.markdown +++ b/website/source/docs/templates/introduction.html.markdown @@ -20,28 +20,15 @@ A template is a JSON object that has a set of keys configuring various components of Packer. The available keys within a template are listed below. Along with each key, it is noted whether it is required or not. -* `description` (optional) is a string providing a description of what - the template does. This output is used only in the - [inspect command](/docs/command-line/inspect.html). - * `builders` (_required_) is an array of one or more objects that defines the builders that will be used to create machine images for this template, and configures each of those builders. For more information on how to define and configure a builder, read the sub-section on [configuring builders in templates](/docs/templates/builders.html). -* `provisioners` (optional) is an array of one or more objects that defines - the provisioners that will be used to install and configure software for - the machines created by each of the builders. This is an optional field. - If it is not specified, then no provisioners will be run. For more - information on how to define and configure a provisioner, read the - sub-section on [configuring provisioners in templates](/docs/templates/provisioners.html). - -* `post-processors` (optional) is an array of one or more objects that defines the - various post-processing steps to take with the built images. This is an optional - field. If not specified, then no post-processing will be done. For more - information on what post-processors do and how they're defined, read the - sub-section on [configuring post-processors in templates](/docs/templates/post-processors.html). +* `description` (optional) is a string providing a description of what + the template does. This output is used only in the + [inspect command](/docs/command-line/inspect.html). * `min_packer_version` (optional) is a string that has a minimum Packer version that is required to parse the template. This can be used to @@ -49,6 +36,25 @@ Along with each key, it is noted whether it is required or not. max version can't be specified because Packer retains backwards compatibility with `packer fix`. +* `post-processors` (optional) is an array of one or more objects that defines the + various post-processing steps to take with the built images. If not specified, + then no post-processing will be done. For more + information on what post-processors do and how they're defined, read the + sub-section on [configuring post-processors in templates](/docs/templates/post-processors.html). + +* `provisioners` (optional) is an array of one or more objects that defines + the provisioners that will be used to install and configure software for + the machines created by each of the builders. If it is not specified, + then no provisioners will be run. For more + information on how to define and configure a provisioner, read the + sub-section on [configuring provisioners in templates](/docs/templates/provisioners.html). + +* `variables` (optional) is an array of one or more key/value strings that defines + user variables contained in the template. + If it is not specified, then no variables are defined. + For more information on how to define and use user variables, read the + sub-section on [user variables in templates](/docs/templates/user-variables.html). + ## Example Template Below is an example of a basic template that is nearly fully functional. It is just