diff --git a/website/source/community/index.html.markdown b/website/source/community/index.html.markdown index 1b21e818a..f4069fbdf 100644 --- a/website/source/community/index.html.markdown +++ b/website/source/community/index.html.markdown @@ -1,22 +1,25 @@ --- -layout: "community" -page_title: "Community" -description: |- - Packer is a new project with a growing community. Despite this, there are dedicated users willing to help through various mediums. ---- +description: | + Packer is a new project with a growing community. Despite this, there are + dedicated users willing to help through various mediums. +layout: community +page_title: Community +... # Community Packer is a new project with a growing community. Despite this, there are dedicated users willing to help through various mediums. -**IRC:** `#packer-tool` on Freenode. +**IRC:** `#packer-tool` on Freenode. -**Mailing List:** [Packer Google Group](http://groups.google.com/group/packer-tool) +**Mailing List:** [Packer Google +Group](http://groups.google.com/group/packer-tool) -**Bug Tracker:** [Issue tracker on GitHub](https://github.com/mitchellh/packer/issues). -Please only use this for reporting bugs. Do not ask for general help here. Use IRC -or the mailing list for that. +**Bug Tracker:** [Issue tracker on +GitHub](https://github.com/mitchellh/packer/issues). Please only use this for +reporting bugs. Do not ask for general help here. Use IRC or the mailing list +for that. ## People @@ -25,62 +28,70 @@ to Packer in some core way. Over time, faces may appear and disappear from this list as contributors come and go.
-
- -
-

Mitchell Hashimoto (@mitchellh)

-

- Mitchell Hashimoto is the creator of Packer. He developed the - core of Packer as well as the Amazon, VirtualBox, and VMware - builders. In addition to Packer, Mitchell is the creator of - Vagrant. He is self - described as "automation obsessed." -

-
-
-
- -
-

Jack Pearkes (@pearkes)

-

- Jack Pearkes created and maintains the DigitalOcean builder - for Packer. Outside of Packer, Jack is an avid open source - contributor and software consultant.

-
-
+
+ +
+

Mitchell Hashimoto (@mitchellh)

+

+ Mitchell Hashimoto is the creator of Packer. He developed the + core of Packer as well as the Amazon, VirtualBox, and VMware + builders. In addition to Packer, Mitchell is the creator of + Vagrant. He is self + described as "automation obsessed." +

+
+
-
- -
-

Mark Peek (@markpeek)

-

- In addition to Packer, Mark Peek helps maintain - various open source projects such as - cloudtools and - IronPort Python libraries. - Mark is also a FreeBSD committer.

-
-
+
+ +
+

Jack Pearkes (@pearkes)

+

+ Jack Pearkes created and maintains the DigitalOcean builder + for Packer. Outside of Packer, Jack is an avid open source + contributor and software consultant.

+
+
-
- -
-

Ross Smith II (@rasa)

-

-Ross Smith maintains our VMware builder on Windows, and provides other valuable assistance. -Ross is an open source enthusiast, published author, and freelance consultant.

-
-
+
+ +
+

Mark Peek (@markpeek)

+

+ In addition to Packer, Mark Peek helps maintain + various open source projects such as + cloudtools and + IronPort Python libraries. + Mark is also a FreeBSD committer.

+
+
-
- -
-

Rickard von Essen
(@rickard-von-essen)

-

-Rickard von Essen maintains our Parallels Desktop builder. Rickard is an polyglot programmer and consults on Continuous Delivery.

-
-
+
+ +
+

Ross Smith II (@rasa)

+

+ +Ross Smith maintains our +VMware builder on Windows, and provides other valuable assistance. Ross is an +open source enthusiast, published author, and freelance consultant. +

+
+
+ +
+ +
+

Rickard von Essen
(@rickard-von-essen)

+

+ +Rickard von Essen maintains our Parallels Desktop builder. Rickard is an +polyglot programmer and consults on Continuous Delivery. +

+
+
+ +
-
diff --git a/website/source/docs/basics/terminology.html.markdown b/website/source/docs/basics/terminology.html.markdown index 4fce2cc79..800478143 100644 --- a/website/source/docs/basics/terminology.html.markdown +++ b/website/source/docs/basics/terminology.html.markdown @@ -1,54 +1,57 @@ --- -layout: "docs" -page_title: "Packer Terminology" -description: |- - There are a handful of terms used throughout the Packer documentation where the meaning may not be immediately obvious if you haven't used Packer before. Luckily, there are relatively few. This page documents all the terminology required to understand and use Packer. The terminology is in alphabetical order for easy referencing. ---- +description: | + There are a handful of terms used throughout the Packer documentation where the + meaning may not be immediately obvious if you haven't used Packer before. + Luckily, there are relatively few. This page documents all the terminology + required to understand and use Packer. The terminology is in alphabetical order + for easy referencing. +layout: docs +page_title: Packer Terminology +... # Packer Terminology -There are a handful of terms used throughout the Packer documentation where -the meaning may not be immediately obvious if you haven't used Packer before. +There are a handful of terms used throughout the Packer documentation where the +meaning may not be immediately obvious if you haven't used Packer before. Luckily, there are relatively few. This page documents all the terminology -required to understand and use Packer. The terminology is in alphabetical -order for easy referencing. +required to understand and use Packer. The terminology is in alphabetical order +for easy referencing. -- `Artifacts` are the results of a single build, and are usually a set of IDs -or files to represent a machine image. Every builder produces a single -artifact. As an example, in the case of the Amazon EC2 builder, the artifact is -a set of AMI IDs (one per region). For the VMware builder, the artifact is a -directory of files comprising the created virtual machine. +- `Artifacts` are the results of a single build, and are usually a set of IDs or + files to represent a machine image. Every builder produces a single artifact. + As an example, in the case of the Amazon EC2 builder, the artifact is a set of + AMI IDs (one per region). For the VMware builder, the artifact is a directory + of files comprising the created virtual machine. -- `Builds` are a single task that eventually produces an image for a single -platform. Multiple builds run in parallel. Example usage in a -sentence: "The Packer build produced an AMI to run our web application." -Or: "Packer is running the builds now for VMware, AWS, and VirtualBox." +- `Builds` are a single task that eventually produces an image for a + single platform. Multiple builds run in parallel. Example usage in a sentence: + "The Packer build produced an AMI to run our web application." Or: "Packer is + running the builds now for VMware, AWS, and VirtualBox." -- `Builders` are components of Packer that are able to create a machine -image for a single platform. Builders read in some configuration and use -that to run and generate a machine image. A builder is invoked as part of a -build in order to create the actual resulting images. Example builders include -VirtualBox, VMware, and Amazon EC2. Builders can be created and added to -Packer in the form of plugins. +- `Builders` are components of Packer that are able to create a machine image + for a single platform. Builders read in some configuration and use that to run + and generate a machine image. A builder is invoked as part of a build in order + to create the actual resulting images. Example builders include VirtualBox, + VMware, and Amazon EC2. Builders can be created and added to Packer in the + form of plugins. -- `Commands` are sub-commands for the `packer` program that perform some -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. +- `Commands` are sub-commands for the `packer` program that perform some 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. -- `Post-processors` are components of Packer that take the result of -a builder or another post-processor and process that to -create a new artifact. Examples of post-processors are -compress to compress artifacts, upload to upload artifacts, etc. +- `Post-processors` are components of Packer that take the result of a builder + or another post-processor and process that to create a new artifact. Examples + of post-processors are compress to compress artifacts, upload to upload + artifacts, etc. -- `Provisioners` are components of Packer that install and configure -software within a running machine prior to that machine being turned -into a static image. They perform the major work of making the image contain -useful software. Example provisioners include shell scripts, Chef, Puppet, -etc. +- `Provisioners` are components of Packer that install and configure software + within a running machine prior to that machine being turned into a + static image. They perform the major work of making the image contain + useful software. Example provisioners include shell scripts, Chef, + Puppet, etc. -- `Templates` are JSON files which define one or more builds -by configuring the various components of Packer. Packer is able to read a -template and use that information to create multiple machine images in -parallel. +- `Templates` are JSON files which define one or more builds by configuring the + various components of Packer. Packer is able to read a template and use that + information to create multiple machine images in parallel. diff --git a/website/source/docs/builders/amazon-chroot.html.markdown b/website/source/docs/builders/amazon-chroot.html.markdown index d6b61ca8b..c3e16a982 100644 --- a/website/source/docs/builders/amazon-chroot.html.markdown +++ b/website/source/docs/builders/amazon-chroot.html.markdown @@ -1,49 +1,52 @@ --- -layout: "docs" -page_title: "Amazon AMI Builder (chroot)" -description: |- - The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by an EBS volume as the root device. For more information on the difference between instance storage and EBS-backed instances, storage for the root device section in the EC2 documentation. ---- +description: | + The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by an + EBS volume as the root device. For more information on the difference between + instance storage and EBS-backed instances, storage for the root device section + in the EC2 documentation. +layout: docs +page_title: 'Amazon AMI Builder (chroot)' +... # AMI Builder (chroot) Type: `amazon-chroot` -The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by -an EBS volume as the root device. For more information on the difference -between instance storage and EBS-backed instances, see the -["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). +The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by an +EBS volume as the root device. For more information on the difference between +instance storage and EBS-backed instances, see the ["storage for the root +device" section in the EC2 +documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). -The difference between this builder and the `amazon-ebs` builder is that -this builder is able to build an EBS-backed AMI without launching a new -EC2 instance. This can dramatically speed up AMI builds for organizations -who need the extra fast build. +The difference between this builder and the `amazon-ebs` builder is that this +builder is able to build an EBS-backed AMI without launching a new EC2 instance. +This can dramatically speed up AMI builds for organizations who need the extra +fast build. -~> **This is an advanced builder** If you're just getting -started with Packer, we recommend starting with the -[amazon-ebs builder](/docs/builders/amazon-ebs.html), which is -much easier to use. +\~> **This is an advanced builder** If you're just getting started with +Packer, we recommend starting with the [amazon-ebs +builder](/docs/builders/amazon-ebs.html), which is much easier to use. -The builder does _not_ manage AMIs. Once it creates an AMI and stores it -in your account, it is up to you to use, delete, etc. the AMI. +The builder does *not* manage AMIs. Once it creates an AMI and stores it in your +account, it is up to you to use, delete, etc. the AMI. ## How Does it Work? -This builder works by creating a new EBS volume from an existing source AMI -and attaching it into an already-running EC2 instance. Once attached, a -[chroot](http://en.wikipedia.org/wiki/Chroot) is used to provision the -system within that volume. After provisioning, the volume is detached, -snapshotted, and an AMI is made. +This builder works by creating a new EBS volume from an existing source AMI and +attaching it into an already-running EC2 instance. Once attached, a +[chroot](http://en.wikipedia.org/wiki/Chroot) is used to provision the system +within that volume. After provisioning, the volume is detached, snapshotted, and +an AMI is made. -Using this process, minutes can be shaved off the AMI creation process -because a new EC2 instance doesn't need to be launched. +Using this process, minutes can be shaved off the AMI creation process because a +new EC2 instance doesn't need to be launched. -There are some restrictions, however. The host EC2 instance where the -volume is attached to must be a similar system (generally the same OS -version, kernel versions, etc.) as the AMI being built. Additionally, -this process is much more expensive because the EC2 instance must be kept -running persistently in order to build AMIs, whereas the other AMI builders -start instances on-demand to build AMIs as needed. +There are some restrictions, however. The host EC2 instance where the volume is +attached to must be a similar system (generally the same OS version, kernel +versions, etc.) as the AMI being built. Additionally, this process is much more +expensive because the EC2 instance must be kept running persistently in order to +build AMIs, whereas the other AMI builders start instances on-demand to build +AMIs as needed. ## Configuration Reference @@ -52,107 +55,109 @@ segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `access_key` (string) - The access key used to communicate with AWS. - If not specified, Packer will use the key from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file - or fall back to 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. +- `access_key` (string) - The access key used to communicate with AWS. If not + specified, Packer will use the key from any + [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) + file or fall back to 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. -* `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. - To help make this unique, use a function like `timestamp` (see - [configuration templates](/docs/templates/configuration-templates.html) for more info) +- `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. To help + make this unique, use a function like `timestamp` (see [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 use the secret from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file - or fall back to 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. +- `secret_key` (string) - The secret key used to communicate with AWS. If not + specified, Packer will use the secret from any + [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) + file or fall back to 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. -* `source_ami` (string) - The source AMI whose root volume will be copied - and provisioned on the currently running instance. This must be an - EBS-backed AMI with a root volume snapshot that you have access to. +- `source_ami` (string) - The source AMI whose root volume will be copied 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: -* `ami_description` (string) - The description to set for the resulting - AMI(s). By default this description is empty. +- `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_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_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_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_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 +- `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". -* `chroot_mounts` (array of array 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. + requires some additional documentation which is in the "Chroot Mounts" + section below. Please read that section for more information on how to + use this. -* `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. +- `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. +- `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. -* `device_path` (string) - The path to the device where the root volume - of the source AMI will be attached. This defaults to "" (empty string), - which forces Packer to find an open device automatically. +- `device_path` (string) - The path to the device where the root volume of the + source AMI will be attached. This defaults to "" (empty string), which forces + Packer to find an open device automatically. -* `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) on - HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. +- `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) + on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS + IAM policy. -* `force_deregister` (boolean) - Force Packer to first deregister an existing -AMI if one with the same name already exists. Default `false`. +- `force_deregister` (boolean) - Force Packer to first deregister an existing + AMI if one with the same name already exists. Default `false`. -* `mount_path` (string) - The path where the volume will be mounted. This is +- `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 - template where the `.Device` variable is replaced with the name of the - device where the volume is attached. + `packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration template + where the `.Device` variable is replaced with the name of the device where the + volume is attached. -* `mount_options` (array of strings) - Options to supply the `mount` command -when mounting devices. Each option will be prefixed with `-o ` and supplied to -the `mount` command ran by Packer. Because this command is ran in a shell, user -discrestion is advised. See [this manual page for the mount command][1] for valid -file system specific options +- `mount_options` (array of strings) - Options to supply the `mount` command + when mounting devices. Each option will be prefixed with `-o` and supplied to + the `mount` command ran by Packer. Because this command is ran in a shell, + user discrestion is advised. See [this manual page for the mount + command](http://linuxcommand.org/man_pages/mount8.html) for valid file system + specific options -* `root_volume_size` (integer) - The size of the root volume for the chroot -environment, and the resulting AMI +- `root_volume_size` (integer) - The size of the root volume for the chroot + environment, and the resulting AMI -* `tags` (object of key/value strings) - Tags applied to the AMI. +- `tags` (object of key/value strings) - Tags applied to the AMI. ## Basic Example Here is a basic example. It is completely valid except for the access keys: -```javascript +``` {.javascript} { "type": "amazon-chroot", "access_key": "YOUR KEY HERE", @@ -164,21 +169,21 @@ Here is a basic example. It is completely valid except for the access keys: ## Chroot Mounts -The `chroot_mounts` configuration can be used to mount additional devices -within the chroot. By default, the following additional mounts are added -into the chroot by Packer: +The `chroot_mounts` configuration can be used to mount additional devices within +the chroot. By default, the following additional mounts are added into the +chroot by Packer: -* `/proc` (proc) -* `/sys` (sysfs) -* `/dev` (bind to real `/dev`) -* `/dev/pts` (devpts) -* `/proc/sys/fs/binfmt_misc` (binfmt_misc) +- `/proc` (proc) +- `/sys` (sysfs) +- `/dev` (bind to real `/dev`) +- `/dev/pts` (devpts) +- `/proc/sys/fs/binfmt_misc` (binfmt\_misc) -These default mounts are usually good enough for anyone and are sane -defaults. However, if you want to change or add the mount points, you may -using the `chroot_mounts` configuration. Here is an example configuration: +These default mounts are usually good enough for anyone and are sane defaults. +However, if you want to change or add the mount points, you may using the +`chroot_mounts` configuration. Here is an example configuration: -```javascript +``` {.javascript} { "chroot_mounts": [ ["proc", "proc", "/proc"], @@ -187,25 +192,25 @@ using the `chroot_mounts` configuration. Here is an example configuration: } ``` -`chroot_mounts` is a list of a 3-tuples of strings. The three components -of the 3-tuple, in order, are: +`chroot_mounts` is a list of a 3-tuples of strings. The three components of the +3-tuple, in order, are: -* The filesystem type. If this is "bind", then Packer will properly bind - the filesystem to another mount point. +- The filesystem type. If this is "bind", then Packer will properly bind the + filesystem to another mount point. -* The source device. +- The source device. -* The mount directory. +- The mount directory. ## Parallelism -A quick note on parallelism: it is perfectly safe to run multiple -_separate_ Packer processes with the `amazon-chroot` builder on the same -EC2 instance. In fact, this is recommended as a way to push the most performance -out of your AMI builds. +A quick note on parallelism: it is perfectly safe to run multiple *separate* +Packer processes with the `amazon-chroot` builder on the same EC2 instance. In +fact, this is recommended as a way to push the most performance out of your AMI +builds. -Packer properly obtains a process lock for the parallelism-sensitive parts -of its internals such as finding an available device. +Packer properly obtains a process lock for the parallelism-sensitive parts of +its internals such as finding an available device. ## Gotchas @@ -213,10 +218,12 @@ One of the difficulties with using the chroot builder is that your provisioning scripts must not leave any processes running or packer will be unable to unmount the filesystem. -For debian based distributions you can setup a [policy-rc.d](http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt) file which will -prevent packages installed by your provisioners from starting services: +For debian based distributions you can setup a +[policy-rc.d](http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt) +file which will prevent packages installed by your provisioners from starting +services: -```javascript +``` {.javascript} { "type": "shell", "inline": [ @@ -235,6 +242,3 @@ prevent packages installed by your provisioners from starting services: ] } ``` - - -[1]: http://linuxcommand.org/man_pages/mount8.html diff --git a/website/source/docs/builders/amazon-ebs.html.markdown b/website/source/docs/builders/amazon-ebs.html.markdown index 69a9a5c04..cb6b7c9d5 100644 --- a/website/source/docs/builders/amazon-ebs.html.markdown +++ b/website/source/docs/builders/amazon-ebs.html.markdown @@ -1,29 +1,32 @@ --- -layout: "docs" -page_title: "Amazon AMI Builder (EBS backed)" -description: |- - The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS volumes for use in EC2. For more information on the difference between EBS-backed instances and instance-store backed instances, see the storage for the root device section in the EC2 documentation. ---- +description: | + The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS + volumes for use in EC2. For more information on the difference between + EBS-backed instances and instance-store backed instances, see the storage for + the root device section in the EC2 documentation. +layout: docs +page_title: 'Amazon AMI Builder (EBS backed)' +... # AMI Builder (EBS backed) Type: `amazon-ebs` The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS -volumes for use in [EC2](http://aws.amazon.com/ec2/). For more information -on the difference between EBS-backed instances and instance-store backed -instances, see the -["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). +volumes for use in [EC2](http://aws.amazon.com/ec2/). For more information on +the difference between EBS-backed instances and instance-store backed instances, +see the ["storage for the root device" section in the EC2 +documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). This builder builds an AMI by launching an EC2 instance from a source AMI, provisioning that running machine, and then creating an AMI from that machine. This is all done in your own AWS account. The builder will create temporary -keypairs, security group rules, etc. that provide it temporary access to -the instance while the image is being created. This simplifies configuration -quite a bit. +keypairs, security group rules, etc. that provide it temporary access to the +instance while the image is being created. This simplifies configuration quite a +bit. -The builder does _not_ manage AMIs. Once it creates an AMI and stores it -in your account, it is up to you to use, delete, etc. the AMI. +The builder does *not* manage AMIs. Once it creates an AMI and stores it in your +account, it is up to you to use, delete, etc. the AMI. ## Configuration Reference @@ -32,170 +35,173 @@ segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `access_key` (string) - The access key used to communicate with AWS. - If not specified, Packer will use the key from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file - or fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. +- `access_key` (string) - The access key used to communicate with AWS. If not + specified, Packer will use the key from any + [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) + file or fall back to 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. - To help make this unique, use a function like `timestamp` (see - [configuration templates](/docs/templates/configuration-templates.html) for more info) +- `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. To help + make this unique, use a function like `timestamp` (see [configuration + templates](/docs/templates/configuration-templates.html) for more info) -* `instance_type` (string) - The EC2 instance type to use while building - the AMI, such as "m1.small". +- `instance_type` (string) - The EC2 instance type to use while building the + AMI, such as "m1.small". -* `region` (string) - The name of the region, such as "us-east-1", in which - to launch the EC2 instance to create the AMI. +- `region` (string) - The name of the region, such as "us-east-1", in which 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 use the secret from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file - or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. +- `secret_key` (string) - The secret key used to communicate with AWS. If not + specified, Packer will use the secret from any + [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) + file or fall back to 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 +- `source_ami` (string) - The initial AMI used as a base for the newly created machine. -* `ssh_username` (string) - The username to use in order to communicate - over SSH to the running machine. +- `ssh_username` (string) - The username to use in order to communicate over SSH + to the running machine. ### Optional: -* `ami_block_device_mappings` (array of block device mappings) - Add the block +- `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) - The device name exposed to the instance (for - example, "/dev/sdh" or "xvdh") + example, "/dev/sdh" or "xvdh") - `virtual_name` (string) - The virtual device name. See the documentation on - [Block Device Mapping][1] for more information + [Block Device + Mapping](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) + for more information - `snapshot_id` (string) - The ID of the snapshot - `volume_type` (string) - The volume type. gp2 for General Purpose (SSD) - volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic - volumes + volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic + volumes - `volume_size` (integer) - The size of the volume, in GiB. Required if not - specifying a `snapshot_id` + specifying a `snapshot_id` - `delete_on_termination` (boolean) - Indicates whether the EBS volume is - deleted on instance termination + deleted on instance termination - `encrypted` (boolean) - Indicates whether to encrypt the volume or not - `no_device` (boolean) - Suppresses the specified device included in the - block device mapping of the AMI + block device mapping of the AMI - `iops` (integer) - The number of I/O operations per second (IOPS) that the - volume supports. See the documentation on [IOPs][2] for more information + volume supports. See the documentation on + [IOPs](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) + for more information +- `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. AWS currently doesn't accept any + value other than "all". -* `ami_description` (string) - The description to set for the resulting - AMI(s). By default this description is empty. +- `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_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. - AWS currently doesn't accept any value other than "all". +- `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_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_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_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. - -* `associate_public_ip_address` (boolean) - If using a non-default VPC, public +- `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. -* `availability_zone` (string) - Destination availability zone to launch instance in. - Leave this empty to allow Amazon to auto-assign. +- `availability_zone` (string) - Destination availability zone to launch + instance in. Leave this empty to allow Amazon to auto-assign. -* `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) on - HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. +- `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) + on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS + IAM policy. -* `force_deregister` (boolean) - Force Packer to first deregister an existing -AMI if one with the same name already exists. Default `false`. +- `force_deregister` (boolean) - Force Packer to first deregister an existing + AMI if one with the same name already exists. Default `false`. -* `iam_instance_profile` (string) - The name of an - [IAM instance profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) +- `iam_instance_profile` (string) - The name of an [IAM instance + profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) to launch the EC2 instance with. -* `launch_block_device_mappings` (array of block device mappings) - Add the +- `launch_block_device_mappings` (array of block device mappings) - Add the block device mappings to the launch instance. The block device mappings are the same as `ami_block_device_mappings` above. -* `run_tags` (object of key/value strings) - Tags to apply to the instance - that is _launched_ to create the AMI. These tags are _not_ applied to - the resulting AMI unless they're duplicated in `tags`. +- `run_tags` (object of key/value strings) - Tags to apply to the instance that + is *launched* to create the AMI. These tags are *not* applied to the resulting + AMI unless they're duplicated in `tags`. -* `security_group_id` (string) - The ID (_not_ the name) of the security - group to assign to the instance. By default this is not set and Packer - will automatically create a new temporary security group to allow SSH - access. Note that if this is specified, you must be sure the security - group allows access to the `ssh_port` given below. +- `security_group_id` (string) - The ID (*not* the name) of the security group + to assign to the instance. By default this is not set and Packer will + automatically create a new temporary security group to allow SSH 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 strings) - 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`. -* `spot_price` (string) - The maximum hourly price to pay for a spot instance - to create the AMI. Spot instances are a type of instance that EC2 starts when - the current spot price is less than the maximum price you specify. Spot price - will be updated based on available spot instance capacity and current spot +- `spot_price` (string) - The maximum hourly price to pay for a spot instance to + create the AMI. Spot instances are a type of instance that EC2 starts when the + current spot price is less than the maximum price you specify. Spot price will + be updated based on available spot instance capacity and current spot instance requests. It may save you some costs. You can set this to "auto" for Packer to automatically discover the best spot price. -* `spot_price_auto_product` (string) - Required if `spot_price` is set to - "auto". This tells Packer what sort of AMI you're launching to find the best - spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, - `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)` +- `spot_price_auto_product` (string) - Required if `spot_price` is set + to "auto". This tells Packer what sort of AMI you're launching to find the + best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, + `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)` -* `ssh_keypair_name` (string) - If specified, this is the key that will be - used for SSH with the machine. By default, this is blank, and Packer will - generate a temporary keypair. `ssh_private_key_file` must be specified - with this. +- `ssh_keypair_name` (string) - If specified, this is the key that will be used + for SSH with the machine. By default, this is blank, and Packer will generate + a temporary keypair. `ssh_private_key_file` must be specified with this. -* `ssh_private_ip` (boolean) - If true, then SSH will always use the private - IP if available. +- `ssh_private_ip` (boolean) - If true, then SSH will always use the private IP + if available. -* `subnet_id` (string) - If using VPC, the ID of the subnet, such as +- `subnet_id` (string) - If using VPC, the ID of the subnet, such as "subnet-12345def", where Packer will launch the EC2 instance. This field is required if you are using an non-default VPC. -* `tags` (object of key/value strings) - Tags applied to the AMI and +- `tags` (object of key/value strings) - Tags applied to the AMI and relevant snapshots. -* `temporary_key_pair_name` (string) - The name of the temporary keypair +- `temporary_key_pair_name` (string) - The name of the temporary keypair to generate. By default, Packer generates a name with a UUID. -* `token` (string) - The access token to use. This is different from - the access key and secret key. If you're not sure what this is, then you - probably don't need it. This will also be read from the `AWS_SECURITY_TOKEN` +- `token` (string) - The access token to use. This is different from the access + key and secret key. If you're not sure what this is, then you probably don't + need it. This will also be read from the `AWS_SECURITY_TOKEN` environmental variable. -* `user_data` (string) - User data to apply when launching the instance. - Note that you need to be careful about escaping characters due to the - templates being JSON. It is often more convenient to use `user_data_file`, - instead. +- `user_data` (string) - User data to apply when launching the instance. Note + that you need to be careful about escaping characters due to the templates + being JSON. It is often more convenient to use `user_data_file`, instead. -* `user_data_file` (string) - Path to a file that will be used for the - user data when launching the instance. +- `user_data_file` (string) - Path to a file that will be used for the user data + when launching the instance. -* `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. +- `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. -* `windows_password_timeout` (string) - The timeout for waiting for - a Windows password for Windows instances. Defaults to 20 minutes. - Example value: "10m" +- `windows_password_timeout` (string) - The timeout for waiting for a Windows + password for Windows instances. Defaults to 20 minutes. Example value: "10m" ## Basic Example Here is a basic example. It is completely valid except for the access keys: -```javascript +``` {.javascript} { "type": "amazon-ebs", "access_key": "YOUR KEY HERE", @@ -208,25 +214,23 @@ Here is a basic example. It is completely valid except for the access keys: } ``` --> **Note:** Packer can also read the access key and secret -access key from environmental variables. See the configuration reference in -the section above for more information on what environmental variables Packer -will look for. +-> **Note:** Packer can also read the access key and secret access key from +environmental variables. See the configuration reference in the section above +for more information on what environmental variables Packer will look for. ## Accessing the Instance to Debug If you need to access the instance to debug for some reason, run the builder -with the `-debug` flag. In debug mode, the Amazon builder will save the -private key in the current directory and will output the DNS or IP information -as well. You can use this information to access the instance as it is -running. +with the `-debug` flag. In debug mode, the Amazon builder will save the private +key in the current directory and will output the DNS or IP information as well. +You can use this information to access the instance as it is running. ## AMI Block Device Mappings Example Here is an example using the optional AMI block device mappings. This will add the /dev/sdb and /dev/sdc block device mappings to the finished AMI. -```javascript +``` {.javascript} { "type": "amazon-ebs", "access_key": "YOUR KEY HERE", @@ -252,9 +256,9 @@ the /dev/sdb and /dev/sdc block device mappings to the finished AMI. ## Tag Example Here is an example using the optional AMI tags. This will add the tags -"OS_Version" and "Release" to the finished AMI. +"OS\_Version" and "Release" to the finished AMI. -```javascript +``` {.javascript} { "type": "amazon-ebs", "access_key": "YOUR KEY HERE", @@ -271,13 +275,10 @@ Here is an example using the optional AMI tags. This will add the tags } ``` --> **Note:** Packer uses pre-built AMIs as the source for building images. +-> **Note:** Packer uses pre-built AMIs as the source for building images. These source AMIs may include volumes that are not flagged to be destroyed on termiation of the instance building the new image. Packer will attempt to clean up all residual volumes that are not designated by the user to remain after termination. If you need to preserve those source volumes, you can overwrite the termination setting by specifying `delete_on_termination=false` in the `launch_device_mappings` block for the device. - -[1]: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html -[2]: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html diff --git a/website/source/docs/builders/amazon-instance.html.markdown b/website/source/docs/builders/amazon-instance.html.markdown index fa3c8a190..5ff36ccf2 100644 --- a/website/source/docs/builders/amazon-instance.html.markdown +++ b/website/source/docs/builders/amazon-instance.html.markdown @@ -1,9 +1,12 @@ --- -layout: "docs" -page_title: "Amazon AMI Builder (instance-store)" -description: |- - The `amazon-instance` Packer builder is able to create Amazon AMIs backed by instance storage as the root device. For more information on the difference between instance storage and EBS-backed instances, see the storage for the root device section in the EC2 documentation. ---- +description: | + The `amazon-instance` Packer builder is able to create Amazon AMIs backed by + instance storage as the root device. For more information on the difference + between instance storage and EBS-backed instances, see the storage for the root + device section in the EC2 documentation. +layout: docs +page_title: 'Amazon AMI Builder (instance-store)' +... # AMI Builder (instance-store) @@ -11,24 +14,24 @@ Type: `amazon-instance` The `amazon-instance` Packer builder is able to create Amazon AMIs backed by instance storage as the root device. For more information on the difference -between instance storage and EBS-backed instances, see the -["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). +between instance storage and EBS-backed instances, see the ["storage for the +root device" section in the EC2 +documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). This builder builds an AMI by launching an EC2 instance from an existing instance-storage backed AMI, provisioning that running machine, and then -bundling and creating a new AMI from that machine. -This is all done in your own AWS account. The builder will create temporary -keypairs, security group rules, etc. that provide it temporary access to -the instance while the image is being created. This simplifies configuration -quite a bit. +bundling and creating a new AMI from that machine. This is all done in your own +AWS account. The builder will create temporary keypairs, security group rules, +etc. that provide it temporary access to the instance while the image is being +created. This simplifies configuration quite a bit. -The builder does _not_ manage AMIs. Once it creates an AMI and stores it -in your account, it is up to you to use, delete, etc. the AMI. +The builder does *not* manage AMIs. Once it creates an AMI and stores it in your +account, it is up to you to use, delete, etc. the AMI. --> **Note** This builder requires that the -[Amazon EC2 AMI Tools](http://aws.amazon.com/developertools/368) -are installed onto the machine. This can be done within a provisioner, but -must be done before the builder finishes running. +-> **Note** This builder requires that the [Amazon EC2 AMI +Tools](http://aws.amazon.com/developertools/368) are installed onto the machine. +This can be done within a provisioner, but must be done before the builder +finishes running. ## Configuration Reference @@ -37,204 +40,207 @@ segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `access_key` (string) - The access key used to communicate with AWS. - If not specified, Packer will use the key from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file - or fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. +- `access_key` (string) - The access key used to communicate with AWS. If not + specified, Packer will use the key from any + [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) + file or fall back to 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 - account ID in the security credentials page of your AWS account. +- `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 account + ID in the security credentials page of your AWS account. -* `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. - To help make this unique, use a function like `timestamp` (see - [configuration templates](/docs/templates/configuration-templates.html) for more info) +- `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. To help + make this unique, use a function like `timestamp` (see [configuration + templates](/docs/templates/configuration-templates.html) for more info) -* `instance_type` (string) - The EC2 instance type to use while building - the AMI, such as "m1.small". +- `instance_type` (string) - The EC2 instance type to use while building the + AMI, such as "m1.small". -* `region` (string) - The name of the region, such as "us-east-1", in which - to launch the EC2 instance to create the AMI. +- `region` (string) - The name of the region, such as "us-east-1", in which to + launch the EC2 instance to create the AMI. -* `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. - This bucket will be created if it doesn't exist. +- `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. 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 use the secret from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file - or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. +- `secret_key` (string) - The secret key used to communicate with AWS. If not + specified, Packer will use the secret from any + [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) + file or fall back to 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 +- `source_ami` (string) - The initial AMI used as a base for the newly created machine. -* `ssh_username` (string) - The username to use in order to communicate - over SSH to the running machine. +- `ssh_username` (string) - The username to use in order to communicate over SSH + to the running machine. -* `x509_cert_path` (string) - The local path to a valid X509 certificate for +- `x509_cert_path` (string) - The local path to a valid X509 certificate for your AWS account. This is used for bundling the AMI. This X509 certificate - must be registered with your account from the security credentials page - in the AWS console. + must be registered with your account from the security credentials page in the + AWS console. -* `x509_key_path` (string) - The local path to the private key for the X509 +- `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: -* `ami_block_device_mappings` (array of block device mappings) - Add the block +- `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) - The device name exposed to the instance (for - example, "/dev/sdh" or "xvdh") + example, "/dev/sdh" or "xvdh") - `virtual_name` (string) - The virtual device name. See the documentation on - [Block Device Mapping][1] for more information + [Block Device + Mapping](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) + for more information - `snapshot_id` (string) - The ID of the snapshot - `volume_type` (string) - The volume type. gp2 for General Purpose (SSD) - volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic - volumes + volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic + volumes - `volume_size` (integer) - The size of the volume, in GiB. Required if not - specifying a `snapshot_id` + specifying a `snapshot_id` - `delete_on_termination` (boolean) - Indicates whether the EBS volume is - deleted on instance termination + deleted on instance termination - `encrypted` (boolean) - Indicates whether to encrypt the volume or not - `no_device` (boolean) - Suppresses the specified device included in the - block device mapping of the AMI + block device mapping of the AMI - `iops` (integer) - The number of I/O operations per second (IOPS) that the - volume supports. See the documentation on [IOPs][2] for more information + volume supports. See the documentation on + [IOPs](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) + for more information +- `ami_description` (string) - The description to set for the resulting AMI(s). + By default this description is empty. -* `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. AWS currently doesn't accept any + value other than "all". -* `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. - AWS currently doesn't accept any value other than "all". +- `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_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_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_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 +- `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". -* `associate_public_ip_address` (boolean) - If using a non-default VPC, public +- `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. + instance will get a Public IP. -* `availability_zone` (string) - Destination availability zone to launch instance in. - Leave this empty to allow Amazon to auto-assign. +- `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 - "/tmp". This directory must exist and be writable. +- `bundle_destination` (string) - The directory on the running instance where + the bundled AMI will be saved prior to uploading. By default this is "/tmp". + This directory must exist and be writable. -* `bundle_prefix` (string) - The prefix for files created from bundling - the root volume. By default this is "image-{{timestamp}}". The `timestamp` - variable should be used to make sure this is unique, otherwise it can - collide with other created AMIs by Packer in your account. +- `bundle_prefix` (string) - The prefix for files created from bundling the + root volume. By default this is "image-{{timestamp}}". The `timestamp` + variable should be used to make sure this is unique, otherwise it can collide + with other created AMIs by Packer in your account. -* `bundle_upload_command` (string) - The command to use to upload the - bundled volume. See the "custom bundle commands" section below for more - information. +- `bundle_upload_command` (string) - The command to use to upload the + bundled volume. See the "custom bundle commands" section below for + more information. -* `bundle_vol_command` (string) - The command to use to bundle the volume. - See the "custom bundle commands" section below for more information. +- `bundle_vol_command` (string) - The command to use to bundle the volume. See + the "custom bundle commands" section below for more information. -* `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) on - HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. +- `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) + on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS + IAM policy. -* `force_deregister` (boolean) - Force Packer to first deregister an existing -AMI if one with the same name already exists. Default `false`. +- `force_deregister` (boolean) - Force Packer to first deregister an existing + AMI if one with the same name already exists. Default `false`. -* `iam_instance_profile` (string) - The name of an - [IAM instance profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) +- `iam_instance_profile` (string) - The name of an [IAM instance + profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) to launch the EC2 instance with. -* `launch_block_device_mappings` (array of block device mappings) - Add the +- `launch_block_device_mappings` (array of block device mappings) - Add the block device mappings to the launch instance. The block device mappings are the same as `ami_block_device_mappings` above. -* `run_tags` (object of key/value strings) - Tags to apply to the instance - that is _launched_ to create the AMI. These tags are _not_ applied to - the resulting AMI unless they're duplicated in `tags`. +- `run_tags` (object of key/value strings) - Tags to apply to the instance that + is *launched* to create the AMI. These tags are *not* applied to the resulting + AMI unless they're duplicated in `tags`. -* `security_group_id` (string) - The ID (_not_ the name) of the security - group to assign to the instance. By default this is not set and Packer - will automatically create a new temporary security group to allow SSH - access. Note that if this is specified, you must be sure the security - group allows access to the `ssh_port` given below. +- `security_group_id` (string) - The ID (*not* the name) of the security group + to assign to the instance. By default this is not set and Packer will + automatically create a new temporary security group to allow SSH 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 strings) - 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`. -* `spot_price` (string) - The maximum hourly price to launch a spot instance - to create the AMI. It is a type of instances that EC2 starts when the maximum +- `spot_price` (string) - The maximum hourly price to launch a spot instance to + create the AMI. It is a type of instances that EC2 starts when the maximum price that you specify exceeds the current spot price. Spot price will be - updated based on available spot instance capacity and current spot Instance - requests. It may save you some costs. You can set this to "auto" for + updated based on available spot instance capacity and current spot + Instance requests. It may save you some costs. You can set this to "auto" for Packer to automatically discover the best spot price. -* `spot_price_auto_product` (string) - Required if `spot_price` is set to - "auto". This tells Packer what sort of AMI you're launching to find the best - spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, - `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)` +- `spot_price_auto_product` (string) - Required if `spot_price` is set + to "auto". This tells Packer what sort of AMI you're launching to find the + best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, + `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)` -* `ssh_keypair_name` (string) - If specified, this is the key that will be - used for SSH with the machine. By default, this is blank, and Packer will - generate a temporary keypair. `ssh_private_key_file` must be specified - with this. +- `ssh_keypair_name` (string) - If specified, this is the key that will be used + for SSH with the machine. By default, this is blank, and Packer will generate + a temporary keypair. `ssh_private_key_file` must be specified with this. -* `ssh_private_ip` (boolean) - If true, then SSH will always use the private - IP if available. +- `ssh_private_ip` (boolean) - If true, then SSH will always use the private IP + if available. -* `subnet_id` (string) - If using VPC, the ID of the subnet, such as +- `subnet_id` (string) - If using VPC, the ID of the subnet, such as "subnet-12345def", where Packer will launch the EC2 instance. This field is required if you are using an non-default VPC. -* `tags` (object of key/value strings) - Tags applied to the AMI. +- `tags` (object of key/value strings) - Tags applied to the AMI. -* `temporary_key_pair_name` (string) - The name of the temporary keypair +- `temporary_key_pair_name` (string) - The name of the temporary keypair to generate. By default, Packer generates a name with a UUID. -* `user_data` (string) - User data to apply when launching the instance. - Note that you need to be careful about escaping characters due to the - templates being JSON. It is often more convenient to use `user_data_file`, - instead. +- `user_data` (string) - User data to apply when launching the instance. Note + that you need to be careful about escaping characters due to the templates + being JSON. It is often more convenient to use `user_data_file`, instead. -* `user_data_file` (string) - Path to a file that will be used for the - user data when launching the instance. +- `user_data_file` (string) - Path to a file that will be used for the user data + when launching the instance. -* `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. +- `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. -* `x509_upload_path` (string) - The path on the remote machine where the - X509 certificate will be uploaded. This path must already exist and be - writable. X509 certificates are uploaded after provisioning is run, so - it is perfectly okay to create this directory as part of the provisioning - process. +- `x509_upload_path` (string) - The path on the remote machine where the X509 + certificate will be uploaded. This path must already exist and be writable. + X509 certificates are uploaded after provisioning is run, so it is perfectly + okay to create this directory as part of the provisioning process. -* `windows_password_timeout` (string) - The timeout for waiting for - a Windows password for Windows instances. Defaults to 20 minutes. - Example value: "10m" +- `windows_password_timeout` (string) - The timeout for waiting for a Windows + password for Windows instances. Defaults to 20 minutes. Example value: "10m" ## Basic Example Here is a basic example. It is completely valid except for the access keys: -```javascript +``` {.javascript} { "type": "amazon-instance", "access_key": "YOUR KEY HERE", @@ -254,84 +260,79 @@ Here is a basic example. It is completely valid except for the access keys: } ``` --> **Note:** Packer can also read the access key and secret -access key from environmental variables. See the configuration reference in -the section above for more information on what environmental variables Packer -will look for. +-> **Note:** Packer can also read the access key and secret access key from +environmental variables. See the configuration reference in the section above +for more information on what environmental variables Packer will look for. ## Accessing the Instance to Debug If you need to access the instance to debug for some reason, run the builder -with the `-debug` flag. In debug mode, the Amazon builder will save the -private key in the current directory and will output the DNS or IP information -as well. You can use this information to access the instance as it is -running. +with the `-debug` flag. In debug mode, the Amazon builder will save the private +key in the current directory and will output the DNS or IP information as well. +You can use this information to access the instance as it is running. ## Custom Bundle Commands -A lot of the process required for creating an instance-store backed AMI -involves commands being run on the actual source instance. Specifically, the -`ec2-bundle-vol` and `ec2-upload-bundle` commands must be used to bundle -the root filesystem and upload it, respectively. +A lot of the process required for creating an instance-store backed AMI involves +commands being run on the actual source instance. Specifically, the +`ec2-bundle-vol` and `ec2-upload-bundle` commands must be used to bundle the +root filesystem and upload it, respectively. Each of these commands have a lot of available flags. Instead of exposing each -possible flag as a template configuration option, the instance-store AMI -builder for Packer lets you customize the entire command used to bundle -and upload the AMI. +possible flag as a template configuration option, the instance-store AMI builder +for Packer lets you customize the entire command used to bundle and upload the +AMI. -These are configured with `bundle_vol_command` and `bundle_upload_command`. -Both of these configurations are -[configuration templates](/docs/templates/configuration-templates.html) -and have support for their own set of template variables. +These are configured with `bundle_vol_command` and `bundle_upload_command`. Both +of these configurations are [configuration +templates](/docs/templates/configuration-templates.html) and have support for +their own set of template variables. ### Bundle Volume Command -The default value for `bundle_vol_command` is shown below. It is split -across multiple lines for convenience of reading. The bundle volume command -is responsible for executing `ec2-bundle-vol` in order to store and image -of the root filesystem to use to create the AMI. +The default value for `bundle_vol_command` is shown below. It is split across +multiple lines for convenience of reading. The bundle volume command is +responsible for executing `ec2-bundle-vol` in order to store and image of the +root filesystem to use to create the AMI. -```text +``` {.text} sudo -i -n ec2-bundle-vol \ - -k {{.KeyPath}} \ - -u {{.AccountId}} \ - -c {{.CertPath}} \ - -r {{.Architecture}} \ - -e {{.PrivatePath}}/* \ - -d {{.Destination}} \ - -p {{.Prefix}} \ - --batch \ - --no-filter + -k {{.KeyPath}} \ + -u {{.AccountId}} \ + -c {{.CertPath}} \ + -r {{.Architecture}} \ + -e {{.PrivatePath}}/* \ + -d {{.Destination}} \ + -p {{.Prefix}} \ + --batch \ + --no-filter ``` The available template variables should be self-explanatory based on the parameters they're used to satisfy the `ec2-bundle-vol` command. -~> **Warning!** Some versions of ec2-bundle-vol silently ignore all .pem and +\~> **Warning!** Some versions of ec2-bundle-vol silently ignore all .pem and .gpg files during the bundling of the AMI, which can cause problems on some -systems, such as Ubuntu. You may want to customize the bundle volume command -to include those files (see the `--no-filter` option of ec2-bundle-vol). +systems, such as Ubuntu. You may want to customize the bundle volume command to +include those files (see the `--no-filter` option of ec2-bundle-vol). ### Bundle Upload Command -The default value for `bundle_upload_command` is shown below. It is split -across multiple lines for convenience of reading. The bundle upload command -is responsible for taking the bundled volume and uploading it to S3. +The default value for `bundle_upload_command` is shown below. It is split across +multiple lines for convenience of reading. The bundle upload command is +responsible for taking the bundled volume and uploading it to S3. -```text +``` {.text} sudo -i -n ec2-upload-bundle \ - -b {{.BucketName}} \ - -m {{.ManifestPath}} \ - -a {{.AccessKey}} \ - -s {{.SecretKey}} \ - -d {{.BundleDirectory}} \ - --batch \ - --region {{.Region}} \ - --retry + -b {{.BucketName}} \ + -m {{.ManifestPath}} \ + -a {{.AccessKey}} \ + -s {{.SecretKey}} \ + -d {{.BundleDirectory}} \ + --batch \ + --region {{.Region}} \ + --retry ``` The available template variables should be self-explanatory based on the parameters they're used to satisfy the `ec2-upload-bundle` command. - -[1]: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html -[2]: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html diff --git a/website/source/docs/builders/amazon.html.markdown b/website/source/docs/builders/amazon.html.markdown index ad336ad1c..69b4e509b 100644 --- a/website/source/docs/builders/amazon.html.markdown +++ b/website/source/docs/builders/amazon.html.markdown @@ -1,44 +1,47 @@ --- -layout: "docs" -page_title: "Amazon AMI Builder" -description: |- - Packer is able to create Amazon AMIs. To achieve this, Packer comes with multiple builders depending on the strategy you want to use to build the AMI. ---- +description: | + Packer is able to create Amazon AMIs. To achieve this, Packer comes with + multiple builders depending on the strategy you want to use to build the AMI. +layout: docs +page_title: Amazon AMI Builder +... # Amazon AMI Builder Packer is able to create Amazon AMIs. To achieve this, Packer comes with -multiple builders depending on the strategy you want to use to build the -AMI. Packer supports the following builders at the moment: +multiple builders depending on the strategy you want to use to build the AMI. +Packer supports the following builders at the moment: -* [amazon-ebs](/docs/builders/amazon-ebs.html) - Create EBS-backed AMIs - by launching a source AMI and re-packaging it into a new AMI after - provisioning. If in doubt, use this builder, which is the easiest to get - started with. +- [amazon-ebs](/docs/builders/amazon-ebs.html) - Create EBS-backed AMIs by + launching a source AMI and re-packaging it into a new AMI after provisioning. + If in doubt, use this builder, which is the easiest to get started with. -* [amazon-instance](/docs/builders/amazon-instance.html) - Create - instance-store AMIs by launching and provisioning a source instance, then - rebundling it and uploading it to S3. +- [amazon-instance](/docs/builders/amazon-instance.html) - Create instance-store + AMIs by launching and provisioning a source instance, then rebundling it and + uploading it to S3. -* [amazon-chroot](/docs/builders/amazon-chroot.html) - Create EBS-backed AMIs +- [amazon-chroot](/docs/builders/amazon-chroot.html) - Create EBS-backed AMIs from an existing EC2 instance by mounting the root device and using a [Chroot](http://en.wikipedia.org/wiki/Chroot) environment to provision that device. This is an **advanced builder and should not be used by - newcomers**. However, it is also the fastest way to build an EBS-backed - AMI since no new EC2 instance needs to be launched. + newcomers**. However, it is also the fastest way to build an EBS-backed AMI + since no new EC2 instance needs to be launched. --> **Don't know which builder to use?** If in doubt, use the -[amazon-ebs builder](/docs/builders/amazon-ebs.html). It is -much easier to use and Amazon generally recommends EBS-backed images nowadays. +-> **Don't know which builder to use?** If in doubt, use the [amazon-ebs +builder](/docs/builders/amazon-ebs.html). It is much easier to use and Amazon +generally recommends EBS-backed images nowadays. ## Using an IAM Instance Profile -If AWS keys are not specified in the template, a [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file or through environment variables -Packer will use credentials provided by the instance's IAM profile, if it has one. +If AWS keys are not specified in the template, a +[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) +file or through environment variables Packer will use credentials provided by +the instance's IAM profile, if it has one. -The following policy document provides the minimal set permissions necessary for Packer to work: +The following policy document provides the minimal set permissions necessary for +Packer to work: -```javascript +``` {.javascript} { "Statement": [{ "Effect": "Allow", diff --git a/website/source/docs/builders/custom.html.markdown b/website/source/docs/builders/custom.html.markdown index a737c1bd1..dc6928d4b 100644 --- a/website/source/docs/builders/custom.html.markdown +++ b/website/source/docs/builders/custom.html.markdown @@ -1,13 +1,15 @@ --- -layout: "docs" -page_title: "Custom Builder" -description: |- - Packer is extensible, allowing you to write new builders without having to modify the core source code of Packer itself. Documentation for creating new builders is covered in the custom builders page of the Packer plugin section. ---- +description: | + Packer is extensible, allowing you to write new builders without having to + modify the core source code of Packer itself. Documentation for creating new + builders is covered in the custom builders page of the Packer plugin section. +layout: docs +page_title: Custom Builder +... # Custom Builder Packer is extensible, allowing you to write new builders without having to -modify the core source code of Packer itself. Documentation for creating -new builders is covered in the [custom builders](/docs/extend/builder.html) -page of the Packer plugin section. +modify the core source code of Packer itself. Documentation for creating new +builders is covered in the [custom builders](/docs/extend/builder.html) page of +the Packer plugin section. diff --git a/website/source/docs/builders/digitalocean.html.markdown b/website/source/docs/builders/digitalocean.html.markdown index c9ef3b315..b20523944 100644 --- a/website/source/docs/builders/digitalocean.html.markdown +++ b/website/source/docs/builders/digitalocean.html.markdown @@ -1,22 +1,26 @@ --- -layout: "docs" -page_title: "DigitalOcean Builder" -description: |- - The `digitalocean` Packer builder is able to create new images for use with DigitalOcean. The builder takes a source image, runs any provisioning necessary on the image after launching it, then snapshots it into a reusable image. This reusable image can then be used as the foundation of new servers that are launched within DigitalOcean. ---- +description: | + The `digitalocean` Packer builder is able to create new images for use with + DigitalOcean. The builder takes a source image, runs any provisioning necessary + on the image after launching it, then snapshots it into a reusable image. This + reusable image can then be used as the foundation of new servers that are + launched within DigitalOcean. +layout: docs +page_title: DigitalOcean Builder +... # DigitalOcean Builder Type: `digitalocean` The `digitalocean` Packer builder is able to create new images for use with -[DigitalOcean](http://www.digitalocean.com). The builder takes a source -image, runs any provisioning necessary on the image after launching it, -then snapshots it into a reusable image. This reusable image can then be -used as the foundation of new servers that are launched within DigitalOcean. +[DigitalOcean](http://www.digitalocean.com). The builder takes a source image, +runs any provisioning necessary on the image after launching it, then snapshots +it into a reusable image. This reusable image can then be used as the foundation +of new servers that are launched within DigitalOcean. -The builder does _not_ manage images. Once it creates an image, it is up to -you to use it or delete it. +The builder does *not* manage images. Once it creates an image, it is up to you +to use it or delete it. ## Configuration Reference @@ -25,50 +29,53 @@ segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `api_token` (string) - The client TOKEN to use to access your account. - It can also be specified via environment variable `DIGITALOCEAN_API_TOKEN`, if set. +- `api_token` (string) - The client TOKEN to use to access your account. It can + also be specified via environment variable `DIGITALOCEAN_API_TOKEN`, if set. -* `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. - See https://developers.digitalocean.com/documentation/v2/#list-all-images for details on how to get a list of the the accepted image names/slugs. +- `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. See + https://developers.digitalocean.com/documentation/v2/\#list-all-images for + details on how to get a list of the the accepted image names/slugs. -* `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. - See https://developers.digitalocean.com/documentation/v2/#list-all-regions for the accepted region names/slugs. +- `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. See + https://developers.digitalocean.com/documentation/v2/\#list-all-regions for + the accepted region names/slugs. -* `size` (string) - The name (or slug) of the droplet size to use. - See https://developers.digitalocean.com/documentation/v2/#list-all-sizes for the accepted size names/slugs. +- `size` (string) - The name (or slug) of the droplet size to use. See + https://developers.digitalocean.com/documentation/v2/\#list-all-sizes for the + accepted size names/slugs. ### Optional: -* `droplet_name` (string) - The name assigned to the droplet. DigitalOcean - sets the hostname of the machine to this value. +- `droplet_name` (string) - The name assigned to the droplet. DigitalOcean sets + the hostname of the machine to this value. -* `private_networking` (boolean) - Set to `true` to enable private networking +- `private_networking` (boolean) - 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) +- `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) -* `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". +- `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". -* `user_data` (string) - User data to launch with the Droplet. +- `user_data` (string) - User data to launch with the Droplet. ## Basic Example -Here is a basic example. It is completely valid as soon as you enter your -own access tokens: +Here is a basic example. It is completely valid as soon as you enter your own +access tokens: -```javascript +``` {.javascript} { "type": "digitalocean", "api_token": "YOUR API KEY", diff --git a/website/source/docs/builders/docker.html.markdown b/website/source/docs/builders/docker.html.markdown index b5fe95075..b2fab5b19 100644 --- a/website/source/docs/builders/docker.html.markdown +++ b/website/source/docs/builders/docker.html.markdown @@ -1,39 +1,40 @@ --- -layout: "docs" -page_title: "Docker Builder" -description: |- - The `docker` Packer builder builds Docker images using Docker. The builder starts a Docker container, runs provisioners within this container, then exports the container for reuse or commits the image. ---- +description: | + The `docker` Packer builder builds Docker images using Docker. The builder + starts a Docker container, runs provisioners within this container, then exports + the container for reuse or commits the image. +layout: docs +page_title: Docker Builder +... # Docker Builder Type: `docker` The `docker` Packer builder builds [Docker](http://www.docker.io) images using -Docker. The builder starts a Docker container, runs provisioners within -this container, then exports the container for reuse or commits the image. +Docker. The builder starts a Docker container, runs provisioners within this +container, then exports the container for reuse or commits the image. -Packer builds Docker containers _without_ the use of -[Dockerfiles](https://docs.docker.com/reference/builder/). -By not using Dockerfiles, Packer is able to provision -containers with portable scripts or configuration management systems -that are not tied to Docker in any way. It also has a simpler mental model: -you provision containers much the same way you provision a normal virtualized -or dedicated server. For more information, read the section on -[Dockerfiles](#toc_8). +Packer builds Docker containers *without* the use of +[Dockerfiles](https://docs.docker.com/reference/builder/). By not using +Dockerfiles, Packer is able to provision containers with portable scripts or +configuration management systems that are not tied to Docker in any way. It also +has a simpler mental model: you provision containers much the same way you +provision a normal virtualized or dedicated server. For more information, read +the section on [Dockerfiles](#toc_8). The Docker builder must run on a machine that has Docker installed. Therefore the builder only works on machines that support Docker (modern Linux machines). -If you want to use Packer to build Docker containers on another platform, -use [Vagrant](http://www.vagrantup.com) to start a Linux environment, then -run Packer within that environment. +If you want to use Packer to build Docker containers on another platform, use +[Vagrant](http://www.vagrantup.com) to start a Linux environment, then run +Packer within that environment. ## Basic Example: Export -Below is a fully functioning example. It doesn't do anything useful, since -no provisioners are defined, but it will effectively repackage an image. +Below is a fully functioning example. It doesn't do anything useful, since no +provisioners are defined, but it will effectively repackage an image. -```javascript +``` {.javascript} { "type": "docker", "image": "ubuntu", @@ -43,11 +44,11 @@ no provisioners are defined, but it will effectively repackage an image. ## Basic Example: Commit -Below is another example, the same as above but instead of exporting the -running container, this one commits the container to an image. The image -can then be more easily tagged, pushed, etc. +Below is another example, the same as above but instead of exporting the running +container, this one commits the container to an image. The image can then be +more easily tagged, pushed, etc. -```javascript +``` {.javascript} { "type": "docker", "image": "ubuntu", @@ -55,7 +56,6 @@ can then be more easily tagged, pushed, etc. } ``` - ## Configuration Reference Configuration options are organized below into two categories: required and @@ -63,47 +63,47 @@ optional. Within each category, the available options are alphabetized and described. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `commit` (boolean) - If true, the container will be committed to an - image rather than exported. This cannot be set if `export_path` is set. +- `commit` (boolean) - If true, the container will be committed to an image + rather than exported. This cannot be set if `export_path` is set. -* `export_path` (string) - The path where the final container will be exported +- `export_path` (string) - The path where the final container will be exported as a tar file. This cannot be set if `commit` is set to true. -* `image` (string) - The base image for the Docker container that will - be started. This image will be pulled from the Docker registry if it - doesn't already exist. +- `image` (string) - The base image for the Docker container that will + be started. This image will be pulled from the Docker registry if it doesn't + already exist. ### Optional: -* `login` (boolean) - Defaults to false. If true, the builder will - login in order to pull the image. The builder only logs in for the - duration of the pull. It always logs out afterwards. +- `login` (boolean) - Defaults to false. If true, the builder will login in + order to pull the image. The builder only logs in for the duration of + the pull. It always logs out afterwards. -* `login_email` (string) - The email to use to authenticate to login. +- `login_email` (string) - The email to use to authenticate to login. -* `login_username` (string) - The username to use to authenticate to login. +- `login_username` (string) - The username to use to authenticate to login. -* `login_password` (string) - The password to use to authenticate to login. +- `login_password` (string) - The password to use to authenticate to login. -* `login_server` (string) - The server address to login to. +- `login_server` (string) - The server address to login to. -* `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. +- `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. -* `run_command` (array of strings) - An array of arguments to pass to +- `run_command` (array of strings) - An array of arguments to pass to `docker run` in order to run the container. By default this is set to - `["-d", "-i", "-t", "{{.Image}}", "/bin/bash"]`. - As you can see, you have a couple template variables to customize, as well. + `["-d", "-i", "-t", "{{.Image}}", "/bin/bash"]`. As you can see, you have a + couple template variables to customize, as well. -* `volumes` (map of strings to strings) - A mapping of additional volumes - to mount into this container. The key of the object is the host path, - the value is the container path. +- `volumes` (map of strings to strings) - A mapping of additional volumes to + mount into this container. The key of the object is the host path, the value + is the container path. ## Using the Artifact: Export @@ -113,27 +113,26 @@ with the [docker-import](/docs/post-processors/docker-import.html) and [docker-push](/docs/post-processors/docker-push.html) post-processors. **Note:** This section is covering how to use an artifact that has been -_exported_. More specifically, if you set `export_path` in your configuration. +*exported*. More specifically, if you set `export_path` in your configuration. If you set `commit`, see the next section. -The example below shows a full configuration that would import and push -the created image. This is accomplished using a sequence definition (a -collection of post-processors that are treated as as single pipeline, see -[Post-Processors](/docs/templates/post-processors.html) -for more information): +The example below shows a full configuration that would import and push the +created image. This is accomplished using a sequence definition (a collection of +post-processors that are treated as as single pipeline, see +[Post-Processors](/docs/templates/post-processors.html) for more information): -```javascript +``` {.javascript} { "post-processors": [ - [ - { - "type": "docker-import", - "repository": "mitchellh/packer", - "tag": "0.7" - }, - "docker-push" - ] - ] + [ + { + "type": "docker-import", + "repository": "mitchellh/packer", + "tag": "0.7" + }, + "docker-push" + ] + ] } ``` @@ -143,10 +142,10 @@ post-processor which will import the artifact as a docker image. The resulting docker image is then passed on to the `docker-push` post-processor which handles pushing the image to a container repository. -If you want to do this manually, however, perhaps from a script, you can -import the image using the process below: +If you want to do this manually, however, perhaps from a script, you can import +the image using the process below: -```text +``` {.text} $ docker import - registry.mydomain.com/mycontainer:latest < artifact.tar ``` @@ -157,23 +156,22 @@ and `docker push`, respectively. If you committed your container to an image, you probably want to tag, save, push, etc. Packer can do this automatically for you. An example is shown below -which tags and pushes an image. This is accomplished using a sequence -definition (a collection of post-processors that are treated as as single -pipeline, see [Post-Processors](/docs/templates/post-processors.html) for more -information): +which tags and pushes an image. This is accomplished using a sequence definition +(a collection of post-processors that are treated as as single pipeline, see +[Post-Processors](/docs/templates/post-processors.html) for more information): -```javascript +``` {.javascript} { "post-processors": [ - [ - { - "type": "docker-tag", - "repository": "mitchellh/packer", - "tag": "0.7" - }, - "docker-push" - ] - ] + [ + { + "type": "docker-tag", + "repository": "mitchellh/packer", + "tag": "0.7" + }, + "docker-push" + ] + ] } ``` @@ -187,52 +185,52 @@ Going a step further, if you wanted to tag and push an image to multiple container repositories, this could be accomplished by defining two, nearly-identical sequence definitions, as demonstrated by the example below: -```javascript +``` {.javascript} { - "post-processors": [ - [ - { - "type": "docker-tag", - "repository": "mitchellh/packer", - "tag": "0.7" - }, - "docker-push" - ], - [ - { - "type": "docker-tag", - "repository": "hashicorp/packer", - "tag": "0.7" - }, - "docker-push" - ] - ] + "post-processors": [ + [ + { + "type": "docker-tag", + "repository": "mitchellh/packer", + "tag": "0.7" + }, + "docker-push" + ], + [ + { + "type": "docker-tag", + "repository": "hashicorp/packer", + "tag": "0.7" + }, + "docker-push" + ] + ] } ``` ## Dockerfiles -This builder allows you to build Docker images _without_ Dockerfiles. +This builder allows you to build Docker images *without* Dockerfiles. -With this builder, you can repeatably create Docker images without the use of -a Dockerfile. You don't need to know the syntax or semantics of Dockerfiles. +With this builder, you can repeatably create Docker images without the use of a +Dockerfile. You don't need to know the syntax or semantics of Dockerfiles. Instead, you can just provide shell scripts, Chef recipes, Puppet manifests, etc. to provision your Docker container just like you would a regular virtualized or dedicated machine. -While Docker has many features, Packer views Docker simply as an LXC -container runner. To that end, Packer is able to repeatably build these -LXC containers using portable provisioning scripts. +While Docker has many features, Packer views Docker simply as an LXC container +runner. To that end, Packer is able to repeatably build these LXC containers +using portable provisioning scripts. -Dockerfiles have some additional features that Packer doesn't support -which are able to be worked around. Many of these features will be automated -by Packer in the future: +Dockerfiles have some additional features that Packer doesn't support which are +able to be worked around. Many of these features will be automated by Packer in +the future: -* Dockerfiles will snapshot the container at each step, allowing you to - go back to any step in the history of building. Packer doesn't do this yet, - but inter-step snapshotting is on the way. +- Dockerfiles will snapshot the container at each step, allowing you to go back + to any step in the history of building. Packer doesn't do this yet, but + inter-step snapshotting is on the way. -* Dockerfiles can contain information such as exposed ports, shared - volumes, and other metadata. Packer builds a raw Docker container image - that has none of this metadata. You can pass in much of this metadata - at runtime with `docker run`. +- Dockerfiles can contain information such as exposed ports, shared volumes, and + other metadata. Packer builds a raw Docker container image that has none of + this metadata. You can pass in much of this metadata at runtime with + `docker run`. diff --git a/website/source/docs/builders/null.html.markdown b/website/source/docs/builders/null.html.markdown index 7398cadd7..037165ba2 100644 --- a/website/source/docs/builders/null.html.markdown +++ b/website/source/docs/builders/null.html.markdown @@ -1,24 +1,28 @@ --- -layout: "docs" -page_title: "Null Builder" -description: |- - The `null` Packer builder is not really a builder, it just sets up an SSH connection and runs the provisioners. It can be used to debug provisioners without incurring high wait times. It does not create any kind of image or artifact. ---- +description: | + The `null` Packer builder is not really a builder, it just sets up an SSH + connection and runs the provisioners. It can be used to debug provisioners + without incurring high wait times. It does not create any kind of image or + artifact. +layout: docs +page_title: Null Builder +... # Null Builder Type: `null` -The `null` Packer builder is not really a builder, it just sets up an SSH connection -and runs the provisioners. It can be used to debug provisioners without -incurring high wait times. It does not create any kind of image or artifact. +The `null` Packer builder is not really a builder, it just sets up an SSH +connection and runs the provisioners. It can be used to debug provisioners +without incurring high wait times. It does not create any kind of image or +artifact. ## Basic Example -Below is a fully functioning example. It doesn't do anything useful, since -no provisioners are defined, but it will connect to the specified host via ssh. +Below is a fully functioning example. It doesn't do anything useful, since no +provisioners are defined, but it will connect to the specified host via ssh. -```javascript +``` {.javascript} { "type": "null", "ssh_host": "127.0.0.1", @@ -31,4 +35,3 @@ no provisioners are defined, but it will connect to the specified host via ssh. The null builder has no configuration parameters other than the [communicator](/docs/templates/communicator.html) settings. - diff --git a/website/source/docs/builders/openstack.html.markdown b/website/source/docs/builders/openstack.html.markdown index fec1a85a6..409275c7b 100644 --- a/website/source/docs/builders/openstack.html.markdown +++ b/website/source/docs/builders/openstack.html.markdown @@ -1,25 +1,30 @@ --- -layout: "docs" -page_title: "OpenStack Builder" -description: |- - The `openstack` Packer builder is able to create new images for use with OpenStack. The builder takes a source image, runs any provisioning necessary on the image after launching it, then creates a new reusable image. This reusable image can then be used as the foundation of new servers that are launched within OpenStack. The builder will create temporary keypairs that provide temporary access to the server while the image is being created. This simplifies configuration quite a bit. ---- +description: | + The `openstack` Packer builder is able to create new images for use with + OpenStack. The builder takes a source image, runs any provisioning necessary on + the image after launching it, then creates a new reusable image. This reusable + image can then be used as the foundation of new servers that are launched within + OpenStack. The builder will create temporary keypairs that provide temporary + access to the server while the image is being created. This simplifies + configuration quite a bit. +layout: docs +page_title: OpenStack Builder +... # OpenStack Builder Type: `openstack` The `openstack` Packer builder is able to create new images for use with -[OpenStack](http://www.openstack.org). The builder takes a source -image, runs any provisioning necessary on the image after launching it, -then creates a new reusable image. This reusable image can then be -used as the foundation of new servers that are launched within OpenStack. -The builder will create temporary keypairs that provide temporary access to -the server while the image is being created. This simplifies configuration -quite a bit. +[OpenStack](http://www.openstack.org). The builder takes a source image, runs +any provisioning necessary on the image after launching it, then creates a new +reusable image. This reusable image can then be used as the foundation of new +servers that are launched within OpenStack. The builder will create temporary +keypairs that provide temporary access to the server while the image is being +created. This simplifies configuration quite a bit. -The builder does _not_ manage images. Once it creates an image, it is up to -you to use it or delete it. +The builder does *not* manage images. Once it creates an image, it is up to you +to use it or delete it. ## Configuration Reference @@ -28,81 +33,79 @@ segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `flavor` (string) - The ID, name, or full URL for the desired flavor for the +- `flavor` (string) - The ID, name, or full URL for the desired flavor for the server to be created. -* `image_name` (string) - The name of the resulting image. +- `image_name` (string) - The name of the resulting image. -* `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. - Unless you specify completely custom SSH settings, the source image must - have `cloud-init` installed so that the keypair gets assigned properly. +- `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. Unless + you specify completely custom SSH settings, the source image must have + `cloud-init` installed so that the keypair gets assigned properly. -* `username` (string) - The username used to connect to the OpenStack service. - If not specified, Packer will use the environment variable - `OS_USERNAME`, if set. +- `username` (string) - The username used to connect to the OpenStack service. + If not specified, Packer will use the environment variable `OS_USERNAME`, + if set. -* `password` (string) - The password used to connect to the OpenStack service. - If not specified, Packer will use the environment variables - `OS_PASSWORD`, if set. +- `password` (string) - The password used to connect to the OpenStack service. + If not specified, Packer will use the environment variables `OS_PASSWORD`, + if set. ### Optional: -* `api_key` (string) - The API key used to access OpenStack. Some OpenStack +- `api_key` (string) - The API key used to access OpenStack. Some OpenStack installations require this. -* `availability_zone` (string) - The availability zone to launch the - server in. If this isn't specified, the default enforced by your OpenStack - cluster will be used. This may be required for some OpenStack clusters. +- `availability_zone` (string) - The availability zone to launch the server in. + If this isn't specified, the default enforced by your OpenStack cluster will + be used. This may be required for some OpenStack clusters. -* `floating_ip` (string) - A specific floating IP to assign to this instance. +- `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. -* `floating_ip_pool` (string) - The name of the floating IP pool to use - to allocate a floating IP. `use_floating_ip` must also be set to true - for this to have an affect. +- `floating_ip_pool` (string) - The name of the floating IP pool to use to + allocate a floating IP. `use_floating_ip` must also be set to true for this to + have an affect. -* `insecure` (boolean) - Whether or not the connection to OpenStack can be done +- `insecure` (boolean) - Whether or not the connection to OpenStack can be done over an insecure connection. By default this is false. -* `networks` (array of strings) - A list of networks by UUID to attach - to this instance. +- `networks` (array of strings) - A list of networks by UUID to attach to + this instance. -* `tenant_id` or `tenant_name` (string) - The tenant ID or name to boot the - instance into. Some OpenStack installations require this. - If not specified, Packer will use the environment variable - `OS_TENANT_NAME`, if set. +- `tenant_id` or `tenant_name` (string) - The tenant ID or name to boot the + instance into. Some OpenStack installations require this. If not specified, + Packer will use the environment variable `OS_TENANT_NAME`, if set. -* `security_groups` (array of strings) - A list of security groups by name - to add to this instance. +- `security_groups` (array of strings) - A list of security groups by name to + add to this instance. -* `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 use the environment variable - `OS_REGION_NAME`, if set. +- `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 use the + environment variable `OS_REGION_NAME`, if set. -* `ssh_interface` (string) - The type of interface to connect via SSH. Values - useful for Rackspace are "public" or "private", and the default behavior is - to connect via whichever is returned first from the OpenStack API. +- `ssh_interface` (string) - The type of interface to connect via SSH. Values + useful for Rackspace are "public" or "private", and the default behavior is to + connect via whichever is returned first from the OpenStack API. -* `use_floating_ip` (boolean) - Whether or not to use a floating IP for +- `use_floating_ip` (boolean) - Whether or not to use a floating IP for the instance. Defaults to false. -* `rackconnect_wait` (boolean) - For rackspace, whether or not to wait for +- `rackconnect_wait` (boolean) - For rackspace, whether or not to wait for Rackconnect to assign the machine an IP address before connecting via SSH. Defaults to false. ## Basic Example: Rackspace public cloud -Here is a basic example. This is a working example to build a -Ubuntu 12.04 LTS (Precise Pangolin) on Rackspace OpenStack cloud offering. +Here is a basic example. This is a working example to build a Ubuntu 12.04 LTS +(Precise Pangolin) on Rackspace OpenStack cloud offering. -```javascript +``` {.javascript} { "type": "openstack", "username": "foo", @@ -117,10 +120,10 @@ Ubuntu 12.04 LTS (Precise Pangolin) on Rackspace OpenStack cloud offering. ## Basic Example: Private OpenStack cloud -This example builds an Ubuntu 14.04 image on a private OpenStack cloud, -powered by Metacloud. +This example builds an Ubuntu 14.04 image on a private OpenStack cloud, powered +by Metacloud. -```javascript +``` {.javascript} { "type": "openstack", "ssh_username": "root", @@ -130,12 +133,12 @@ powered by Metacloud. } ``` -In this case, the connection information for connecting to OpenStack -doesn't appear in the template. That is because I source a standard -OpenStack script with environment variables set before I run this. This -script is setting environment variables like: +In this case, the connection information for connecting to OpenStack doesn't +appear in the template. That is because I source a standard OpenStack script +with environment variables set before I run this. This script is setting +environment variables like: -* `OS_AUTH_URL` -* `OS_TENANT_ID` -* `OS_USERNAME` -* `OS_PASSWORD` +- `OS_AUTH_URL` +- `OS_TENANT_ID` +- `OS_USERNAME` +- `OS_PASSWORD` diff --git a/website/source/docs/builders/parallels-iso.html.markdown b/website/source/docs/builders/parallels-iso.html.markdown index f0192b301..d89b5394f 100644 --- a/website/source/docs/builders/parallels-iso.html.markdown +++ b/website/source/docs/builders/parallels-iso.html.markdown @@ -1,31 +1,31 @@ --- -layout: "docs" -page_title: "Parallels Builder (from an ISO)" -description: |- - The Parallels Packer builder is able to create Parallels Desktop for Mac virtual machines and export them in the PVM format, starting from an ISO image. ---- +description: | + The Parallels Packer builder is able to create Parallels Desktop for Mac virtual + machines and export them in the PVM format, starting from an ISO image. +layout: docs +page_title: 'Parallels Builder (from an ISO)' +... # Parallels Builder (from an ISO) Type: `parallels-iso` -The Parallels Packer builder is able to create -[Parallels Desktop for Mac](http://www.parallels.com/products/desktop/) virtual -machines and export them in the PVM format, starting from an -ISO image. +The Parallels Packer builder is able to create [Parallels Desktop for +Mac](http://www.parallels.com/products/desktop/) virtual machines and export +them in the PVM format, starting from an ISO image. -The builder builds a virtual machine by creating a new virtual machine -from scratch, booting it, installing an OS, provisioning software within -the OS, then shutting it down. The result of the Parallels builder is a directory -containing all the files necessary to run the virtual machine portably. +The builder builds a virtual machine by creating a new virtual machine from +scratch, booting it, installing an OS, provisioning software within the OS, then +shutting it down. The result of the Parallels builder is a directory containing +all the files necessary to run the virtual machine portably. ## Basic Example -Here is a basic example. This example is not functional. It will start the -OS installer but then fail because we don't provide the preseed file for -Ubuntu to self-install. Still, the example serves to show the basic configuration: +Here is a basic example. This example is not functional. It will start the OS +installer but then fail because we don't provide the preseed file for Ubuntu to +self-install. Still, the example serves to show the basic configuration: -```javascript +``` {.javascript} { "type": "parallels-iso", "guest_os_type": "ubuntu", @@ -40,219 +40,219 @@ Ubuntu to self-install. Still, the example serves to show the basic configuratio } ``` -It is important to add a `shutdown_command`. By default Packer halts the -virtual machine and the file system may not be sync'd. Thus, changes made in a +It is important to add a `shutdown_command`. By default Packer halts the virtual +machine and the file system may not be sync'd. Thus, changes made in a provisioner might not be saved. ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### 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 - to booting a virtual machine with the ISO attached. The type of the - checksum is specified with `iso_checksum_type`, documented below. +- `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 to booting a + virtual machine with the ISO attached. The type of the checksum is specified + with `iso_checksum_type`, documented below. -* `iso_checksum_type` (string) - The type of the checksum specified in +- `iso_checksum_type` (string) - The type of the checksum specified in `iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or "sha512" currently. While "none" will skip checksumming, this is not recommended since ISO files are generally large and corruption does happen from time to time. -* `iso_url` (string) - A URL to the ISO containing the installation image. - This URL can be either an HTTP URL or a file URL (or path to a file). - If this is an HTTP URL, Packer will download it and cache it between - runs. +- `iso_url` (string) - A URL to the ISO containing the installation image. This + URL can be either an HTTP URL or a file URL (or path to a file). If this is an + HTTP URL, Packer will download it and cache it between runs. -* `ssh_username` (string) - The username to use to SSH into the machine - once the OS is installed. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. -* `parallels_tools_flavor` (string) - The flavor of the Parallels Tools ISO to +- `parallels_tools_flavor` (string) - The flavor of the Parallels Tools ISO to install into the VM. Valid values are "win", "lin", "mac", "os2" and "other". This can be omitted only if `parallels_tools_mode` is "disable". ### 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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `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_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 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. +- `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_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 --distribution list`. Setting the correct value hints to - Parallels Desktop 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 --distribution 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". +- `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". -* `host_interfaces` (array of strings) - A list of which interfaces on the - host should be searched for a IP address. The first IP address found on - one of these will be used as `{{ .HTTPIP }}` in the `boot_command`. - Defaults to ["en0", "en1", "en2", "en3", "en4", "en5", "en6", "en7", "en8", - "en9", "ppp0", "ppp1", "ppp2"]. +- `host_interfaces` (array of strings) - A list of which interfaces on the host + should be searched for a IP address. The first IP address found on one of + these will be used as `{{ .HTTPIP }}` in the `boot_command`. Defaults to + \["en0", "en1", "en2", "en3", "en4", "en5", "en6", "en7", "en8", "en9", + "ppp0", "ppp1", "ppp2"\]. -* `http_directory` (string) - Path to a directory to serve using an HTTP - server. The files in this directory will be available over HTTP that will - be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is "", which means no HTTP - server will be started. The address and port of the HTTP server will be - available as variables in `boot_command`. This is covered in more detail - below. +- `http_directory` (string) - Path to a directory to serve using an HTTP server. + The files in this directory will be available over HTTP that will be + requestable from the virtual machine. This is useful for hosting kickstart + files and so on. By default this is "", which means no HTTP server will + be started. The address and port of the HTTP server will be available as + variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (integer) - 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 - server to be on one port, make this minimum and maximum port the same. - By default the values are 8000 and 9000, respectively. + server to be on one port, make this minimum and maximum port the same. By + default the values are 8000 and 9000, respectively. -* `iso_urls` (array of strings) - Multiple URLs for the ISO to download. - Packer will try these in order. If anything goes wrong attempting to download - or while downloading a single URL, it will move on to the next. All URLs - must point to the same file (same checksum). By default this is empty - and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. +- `iso_urls` (array of strings) - Multiple URLs for the ISO to download. Packer + will try these in order. If anything goes wrong attempting to download or + while downloading a single URL, it will move on to the next. All URLs must + point to the same file (same checksum). By default this is empty and `iso_url` + is used. Only one of `iso_url` or `iso_urls` can be specified. -* `output_directory` (string) - This is the path to the directory where the +- `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. + 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. -* `parallels_tools_guest_path` (string) - The path in the virtual machine to upload - Parallels Tools. This only takes effect if `parallels_tools_mode` is "upload". - This is a [configuration template](/docs/templates/configuration-templates.html) - that has a single valid variable: `Flavor`, which will be the value of - `parallels_tools_flavor`. By default this is "prl-tools-{{.Flavor}}.iso" which - should upload into the login directory of the user. +- `parallels_tools_guest_path` (string) - The path in the virtual machine to + upload Parallels Tools. This only takes effect if `parallels_tools_mode` + is "upload". This is a [configuration + template](/docs/templates/configuration-templates.html) that has a single + valid variable: `Flavor`, which will be the value of `parallels_tools_flavor`. + By default this is "prl-tools-{{.Flavor}}.iso" which should upload into the + login directory of the user. -* `parallels_tools_mode` (string) - The method by which Parallels Tools are made +- `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". If the mode is "attach" the Parallels Tools ISO will be attached as a CD device to the virtual machine. If the mode is "upload" the Parallels Tools ISO will be uploaded to the path specified by `parallels_tools_guest_path`. The default value is "upload". -* `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in +- `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 + 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. + where the `Name` variable is replaced with the VM name. More details on how to + use `prlctl` are below. -* `prlctl_post` (array of array of strings) - Identical to `prlctl`, - except that it is run after the virtual machine is shutdown, and before the - virtual machine is exported. +- `prlctl_post` (array of array of strings) - Identical to `prlctl`, except that + it is run after the virtual machine is shutdown, and before the virtual + machine is exported. -* `prlctl_version_file` (string) - The path within the virtual machine to upload +- `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 - ".prlctl_version", which will generally upload it into the home directory. + ".prlctl\_version", which will generally upload it into the home directory. -* `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. +- `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. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - If it doesn't shut down in this time, it is an error. By default, the timeout - is "5m", or five minutes. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. If it + doesn't shut down in this time, it is an error. By default, the timeout is + "5m", or five minutes. -* `vm_name` (string) - This is the name of the PVM directory for the new - virtual machine, without the file extension. By default this is - "packer-BUILDNAME", where "BUILDNAME" is the name of the build. +- `vm_name` (string) - This is the name of the PVM directory for the new virtual + machine, without the file extension. By default this is "packer-BUILDNAME", + where "BUILDNAME" is the name of the build. ## Boot Command -The `boot_command` configuration is very important: it specifies the keys -to type when the virtual machine is first booted in order to start the -OS installer. This command is typed after `boot_wait`, which gives the -virtual machine some time to actually load the ISO. +The `boot_command` configuration is very important: it specifies the keys to +type when the virtual machine is first booted in order to start the OS +installer. This command is typed after `boot_wait`, which gives the virtual +machine some time to actually load the ISO. -As documented above, the `boot_command` is an array of strings. The -strings are all typed in sequence. It is an array only to improve readability -within the template. +As documented above, the `boot_command` is an array of strings. The strings are +all typed in sequence. It is an array only to improve readability within the +template. The boot command is "typed" character for character (using the Parallels Virtualization SDK, see [Parallels Builder](/docs/builders/parallels.html)) -simulating a human actually typing the keyboard. There are a set of special -keys available. If these are in your boot command, they will be replaced by -the proper key: +simulating a human actually typing the keyboard. There are a set of special keys +available. If these are in your boot command, they will be replaced by the +proper key: -* `` - Backspace +- `` - Backspace -* `` - Delete +- `` - Delete -* `` and `` - Simulates an actual "enter" or "return" keypress. +- `` and `` - Simulates an actual "enter" or "return" keypress. -* `` - Simulates pressing the escape key. +- `` - Simulates pressing the escape key. -* `` - Simulates pressing the tab key. +- `` - Simulates pressing the tab key. -* `` - `` - Simulates pressing a function key. +- `` - `` - Simulates pressing a function key. -* `` `` `` `` - Simulates pressing an arrow key. +- `` `` `` `` - Simulates pressing an arrow key. -* `` - Simulates pressing the spacebar. +- `` - Simulates pressing the spacebar. -* `` - Simulates pressing the insert key. +- `` - Simulates pressing the insert key. -* `` `` - Simulates pressing the home and end keys. +- `` `` - Simulates pressing the home and end keys. -* `` `` - Simulates pressing the page up and page down keys. +- `` `` - Simulates pressing the page up and page down keys. -* `` `` `` - Adds a 1, 5 or 10 second pause before sending any additional keys. This - is useful if you have to generally wait for the UI to update before typing more. +- `` `` `` - Adds a 1, 5 or 10 second pause before sending + any additional keys. This is useful if you have to generally wait for the UI + to update before typing more. In addition to the special keys, each command to type is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The available variables are: +[configuration template](/docs/templates/configuration-templates.html). 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! +- `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! -Example boot command. This is actually a working boot command used to start -an Ubuntu 12.04 installer: +Example boot command. This is actually a working boot command used to start an +Ubuntu 12.04 installer: -```text +``` {.text} [ "", "/install/vmlinuz noapic ", @@ -267,17 +267,18 @@ an Ubuntu 12.04 installer: ``` ## prlctl Commands + In order to perform extra customization of the virtual machine, a template can define extra calls to `prlctl` to perform. [prlctl](http://download.parallels.com/desktop/v9/ga/docs/en_US/Parallels%20Command%20Line%20Reference%20Guide.pdf) is the command-line interface to Parallels Desktop. It can be used to configure the virtual machine, such as set RAM, CPUs, etc. -Extra `prlctl` commands are defined in the template in the `prlctl` section. -An example is shown below that sets the memory and number of CPUs within the +Extra `prlctl` commands are defined in the template in the `prlctl` section. An +example is shown below that sets the memory and number of CPUs within the virtual machine: -```javascript +``` {.javascript} { "prlctl": [ ["set", "{{.Name}}", "--memsize", "1024"], @@ -291,7 +292,7 @@ executed in the order defined. So in the above example, the memory will be set followed by the CPUs. Each command itself is an array of strings, where each string is an argument to -`prlctl`. Each argument is treated as a -[configuration template](/docs/templates/configuration-templates.html). The only -available variable is `Name` which is replaced with the unique name of the VM, -which is required for many `prlctl` calls. +`prlctl`. Each argument is treated as a [configuration +template](/docs/templates/configuration-templates.html). The only available +variable is `Name` which is replaced with the unique name of the VM, which is +required for many `prlctl` calls. diff --git a/website/source/docs/builders/parallels-pvm.html.markdown b/website/source/docs/builders/parallels-pvm.html.markdown index 4083a57fd..f4f9f352c 100644 --- a/website/source/docs/builders/parallels-pvm.html.markdown +++ b/website/source/docs/builders/parallels-pvm.html.markdown @@ -1,30 +1,31 @@ --- -layout: "docs" -page_title: "Parallels Builder (from a PVM)" -description: |- - This Parallels builder is able to create Parallels Desktop for Mac virtual machines and export them in the PVM format, starting from an existing PVM (exported virtual machine image). ---- +description: | + This Parallels builder is able to create Parallels Desktop for Mac virtual + machines and export them in the PVM format, starting from an existing PVM + (exported virtual machine image). +layout: docs +page_title: 'Parallels Builder (from a PVM)' +... # Parallels Builder (from a PVM) Type: `parallels-pvm` -This Parallels builder is able to create -[Parallels Desktop for Mac](http://www.parallels.com/products/desktop/) -virtual machines and export them in the PVM format, starting from an -existing PVM (exported virtual machine image). +This Parallels builder is able to create [Parallels Desktop for +Mac](http://www.parallels.com/products/desktop/) virtual machines and export +them in the PVM format, starting from an existing PVM (exported virtual machine +image). -The builder builds a virtual machine by importing an existing PVM -file. It then boots this image, runs provisioners on this new VM, and -exports that VM to create the image. The imported machine is deleted prior -to finishing the build. +The builder builds a virtual machine by importing an existing PVM file. It then +boots this image, runs provisioners on this new VM, and exports that VM to +create the image. The imported machine is deleted prior to finishing the build. ## Basic Example Here is a basic example. This example is functional if you have an PVM matching the settings here. -```javascript +``` {.javascript} { "type": "parallels-pvm", "parallels_tools_flavor": "lin", @@ -36,175 +37,180 @@ the settings here. } ``` -It is important to add a `shutdown_command`. By default Packer halts the -virtual machine and the file system may not be sync'd. Thus, changes made in a +It is important to add a `shutdown_command`. By default Packer halts the virtual +machine and the file system may not be sync'd. Thus, changes made in a provisioner might not be saved. ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `source_path` (string) - The path to a PVM directory that acts as - the source of this build. +- `source_path` (string) - The path to a PVM directory that acts as the source + of this build. -* `ssh_username` (string) - The username to use to SSH into the machine - once the OS is installed. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. -* `parallels_tools_flavor` (string) - The flavor of the Parallels Tools ISO to +- `parallels_tools_flavor` (string) - The flavor of the Parallels Tools ISO to install into the VM. Valid values are "win", "lin", "mac", "os2" and "other". This can be omitted only if `parallels_tools_mode` is "disable". ### 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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `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. +- `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. -* `reassign_mac` (boolean) - If this is "false" the MAC address of the first - NIC will reused when imported else a new MAC address will be generated by - Parallels. Defaults to "false". +- `reassign_mac` (boolean) - If this is "false" the MAC address of the first NIC + will reused when imported else a new MAC address will be generated + by Parallels. Defaults to "false". -* `output_directory` (string) - This is the path to the directory where the +- `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. + 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. -* `parallels_tools_guest_path` (string) - The path in the VM to upload +- `parallels_tools_guest_path` (string) - The path in the VM to upload Parallels Tools. This only takes effect if `parallels_tools_mode` is "upload". - This is a [configuration template](/docs/templates/configuration-templates.html) - that has a single valid variable: `Flavor`, which will be the value of - `parallels_tools_flavor`. By default this is "prl-tools-{{.Flavor}}.iso" which - should upload into the login directory of the user. + This is a [configuration + template](/docs/templates/configuration-templates.html) that has a single + valid variable: `Flavor`, which will be the value of `parallels_tools_flavor`. + By default this is "prl-tools-{{.Flavor}}.iso" which should upload into the + login directory of the user. -* `parallels_tools_mode` (string) - The method by which Parallels Tools are made +- `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". If the mode is "attach" the Parallels Tools ISO will be attached as a CD device to the virtual machine. If the mode is "upload" the Parallels Tools ISO will be uploaded to the path specified by `parallels_tools_guest_path`. The default value is "upload". -* `prlctl` (array of array of strings) - Custom `prlctl` commands to execute in +- `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 + 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. + where the `Name` variable is replaced with the VM name. More details on how to + use `prlctl` are below. -* `prlctl_post` (array of array of strings) - Identical to `prlctl`, - except that it is run after the virtual machine is shutdown, and before the - virtual machine is exported. +- `prlctl_post` (array of array of strings) - Identical to `prlctl`, except that + it is run after the virtual machine is shutdown, and before the virtual + machine is exported. -* `prlctl_version_file` (string) - The path within the virtual machine to upload +- `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 - ".prlctl_version", which will generally upload it into the home directory. + ".prlctl\_version", which will generally upload it into the home directory. -* `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. +- `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. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - If it doesn't shut down in this time, it is an error. By default, the timeout - is "5m", or five minutes. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. If it + doesn't shut down in this time, it is an error. By default, the timeout is + "5m", or five minutes. -* `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 - the name of the build. +- `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 the + name of the build. ## Parallels Tools + After the virtual machine is up and the operating system is installed, Packer uploads the Parallels Tools into the virtual machine. The path where they are uploaded is controllable by `parallels_tools_path`, and defaults to "prl-tools.iso". Without an absolute path, it is uploaded to the home directory -of the SSH user. Parallels Tools ISO's can be found in: -"/Applications/Parallels Desktop.app/Contents/Resources/Tools/" +of the SSH user. Parallels Tools ISO's can be found in: "/Applications/Parallels +Desktop.app/Contents/Resources/Tools/" ## Boot Command -The `boot_command` specifies the keys to type when the virtual machine is first booted. This command is typed after `boot_wait`. +The `boot_command` specifies the keys to type when the virtual machine is first +booted. This command is typed after `boot_wait`. -As documented above, the `boot_command` is an array of strings. The -strings are all typed in sequence. It is an array only to improve readability -within the template. +As documented above, the `boot_command` is an array of strings. The strings are +all typed in sequence. It is an array only to improve readability within the +template. The boot command is "typed" character for character (using the Parallels Virtualization SDK, see [Parallels Builder](/docs/builders/parallels.html)) -simulating a human actually typing the keyboard. There are a set of special -keys available. If these are in your boot command, they will be replaced by -the proper key: +simulating a human actually typing the keyboard. There are a set of special keys +available. If these are in your boot command, they will be replaced by the +proper key: -* `` - Backspace +- `` - Backspace -* `` - Delete +- `` - Delete -* `` and `` - Simulates an actual "enter" or "return" keypress. +- `` and `` - Simulates an actual "enter" or "return" keypress. -* `` - Simulates pressing the escape key. +- `` - Simulates pressing the escape key. -* `` - Simulates pressing the tab key. +- `` - Simulates pressing the tab key. -* `` - `` - Simulates pressing a function key. +- `` - `` - Simulates pressing a function key. -* `` `` `` `` - Simulates pressing an arrow key. +- `` `` `` `` - Simulates pressing an arrow key. -* `` - Simulates pressing the spacebar. +- `` - Simulates pressing the spacebar. -* `` - Simulates pressing the insert key. +- `` - Simulates pressing the insert key. -* `` `` - Simulates pressing the home and end keys. +- `` `` - Simulates pressing the home and end keys. -* `` `` - Simulates pressing the page up and page down keys. +- `` `` - Simulates pressing the page up and page down keys. -* `` `` `` - Adds a 1, 5 or 10 second pause before sending any additional keys. This - is useful if you have to generally wait for the UI to update before typing more. +- `` `` `` - Adds a 1, 5 or 10 second pause before sending + any additional keys. This is useful if you have to generally wait for the UI + to update before typing more. In addition to the special keys, each command to type is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The available variables are: +[configuration template](/docs/templates/configuration-templates.html). The +available variables are: ## prlctl Commands + In order to perform extra customization of the virtual machine, a template can define extra calls to `prlctl` to perform. [prlctl](http://download.parallels.com/desktop/v9/ga/docs/en_US/Parallels%20Command%20Line%20Reference%20Guide.pdf) is the command-line interface to Parallels Desktop. It can be used to configure the virtual machine, such as set RAM, CPUs, etc. -Extra `prlctl` commands are defined in the template in the `prlctl` section. -An example is shown below that sets the memory and number of CPUs within the +Extra `prlctl` commands are defined in the template in the `prlctl` section. An +example is shown below that sets the memory and number of CPUs within the virtual machine: -```javascript +``` {.javascript} { "prlctl": [ ["set", "{{.Name}}", "--memsize", "1024"], @@ -218,7 +224,7 @@ executed in the order defined. So in the above example, the memory will be set followed by the CPUs. Each command itself is an array of strings, where each string is an argument to -`prlctl`. Each argument is treated as a -[configuration template](/docs/templates/configuration-templates.html). The only -available variable is `Name` which is replaced with the unique name of the VM, -which is required for many `prlctl` calls. +`prlctl`. Each argument is treated as a [configuration +template](/docs/templates/configuration-templates.html). The only available +variable is `Name` which is replaced with the unique name of the VM, which is +required for many `prlctl` calls. diff --git a/website/source/docs/builders/parallels.html.markdown b/website/source/docs/builders/parallels.html.markdown index db5f62139..7d355eaef 100644 --- a/website/source/docs/builders/parallels.html.markdown +++ b/website/source/docs/builders/parallels.html.markdown @@ -1,34 +1,37 @@ --- -layout: "docs" -page_title: "Parallels Builder" -description: |- - The Parallels Packer builder is able to create Parallels Desktop for Mac virtual machines and export them in the PVM format. ---- +description: | + The Parallels Packer builder is able to create Parallels Desktop for Mac virtual + machines and export them in the PVM format. +layout: docs +page_title: Parallels Builder +... # Parallels Builder -The Parallels Packer builder is able to create [Parallels Desktop for Mac](http://www.parallels.com/products/desktop/) virtual machines and export them in the PVM format. +The Parallels Packer builder is able to create [Parallels Desktop for +Mac](http://www.parallels.com/products/desktop/) virtual machines and export +them in the PVM format. -Packer actually comes with multiple builders able to create Parallels -machines, depending on the strategy you want to use to build the image. -Packer supports the following Parallels builders: +Packer actually comes with multiple builders able to create Parallels machines, +depending on the strategy you want to use to build the image. Packer supports +the following Parallels builders: -* [parallels-iso](/docs/builders/parallels-iso.html) - Starts from - an ISO file, creates a brand new Parallels VM, installs an OS, - provisions software within the OS, then exports that machine to create - an image. This is best for people who want to start from scratch. - -* [parallels-pvm](/docs/builders/parallels-pvm.html) - This builder - imports an existing PVM file, runs provisioners on top of that VM, - and exports that machine to create an image. This is best if you have - an existing Parallels VM export you want to use as the source. As an - additional benefit, you can feed the artifact of this builder back into - itself to iterate on a machine. +- [parallels-iso](/docs/builders/parallels-iso.html) - Starts from an ISO file, + creates a brand new Parallels VM, installs an OS, provisions software within + the OS, then exports that machine to create an image. This is best for people + who want to start from scratch. +- [parallels-pvm](/docs/builders/parallels-pvm.html) - This builder imports an + existing PVM file, runs provisioners on top of that VM, and exports that + machine to create an image. This is best if you have an existing Parallels VM + export you want to use as the source. As an additional benefit, you can feed + the artifact of this builder back into itself to iterate on a machine. ## Requirements -In addition to [Parallels Desktop for Mac](http://www.parallels.com/products/desktop/) this requires the -[Parallels Virtualization SDK](http://www.parallels.com/downloads/desktop/). +In addition to [Parallels Desktop for +Mac](http://www.parallels.com/products/desktop/) this requires the [Parallels +Virtualization SDK](http://www.parallels.com/downloads/desktop/). -The SDK can be installed by downloading and following the instructions in the dmg. +The SDK can be installed by downloading and following the instructions in the +dmg. diff --git a/website/source/docs/builders/qemu.html.markdown b/website/source/docs/builders/qemu.html.markdown index ce39c53ec..57c53e4c0 100644 --- a/website/source/docs/builders/qemu.html.markdown +++ b/website/source/docs/builders/qemu.html.markdown @@ -1,30 +1,31 @@ --- -layout: "docs" -page_title: "QEMU Builder" -description: |- - The Qemu Packer builder is able to create KVM and Xen virtual machine images. Support for Xen is experimental at this time. ---- +description: | + The Qemu Packer builder is able to create KVM and Xen virtual machine images. + Support for Xen is experimental at this time. +layout: docs +page_title: QEMU Builder +... # QEMU Builder Type: `qemu` -The Qemu Packer builder is able to create [KVM](http://www.linux-kvm.org) -and [Xen](http://www.xenproject.org) virtual machine images. Support -for Xen is experimental at this time. +The Qemu Packer builder is able to create [KVM](http://www.linux-kvm.org) and +[Xen](http://www.xenproject.org) virtual machine images. Support for Xen is +experimental at this time. -The builder builds a virtual machine by creating a new virtual machine -from scratch, booting it, installing an OS, rebooting the machine with the -boot media as the virtual hard drive, provisioning software within -the OS, then shutting it down. The result of the Qemu builder is a directory -containing the image file necessary to run the virtual machine on KVM or Xen. +The builder builds a virtual machine by creating a new virtual machine from +scratch, booting it, installing an OS, rebooting the machine with the boot media +as the virtual hard drive, provisioning software within the OS, then shutting it +down. The result of the Qemu builder is a directory containing the image file +necessary to run the virtual machine on KVM or Xen. ## Basic Example -Here is a basic example. This example is functional so long as you fixup -paths to files, URLS for ISOs and checksums. +Here is a basic example. This example is functional so long as you fixup paths +to files, URLS for ISOs and checksums. -```javascript +``` {.javascript} { "builders": [ @@ -62,153 +63,153 @@ paths to files, URLS for ISOs and checksums. } ``` -A working CentOS 6.x kickstart file can be found -[at this URL](https://gist.github.com/mitchellh/7328271/#file-centos6-ks-cfg), adapted from an unknown source. -Place this file in the http directory with the proper name. For the -example above, it should go into "httpdir" with a name of "centos6-ks.cfg". +A working CentOS 6.x kickstart file can be found [at this +URL](https://gist.github.com/mitchellh/7328271/#file-centos6-ks-cfg), adapted +from an unknown source. Place this file in the http directory with the proper +name. For the example above, it should go into "httpdir" with a name of +"centos6-ks.cfg". ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### 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 - to booting a virtual machine with the ISO attached. The type of the - checksum is specified with `iso_checksum_type`, documented below. +- `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 to booting a + virtual machine with the ISO attached. The type of the checksum is specified + with `iso_checksum_type`, documented below. -* `iso_checksum_type` (string) - The type of the checksum specified in - `iso_checksum`. Valid values are "md5", "sha1", "sha256", or "sha512" currently. +- `iso_checksum_type` (string) - The type of the checksum specified in + `iso_checksum`. Valid values are "md5", "sha1", "sha256", or + "sha512" currently. -* `iso_url` (string) - A URL to the ISO containing the installation image. - This URL can be either an HTTP URL or a file URL (or path to a file). - If this is an HTTP URL, Packer will download it and cache it between - runs. +- `iso_url` (string) - A URL to the ISO containing the installation image. This + URL can be either an HTTP URL or a file URL (or path to a file). If this is an + HTTP URL, Packer will download it and cache it between runs. -* `ssh_username` (string) - The username to use to SSH into the machine - once the OS is installed. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. ### Optional: -* `accelerator` (string) - The accelerator type to use when running the VM. - This may have a value of either "none", "kvm", "tcg", or "xen" and you must have that - support in on the machine on which you run the builder. By default "kvm" +- `accelerator` (string) - The accelerator type to use when running the VM. This + may have a value of either "none", "kvm", "tcg", or "xen" and you must have + that support in on the machine on which you run the builder. By default "kvm" is used. -* `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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `disk_cache` (string) - The cache mode to use for disk. Allowed values - include any of "writethrough", "writeback", "none", "unsafe" or - "directsync". By default, this is set to "writeback". +- `disk_cache` (string) - The cache mode to use for disk. Allowed values include + any of "writethrough", "writeback", "none", "unsafe" or "directsync". By + default, this is set to "writeback". -* `disk_discard` (string) - The discard mode to use for disk. Allowed values - include any of "unmap" or "ignore". By default, this is set to "ignore". +- `disk_discard` (string) - The discard mode to use for disk. Allowed values + include any of "unmap" or "ignore". By default, this is set to "ignore". -* `disk_image` (boolean) - Packer defaults to building from an ISO file, - this parameter controls whether the ISO URL supplied is actually a bootable - QEMU image. When this value is set to true, the machine will clone the - source, resize it according to `disk_size` and boot the image. +- `disk_image` (boolean) - Packer defaults to building from an ISO file, this + parameter controls whether the ISO URL supplied is actually a bootable + QEMU image. When this value is set to true, the machine will clone the source, + resize it according to `disk_size` and boot the image. -* `disk_interface` (string) - The interface to use for the disk. Allowed - values include any of "ide," "scsi" or "virtio." Note also that any boot - commands or kickstart type scripts must have proper adjustments for - resulting device names. The Qemu builder uses "virtio" by default. +- `disk_interface` (string) - The interface to use for the disk. Allowed values + include any of "ide," "scsi" or "virtio." Note also that any boot commands or + kickstart type scripts must have proper adjustments for resulting + device names. The Qemu builder uses "virtio" by default. -* `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_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 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. +- `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. -* `format` (string) - Either "qcow2" or "raw", this specifies the output - format of the virtual machine image. This defaults to "qcow2". +- `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 QEMU 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. +- `headless` (boolean) - Packer defaults to building QEMU 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. -* `http_directory` (string) - Path to a directory to serve using an HTTP - server. The files in this directory will be available over HTTP that will - be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is "", which means no HTTP - server will be started. The address and port of the HTTP server will be - available as variables in `boot_command`. This is covered in more detail - below. +- `http_directory` (string) - Path to a directory to serve using an HTTP server. + The files in this directory will be available over HTTP that will be + requestable from the virtual machine. This is useful for hosting kickstart + files and so on. By default this is "", which means no HTTP server will + be started. The address and port of the HTTP server will be available as + variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (integer) - 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 - server to be on one port, make this minimum and maximum port the same. - By default the values are 8000 and 9000, respectively. + server to be on one port, make this minimum and maximum port the same. By + default the values are 8000 and 9000, respectively. -* `iso_urls` (array of strings) - Multiple URLs for the ISO to download. - Packer will try these in order. If anything goes wrong attempting to download - or while downloading a single URL, it will move on to the next. All URLs - must point to the same file (same checksum). By default this is empty - and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. +- `iso_urls` (array of strings) - Multiple URLs for the ISO to download. Packer + will try these in order. If anything goes wrong attempting to download or + while downloading a single URL, it will move on to the next. All URLs must + point to the same file (same checksum). By default this is empty and `iso_url` + is used. Only one of `iso_url` or `iso_urls` can be specified. -* `machine_type` (string) - The type of machine emulation to use. Run - your qemu binary with the flags `-machine help` to list available types - for your system. This defaults to "pc". +- `machine_type` (string) - The type of machine emulation to use. Run your qemu + binary with the flags `-machine help` to list available types for your system. + This defaults to "pc". -* `net_device` (string) - The driver to use for the network interface. Allowed - values "ne2k_pci," "i82551," "i82557b," "i82559er," "rtl8139," "e1000," +- `net_device` (string) - The driver to use for the network interface. Allowed + 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 +- `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. + 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 +- `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 choice for some systems. -* `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 - switch/value pairs. Any value specified as an empty string is ignored. - All values after the switch are concatenated with no separator. +- `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 switch/value pairs. + Any value specified as an empty string is ignored. All values after the switch + are concatenated with no separator. -~> **Warning:** The qemu command line allows extreme flexibility, so beware of -conflicting arguments causing failures of your run. For instance, using +\~> **Warning:** The qemu command line allows extreme flexibility, so beware +of conflicting arguments causing failures of your run. For instance, using --no-acpi could break the ability to send power signal type commands (e.g., -shutdown -P now) to the virtual machine, thus preventing proper shutdown. To -see the defaults, look in the packer.log file and search for the -qemu-system-x86 command. The arguments are all printed for review. +shutdown -P now) to the virtual machine, thus preventing proper shutdown. To see +the defaults, look in the packer.log file and search for the qemu-system-x86 +command. The arguments are all printed for review. The following shows a sample usage: -```javascript +``` {.javascript} // ... "qemuargs": [ [ "-m", "1024M" ], @@ -227,88 +228,87 @@ qemu-system-x86 command. The arguments are all printed for review. would produce the following (not including other defaults supplied by the builder and not otherwise conflicting with the qemuargs): 
-	qemu-system-x86 -m 1024m --no-acpi -netdev user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device virtio-net,netdev=mynet0"
+  qemu-system-x86 -m 1024m --no-acpi -netdev user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device virtio-net,netdev=mynet0"
+- `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. -* `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. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. If it + doesn't shut down in this time, it is an error. By default, the timeout is + "5m", or five minutes. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - 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` (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, +- `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 host port. -* `vm_name` (string) - This is the name of the image (QCOW2 or IMG) file for - the new virtual machine, without the file extension. By default this is +- `vm_name` (string) - This is the name of the image (QCOW2 or IMG) file for 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. +- `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 -to type when the virtual machine is first booted in order to start the -OS installer. This command is typed after `boot_wait`, which gives the -virtual machine some time to actually load the ISO. +The `boot_command` configuration is very important: it specifies the keys to +type when the virtual machine is first booted in order to start the OS +installer. This command is typed after `boot_wait`, which gives the virtual +machine some time to actually load the ISO. -As documented above, the `boot_command` is an array of strings. The -strings are all typed in sequence. It is an array only to improve readability -within the template. +As documented above, the `boot_command` is an array of strings. The strings are +all typed in sequence. It is an array only to improve readability within the +template. -The boot command is "typed" character for character over a VNC connection -to the machine, simulating a human actually typing the keyboard. There are -a set of special keys available. If these are in your boot command, they -will be replaced by the proper key: +The boot command is "typed" character for character over a VNC connection to the +machine, simulating a human actually typing the keyboard. There are a set of +special keys available. If these are in your boot command, they will be replaced +by the proper key: -* `` - Backspace +- `` - Backspace -* `` - Delete +- `` - Delete -* `` and `` - Simulates an actual "enter" or "return" keypress. +- `` and `` - Simulates an actual "enter" or "return" keypress. -* `` - Simulates pressing the escape key. +- `` - Simulates pressing the escape key. -* `` - Simulates pressing the tab key. +- `` - Simulates pressing the tab key. -* `` - `` - Simulates pressing a function key. +- `` - `` - Simulates pressing a function key. -* `` `` `` `` - Simulates pressing an arrow key. +- `` `` `` `` - Simulates pressing an arrow key. -* `` - Simulates pressing the spacebar. +- `` - Simulates pressing the spacebar. -* `` - Simulates pressing the insert key. +- `` - Simulates pressing the insert key. -* `` `` - Simulates pressing the home and end keys. +- `` `` - Simulates pressing the home and end keys. -* `` `` - Simulates pressing the page up and page down keys. +- `` `` - Simulates pressing the page up and page down keys. -* `` `` `` - Adds a 1, 5 or 10 second pause before sending any additional keys. This - is useful if you have to generally wait for the UI to update before typing more. +- `` `` `` - Adds a 1, 5 or 10 second pause before sending + any additional keys. This is useful if you have to generally wait for the UI + to update before typing more. In addition to the special keys, each command to type is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The available variables are: +[configuration template](/docs/templates/configuration-templates.html). 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! +- `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! -Example boot command. This is actually a working boot command used to start -an CentOS 6.4 installer: +Example boot command. This is actually a working boot command used to start an +CentOS 6.4 installer: -```javascript +``` {.javascript} "boot_command": [ "", diff --git a/website/source/docs/builders/virtualbox-iso.html.markdown b/website/source/docs/builders/virtualbox-iso.html.markdown index 97ba056f8..bdccdf768 100644 --- a/website/source/docs/builders/virtualbox-iso.html.markdown +++ b/website/source/docs/builders/virtualbox-iso.html.markdown @@ -1,30 +1,31 @@ --- -layout: "docs" -page_title: "VirtualBox Builder (from an ISO)" -description: |- - The VirtualBox Packer builder is able to create VirtualBox virtual machines and export them in the OVF format, starting from an ISO image. ---- +description: | + The VirtualBox Packer builder is able to create VirtualBox virtual machines and + export them in the OVF format, starting from an ISO image. +layout: docs +page_title: 'VirtualBox Builder (from an ISO)' +... # VirtualBox Builder (from an ISO) Type: `virtualbox-iso` -The VirtualBox Packer builder is able to create [VirtualBox](https://www.virtualbox.org/) -virtual machines and export them in the OVF format, starting from an -ISO image. +The VirtualBox Packer builder is able to create +[VirtualBox](https://www.virtualbox.org/) virtual machines and export them in +the OVF format, starting from an ISO image. -The builder builds a virtual machine by creating a new virtual machine -from scratch, booting it, installing an OS, provisioning software within -the OS, then shutting it down. The result of the VirtualBox builder is a directory -containing all the files necessary to run the virtual machine portably. +The builder builds a virtual machine by creating a new virtual machine from +scratch, booting it, installing an OS, provisioning software within the OS, then +shutting it down. The result of the VirtualBox builder is a directory containing +all the files necessary to run the virtual machine portably. ## Basic Example -Here is a basic example. This example is not functional. It will start the -OS installer but then fail because we don't provide the preseed file for -Ubuntu to self-install. Still, the example serves to show the basic configuration: +Here is a basic example. This example is not functional. It will start the OS +installer but then fail because we don't provide the preseed file for Ubuntu to +self-install. Still, the example serves to show the basic configuration: -```javascript +``` {.javascript} { "type": "virtualbox-iso", "guest_os_type": "Ubuntu_64", @@ -37,250 +38,249 @@ Ubuntu to self-install. Still, the example serves to show the basic configuratio } ``` -It is important to add a `shutdown_command`. By default Packer halts the -virtual machine and the file system may not be sync'd. Thus, changes made in a +It is important to add a `shutdown_command`. By default Packer halts the virtual +machine and the file system may not be sync'd. Thus, changes made in a provisioner might not be saved. ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### 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 - to booting a virtual machine with the ISO attached. The type of the - checksum is specified with `iso_checksum_type`, documented below. +- `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 to booting a + virtual machine with the ISO attached. The type of the checksum is specified + with `iso_checksum_type`, documented below. -* `iso_checksum_type` (string) - The type of the checksum specified in +- `iso_checksum_type` (string) - The type of the checksum specified in `iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or "sha512" currently. While "none" will skip checksumming, this is not recommended since ISO files are generally large and corruption does happen from time to time. -* `iso_url` (string) - A URL to the ISO containing the installation image. - This URL can be either an HTTP URL or a file URL (or path to a file). - If this is an HTTP URL, Packer will download it and cache it between - runs. +- `iso_url` (string) - A URL to the ISO containing the installation image. This + URL can be either an HTTP URL or a file URL (or path to a file). If this is an + HTTP URL, Packer will download it and cache it between runs. -* `ssh_username` (string) - The username to use to SSH into the machine - once the OS is installed. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. ### 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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `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_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. +- `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 - 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. +- `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. -* `format` (string) - Either "ovf" or "ova", this specifies the output - format of the exported virtual machine. This defaults to "ovf". +- `format` (string) - Either "ovf" or "ova", this specifies the output format of + the exported virtual machine. This defaults to "ovf". -* `guest_additions_mode` (string) - The method by which guest additions - are made available to the guest for installation. Valid options are - "upload", "attach", or "disable". If the mode is "attach" the guest - additions ISO will be attached as a CD device to the virtual machine. - If the mode is "upload" the guest additions ISO will be uploaded to - the path specified by `guest_additions_path`. The default value is - "upload". If "disable" is used, guest additions won't be downloaded, - either. +- `guest_additions_mode` (string) - The method by which guest additions are made + available to the guest for installation. Valid options are "upload", "attach", + or "disable". If the mode is "attach" the guest additions ISO will be attached + as a CD device to the virtual machine. If the mode is "upload" the guest + additions ISO will be uploaded to the path specified by + `guest_additions_path`. The default value is "upload". If "disable" is used, + guest additions won't be downloaded, either. -* `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](/docs/templates/configuration-templates.html) - where the `Version` variable is replaced with the VirtualBox version. +- `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](/docs/templates/configuration-templates.html) 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 VirtualBox website, so this only - needs to be set if you want to be explicit about the checksum. +- `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 VirtualBox website, so this only needs to be set if you + want to be explicit about the checksum. -* `guest_additions_url` (string) - The URL to the guest additions ISO - to upload. This can also be a file 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_url` (string) - The URL to the guest additions ISO to upload. + This can also be a file 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_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 `VBoxManage list ostypes`. Setting the correct value hints to VirtualBox - 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 + `VBoxManage list ostypes`. Setting the correct value hints to VirtualBox how + to optimize the virtual hardware to work best with that operating system. -* `hard_drive_interface` (string) - The type of controller that the primary - hard drive is attached to, defaults to "ide". When set to "sata", the - drive is attached to an AHCI SATA controller. When set to "scsi", the drive - is attached to an LsiLogic SCSI controller. +- `hard_drive_interface` (string) - The type of controller that the primary hard + drive is attached to, defaults to "ide". When set to "sata", the drive is + attached to an AHCI SATA controller. When set to "scsi", the drive is attached + to an LsiLogic SCSI controller. -* `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. +- `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. -* `http_directory` (string) - Path to a directory to serve using an HTTP - server. The files in this directory will be available over HTTP that will - be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is "", which means no HTTP - server will be started. The address and port of the HTTP server will be - available as variables in `boot_command`. This is covered in more detail - below. +- `http_directory` (string) - Path to a directory to serve using an HTTP server. + The files in this directory will be available over HTTP that will be + requestable from the virtual machine. This is useful for hosting kickstart + files and so on. By default this is "", which means no HTTP server will + be started. The address and port of the HTTP server will be available as + variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (integer) - 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 - server to be on one port, make this minimum and maximum port the same. - By default the values are 8000 and 9000, respectively. + server to be on one port, make this minimum and maximum port the same. By + default the values are 8000 and 9000, respectively. -* `iso_interface` (string) - The type of controller that the ISO is attached - to, defaults to "ide". When set to "sata", the drive is attached to an - AHCI SATA controller. +- `iso_interface` (string) - The type of controller that the ISO is attached to, + defaults to "ide". When set to "sata", the drive is attached to an AHCI + SATA controller. -* `iso_urls` (array of strings) - Multiple URLs for the ISO to download. - Packer will try these in order. If anything goes wrong attempting to download - or while downloading a single URL, it will move on to the next. All URLs - must point to the same file (same checksum). By default this is empty - and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. +- `iso_urls` (array of strings) - Multiple URLs for the ISO to download. Packer + will try these in order. If anything goes wrong attempting to download or + while downloading a single URL, it will move on to the next. All URLs must + point to the same file (same checksum). By default this is empty and `iso_url` + is used. Only one of `iso_url` or `iso_urls` can be specified. -* `output_directory` (string) - This is the path to the directory where the +- `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. + 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. -* `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 unless a shutdown command takes place inside script so this may - safely be omitted. If one or more scripts require a reboot it is suggested to leave this blank - since reboots may fail and specify the final shutdown command in your last script. +- `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 unless a shutdown + command takes place inside script so this may safely be omitted. If one or + more scripts require a reboot it is suggested to leave this blank since + reboots may fail and specify the final shutdown command in your last script. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - If it doesn't shut down in this time, it is an error. By default, the timeout - is "5m", or five minutes. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. 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` (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, +- `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 host port. -* `ssh_skip_nat_mapping` (boolean) - Defaults to false. When enabled, Packer does - not setup forwarded port mapping for SSH requests and uses `ssh_port` on the - host to communicate to the virtual machine +- `ssh_skip_nat_mapping` (boolean) - Defaults to false. When enabled, Packer + does not setup forwarded port mapping for SSH requests and uses `ssh_port` on + the host to communicate to the virtual machine -* `vboxmanage` (array of array of strings) - Custom `VBoxManage` 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 `VBoxManage` (but excluding `VBoxManage` - 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 `VBoxManage` are below. +- `vboxmanage` (array of array of strings) - Custom `VBoxManage` 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 `VBoxManage` (but excluding `VBoxManage` 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 `VBoxManage` + are below. -* `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, +- `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, except that it is run after the virtual machine is shutdown, and before the virtual machine is exported. -* `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 be upload it into - the home directory. +- `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 be upload it into the + home directory. -* `vm_name` (string) - This is the name of the OVF file for the new virtual +- `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. ## Boot Command -The `boot_command` configuration is very important: it specifies the keys -to type when the virtual machine is first booted in order to start the -OS installer. This command is typed after `boot_wait`, which gives the -virtual machine some time to actually load the ISO. +The `boot_command` configuration is very important: it specifies the keys to +type when the virtual machine is first booted in order to start the OS +installer. This command is typed after `boot_wait`, which gives the virtual +machine some time to actually load the ISO. -As documented above, the `boot_command` is an array of strings. The -strings are all typed in sequence. It is an array only to improve readability -within the template. +As documented above, the `boot_command` is an array of strings. The strings are +all typed in sequence. It is an array only to improve readability within the +template. -The boot command is "typed" character for character over a VNC connection -to the machine, simulating a human actually typing the keyboard. There are -a set of special keys available. If these are in your boot command, they -will be replaced by the proper key: +The boot command is "typed" character for character over a VNC connection to the +machine, simulating a human actually typing the keyboard. There are a set of +special keys available. If these are in your boot command, they will be replaced +by the proper key: -* `` - Backspace +- `` - Backspace -* `` - Delete +- `` - Delete -* `` and `` - Simulates an actual "enter" or "return" keypress. +- `` and `` - Simulates an actual "enter" or "return" keypress. -* `` - Simulates pressing the escape key. +- `` - Simulates pressing the escape key. -* `` - Simulates pressing the tab key. +- `` - Simulates pressing the tab key. -* `` - `` - Simulates pressing a function key. +- `` - `` - Simulates pressing a function key. -* `` `` `` `` - Simulates pressing an arrow key. +- `` `` `` `` - Simulates pressing an arrow key. -* `` - Simulates pressing the spacebar. +- `` - Simulates pressing the spacebar. -* `` - Simulates pressing the insert key. +- `` - Simulates pressing the insert key. -* `` `` - Simulates pressing the home and end keys. +- `` `` - Simulates pressing the home and end keys. -* `` `` - Simulates pressing the page up and page down keys. +- `` `` - Simulates pressing the page up and page down keys. -* `` `` `` - Adds a 1, 5 or 10 second pause before sending any additional keys. This - is useful if you have to generally wait for the UI to update before typing more. +- `` `` `` - Adds a 1, 5 or 10 second pause before sending + any additional keys. This is useful if you have to generally wait for the UI + to update before typing more. In addition to the special keys, each command to type is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The available variables are: +[configuration template](/docs/templates/configuration-templates.html). 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! +- `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! -Example boot command. This is actually a working boot command used to start -an Ubuntu 12.04 installer: +Example boot command. This is actually a working boot command used to start an +Ubuntu 12.04 installer: -```text +``` {.text} [ "", "/install/vmlinuz noapic ", @@ -296,31 +296,32 @@ an Ubuntu 12.04 installer: ## Guest Additions -Packer will automatically download the proper guest additions for the -version of VirtualBox that is running and upload those guest additions into -the virtual machine so that provisioners can easily install them. +Packer will automatically download the proper guest additions for the version of +VirtualBox that is running and upload those guest additions into the virtual +machine so that provisioners can easily install them. -Packer downloads the guest additions from the official VirtualBox website, -and verifies the file with the official checksums released by VirtualBox. +Packer downloads the guest additions from the official VirtualBox website, and +verifies the file with the official checksums released by VirtualBox. -After the virtual machine is up and the operating system is installed, -Packer uploads the guest additions into the virtual machine. The path where -they are uploaded is controllable by `guest_additions_path`, and defaults -to "VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the -home directory of the SSH user. +After the virtual machine is up and the operating system is installed, Packer +uploads the guest additions into the virtual machine. The path where they are +uploaded is controllable by `guest_additions_path`, and defaults to +"VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the home +directory of the SSH user. ## VBoxManage Commands -In order to perform extra customization of the virtual machine, a template -can define extra calls to `VBoxManage` to perform. [VBoxManage](http://www.virtualbox.org/manual/ch08.html) -is the command-line interface to VirtualBox where you can completely control -VirtualBox. It can be used to do things such as set RAM, CPUs, etc. +In order to perform extra customization of the virtual machine, a template can +define extra calls to `VBoxManage` to perform. +[VBoxManage](http://www.virtualbox.org/manual/ch08.html) is the command-line +interface to VirtualBox where you can completely control VirtualBox. It can be +used to do things such as set RAM, CPUs, etc. -Extra VBoxManage commands are defined in the template in the `vboxmanage` section. -An example is shown below that sets the memory and number of CPUs within the -virtual machine: +Extra VBoxManage commands are defined in the template in the `vboxmanage` +section. An example is shown below that sets the memory and number of CPUs +within the virtual machine: -```javascript +``` {.javascript} { "vboxmanage": [ ["modifyvm", "{{.Name}}", "--memory", "1024"], @@ -329,12 +330,12 @@ virtual machine: } ``` -The value of `vboxmanage` is an array of commands to execute. These commands -are executed in the order defined. So in the above example, the memory will be -set followed by the CPUs. +The value of `vboxmanage` is an array of commands to execute. These commands are +executed in the order defined. So in the above example, the memory will be set +followed by the CPUs. -Each command itself is an array of strings, where each string is an argument -to `VBoxManage`. Each argument is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The only available variable is `Name` which is replaced with the unique -name of the VM, which is required for many VBoxManage calls. +Each command itself is an array of strings, where each string is an argument to +`VBoxManage`. Each argument is treated as a [configuration +template](/docs/templates/configuration-templates.html). The only available +variable is `Name` which is replaced with the unique name of the VM, which is +required for many VBoxManage calls. diff --git a/website/source/docs/builders/virtualbox-ovf.html.markdown b/website/source/docs/builders/virtualbox-ovf.html.markdown index 0a4516d02..dcf5dbd5c 100644 --- a/website/source/docs/builders/virtualbox-ovf.html.markdown +++ b/website/source/docs/builders/virtualbox-ovf.html.markdown @@ -1,39 +1,41 @@ --- -layout: "docs" -page_title: "VirtualBox Builder (from an OVF/OVA)" -description: |- - This VirtualBox Packer builder is able to create VirtualBox virtual machines and export them in the OVF format, starting from an existing OVF/OVA (exported virtual machine image). ---- +description: | + This VirtualBox Packer builder is able to create VirtualBox virtual machines and + export them in the OVF format, starting from an existing OVF/OVA (exported + virtual machine image). +layout: docs +page_title: 'VirtualBox Builder (from an OVF/OVA)' +... # VirtualBox Builder (from an OVF/OVA) Type: `virtualbox-ovf` -This VirtualBox Packer builder is able to create [VirtualBox](https://www.virtualbox.org/) -virtual machines and export them in the OVF format, starting from an -existing OVF/OVA (exported virtual machine image). +This VirtualBox Packer builder is able to create +[VirtualBox](https://www.virtualbox.org/) virtual machines and export them in +the OVF format, starting from an existing OVF/OVA (exported virtual machine +image). -When exporting from VirtualBox make sure to choose OVF Version 2, since Version 1 is not compatible and will generate errors like this: +When exporting from VirtualBox make sure to choose OVF Version 2, since Version +1 is not compatible and will generate errors like this: -``` -==> virtualbox-ovf: Progress state: VBOX_E_FILE_ERROR -==> virtualbox-ovf: VBoxManage: error: Appliance read failed -==> virtualbox-ovf: VBoxManage: error: Error reading "source.ova": element "Section" has no "type" attribute, line 21 -==> virtualbox-ovf: VBoxManage: error: Details: code VBOX_E_FILE_ERROR (0x80bb0004), component Appliance, interface IAppliance -==> virtualbox-ovf: VBoxManage: error: Context: "int handleImportAppliance(HandlerArg*)" at line 304 of file VBoxManageAppliance.cpp -``` + ==> virtualbox-ovf: Progress state: VBOX_E_FILE_ERROR + ==> virtualbox-ovf: VBoxManage: error: Appliance read failed + ==> virtualbox-ovf: VBoxManage: error: Error reading "source.ova": element "Section" has no "type" attribute, line 21 + ==> virtualbox-ovf: VBoxManage: error: Details: code VBOX_E_FILE_ERROR (0x80bb0004), component Appliance, interface IAppliance + ==> virtualbox-ovf: VBoxManage: error: Context: "int handleImportAppliance(HandlerArg*)" at line 304 of file VBoxManageAppliance.cpp -The builder builds a virtual machine by importing an existing OVF or OVA -file. It then boots this image, runs provisioners on this new VM, and -exports that VM to create the image. The imported machine is deleted prior -to finishing the build. +The builder builds a virtual machine by importing an existing OVF or OVA file. +It then boots this image, runs provisioners on this new VM, and exports that VM +to create the image. The imported machine is deleted prior to finishing the +build. ## Basic Example Here is a basic example. This example is functional if you have an OVF matching the settings here. -```javascript +``` {.javascript} { "type": "virtualbox-ovf", "source_path": "source.ovf", @@ -43,193 +45,194 @@ the settings here. } ``` -It is important to add a `shutdown_command`. By default Packer halts the -virtual machine and the file system may not be sync'd. Thus, changes made in a +It is important to add a `shutdown_command`. By default Packer halts the virtual +machine and the file system may not be sync'd. Thus, changes made in a provisioner might not be saved. ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `source_path` (string) - The path to an OVF or OVA file that acts as - the source of this build. +- `source_path` (string) - The path to an OVF or OVA file that acts as the + source of this build. -* `ssh_username` (string) - The username to use to SSH into the machine - once the OS is installed. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. ### 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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `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. +- `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 - 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. +- `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. -* `format` (string) - Either "ovf" or "ova", this specifies the output - format of the exported virtual machine. This defaults to "ovf". +- `format` (string) - Either "ovf" or "ova", this specifies the output format of + the exported virtual machine. This defaults to "ovf". -* `guest_additions_mode` (string) - The method by which guest additions - are made available to the guest for installation. Valid options are - "upload", "attach", or "disable". If the mode is "attach" the guest - additions ISO will be attached as a CD device to the virtual machine. - If the mode is "upload" the guest additions ISO will be uploaded to - the path specified by `guest_additions_path`. The default value is - "upload". If "disable" is used, guest additions won't be downloaded, - either. +- `guest_additions_mode` (string) - The method by which guest additions are made + available to the guest for installation. Valid options are "upload", "attach", + or "disable". If the mode is "attach" the guest additions ISO will be attached + as a CD device to the virtual machine. If the mode is "upload" the guest + additions ISO will be uploaded to the path specified by + `guest_additions_path`. The default value is "upload". If "disable" is used, + guest additions won't be downloaded, either. -* `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](/docs/templates/configuration-templates.html) - where the `Version` variable is replaced with the VirtualBox version. +- `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](/docs/templates/configuration-templates.html) 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 VirtualBox website, so this only - needs to be set if you want to be explicit about the checksum. +- `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 VirtualBox website, so this only needs to be set if you + want to be explicit about the checksum. -* `guest_additions_url` (string) - The URL to the guest additions ISO - to upload. This can also be a file URL if the ISO is at a local path. - By default the VirtualBox builder will go and download the proper - guest additions ISO from the internet. +- `guest_additions_url` (string) - The URL to the guest additions ISO to upload. + This can also be a file URL if the ISO is at a local path. By default the + VirtualBox builder will go and download the proper guest additions ISO from + the internet. -* `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. +- `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. -* `http_directory` (string) - Path to a directory to serve using an HTTP - server. The files in this directory will be available over HTTP that will - be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is "", which means no HTTP - server will be started. The address and port of the HTTP server will be - available as variables in `boot_command`. This is covered in more detail - below. +- `http_directory` (string) - Path to a directory to serve using an HTTP server. + The files in this directory will be available over HTTP that will be + requestable from the virtual machine. This is useful for hosting kickstart + files and so on. By default this is "", which means no HTTP server will + be started. The address and port of the HTTP server will be available as + variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (integer) - 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 - server to be on one port, make this minimum and maximum port the same. - By default the values are 8000 and 9000, respectively. + server to be on one port, make this minimum and maximum port the same. By + default the values are 8000 and 9000, respectively. -* `import_flags` (array of strings) - Additional flags to pass to - `VBoxManage import`. This can be used to add additional command-line flags - such as `--eula-accept` to accept a EULA in the OVF. +- `import_flags` (array of strings) - Additional flags to pass to + `VBoxManage import`. This can be used to add additional command-line flags + such as `--eula-accept` to accept a EULA in the OVF. -* `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. +- `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 +- `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. + 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. -* `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 unless a shutdown command takes place inside script so this may - safely be omitted. If one or more scripts require a reboot it is suggested to leave this blank - since reboots may fail and specify the final shutdown command in your last script. +- `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 unless a shutdown + command takes place inside script so this may safely be omitted. If one or + more scripts require a reboot it is suggested to leave this blank since + reboots may fail and specify the final shutdown command in your last script. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - If it doesn't shut down in this time, it is an error. By default, the timeout - is "5m", or five minutes. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. 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` (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, +- `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 host port. -* `ssh_skip_nat_mapping` (boolean) - Defaults to false. When enabled, Packer does - not setup forwarded port mapping for SSH requests and uses `ssh_port` on the - host to communicate to the virtual machine +- `ssh_skip_nat_mapping` (boolean) - Defaults to false. When enabled, Packer + does not setup forwarded port mapping for SSH requests and uses `ssh_port` on + the host to communicate to the virtual machine -* `vboxmanage` (array of array of strings) - Custom `VBoxManage` 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 `VBoxManage` (but excluding `VBoxManage` - 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 `VBoxManage` are below. +- `vboxmanage` (array of array of strings) - Custom `VBoxManage` 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 `VBoxManage` (but excluding `VBoxManage` 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 `VBoxManage` + are below. -* `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, +- `vboxmanage_post` (array of array of strings) - Identical to `vboxmanage`, except that it is run after the virtual machine is shutdown, and before the virtual machine is exported. -* `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 be upload it into - the home directory. +- `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 be upload it into the + home directory. -* `vm_name` (string) - This is the name of the virtual machine when it is - imported as well as the name of the OVF file when the virtual machine is - exported. By default this is "packer-BUILDNAME", where "BUILDNAME" is - the name of the build. +- `vm_name` (string) - This is the name of the virtual machine when it is + imported as well as the name of the OVF file when the virtual machine + is exported. By default this is "packer-BUILDNAME", where "BUILDNAME" is the + name of the build. ## Guest Additions -Packer will automatically download the proper guest additions for the -version of VirtualBox that is running and upload those guest additions into -the virtual machine so that provisioners can easily install them. +Packer will automatically download the proper guest additions for the version of +VirtualBox that is running and upload those guest additions into the virtual +machine so that provisioners can easily install them. -Packer downloads the guest additions from the official VirtualBox website, -and verifies the file with the official checksums released by VirtualBox. +Packer downloads the guest additions from the official VirtualBox website, and +verifies the file with the official checksums released by VirtualBox. -After the virtual machine is up and the operating system is installed, -Packer uploads the guest additions into the virtual machine. The path where -they are uploaded is controllable by `guest_additions_path`, and defaults -to "VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the -home directory of the SSH user. +After the virtual machine is up and the operating system is installed, Packer +uploads the guest additions into the virtual machine. The path where they are +uploaded is controllable by `guest_additions_path`, and defaults to +"VBoxGuestAdditions.iso". Without an absolute path, it is uploaded to the home +directory of the SSH user. ## VBoxManage Commands -In order to perform extra customization of the virtual machine, a template -can define extra calls to `VBoxManage` to perform. [VBoxManage](http://www.virtualbox.org/manual/ch08.html) -is the command-line interface to VirtualBox where you can completely control -VirtualBox. It can be used to do things such as set RAM, CPUs, etc. +In order to perform extra customization of the virtual machine, a template can +define extra calls to `VBoxManage` to perform. +[VBoxManage](http://www.virtualbox.org/manual/ch08.html) is the command-line +interface to VirtualBox where you can completely control VirtualBox. It can be +used to do things such as set RAM, CPUs, etc. -Extra VBoxManage commands are defined in the template in the `vboxmanage` section. -An example is shown below that sets the memory and number of CPUs within the -virtual machine: +Extra VBoxManage commands are defined in the template in the `vboxmanage` +section. An example is shown below that sets the memory and number of CPUs +within the virtual machine: -```javascript +``` {.javascript} { "vboxmanage": [ ["modifyvm", "{{.Name}}", "--memory", "1024"], @@ -238,12 +241,12 @@ virtual machine: } ``` -The value of `vboxmanage` is an array of commands to execute. These commands -are executed in the order defined. So in the above example, the memory will be -set followed by the CPUs. +The value of `vboxmanage` is an array of commands to execute. These commands are +executed in the order defined. So in the above example, the memory will be set +followed by the CPUs. -Each command itself is an array of strings, where each string is an argument -to `VBoxManage`. Each argument is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The only available variable is `Name` which is replaced with the unique -name of the VM, which is required for many VBoxManage calls. +Each command itself is an array of strings, where each string is an argument to +`VBoxManage`. Each argument is treated as a [configuration +template](/docs/templates/configuration-templates.html). The only available +variable is `Name` which is replaced with the unique name of the VM, which is +required for many VBoxManage calls. diff --git a/website/source/docs/builders/virtualbox.html.markdown b/website/source/docs/builders/virtualbox.html.markdown index 26e94b5b8..f96d37515 100644 --- a/website/source/docs/builders/virtualbox.html.markdown +++ b/website/source/docs/builders/virtualbox.html.markdown @@ -1,27 +1,28 @@ --- -layout: "docs" -page_title: "VirtualBox Builder" -description: |- - The VirtualBox Packer builder is able to create VirtualBox virtual machines and export them in the OVA or OVF format. ---- +description: | + The VirtualBox Packer builder is able to create VirtualBox virtual machines and + export them in the OVA or OVF format. +layout: docs +page_title: VirtualBox Builder +... # VirtualBox Builder -The VirtualBox Packer builder is able to create [VirtualBox](http://www.virtualbox.org) -virtual machines and export them in the OVA or OVF format. +The VirtualBox Packer builder is able to create +[VirtualBox](http://www.virtualbox.org) virtual machines and export them in the +OVA or OVF format. -Packer actually comes with multiple builders able to create VirtualBox -machines, depending on the strategy you want to use to build the image. -Packer supports the following VirtualBox builders: +Packer actually comes with multiple builders able to create VirtualBox machines, +depending on the strategy you want to use to build the image. Packer supports +the following VirtualBox builders: -* [virtualbox-iso](/docs/builders/virtualbox-iso.html) - Starts from - an ISO file, creates a brand new VirtualBox VM, installs an OS, - provisions software within the OS, then exports that machine to create - an image. This is best for people who want to start from scratch. +- [virtualbox-iso](/docs/builders/virtualbox-iso.html) - Starts from an ISO + file, creates a brand new VirtualBox VM, installs an OS, provisions software + within the OS, then exports that machine to create an image. This is best for + people who want to start from scratch. -* [virtualbox-ovf](/docs/builders/virtualbox-ovf.html) - This builder - imports an existing OVF/OVA file, runs provisioners on top of that VM, - and exports that machine to create an image. This is best if you have - an existing VirtualBox VM export you want to use as the source. As an - additional benefit, you can feed the artifact of this builder back into - itself to iterate on a machine. +- [virtualbox-ovf](/docs/builders/virtualbox-ovf.html) - This builder imports an + existing OVF/OVA file, runs provisioners on top of that VM, and exports that + machine to create an image. This is best if you have an existing VirtualBox VM + export you want to use as the source. As an additional benefit, you can feed + the artifact of this builder back into itself to iterate on a machine. diff --git a/website/source/docs/builders/vmware-iso.html.markdown b/website/source/docs/builders/vmware-iso.html.markdown index 8ac3a9fd3..ad2ac5c33 100644 --- a/website/source/docs/builders/vmware-iso.html.markdown +++ b/website/source/docs/builders/vmware-iso.html.markdown @@ -1,37 +1,40 @@ --- -layout: "docs" -page_title: "VMware Builder from ISO" -description: |- - This VMware Packer builder is able to create VMware virtual machines from an ISO file as a source. It currently supports building virtual machines on hosts running VMware Fusion for OS X, VMware Workstation for Linux and Windows, and VMware Player on Linux. It can also build machines directly on VMware vSphere Hypervisor using SSH as opposed to the vSphere API. ---- +description: | + This VMware Packer builder is able to create VMware virtual machines from an ISO + file as a source. It currently supports building virtual machines on hosts + running VMware Fusion for OS X, VMware Workstation for Linux and Windows, and + VMware Player on Linux. It can also build machines directly on VMware vSphere + Hypervisor using SSH as opposed to the vSphere API. +layout: docs +page_title: VMware Builder from ISO +... # VMware Builder (from ISO) Type: `vmware-iso` -This VMware Packer builder is able to create VMware virtual machines from an -ISO file as a source. It currently -supports building virtual machines on hosts running -[VMware Fusion](http://www.vmware.com/products/fusion/overview.html) for OS X, -[VMware Workstation](http://www.vmware.com/products/workstation/overview.html) -for Linux and Windows, and -[VMware Player](http://www.vmware.com/products/player/) on Linux. It can -also build machines directly on -[VMware vSphere Hypervisor](http://www.vmware.com/products/vsphere-hypervisor/) -using SSH as opposed to the vSphere API. +This VMware Packer builder is able to create VMware virtual machines from an ISO +file as a source. It currently supports building virtual machines on hosts +running [VMware Fusion](http://www.vmware.com/products/fusion/overview.html) for +OS X, [VMware +Workstation](http://www.vmware.com/products/workstation/overview.html) for Linux +and Windows, and [VMware Player](http://www.vmware.com/products/player/) on +Linux. It can also build machines directly on [VMware vSphere +Hypervisor](http://www.vmware.com/products/vsphere-hypervisor/) using SSH as +opposed to the vSphere API. -The builder builds a virtual machine by creating a new virtual machine -from scratch, booting it, installing an OS, provisioning software within -the OS, then shutting it down. The result of the VMware builder is a directory -containing all the files necessary to run the virtual machine. +The builder builds a virtual machine by creating a new virtual machine from +scratch, booting it, installing an OS, provisioning software within the OS, then +shutting it down. The result of the VMware builder is a directory containing all +the files necessary to run the virtual machine. ## Basic Example -Here is a basic example. This example is not functional. It will start the -OS installer but then fail because we don't provide the preseed file for -Ubuntu to self-install. Still, the example serves to show the basic configuration: +Here is a basic example. This example is not functional. It will start the OS +installer but then fail because we don't provide the preseed file for Ubuntu to +self-install. Still, the example serves to show the basic configuration: -```javascript +``` {.javascript} { "type": "vmware-iso", "iso_url": "http://old-releases.ubuntu.com/releases/precise/ubuntu-12.04.2-server-amd64.iso", @@ -44,261 +47,261 @@ Ubuntu to self-install. Still, the example serves to show the basic configuratio ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### 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 - to booting a virtual machine with the ISO attached. The type of the - checksum is specified with `iso_checksum_type`, documented below. +- `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 to booting a + virtual machine with the ISO attached. The type of the checksum is specified + with `iso_checksum_type`, documented below. -* `iso_checksum_type` (string) - The type of the checksum specified in +- `iso_checksum_type` (string) - The type of the checksum specified in `iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or "sha512" currently. While "none" will skip checksumming, this is not recommended since ISO files are generally large and corruption does happen from time to time. -* `iso_url` (string) - A URL to the ISO containing the installation image. - This URL can be either an HTTP URL or a file URL (or path to a file). - If this is an HTTP URL, Packer will download it and cache it between - runs. +- `iso_url` (string) - A URL to the ISO containing the installation image. This + URL can be either an HTTP URL or a file URL (or path to a file). If this is an + HTTP URL, Packer will download it and cache it between runs. -* `ssh_username` (string) - The username to use to SSH into the machine - once the OS is installed. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. ### Optional: -* `disk_additional_size` (array of integers) - The size(s) of any additional +- `disk_additional_size` (array of integers) - The size(s) of any additional hard disks for the VM in megabytes. If this is not specified then the VM will only contain a primary hard disk. 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. -* `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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `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). +- `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). -* `disk_type_id` (string) - The type of VMware virtual disk to create. - The default is "1", which corresponds to a growable virtual disk split in - 2GB files. This option is for advanced usage, modify only if you - know what you're doing. For more information, please consult the - [Virtual Disk Manager User's Guide](http://www.vmware.com/pdf/VirtualDiskManager.pdf) - for desktop VMware clients. For ESXi, refer to the proper ESXi documentation. +- `disk_type_id` (string) - The type of VMware virtual disk to create. The + default is "1", which corresponds to a growable virtual disk split in + 2GB files. This option is for advanced usage, modify only if you know what + you're doing. For more information, please consult the [Virtual Disk Manager + User's Guide](http://www.vmware.com/pdf/VirtualDiskManager.pdf) for desktop + VMware clients. For ESXi, refer to the proper ESXi documentation. -* `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. +- `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. -* `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this - is "/Applications/VMware Fusion.app" but this setting allows you to +- `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this is + "/Applications/VMware Fusion.app" but this setting allows you to customize this. -* `guest_os_type` (string) - The guest OS type being installed. This will be - set in the VMware VMX. By default this is "other". By specifying a more specific - OS type, VMware may perform some optimizations or virtual hardware changes - to better support the operating system running in the virtual machine. +- `guest_os_type` (string) - The guest OS type being installed. This will be set + in the VMware VMX. By default this is "other". By specifying a more specific + OS type, VMware may perform some optimizations or virtual hardware changes to + better support the operating system running in the virtual machine. -* `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 - connection information in case you need to connect to the console to - debug the build process. +- `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 connection information in case you need to + connect to the console to debug the build process. -* `http_directory` (string) - Path to a directory to serve using an HTTP - server. The files in this directory will be available over HTTP that will - be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is "", which means no HTTP - server will be started. The address and port of the HTTP server will be - available as variables in `boot_command`. This is covered in more detail - below. +- `http_directory` (string) - Path to a directory to serve using an HTTP server. + The files in this directory will be available over HTTP that will be + requestable from the virtual machine. This is useful for hosting kickstart + files and so on. By default this is "", which means no HTTP server will + be started. The address and port of the HTTP server will be available as + variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (integer) - 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 - server to be on one port, make this minimum and maximum port the same. - By default the values are 8000 and 9000, respectively. + server to be on one port, make this minimum and maximum port the same. By + default the values are 8000 and 9000, respectively. -* `iso_urls` (array of strings) - Multiple URLs for the ISO to download. - Packer will try these in order. If anything goes wrong attempting to download - or while downloading a single URL, it will move on to the next. All URLs - must point to the same file (same checksum). By default this is empty - and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified. +- `iso_urls` (array of strings) - Multiple URLs for the ISO to download. Packer + will try these in order. If anything goes wrong attempting to download or + while downloading a single URL, it will move on to the next. All URLs must + point to the same file (same checksum). By default this is empty and `iso_url` + is used. Only one of `iso_url` or `iso_urls` can be specified. -* `output_directory` (string) - This is the path to the directory where the +- `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. + 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. -* `remote_cache_datastore` (string) - The path to the datastore where - supporting files will be stored during the build on the remote machine. - By default this is the same as the `remote_datastore` option. This only - has an effect if `remote_type` is enabled. +- `remote_cache_datastore` (string) - The path to the datastore where supporting + files will be stored during the build on the remote machine. By default this + is the same as the `remote_datastore` option. This only has an effect if + `remote_type` is enabled. -* `remote_cache_directory` (string) - The path where the ISO and/or floppy - files will be stored during the build on the remote machine. The path is - relative to the `remote_cache_datastore` on the remote machine. By default - this is "packer_cache". This only has an effect if `remote_type` is enabled. +- `remote_cache_directory` (string) - The path where the ISO and/or floppy files + will be stored during the build on the remote machine. The path is relative to + the `remote_cache_datastore` on the remote machine. By default this + is "packer\_cache". This only has an effect if `remote_type` is enabled. -* `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 +- `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. -* `remote_host` (string) - The host of the remote machine used for access. - This is only required if `remote_type` is enabled. +- `remote_host` (string) - The host of the remote machine used for access. This + is only required if `remote_type` is enabled. -* `remote_password` (string) - The SSH password for the user used to - access the remote machine. By default this is empty. This only has an - effect if `remote_type` is enabled. +- `remote_password` (string) - The SSH password for the user used to 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_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 +- `remote_username` (string) - The username for the SSH user that will access the remote machine. This is required if `remote_type` is enabled. -* `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. +- `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. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - If it doesn't shut down in this time, it is an error. By default, the timeout - is "5m", or five minutes. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. 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 +- `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. -* `tools_upload_flavor` (string) - The flavor of the VMware Tools ISO to - upload into the VM. Valid values are "darwin", "linux", and "windows". - By default, this is empty, which means VMware tools won't be uploaded. +- `tools_upload_flavor` (string) - The flavor of the VMware Tools ISO to upload + into the VM. Valid values are "darwin", "linux", and "windows". By default, + this is empty, which means VMware tools won't be uploaded. -* `tools_upload_path` (string) - The path in the VM to upload the VMware - tools. This only takes effect if `tools_upload_flavor` is non-empty. - This is a [configuration template](/docs/templates/configuration-templates.html) - that has a single valid variable: `Flavor`, which will be the value of - `tools_upload_flavor`. By default the upload path is set to - `{{.Flavor}}.iso`. This setting is not used when `remote_type` is "esx5". +- `tools_upload_path` (string) - The path in the VM to upload the VMware tools. + This only takes effect if `tools_upload_flavor` is non-empty. This is a + [configuration template](/docs/templates/configuration-templates.html) that + has a single valid variable: `Flavor`, which will be the value of + `tools_upload_flavor`. By default the upload path is set to `{{.Flavor}}.iso`. + This setting is not used when `remote_type` is "esx5". -* `version` (string) - The [vmx hardware version](http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1003746) for the new virtual machine. Only the default value has been tested, any other value is experimental. Default value is '9'. +- `version` (string) - The [vmx hardware + version](http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1003746) + for the new virtual machine. Only the default value has been tested, any other + value is experimental. Default value is '9'. -* `vm_name` (string) - This is the name of the VMX file for the new virtual +- `vm_name` (string) - This is the name of the VMX file for the new virtual machine, without the file extension. By default this is "packer-BUILDNAME", where "BUILDNAME" is the name of the build. -* `vmdk_name` (string) - The filename of the virtual disk that'll be created, +- `vmdk_name` (string) - The filename of the virtual disk that'll be created, without the extension. This defaults to "packer". -* `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. +- `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. -* `vmx_data_post` (object of key/value strings) - Identical to `vmx_data`, +- `vmx_data_post` (object of key/value strings) - Identical to `vmx_data`, except that it is run after the virtual machine is shutdown, and before the virtual machine is exported. -* `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 - 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. +- `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 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. -* `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. +- `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 -to type when the virtual machine is first booted in order to start the -OS installer. This command is typed after `boot_wait`, which gives the -virtual machine some time to actually load the ISO. +The `boot_command` configuration is very important: it specifies the keys to +type when the virtual machine is first booted in order to start the OS +installer. This command is typed after `boot_wait`, which gives the virtual +machine some time to actually load the ISO. -As documented above, the `boot_command` is an array of strings. The -strings are all typed in sequence. It is an array only to improve readability -within the template. +As documented above, the `boot_command` is an array of strings. The strings are +all typed in sequence. It is an array only to improve readability within the +template. -The boot command is "typed" character for character over a VNC connection -to the machine, simulating a human actually typing the keyboard. There are -a set of special keys available. If these are in your boot command, they -will be replaced by the proper key: +The boot command is "typed" character for character over a VNC connection to the +machine, simulating a human actually typing the keyboard. There are a set of +special keys available. If these are in your boot command, they will be replaced +by the proper key: -* `` - Backspace +- `` - Backspace -* `` - Delete +- `` - Delete -* `` and `` - Simulates an actual "enter" or "return" keypress. +- `` and `` - Simulates an actual "enter" or "return" keypress. -* `` - Simulates pressing the escape key. +- `` - Simulates pressing the escape key. -* `` - Simulates pressing the tab key. +- `` - Simulates pressing the tab key. -* `` - `` - Simulates pressing a function key. +- `` - `` - Simulates pressing a function key. -* `` `` `` `` - Simulates pressing an arrow key. +- `` `` `` `` - Simulates pressing an arrow key. -* `` - Simulates pressing the spacebar. +- `` - Simulates pressing the spacebar. -* `` - Simulates pressing the insert key. +- `` - Simulates pressing the insert key. -* `` `` - Simulates pressing the home and end keys. +- `` `` - Simulates pressing the home and end keys. -* `` `` - Simulates pressing the page up and page down keys. +- `` `` - Simulates pressing the page up and page down keys. -* `` `` `` - Adds a 1, 5 or 10 second pause before sending any additional keys. This - is useful if you have to generally wait for the UI to update before typing more. +- `` `` `` - Adds a 1, 5 or 10 second pause before sending + any additional keys. This is useful if you have to generally wait for the UI + to update before typing more. In addition to the special keys, each command to type is treated as a -[configuration template](/docs/templates/configuration-templates.html). -The available variables are: +[configuration template](/docs/templates/configuration-templates.html). 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! +- `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! -Example boot command. This is actually a working boot command used to start -an Ubuntu 12.04 installer: +Example boot command. This is actually a working boot command used to start an +Ubuntu 12.04 installer: -```text +``` {.text} [ "", "/install/vmlinuz noapic ", @@ -314,71 +317,73 @@ an Ubuntu 12.04 installer: ## VMX Template -The heart of a VMware machine is the "vmx" file. This contains all the -virtual hardware metadata necessary for the VM to function. Packer by default -uses a [safe, flexible VMX file](https://github.com/mitchellh/packer/blob/20541a7eda085aa5cf35bfed5069592ca49d106e/builder/vmware/step_create_vmx.go#L84). -But for advanced users, this template can be customized. This allows -Packer to build virtual machines of effectively any guest operating system -type. +The heart of a VMware machine is the "vmx" file. This contains all the virtual +hardware metadata necessary for the VM to function. Packer by default uses a +[safe, flexible VMX +file](https://github.com/mitchellh/packer/blob/20541a7eda085aa5cf35bfed5069592ca49d106e/builder/vmware/step_create_vmx.go#L84). +But for advanced users, this template can be customized. This allows Packer to +build virtual machines of effectively any guest operating system type. -~> **This is an advanced feature.** Modifying the VMX template -can easily cause your virtual machine to not boot properly. Please only -modify the template if you know what you're doing. +\~> **This is an advanced feature.** Modifying the VMX template can easily +cause your virtual machine to not boot properly. Please only modify the template +if you know what you're doing. -Within the template, a handful of variables are available so that your -template can continue working with the rest of the Packer machinery. Using -these variables isn't required, however. +Within the template, a handful of variables are available so that your template +can continue working with the rest of the Packer machinery. Using these +variables isn't required, however. -* `Name` - The name of the virtual machine. -* `GuestOS` - The VMware-valid guest OS type. -* `DiskName` - The filename (without the suffix) of the main virtual disk. -* `ISOPath` - The path to the ISO to use for the OS installation. -* `Version` - The Hardware version VMWare will execute this vm under. Also known as the `virtualhw.version`. +- `Name` - The name of the virtual machine. +- `GuestOS` - The VMware-valid guest OS type. +- `DiskName` - The filename (without the suffix) of the main virtual disk. +- `ISOPath` - The path to the ISO to use for the OS installation. +- `Version` - The Hardware version VMWare will execute this vm under. Also known + as the `virtualhw.version`. ## Building on a Remote vSphere Hypervisor -In addition to using the desktop products of VMware locally to build -virtual machines, Packer can use a remote VMware Hypervisor to build -the virtual machine. +In addition to using the desktop products of VMware locally to build virtual +machines, Packer can use a remote VMware Hypervisor to build the virtual +machine. --> **Note:** Packer supports ESXi 5.1 and above. +-> **Note:** Packer supports ESXi 5.1 and above. -Before using a remote vSphere Hypervisor, you need to enable GuestIPHack by running the following command: +Before using a remote vSphere Hypervisor, you need to enable GuestIPHack by +running the following command: -```text +``` {.text} esxcli system settings advanced set -o /Net/GuestIPHack -i 1 ``` -When using a remote VMware Hypervisor, the builder still downloads the -ISO and various files locally, and uploads these to the remote machine. -Packer currently uses SSH to communicate to the ESXi machine rather than -the vSphere API. At some point, the vSphere API may be used. +When using a remote VMware Hypervisor, the builder still downloads the ISO and +various files locally, and uploads these to the remote machine. Packer currently +uses SSH to communicate to the ESXi machine rather than the vSphere API. At some +point, the vSphere API may be used. -Packer also requires VNC to issue boot commands during a build, -which may be disabled on some remote VMware Hypervisors. Please consult -the appropriate documentation on how to update VMware Hypervisor's firewall -to allow these connections. +Packer also requires VNC to issue boot commands during a build, which may be +disabled on some remote VMware Hypervisors. Please consult the appropriate +documentation on how to update VMware Hypervisor's firewall to allow these +connections. -To use a remote VMware vSphere Hypervisor to build your virtual machine, -fill in the required `remote_*` configurations: +To use a remote VMware vSphere Hypervisor to build your virtual machine, fill in +the required `remote_*` configurations: -* `remote_type` - This must be set to "esx5". +- `remote_type` - This must be set to "esx5". -* `remote_host` - The host of the remote machine. +- `remote_host` - The host of the remote machine. -Additionally, there are some optional configurations that you'll likely -have to modify as well: +Additionally, there are some optional configurations that you'll likely have to +modify as well: -* `remote_datastore` - The path to the datastore where the VM will be - stored on the ESXi machine. +- `remote_datastore` - The path to the datastore where the VM will be stored on + the ESXi machine. -* `remote_cache_datastore` - The path to the datastore where - supporting files will be stored during the build on the remote machine. +- `remote_cache_datastore` - The path to the datastore where supporting files + will be stored during the build on the remote machine. -* `remote_cache_directory` - The path where the ISO and/or floppy - files will be stored during the build on the remote machine. The path is - relative to the `remote_cache_datastore` on the remote machine. +- `remote_cache_directory` - The path where the ISO and/or floppy files will be + stored during the build on the remote machine. The path is relative to the + `remote_cache_datastore` on the remote machine. -* `remote_username` - The SSH username used to access the remote machine. +- `remote_username` - The SSH username used to access the remote machine. -* `remote_password` - The SSH password for access to the remote machine. +- `remote_password` - The SSH password for access to the remote machine. diff --git a/website/source/docs/builders/vmware-vmx.html.markdown b/website/source/docs/builders/vmware-vmx.html.markdown index e28ea3f89..bd1afb83c 100644 --- a/website/source/docs/builders/vmware-vmx.html.markdown +++ b/website/source/docs/builders/vmware-vmx.html.markdown @@ -1,34 +1,37 @@ --- -layout: "docs" -page_title: "VMware Builder from VMX" -description: |- - This VMware Packer builder is able to create VMware virtual machines from an existing VMware virtual machine (a VMX file). It currently supports building virtual machines on hosts running VMware Fusion Professional for OS X, VMware Workstation for Linux and Windows, and VMware Player on Linux. ---- +description: | + This VMware Packer builder is able to create VMware virtual machines from an + existing VMware virtual machine (a VMX file). It currently supports building + virtual machines on hosts running VMware Fusion Professional for OS X, VMware + Workstation for Linux and Windows, and VMware Player on Linux. +layout: docs +page_title: VMware Builder from VMX +... # VMware Builder (from VMX) Type: `vmware-vmx` This VMware Packer builder is able to create VMware virtual machines from an -existing VMware virtual machine (a VMX file). It currently -supports building virtual machines on hosts running -[VMware Fusion Professional](http://www.vmware.com/products/fusion-professional/) for OS X, +existing VMware virtual machine (a VMX file). It currently supports building +virtual machines on hosts running [VMware Fusion +Professional](http://www.vmware.com/products/fusion-professional/) for OS X, [VMware Workstation](http://www.vmware.com/products/workstation/overview.html) -for Linux and Windows, and -[VMware Player](http://www.vmware.com/products/player/) on Linux. +for Linux and Windows, and [VMware +Player](http://www.vmware.com/products/player/) on Linux. -The builder builds a virtual machine by cloning the VMX file using -the clone capabilities introduced in VMware Fusion Professional 6, Workstation 10, -and Player 6. After cloning the VM, it provisions software within the -new machine, shuts it down, and compacts the disks. The resulting folder -contains a new VMware virtual machine. +The builder builds a virtual machine by cloning the VMX file using the clone +capabilities introduced in VMware Fusion Professional 6, Workstation 10, and +Player 6. After cloning the VM, it provisions software within the new machine, +shuts it down, and compacts the disks. The resulting folder contains a new +VMware virtual machine. ## Basic Example -Here is an example. This example is fully functional as long as the source -path points to a real VMX file with the proper settings: +Here is an example. This example is fully functional as long as the source path +points to a real VMX file with the proper settings: -```javascript +``` {.javascript} { "type": "vmware-vmx", "source_path": "/path/to/a/vm.vmx", @@ -40,110 +43,109 @@ path points to a real VMX file with the proper settings: ## Configuration Reference -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. +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. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) -can be configured for this builder. +[communicator](/docs/templates/communicator.html) can be configured for this +builder. ### Required: -* `source_path` (string) - Path to the source VMX file to clone. +- `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. +- `ssh_username` (string) - The username to use to SSH into the machine once the + OS is installed. ### 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 - be to type just enough to initialize the operating system installer. Special - keys can be typed as well, and are covered in the section below on the boot - command. If this is not specified, it is assumed the installer will start - itself. +- `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 be to + type just enough to initialize the operating system installer. Special keys + can be typed as well, and are covered in the section below on the + boot command. If this is not specified, it is assumed the installer will + start itself. -* `boot_wait` (string) - The time to wait after booting the initial virtual +- `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. + 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. -* `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. +- `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. -* `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this - is "/Applications/VMware Fusion.app" but this setting allows you to +- `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this is + "/Applications/VMware Fusion.app" but this setting allows you to customize this. -* `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 - connection information in case you need to connect to the console to - debug the build process. +- `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 connection information in case you need to + connect to the console to debug the build process. -* `http_directory` (string) - Path to a directory to serve using an HTTP - server. The files in this directory will be available over HTTP that will - be requestable from the virtual machine. This is useful for hosting - kickstart files and so on. By default this is "", which means no HTTP - server will be started. The address and port of the HTTP server will be - available as variables in `boot_command`. This is covered in more detail - below. +- `http_directory` (string) - Path to a directory to serve using an HTTP server. + The files in this directory will be available over HTTP that will be + requestable from the virtual machine. This is useful for hosting kickstart + files and so on. By default this is "", which means no HTTP server will + be started. The address and port of the HTTP server will be available as + variables in `boot_command`. This is covered in more detail below. -* `http_port_min` and `http_port_max` (integer) - 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 - server to be on one port, make this minimum and maximum port the same. - By default the values are 8000 and 9000, respectively. + server to be on one port, make this minimum and maximum port the same. By + default the values are 8000 and 9000, respectively. -* `output_directory` (string) - This is the path to the directory where the +- `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. + 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. -* `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 unless a shutdown command takes place inside script so this may - safely be omitted. If one or more scripts require a reboot it is suggested to leave this blank - since reboots may fail and specify the final shutdown command in your last script. +- `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 unless a shutdown + command takes place inside script so this may safely be omitted. If one or + more scripts require a reboot it is suggested to leave this blank since + reboots may fail and specify the final shutdown command in your last script. -* `shutdown_timeout` (string) - The amount of time to wait after executing - the `shutdown_command` for the virtual machine to actually shut down. - If it doesn't shut down in this time, it is an error. By default, the timeout - is "5m", or five minutes. +- `shutdown_timeout` (string) - The amount of time to wait after executing the + `shutdown_command` for the virtual machine to actually shut down. 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 +- `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. -* `vm_name` (string) - This is the name of the VMX file for the new virtual +- `vm_name` (string) - This is the name of the VMX file for the new virtual machine, without the file extension. By default this is "packer-BUILDNAME", where "BUILDNAME" is the name of the build. -* `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. +- `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. -* `vmx_data_post` (object of key/value strings) - Identical to `vmx_data`, +- `vmx_data_post` (object of key/value strings) - Identical to `vmx_data`, except that it is run after the virtual machine is shutdown, and before the virtual machine is exported. -* `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. +- `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. diff --git a/website/source/docs/builders/vmware.html.markdown b/website/source/docs/builders/vmware.html.markdown index 84d94a369..e77fe574a 100644 --- a/website/source/docs/builders/vmware.html.markdown +++ b/website/source/docs/builders/vmware.html.markdown @@ -1,27 +1,28 @@ --- -layout: "docs" -page_title: "VMware Builder" -description: |- - The VMware Packer builder is able to create VMware virtual machines for use with any VMware product. ---- +description: | + The VMware Packer builder is able to create VMware virtual machines for use with + any VMware product. +layout: docs +page_title: VMware Builder +... # VMware Builder -The VMware Packer builder is able to create VMware virtual machines for use -with any VMware product. +The VMware Packer builder is able to create VMware virtual machines for use with +any VMware product. -Packer actually comes with multiple builders able to create VMware -machines, depending on the strategy you want to use to build the image. -Packer supports the following VMware builders: +Packer actually comes with multiple builders able to create VMware machines, +depending on the strategy you want to use to build the image. Packer supports +the following VMware builders: -* [vmware-iso](/docs/builders/vmware-iso.html) - Starts from - an ISO file, creates a brand new VMware VM, installs an OS, - provisions software within the OS, then exports that machine to create - an image. This is best for people who want to start from scratch. +- [vmware-iso](/docs/builders/vmware-iso.html) - Starts from an ISO file, + creates a brand new VMware VM, installs an OS, provisions software within the + OS, then exports that machine to create an image. This is best for people who + want to start from scratch. -* [vmware-vmx](/docs/builders/vmware-vmx.html) - This builder - imports an existing VMware machine (from a VMX file), runs provisioners - on top of that VM, and exports that machine to create an image. - This is best if you have an existing VMware VM you want to use as the - source. As an additional benefit, you can feed the artifact of this - builder back into Packer to iterate on a machine. +- [vmware-vmx](/docs/builders/vmware-vmx.html) - This builder imports an + existing VMware machine (from a VMX file), runs provisioners on top of that + VM, and exports that machine to create an image. This is best if you have an + existing VMware VM you want to use as the source. As an additional benefit, + you can feed the artifact of this builder back into Packer to iterate on + a machine. diff --git a/website/source/docs/command-line/build.html.markdown b/website/source/docs/command-line/build.html.markdown index bada564a1..92afda570 100644 --- a/website/source/docs/command-line/build.html.markdown +++ b/website/source/docs/command-line/build.html.markdown @@ -1,37 +1,40 @@ --- -layout: "docs" -page_title: "Build - Command-Line" -description: |- - The `packer build` Packer command takes a template and runs all the builds within it in order to generate a set of artifacts. The various builds specified within a template are executed in parallel, unless otherwise specified. And the artifacts that are created will be outputted at the end of the build. ---- +description: | + The `packer build` Packer command takes a template and runs all the builds + within it in order to generate a set of artifacts. The various builds specified + within a template are executed in parallel, unless otherwise specified. And the + artifacts that are created will be outputted at the end of the build. +layout: docs +page_title: 'Build - Command-Line' +... # Command-Line: Build -The `packer build` Packer command takes a template and runs all the builds within -it in order to generate a set of artifacts. The various builds specified within -a template are executed in parallel, unless otherwise specified. And the +The `packer build` Packer command takes a template and runs all the builds +within it in order to generate a set of artifacts. The various builds specified +within a template are executed in parallel, unless otherwise specified. And the artifacts that are created will be outputted at the end of the build. ## Options -* `-color=false` - Disables colorized output. Enabled by default. +- `-color=false` - Disables colorized output. Enabled by default. -* `-debug` - Disables parallelization and enables debug mode. Debug mode flags +- `-debug` - Disables parallelization and enables debug mode. Debug mode flags the builders that they should output debugging information. The exact behavior of debug mode is left to the builder. In general, builders usually will stop - between each step, waiting for keyboard input before continuing. This will allow - the user to inspect state and so on. + 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 +- `-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. +- `-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. -* `-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. +- `-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/command-line/fix.html.markdown b/website/source/docs/command-line/fix.html.markdown index 958ebd0f8..eb383fec6 100644 --- a/website/source/docs/command-line/fix.html.markdown +++ b/website/source/docs/command-line/fix.html.markdown @@ -1,33 +1,34 @@ --- -layout: "docs" -page_title: "Fix - Command-Line" -description: |- - The `packer fix` Packer command takes a template and finds backwards incompatible parts of it and brings it up to date so it can be used with the latest version of Packer. After you update to a new Packer release, you should run the fix command to make sure your templates work with the new release. ---- +description: | + The `packer fix` Packer command takes a template and finds backwards + incompatible parts of it and brings it up to date so it can be used with the + latest version of Packer. After you update to a new Packer release, you should + run the fix command to make sure your templates work with the new release. +layout: docs +page_title: 'Fix - Command-Line' +... # Command-Line: Fix -The `packer fix` Packer command takes a template and finds backwards incompatible -parts of it and brings it up to date so it can be used with the latest version -of Packer. After you update to a new Packer release, you should run the -fix command to make sure your templates work with the new release. +The `packer fix` Packer command takes a template and finds backwards +incompatible parts of it and brings it up to date so it can be used with the +latest version of Packer. After you update to a new Packer release, you should +run the fix command to make sure your templates work with the new release. -The fix command will output the changed template to standard out, so you -should redirect standard using standard OS-specific techniques if you want to -save it to a file. For example, on Linux systems, you may want to do this: +The fix command will output the changed template to standard out, so you should +redirect standard using standard OS-specific techniques if you want to save it +to a file. For example, on Linux systems, you may want to do this: -``` -$ packer fix old.json > new.json -``` + $ packer fix old.json > new.json -If fixing fails for any reason, the fix command will exit with a non-zero -exit status. Error messages appear on standard error, so if you're redirecting +If fixing fails for any reason, the fix command will exit with a non-zero exit +status. Error messages appear on standard error, so if you're redirecting output, you'll still see error messages. --> **Even when Packer fix doesn't do anything** to the template, -the template will be outputted to standard out. Things such as configuration -key ordering and indentation may be changed. The output format however, is -pretty-printed for human readability. +-> **Even when Packer fix doesn't do anything** to the template, the template +will be outputted to standard out. Things such as configuration key ordering and +indentation may be changed. The output format however, is pretty-printed for +human readability. -The full list of fixes that the fix command performs is visible in the -help output, which can be seen via `packer fix -h`. +The full list of fixes that the fix command performs is visible in the help +output, which can be seen via `packer fix -h`. diff --git a/website/source/docs/command-line/inspect.html.markdown b/website/source/docs/command-line/inspect.html.markdown index 09f979208..a1a86e3e5 100644 --- a/website/source/docs/command-line/inspect.html.markdown +++ b/website/source/docs/command-line/inspect.html.markdown @@ -1,33 +1,35 @@ --- -layout: "docs" -page_title: "Inspect - Command-Line" -description: |- - The `packer inspect` Packer command takes a template and outputs the various components a template defines. This can help you quickly learn about a template without having to dive into the JSON itself. The command will tell you things like what variables a template accepts, the builders it defines, the provisioners it defines and the order they'll run, and more. ---- +description: | + The `packer inspect` Packer command takes a template and outputs the various + components a template defines. This can help you quickly learn about a template + without having to dive into the JSON itself. The command will tell you things + like what variables a template accepts, the builders it defines, the + provisioners it defines and the order they'll run, and more. +layout: docs +page_title: 'Inspect - Command-Line' +... # Command-Line: Inspect -The `packer inspect` Packer command takes a template and outputs the various components -a template defines. This can help you quickly learn about a template without -having to dive into the JSON itself. -The command will tell you things like what variables a template accepts, -the builders it defines, the provisioners it defines and the order they'll -run, and more. +The `packer inspect` Packer command takes a template and outputs the various +components a template defines. This can help you quickly learn about a template +without having to dive into the JSON itself. The command will tell you things +like what variables a template accepts, the builders it defines, the +provisioners it defines and the order they'll run, and more. -This command is extra useful when used with -[machine-readable output](/docs/command-line/machine-readable.html) enabled. -The command outputs the components in a way that is parseable by machines. +This command is extra useful when used with [machine-readable +output](/docs/command-line/machine-readable.html) enabled. The command outputs +the components in a way that is parseable by machines. -The command doesn't validate the actual configuration of the various -components (that is what the `validate` command is for), but it will -validate the syntax of your template by necessity. +The command doesn't validate the actual configuration of the various components +(that is what the `validate` command is for), but it will validate the syntax of +your template by necessity. ## Usage Example -Given a basic template, here is an example of what the output might -look like: +Given a basic template, here is an example of what the output might look like: -```text +``` {.text} $ packer inspect template.json Variables and their defaults: diff --git a/website/source/docs/command-line/introduction.html.markdown b/website/source/docs/command-line/introduction.html.markdown index 0a97e0056..ea9834397 100644 --- a/website/source/docs/command-line/introduction.html.markdown +++ b/website/source/docs/command-line/introduction.html.markdown @@ -1,24 +1,27 @@ --- -layout: "docs" -page_title: "Packer Command-Line" -description: |- - Packer is controlled using a command-line interface. All interaction with Packer is done via the `packer` tool. Like many other command-line tools, the `packer` tool takes a subcommand to execute, and that subcommand may have additional options as well. Subcommands are executed with `packer SUBCOMMAND`, where "SUBCOMMAND" is obviously the actual command you wish to execute. ---- +description: | + Packer is controlled using a command-line interface. All interaction with Packer + is done via the `packer` tool. Like many other command-line tools, the `packer` + tool takes a subcommand to execute, and that subcommand may have additional + options as well. Subcommands are executed with `packer SUBCOMMAND`, where + "SUBCOMMAND" is obviously the actual command you wish to execute. +layout: docs +page_title: 'Packer Command-Line' +... # Packer Command-Line -Packer is controlled using a command-line interface. All interaction with -Packer is done via the `packer` tool. Like many other command-line tools, -the `packer` tool takes a subcommand to execute, and that subcommand may -have additional options as well. Subcommands are executed with -`packer SUBCOMMAND`, where "SUBCOMMAND" is obviously the actual command you wish -to execute. +Packer is controlled using a command-line interface. All interaction with Packer +is done via the `packer` tool. Like many other command-line tools, the `packer` +tool takes a subcommand to execute, and that subcommand may have additional +options as well. Subcommands are executed with `packer SUBCOMMAND`, where +"SUBCOMMAND" is obviously the actual command you wish to execute. If you run `packer` by itself, help will be displayed showing all available subcommands and a brief synopsis of what they do. In addition to this, you can -run any `packer` command with the `-h` flag to output more detailed help for -a specific subcommand. +run any `packer` command with the `-h` flag to output more detailed help for a +specific subcommand. -In addition to the documentation available on the command-line, each command -is documented on this website. You can find the documentation for a specific +In addition to the documentation available on the command-line, each command is +documented on this website. You can find the documentation for a specific subcommand using the navigation to the left. diff --git a/website/source/docs/command-line/machine-readable.html.markdown b/website/source/docs/command-line/machine-readable.html.markdown index 5fed33310..550a14f35 100644 --- a/website/source/docs/command-line/machine-readable.html.markdown +++ b/website/source/docs/command-line/machine-readable.html.markdown @@ -1,30 +1,33 @@ --- -layout: "docs" -page_title: "Machine-Readable Output - Command-Line" -description: |- - By default, the output of Packer is very human-readable. It uses nice formatting, spacing, and colors in order to make Packer a pleasure to use. However, Packer was built with automation in mind. To that end, Packer supports a fully machine-readable output setting, allowing you to use Packer in automated environments. ---- +description: | + By default, the output of Packer is very human-readable. It uses nice + formatting, spacing, and colors in order to make Packer a pleasure to use. + However, Packer was built with automation in mind. To that end, Packer supports + a fully machine-readable output setting, allowing you to use Packer in automated + environments. +layout: docs +page_title: 'Machine-Readable Output - Command-Line' +... # Machine-Readable Output By default, the output of Packer is very human-readable. It uses nice formatting, spacing, and colors in order to make Packer a pleasure to use. -However, Packer was built with automation in mind. To that end, Packer -supports a fully machine-readable output setting, allowing you to use -Packer in automated environments. +However, Packer was built with automation in mind. To that end, Packer supports +a fully machine-readable output setting, allowing you to use Packer in automated +environments. -The machine-readable output format is easy to use and read and was made -with Unix tools in mind, so it is awk/sed/grep/etc. friendly. +The machine-readable output format is easy to use and read and was made with +Unix tools in mind, so it is awk/sed/grep/etc. friendly. ## Enabling The machine-readable output format can be enabled by passing the -`-machine-readable` flag to any Packer command. This immediately enables -all output to become machine-readable on stdout. Logging, if enabled, -continues to appear on stderr. An example of the output is shown -below: +`-machine-readable` flag to any Packer command. This immediately enables all +output to become machine-readable on stdout. Logging, if enabled, continues to +appear on stderr. An example of the output is shown below: -```text +``` {.text} $ packer -machine-readable version 1376289459,,version,0.2.4 1376289459,,version-prerelease, @@ -32,54 +35,50 @@ $ packer -machine-readable version 1376289459,,ui,say,Packer v0.2.4.dev (eed6ece+CHANGES) ``` -The format will be covered in more detail later. But as you can see, -the output immediately becomes machine-friendly. Try some other commands -with the `-machine-readable` flag to see! +The format will be covered in more detail later. But as you can see, the output +immediately becomes machine-friendly. Try some other commands with the +`-machine-readable` flag to see! ## Format -The machine readable format is a line-oriented, comma-delimited text -format. This makes it extremely easy to parse using standard Unix tools such -as awk or grep in addition to full programming languages like Ruby or -Python. +The machine readable format is a line-oriented, comma-delimited text format. +This makes it extremely easy to parse using standard Unix tools such as awk or +grep in addition to full programming languages like Ruby or Python. The format is: -```text +``` {.text} timestamp,target,type,data... ``` Each component is explained below: -* **timestamp** is a Unix timestamp in UTC of when the message was - printed. +- **timestamp** is a Unix timestamp in UTC of when the message was printed. -* **target** is the target of the following output. This is empty if - the message is related to Packer globally. Otherwise, this is generally - a build name so you can relate output to a specific build while parallel - builds are running. +- **target** is the target of the following output. This is empty if the message + is related to Packer globally. Otherwise, this is generally a build name so + you can relate output to a specific build while parallel builds are running. -* **type** is the type of machine-readable message being outputted. There - are a set of standard types which are covered later, but each component - of Packer (builders, provisioners, etc.) may output their own custom types - as well, allowing the machine-readable output to be infinitely flexible. +- **type** is the type of machine-readable message being outputted. There are a + set of standard types which are covered later, but each component of Packer + (builders, provisioners, etc.) may output their own custom types as well, + allowing the machine-readable output to be infinitely flexible. -* **data** is zero or more comma-seperated values associated with the prior - type. The exact amount and meaning of this data is type-dependent, so you - must read the documentation associated with the type to understand fully. +- **data** is zero or more comma-seperated values associated with the + prior type. The exact amount and meaning of this data is type-dependent, so + you must read the documentation associated with the type to understand fully. Within the format, if data contains a comma, it is replaced with -`%!(PACKER_COMMA)`. This was preferred over an escape character such as -`\'` because it is more friendly to tools like awk. +`%!(PACKER_COMMA)`. This was preferred over an escape character such as `\'` +because it is more friendly to tools like awk. -Newlines within the format are replaced with their respective standard -escape sequence. Newlines become a literal `\n` within the output. Carriage -returns become a literal `\r`. +Newlines within the format are replaced with their respective standard escape +sequence. Newlines become a literal `\n` within the output. Carriage returns +become a literal `\r`. ## Message Types -The set of machine-readable message types can be found in the -[machine-readable format](/docs/machine-readable/index.html) -complete documentation section. This section contains documentation -on all the message types exposed by Packer core as well as all the -components that ship with Packer by default. +The set of machine-readable message types can be found in the [machine-readable +format](/docs/machine-readable/index.html) complete documentation section. This +section contains documentation on all the message types exposed by Packer core +as well as all the components that ship with Packer by default. diff --git a/website/source/docs/command-line/push.html.markdown b/website/source/docs/command-line/push.html.markdown index 5833b917f..0cc9699f5 100644 --- a/website/source/docs/command-line/push.html.markdown +++ b/website/source/docs/command-line/push.html.markdown @@ -1,9 +1,10 @@ --- -layout: "docs" -page_title: "Push - Command-Line" -description: |- - The `packer push` Packer command takes a template and pushes it to a build service that will automatically build this Packer template. ---- +description: | + The `packer push` Packer command takes a template and pushes it to a build + service that will automatically build this Packer template. +layout: docs +page_title: 'Push - Command-Line' +... # Command-Line: Push @@ -16,36 +17,36 @@ External build services such as HashiCorp's Atlas make it easy to iterate on Packer templates, especially when the builder you are running may not be easily accessable (such as developing `qemu` builders on Mac or Windows). -!> The Packer build service will receive the raw copy of your Packer template +!> The Packer build service will receive the raw copy of your Packer template when you push. **If you have sensitive data in your Packer template, you should move that data into Packer variables or environment variables!** -For the `push` command to work, the [push configuration](/docs/templates/push.html) -must be completed within the template. +For the `push` command to work, the [push +configuration](/docs/templates/push.html) must be completed within the template. ## Options -* `-message` - A message to identify the purpose or changes in this Packer +- `-message` - A message to identify the purpose or changes in this Packer template much like a VCS commit message. This message will be passed to the Packer build service. This option is also available as a short option `-m`. -* `-token` - An access token for authenticating the push to the Packer build +- `-token` - An access token for authenticating the push to the Packer build service such as Atlas. This can also be specified within the push configuration in the template. -* `-name` - The name of the build in the service. This typically - looks like `hashicorp/precise64`. +- `-name` - The name of the build in the service. This typically looks like + `hashicorp/precise64`. ## Examples Push a Packer template: -```shell +``` {.shell} $ packer push -m "Updating the apache version" template.json ``` Push a Packer template with a custom token: -```shell +``` {.shell} $ packer push -token ABCD1234 template.json ``` diff --git a/website/source/docs/command-line/validate.html.markdown b/website/source/docs/command-line/validate.html.markdown index 530f00295..e17f23dc4 100644 --- a/website/source/docs/command-line/validate.html.markdown +++ b/website/source/docs/command-line/validate.html.markdown @@ -1,20 +1,24 @@ --- -layout: "docs" -page_title: "Validate - Command-Line" -description: |- - The `packer validate` Packer command is used to validate the syntax and configuration of a template. The command will return a zero exit status on success, and a non-zero exit status on failure. Additionally, if a template doesn't validate, any error messages will be outputted. ---- +description: | + The `packer validate` Packer command is used to validate the syntax and + configuration of a template. The command will return a zero exit status on + success, and a non-zero exit status on failure. Additionally, if a template + doesn't validate, any error messages will be outputted. +layout: docs +page_title: 'Validate - Command-Line' +... # Command-Line: Validate -The `packer validate` Packer command is used to validate the syntax and configuration -of a [template](/docs/templates/introduction.html). The command will return -a zero exit status on success, and a non-zero exit status on failure. Additionally, -if a template doesn't validate, any error messages will be outputted. +The `packer validate` Packer command is used to validate the syntax and +configuration of a [template](/docs/templates/introduction.html). The command +will return a zero exit status on success, and a non-zero exit status on +failure. Additionally, if a template doesn't validate, any error messages will +be outputted. Example usage: -```text +``` {.text} $ packer validate my-template.json Template validation failed. Errors are shown below. @@ -25,5 +29,5 @@ Errors validating build 'vmware'. 1 error(s) occurred: ## Options -* `-syntax-only` - Only the syntax of the template is checked. The configuration +- `-syntax-only` - Only the syntax of the template is checked. The configuration is not validated. diff --git a/website/source/docs/extend/builder.html.markdown b/website/source/docs/extend/builder.html.markdown index a841d5c3d..41a83bcef 100644 --- a/website/source/docs/extend/builder.html.markdown +++ b/website/source/docs/extend/builder.html.markdown @@ -1,167 +1,170 @@ --- -layout: "docs" -page_title: "Custom Builder - Extend Packer" -description: |- - Packer Builders are the components of Packer responsible for creating a machine, bringing it to a point where it can be provisioned, and then turning that provisioned machine into some sort of machine image. Several builders are officially distributed with Packer itself, such as the AMI builder, the VMware builder, etc. However, it is possible to write custom builders using the Packer plugin interface, and this page documents how to do that. ---- +description: | + Packer Builders are the components of Packer responsible for creating a machine, + bringing it to a point where it can be provisioned, and then turning that + provisioned machine into some sort of machine image. Several builders are + officially distributed with Packer itself, such as the AMI builder, the VMware + builder, etc. However, it is possible to write custom builders using the Packer + plugin interface, and this page documents how to do that. +layout: docs +page_title: 'Custom Builder - Extend Packer' +... # Custom Builder Development Packer Builders are the components of Packer responsible for creating a machine, -bringing it to a point where it can be provisioned, and then turning -that provisioned machine into some sort of machine image. Several builders -are officially distributed with Packer itself, such as the AMI builder, the -VMware builder, etc. However, it is possible to write custom builders using -the Packer plugin interface, and this page documents how to do that. +bringing it to a point where it can be provisioned, and then turning that +provisioned machine into some sort of machine image. Several builders are +officially distributed with Packer itself, such as the AMI builder, the VMware +builder, etc. However, it is possible to write custom builders using the Packer +plugin interface, and this page documents how to do that. -Prior to reading this page, it is assumed you have read the page on -[plugin development basics](/docs/extend/developing-plugins.html). +Prior to reading this page, it is assumed you have read the page on [plugin +development basics](/docs/extend/developing-plugins.html). -~> **Warning!** This is an advanced topic. If you're new to Packer, we +\~> **Warning!** This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins. ## The Interface The interface that must be implemented for a builder is the `packer.Builder` -interface. It is reproduced below for easy reference. The actual interface -in the source code contains some basic documentation as well explaining -what each method should do. +interface. It is reproduced below for easy reference. The actual interface in +the source code contains some basic documentation as well explaining what each +method should do. -```go +``` {.go} type Builder interface { - Prepare(...interface{}) error - Run(ui Ui, hook Hook, cache Cache) (Artifact, error) - Cancel() + Prepare(...interface{}) error + Run(ui Ui, hook Hook, cache Cache) (Artifact, error) + Cancel() } ``` ### The "Prepare" Method -The `Prepare` method for each builder is called prior to any runs with -the configuration that was given in the template. This is passed in as -an array of `interface{}` types, but is generally `map[string]interface{}`. The prepare +The `Prepare` method for each builder is called prior to any runs with the +configuration that was given in the template. This is passed in as an array of +`interface{}` types, but is generally `map[string]interface{}`. The prepare method is responsible for translating this configuration into an internal structure, validating it, and returning any errors. For multiple parameters, they should be merged together into the final -configuration, with later parameters overwriting any previous configuration. -The exact semantics of the merge are left to the builder author. +configuration, with later parameters overwriting any previous configuration. The +exact semantics of the merge are left to the builder author. For decoding the `interface{}` into a meaningful structure, the -[mapstructure](https://github.com/mitchellh/mapstructure) library is recommended. -Mapstructure will take an `interface{}` and decode it into an arbitrarily -complex struct. If there are any errors, it generates very human friendly -errors that can be returned directly from the prepare method. +[mapstructure](https://github.com/mitchellh/mapstructure) library is +recommended. Mapstructure will take an `interface{}` and decode it into an +arbitrarily complex struct. If there are any errors, it generates very human +friendly errors that can be returned directly from the prepare method. -While it is not actively enforced, **no side effects** should occur from -running the `Prepare` method. Specifically, don't create files, don't launch -virtual machines, etc. Prepare's purpose is solely to configure the builder -and validate the configuration. +While it is not actively enforced, **no side effects** should occur from running +the `Prepare` method. Specifically, don't create files, don't launch virtual +machines, etc. Prepare's purpose is solely to configure the builder and validate +the configuration. -In addition to normal configuration, Packer will inject a `map[string]interface{}` -with a key of `packer.DebugConfigKey` set to boolean `true` if debug mode -is enabled for the build. If this is set to true, then the builder -should enable a debug mode which assists builder developers and advanced -users to introspect what is going on during a build. During debug -builds, parallelism is strictly disabled, so it is safe to request input -from stdin and so on. +In addition to normal configuration, Packer will inject a +`map[string]interface{}` with a key of `packer.DebugConfigKey` set to boolean +`true` if debug mode is enabled for the build. If this is set to true, then the +builder should enable a debug mode which assists builder developers and advanced +users to introspect what is going on during a build. During debug builds, +parallelism is strictly disabled, so it is safe to request input from stdin and +so on. ### The "Run" Method -`Run` is where all the interesting stuff happens. Run is executed, often -in parallel for multiple builders, to actually build the machine, provision -it, and create the resulting machine image, which is returned as an -implementation of the `packer.Artifact` interface. +`Run` is where all the interesting stuff happens. Run is executed, often in +parallel for multiple builders, to actually build the machine, provision it, and +create the resulting machine image, which is returned as an implementation of +the `packer.Artifact` interface. The `Run` method takes three parameters. These are all very useful. The -`packer.Ui` object is used to send output to the console. `packer.Hook` is -used to execute hooks, which are covered in more detail in the hook section -below. And `packer.Cache` is used to store files between multiple Packer -runs, and is covered in more detail in the cache section below. +`packer.Ui` object is used to send output to the console. `packer.Hook` is used +to execute hooks, which are covered in more detail in the hook section below. +And `packer.Cache` is used to store files between multiple Packer runs, and is +covered in more detail in the cache section below. Because builder runs are typically a complex set of many steps, the -[multistep](https://github.com/mitchellh/multistep) library is recommended -to bring order to the complexity. Multistep is a library which allows you to -separate your logic into multiple distinct "steps" and string them together. -It fully supports cancellation mid-step and so on. Please check it out, it is -how the built-in builders are all implemented. +[multistep](https://github.com/mitchellh/multistep) library is recommended to +bring order to the complexity. Multistep is a library which allows you to +separate your logic into multiple distinct "steps" and string them together. It +fully supports cancellation mid-step and so on. Please check it out, it is how +the built-in builders are all implemented. -Finally, as a result of `Run`, an implementation of `packer.Artifact` should -be returned. More details on creating a `packer.Artifact` are covered in the -artifact section below. If something goes wrong during the build, an error -can be returned, as well. Note that it is perfectly fine to produce no artifact -and no error, although this is rare. +Finally, as a result of `Run`, an implementation of `packer.Artifact` should be +returned. More details on creating a `packer.Artifact` are covered in the +artifact section below. If something goes wrong during the build, an error can +be returned, as well. Note that it is perfectly fine to produce no artifact and +no error, although this is rare. ### The "Cancel" Method -The `Run` method is often run in parallel. The `Cancel` method can be -called at any time and requests cancellation of any builder run in progress. -This method should block until the run actually stops. +The `Run` method is often run in parallel. The `Cancel` method can be called at +any time and requests cancellation of any builder run in progress. This method +should block until the run actually stops. -Cancels are most commonly triggered by external interrupts, such as the -user pressing `Ctrl-C`. Packer will only exit once all the builders clean up, -so it is important that you architect your builder in a way that it is quick -to respond to these cancellations and clean up after itself. +Cancels are most commonly triggered by external interrupts, such as the user +pressing `Ctrl-C`. Packer will only exit once all the builders clean up, so it +is important that you architect your builder in a way that it is quick to +respond to these cancellations and clean up after itself. ## Creating an Artifact The `Run` method is expected to return an implementation of the -`packer.Artifact` interface. Each builder must create their own -implementation. The interface is very simple and the documentation on the -interface is quite clear. +`packer.Artifact` interface. Each builder must create their own implementation. +The interface is very simple and the documentation on the interface is quite +clear. -The only part of an artifact that may be confusing is the `BuilderId` -method. This method must return an absolutely unique ID for the builder. -In general, I follow the practice of making the ID contain my GitHub username -and then the platform it is building for. For example, the builder ID of -the VMware builder is "mitchellh.vmware" or something similar. +The only part of an artifact that may be confusing is the `BuilderId` method. +This method must return an absolutely unique ID for the builder. In general, I +follow the practice of making the ID contain my GitHub username and then the +platform it is building for. For example, the builder ID of the VMware builder +is "mitchellh.vmware" or something similar. -Post-processors use the builder ID value in order to make some assumptions -about the artifact results, so it is important it never changes. +Post-processors use the builder ID value in order to make some assumptions about +the artifact results, so it is important it never changes. -Other than the builder ID, the rest should be self-explanatory by reading -the [packer.Artifact interface documentation](#). +Other than the builder ID, the rest should be self-explanatory by reading the +[packer.Artifact interface documentation](#). ## Provisioning Packer has built-in support for provisioning, but the moment when provisioning -runs must be invoked by the builder itself, since only the builder knows -when the machine is running and ready for communication. +runs must be invoked by the builder itself, since only the builder knows when +the machine is running and ready for communication. When the machine is ready to be provisioned, run the `packer.HookProvision` hook, making sure the communicator is not nil, since this is required for provisioners. An example of calling the hook is shown below: -```go +``` {.go} hook.Run(packer.HookProvision, ui, comm, nil) ``` -At this point, Packer will run the provisioners and no additional work -is necessary. +At this point, Packer will run the provisioners and no additional work is +necessary. --> **Note:** Hooks are still undergoing thought around their -general design and will likely change in a future version. They aren't -fully "baked" yet, so they aren't documented here other than to tell you -how to hook in provisioners. +-> **Note:** Hooks are still undergoing thought around their general design +and will likely change in a future version. They aren't fully "baked" yet, so +they aren't documented here other than to tell you how to hook in provisioners. ## Caching Files -It is common for some builders to deal with very large files, or files that -take a long time to generate. For example, the VMware builder has the capability -to download the operating system ISO from the internet. This is timely process, -so it would be convenient to cache the file. This sort of caching is a core -part of Packer that is exposed to builders. +It is common for some builders to deal with very large files, or files that take +a long time to generate. For example, the VMware builder has the capability to +download the operating system ISO from the internet. This is timely process, so +it would be convenient to cache the file. This sort of caching is a core part of +Packer that is exposed to builders. The cache interface is `packer.Cache`. It behaves much like a Go -[RWMutex](http://golang.org/pkg/sync/#RWMutex). The builder requests a "lock" -on certain cache keys, and is given exclusive access to that key for the -duration of the lock. This locking mechanism allows multiple builders to -share cache data even though they're running in parallel. +[RWMutex](http://golang.org/pkg/sync/#RWMutex). The builder requests a "lock" on +certain cache keys, and is given exclusive access to that key for the duration +of the lock. This locking mechanism allows multiple builders to share cache data +even though they're running in parallel. For example, both the VMware and VirtualBox builders support downloading an operating system ISO from the internet. Most of the time, this ISO is identical. The locking mechanisms of the cache allow one of the builders to download it only once, but allow both builders to share the downloaded file. -The [documentation for packer.Cache](#) is -very detailed in how it works. +The [documentation for packer.Cache](#) is very detailed in how it works. diff --git a/website/source/docs/extend/command.html.markdown b/website/source/docs/extend/command.html.markdown index 1a4625c9b..2d611ebf4 100644 --- a/website/source/docs/extend/command.html.markdown +++ b/website/source/docs/extend/command.html.markdown @@ -1,57 +1,57 @@ --- -layout: "docs" -page_title: "Custom Command Development" -description: |- - Packer Commands are the components of Packer that add functionality to the `packer` application. Packer comes with a set of commands out of the box, such as `build`. Commands are invoked as `packer `. Custom commands allow you to add new commands to Packer to perhaps perform new functionality. ---- +description: | + Packer Commands are the components of Packer that add functionality to the + `packer` application. Packer comes with a set of commands out of the box, such + as `build`. Commands are invoked as `packer `. Custom commands allow + you to add new commands to Packer to perhaps perform new functionality. +layout: docs +page_title: Custom Command Development +... # Custom Command Development Packer Commands are the components of Packer that add functionality to the -`packer` application. Packer comes with a set of commands out of the -box, such as `build`. Commands are invoked as `packer `. -Custom commands allow you to add new commands to Packer to perhaps -perform new functionality. +`packer` application. Packer comes with a set of commands out of the box, such +as `build`. Commands are invoked as `packer `. Custom commands allow +you to add new commands to Packer to perhaps perform new functionality. -Prior to reading this page, it is assumed you have read the page on -[plugin development basics](/docs/extend/developing-plugins.html). +Prior to reading this page, it is assumed you have read the page on [plugin +development basics](/docs/extend/developing-plugins.html). -Command plugins implement the `packer.Command` interface and are served -using the `plugin.ServeCommand` function. Commands actually have no control -over what keyword invokes the command with the `packer` binary. The keyword -to invoke the command depends on how the plugin is installed and configured -in the core Packer configuration. +Command plugins implement the `packer.Command` interface and are served using +the `plugin.ServeCommand` function. Commands actually have no control over what +keyword invokes the command with the `packer` binary. The keyword to invoke the +command depends on how the plugin is installed and configured in the core Packer +configuration. -~> **Warning!** This is an advanced topic. If you're new to Packer, we +\~> **Warning!** This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins. ## The Interface The interface that must be implemented for a command is the `packer.Command` -interface. It is reproduced below for easy reference. The actual interface -in the source code contains some basic documentation as well explaining -what each method should do. +interface. It is reproduced below for easy reference. The actual interface in +the source code contains some basic documentation as well explaining what each +method should do. -```go +``` {.go} type Command interface { - Help() string - Run(env Environment, args []string) int - Synopsis() string + Help() string + Run(env Environment, args []string) int + Synopsis() string } ``` ### The "Help" Method -The `Help` method returns long-form help. This help is most commonly -shown when a command is invoked with the `--help` or `-h` option. -The help should document all the available command line flags, purpose -of the command, etc. +The `Help` method returns long-form help. This help is most commonly shown when +a command is invoked with the `--help` or `-h` option. The help should document +all the available command line flags, purpose of the command, etc. -Packer commands generally follow the following format for help, but -it is not required. You're allowed to make the help look like anything -you please. +Packer commands generally follow the following format for help, but it is not +required. You're allowed to make the help look like anything you please. -```text +``` {.text} Usage: packer COMMAND [options] ARGS... Brief one or two sentence about the function of the command. @@ -64,23 +64,23 @@ Options: ### The "Run" Method -`Run` is what is called when the command is actually invoked. It is given -the `packer.Environment`, which has access to almost all components of -the current Packer run, such as UI, builders, other plugins, etc. In addition -to the environment, the remaining command line args are given. These command -line args have already been stripped of the command name, so they can be -passed directly into something like the standard Go `flag` package for -command-line flag parsing. +`Run` is what is called when the command is actually invoked. It is given the +`packer.Environment`, which has access to almost all components of the current +Packer run, such as UI, builders, other plugins, etc. In addition to the +environment, the remaining command line args are given. These command line args +have already been stripped of the command name, so they can be passed directly +into something like the standard Go `flag` package for command-line flag +parsing. -The return value of `Run` is the exit status for the command. If everything -ran successfully, this should be 0. If any errors occurred, it should be any +The return value of `Run` is the exit status for the command. If everything ran +successfully, this should be 0. If any errors occurred, it should be any positive integer. ### The "Synopsis" Method -The `Synopsis` method should return a short single-line description -of what the command does. This is used when `packer` is invoked on its own -in order to show a brief summary of the commands that Packer supports. +The `Synopsis` method should return a short single-line description of what the +command does. This is used when `packer` is invoked on its own in order to show +a brief summary of the commands that Packer supports. -The synopsis should be no longer than around 50 characters, since it is -already appearing on a line with other text. +The synopsis should be no longer than around 50 characters, since it is already +appearing on a line with other text. diff --git a/website/source/docs/extend/developing-plugins.html.markdown b/website/source/docs/extend/developing-plugins.html.markdown index 4e38c27a3..2ccdd437f 100644 --- a/website/source/docs/extend/developing-plugins.html.markdown +++ b/website/source/docs/extend/developing-plugins.html.markdown @@ -1,73 +1,75 @@ --- -layout: "docs" -page_title: "Developing Plugins" -description: |- - This page will document how you can develop your own Packer plugins. Prior to reading this, it is assumed that you're comfortable with Packer and also know the basics of how Plugins work, from a user standpoint. ---- +description: | + This page will document how you can develop your own Packer plugins. Prior to + reading this, it is assumed that you're comfortable with Packer and also know + the basics of how Plugins work, from a user standpoint. +layout: docs +page_title: Developing Plugins +... # Developing Plugins -This page will document how you can develop your own Packer plugins. -Prior to reading this, it is assumed that you're comfortable with Packer -and also know the [basics of how Plugins work](/docs/extend/plugins.html), -from a user standpoint. +This page will document how you can develop your own Packer plugins. Prior to +reading this, it is assumed that you're comfortable with Packer and also know +the [basics of how Plugins work](/docs/extend/plugins.html), from a user +standpoint. Packer plugins must be written in [Go](http://golang.org/), so it is also -assumed that you're familiar with the language. This page will not be a -Go language tutorial. Thankfully, if you are familiar with Go, the Go toolchain +assumed that you're familiar with the language. This page will not be a Go +language tutorial. Thankfully, if you are familiar with Go, the Go toolchain makes it extremely easy to develop Packer plugins. -~> **Warning!** This is an advanced topic. If you're new to Packer, we +\~> **Warning!** This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins. ## Plugin System Architecture Packer has a fairly unique plugin architecture. Instead of loading plugins -directly into a running application, Packer runs each plugin as a -_separate application_. Inter-process communication and RPC is then used -to communicate between the many running Packer processes. Packer core -itself is responsible for orchestrating the processes and handles cleanup. +directly into a running application, Packer runs each plugin as a *separate +application*. Inter-process communication and RPC is then used to communicate +between the many running Packer processes. Packer core itself is responsible for +orchestrating the processes and handles cleanup. The beauty of this is that your plugin can have any dependencies it wants. Dependencies don't need to line up with what Packer core or any other plugin -uses, because they're completely isolated into the process space of the -plugin itself. +uses, because they're completely isolated into the process space of the plugin +itself. -And, thanks to Go's [interfaces](http://golang.org/doc/effective_go.html#interfaces_and_types), -it doesn't even look like inter-process communication is occurring. You just -use the interfaces like normal, but in fact they're being executed in -a remote process. Pretty cool. +And, thanks to Go's +[interfaces](http://golang.org/doc/effective_go.html#interfaces_and_types), it +doesn't even look like inter-process communication is occurring. You just use +the interfaces like normal, but in fact they're being executed in a remote +process. Pretty cool. ## Plugin Development Basics -Developing a plugin is quite simple. All the various kinds of plugins -have a corresponding interface. The plugin simply needs to implement -this interface and expose it using the Packer plugin package (covered here shortly), -and that's it! +Developing a plugin is quite simple. All the various kinds of plugins have a +corresponding interface. The plugin simply needs to implement this interface and +expose it using the Packer plugin package (covered here shortly), and that's it! -There are two packages that really matter that every plugin must use. -Other than the following two packages, you're encouraged to use whatever -packages you want. Because plugins are their own processes, there is -no danger of colliding dependencies. +There are two packages that really matter that every plugin must use. Other than +the following two packages, you're encouraged to use whatever packages you want. +Because plugins are their own processes, there is no danger of colliding +dependencies. -* `github.com/mitchellh/packer` - Contains all the interfaces that you - have to implement for any given plugin. +- `github.com/mitchellh/packer` - Contains all the interfaces that you have to + implement for any given plugin. -* `github.com/mitchellh/packer/plugin` - Contains the code to serve the - plugin. This handles all the inter-process communication stuff. +- `github.com/mitchellh/packer/plugin` - Contains the code to serve the plugin. + This handles all the inter-process communication stuff. There are two steps involved in creating a plugin: -1. Implement the desired interface. For example, if you're building a - builder plugin, implement the `packer.Builder` interface. +1. Implement the desired interface. For example, if you're building a builder + plugin, implement the `packer.Builder` interface. -2. Serve the interface by calling the appropriate plugin serving method - in your main method. In the case of a builder, this is `plugin.ServeBuilder`. +2. Serve the interface by calling the appropriate plugin serving method in your + main method. In the case of a builder, this is `plugin.ServeBuilder`. A basic example is shown below. In this example, assume the `Builder` struct implements the `packer.Builder` interface: -```go +``` {.go} import ( "github.com/mitchellh/packer/plugin" ) @@ -76,40 +78,38 @@ import ( type Builder struct{} func main() { - plugin.ServeBuilder(new(Builder)) + plugin.ServeBuilder(new(Builder)) } ``` **That's it!** `plugin.ServeBuilder` handles all the nitty gritty of -communicating with Packer core and serving your builder over RPC. It -can't get much easier than that. +communicating with Packer core and serving your builder over RPC. It can't get +much easier than that. -Next, just build your plugin like a normal Go application, using `go build` -or however you please. The resulting binary is the plugin that can be -installed using standard installation procedures. +Next, just build your plugin like a normal Go application, using `go build` or +however you please. The resulting binary is the plugin that can be installed +using standard installation procedures. -The specifics of how to implement each type of interface are covered -in the relevant subsections available in the navigation to the left. +The specifics of how to implement each type of interface are covered in the +relevant subsections available in the navigation to the left. -~> **Lock your dependencies!** Unfortunately, Go's dependency -management story is fairly sad. There are various unofficial methods out -there for locking dependencies, and using one of them is highly recommended -since the Packer codebase will continue to improve, potentially breaking -APIs along the way until there is a stable release. By locking your dependencies, -your plugins will continue to work with the version of Packer you lock to. +\~> **Lock your dependencies!** Unfortunately, Go's dependency management +story is fairly sad. There are various unofficial methods out there for locking +dependencies, and using one of them is highly recommended since the Packer +codebase will continue to improve, potentially breaking APIs along the way until +there is a stable release. By locking your dependencies, your plugins will +continue to work with the version of Packer you lock to. ## Logging and Debugging -Plugins can use the standard Go `log` package to log. Anything logged -using this will be available in the Packer log files automatically. -The Packer log is visible on stderr when the `PACKER_LOG` environmental -is set. +Plugins can use the standard Go `log` package to log. Anything logged using this +will be available in the Packer log files automatically. The Packer log is +visible on stderr when the `PACKER_LOG` environmental is set. -Packer will prefix any logs from plugins with the path to that plugin -to make it identifiable where the logs come from. Some example logs are -shown below: +Packer will prefix any logs from plugins with the path to that plugin to make it +identifiable where the logs come from. Some example logs are shown below: -```text +``` {.text} 2013/06/10 21:44:43 ui: Available commands are: 2013/06/10 21:44:43 Loading command: build 2013/06/10 21:44:43 packer-command-build: 2013/06/10 21:44:43 Plugin minimum port: 10000 @@ -117,31 +117,31 @@ shown below: 2013/06/10 21:44:43 packer-command-build: 2013/06/10 21:44:43 Plugin address: :10000 ``` -As you can see, the log messages from the "build" command plugin are -prefixed with "packer-command-build". Log output is _extremely_ helpful -in debugging issues and you're encouraged to be as verbose as you need to -be in order for the logs to be helpful. +As you can see, the log messages from the "build" command plugin are prefixed +with "packer-command-build". Log output is *extremely* helpful in debugging +issues and you're encouraged to be as verbose as you need to be in order for the +logs to be helpful. ## Plugin Development Tips -Here are some tips for developing plugins, often answering common questions -or concerns. +Here are some tips for developing plugins, often answering common questions or +concerns. ### Naming Conventions -It is standard practice to name the resulting plugin application -in the format of `packer-TYPE-NAME`. For example, if you're building a -new builder for CustomCloud, it would be standard practice to name the -resulting plugin `packer-builder-custom-cloud`. This naming convention -helps users identify the purpose of a plugin. +It is standard practice to name the resulting plugin application in the format +of `packer-TYPE-NAME`. For example, if you're building a new builder for +CustomCloud, it would be standard practice to name the resulting plugin +`packer-builder-custom-cloud`. This naming convention helps users identify the +purpose of a plugin. ### Testing Plugins -While developing plugins, you can configure your Packer configuration -to point directly to the compiled plugin in order to test it. For example, -building the CustomCloud plugin, I may configure packer like so: +While developing plugins, you can configure your Packer configuration to point +directly to the compiled plugin in order to test it. For example, building the +CustomCloud plugin, I may configure packer like so: -```javascript +``` {.javascript} { "builders": { "custom-cloud": "/an/absolute/path/to/packer-builder-custom-cloud" @@ -149,13 +149,13 @@ building the CustomCloud plugin, I may configure packer like so: } ``` -This would configure Packer to have the "custom-cloud" plugin, and execute -the binary that I am building during development. This is extremely useful -during development. +This would configure Packer to have the "custom-cloud" plugin, and execute the +binary that I am building during development. This is extremely useful during +development. ### Distributing Plugins -It is recommended you use a tool like [goxc](https://github.com/laher/goxc) -in order to cross-compile your plugin for every platform that Packer supports, -since Go applications are platform-specific. goxc will allow you to build -for every platform from your own computer. +It is recommended you use a tool like [goxc](https://github.com/laher/goxc) in +order to cross-compile your plugin for every platform that Packer supports, +since Go applications are platform-specific. goxc will allow you to build for +every platform from your own computer. diff --git a/website/source/docs/extend/plugins.html.markdown b/website/source/docs/extend/plugins.html.markdown index c257fb702..f8b800a30 100644 --- a/website/source/docs/extend/plugins.html.markdown +++ b/website/source/docs/extend/plugins.html.markdown @@ -1,68 +1,71 @@ --- -layout: "docs" -page_title: "Packer Plugins - Extend Packer" -description: |- - Packer Plugins allow new functionality to be added to Packer without modifying the core source code. Packer plugins are able to add new commands, builders, provisioners, hooks, and more. In fact, much of Packer itself is implemented by writing plugins that are simply distributed with Packer. For example, all the commands, builders, provisioners, and more that ship with Packer are implemented as Plugins that are simply hardcoded to load with Packer. ---- +description: | + Packer Plugins allow new functionality to be added to Packer without modifying + the core source code. Packer plugins are able to add new commands, builders, + provisioners, hooks, and more. In fact, much of Packer itself is implemented by + writing plugins that are simply distributed with Packer. For example, all the + commands, builders, provisioners, and more that ship with Packer are implemented + as Plugins that are simply hardcoded to load with Packer. +layout: docs +page_title: 'Packer Plugins - Extend Packer' +... # Packer Plugins -Packer Plugins allow new functionality to be added to Packer without -modifying the core source code. Packer plugins are able to add new -commands, builders, provisioners, hooks, and more. In fact, much of Packer -itself is implemented by writing plugins that are simply distributed with -Packer. For example, all the commands, builders, provisioners, and more -that ship with Packer are implemented as Plugins that are simply hardcoded -to load with Packer. +Packer Plugins allow new functionality to be added to Packer without modifying +the core source code. Packer plugins are able to add new commands, builders, +provisioners, hooks, and more. In fact, much of Packer itself is implemented by +writing plugins that are simply distributed with Packer. For example, all the +commands, builders, provisioners, and more that ship with Packer are implemented +as Plugins that are simply hardcoded to load with Packer. -This page will cover how to install and use plugins. If you're interested -in developing plugins, the documentation for that is available the -[developing plugins](/docs/extend/developing-plugins.html) page. +This page will cover how to install and use plugins. If you're interested in +developing plugins, the documentation for that is available the [developing +plugins](/docs/extend/developing-plugins.html) page. -Because Packer is so young, there is no official listing of available -Packer plugins. Plugins are best found via Google. Typically, searching -"packer plugin _x_" will find what you're looking for if it exists. As -Packer gets older, an official plugin directory is planned. +Because Packer is so young, there is no official listing of available Packer +plugins. Plugins are best found via Google. Typically, searching "packer plugin +*x*" will find what you're looking for if it exists. As Packer gets older, an +official plugin directory is planned. ## How Plugins Work -Packer plugins are completely separate, standalone applications that the -core of Packer starts and communicates with. +Packer plugins are completely separate, standalone applications that the core of +Packer starts and communicates with. -These plugin applications aren't meant to be run manually. Instead, Packer core executes -these plugin applications in a certain way and communicates with them. +These plugin applications aren't meant to be run manually. Instead, Packer core +executes these plugin applications in a certain way and communicates with them. For example, the VMware builder is actually a standalone binary named -`packer-builder-vmware`. The next time you run a Packer build, look at -your process list and you should see a handful of `packer-` prefixed -applications running. +`packer-builder-vmware`. The next time you run a Packer build, look at your +process list and you should see a handful of `packer-` prefixed applications +running. ## Installing Plugins -The easiest way to install a plugin is to name it correctly, then place -it in the proper directory. To name a plugin correctly, make sure the -binary is named `packer-TYPE-NAME`. For example, `packer-builder-amazon-ebs` -for a "builder" type plugin named "amazon-ebs". Valid types for plugins -are down this page more. +The easiest way to install a plugin is to name it correctly, then place it in +the proper directory. To name a plugin correctly, make sure the binary is named +`packer-TYPE-NAME`. For example, `packer-builder-amazon-ebs` for a "builder" +type plugin named "amazon-ebs". Valid types for plugins are down this page more. -Once the plugin is named properly, Packer automatically discovers plugins -in the following directories in the given order. If a conflicting plugin is -found later, it will take precedence over one found earlier. +Once the plugin is named properly, Packer automatically discovers plugins in the +following directories in the given order. If a conflicting plugin is found +later, it will take precedence over one found earlier. -1. The directory where `packer` is, or the executable directory. +1. The directory where `packer` is, or the executable directory. -2. `~/.packer.d/plugins` on Unix systems or `%APPDATA%/packer.d/plugins` on - Windows. +2. `~/.packer.d/plugins` on Unix systems or `%APPDATA%/packer.d/plugins` + on Windows. -3. The current working directory. +3. The current working directory. The valid types for plugins are: -* `builder` - Plugins responsible for building images for a specific platform. +- `builder` - Plugins responsible for building images for a specific platform. -* `command` - A CLI sub-command for `packer`. +- `command` - A CLI sub-command for `packer`. -* `post-processor` - A post-processor responsible for taking an artifact - from a builder and turning it into something else. +- `post-processor` - A post-processor responsible for taking an artifact from a + builder and turning it into something else. -* `provisioner` - A provisioner to install software on images created by - a builder. +- `provisioner` - A provisioner to install software on images created by + a builder. diff --git a/website/source/docs/extend/post-processor.html.markdown b/website/source/docs/extend/post-processor.html.markdown index 204cc593b..1120bc31d 100644 --- a/website/source/docs/extend/post-processor.html.markdown +++ b/website/source/docs/extend/post-processor.html.markdown @@ -1,92 +1,89 @@ --- -layout: "docs" -page_title: "Custom Post-Processor Development" -description: |- - Packer Post-processors are the components of Packer that transform one artifact into another, for example by compressing files, or uploading them. ---- +description: | + Packer Post-processors are the components of Packer that transform one artifact + into another, for example by compressing files, or uploading them. +layout: docs +page_title: 'Custom Post-Processor Development' +... # Custom Post-Processor Development Packer Post-processors are the components of Packer that transform one artifact into another, for example by compressing files, or uploading them. -In the compression example, the transformation would be taking an artifact -with a set of files, compressing those files, and returning a new -artifact with only a single file (the compressed archive). For the -upload example, the transformation would be taking an artifact with -some set of files, uploading those files, and returning an artifact -with a single ID: the URL of the upload. +In the compression example, the transformation would be taking an artifact with +a set of files, compressing those files, and returning a new artifact with only +a single file (the compressed archive). For the upload example, the +transformation would be taking an artifact with some set of files, uploading +those files, and returning an artifact with a single ID: the URL of the upload. -Prior to reading this page, it is assumed you have read the page on -[plugin development basics](/docs/extend/developing-plugins.html). +Prior to reading this page, it is assumed you have read the page on [plugin +development basics](/docs/extend/developing-plugins.html). -Post-processor plugins implement the `packer.PostProcessor` interface and -are served using the `plugin.ServePostProcessor` function. +Post-processor plugins implement the `packer.PostProcessor` interface and are +served using the `plugin.ServePostProcessor` function. -~> **Warning!** This is an advanced topic. If you're new to Packer, we +\~> **Warning!** This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins. - ## The Interface The interface that must be implemented for a post-processor is the -`packer.PostProcessor` interface. It is reproduced below for easy reference. -The actual interface in the source code contains some basic documentation as well explaining -what each method should do. +`packer.PostProcessor` interface. It is reproduced below for easy reference. The +actual interface in the source code contains some basic documentation as well +explaining what each method should do. -```go +``` {.go} type PostProcessor interface { - Configure(interface{}) error - PostProcess(Ui, Artifact) (a Artifact, keep bool, err error) + Configure(interface{}) error + PostProcess(Ui, Artifact) (a Artifact, keep bool, err error) } ``` ### The "Configure" Method -The `Configure` method for each post-processor is called early in the -build process to configure the post-processor. The configuration is passed -in as a raw `interface{}`. The configure method is responsible for translating -this configuration into an internal structure, validating it, and returning -any errors. +The `Configure` method for each post-processor is called early in the build +process to configure the post-processor. The configuration is passed in as a raw +`interface{}`. The configure method is responsible for translating this +configuration into an internal structure, validating it, and returning any +errors. For decoding the `interface{}` into a meaningful structure, the [mapstructure](https://github.com/mitchellh/mapstructure) library is recommended. Mapstructure will take an `interface{}` and decode it into an arbitrarily complex struct. If there are any errors, it generates very -human-friendly errors that can be returned directly from the configure -method. +human-friendly errors that can be returned directly from the configure method. -While it is not actively enforced, **no side effects** should occur from -running the `Configure` method. Specifically, don't create files, don't -create network connections, etc. Configure's purpose is solely to setup -internal state and validate the configuration as much as possible. +While it is not actively enforced, **no side effects** should occur from running +the `Configure` method. Specifically, don't create files, don't create network +connections, etc. Configure's purpose is solely to setup internal state and +validate the configuration as much as possible. -`Configure` being run is not an indication that `PostProcess` will ever -run. For example, `packer validate` will run `Configure` to verify the -configuration validates, but will never actually run the build. +`Configure` being run is not an indication that `PostProcess` will ever run. For +example, `packer validate` will run `Configure` to verify the configuration +validates, but will never actually run the build. ### The "PostProcess" Method -The `PostProcess` method is where the real work goes. PostProcess is -responsible for taking one `packer.Artifact` implementation, and transforming -it into another. +The `PostProcess` method is where the real work goes. PostProcess is responsible +for taking one `packer.Artifact` implementation, and transforming it into +another. When we say "transform," we don't mean actually modifying the existing -`packer.Artifact` value itself. We mean taking the contents of the artifact -and creating a new artifact from that. For example, if we were creating -a "compress" post-processor that is responsible for compressing files, -the transformation would be taking the `Files()` from the original artifact, -compressing them, and creating a new artifact with a single file: the -compressed archive. +`packer.Artifact` value itself. We mean taking the contents of the artifact and +creating a new artifact from that. For example, if we were creating a "compress" +post-processor that is responsible for compressing files, the transformation +would be taking the `Files()` from the original artifact, compressing them, and +creating a new artifact with a single file: the compressed archive. -The result signature of this method is `(Artifact, bool, error)`. Each -return value is explained below: +The result signature of this method is `(Artifact, bool, error)`. Each return +value is explained below: -* `Artifact` - The newly created artifact if no errors occurred. -* `bool` - If true, the input artifact will forcefully be kept. By default, +- `Artifact` - The newly created artifact if no errors occurred. +- `bool` - If true, the input artifact will forcefully be kept. By default, Packer typically deletes all input artifacts, since the user doesn't generally want intermediary artifacts. However, some post-processors depend on the previous artifact existing. If this is `true`, it forces packer to keep the artifact around. -* `error` - Non-nil if there was an error in any way. If this is the case, - the other two return values are ignored. +- `error` - Non-nil if there was an error in any way. If this is the case, the + other two return values are ignored. diff --git a/website/source/docs/extend/provisioner.html.markdown b/website/source/docs/extend/provisioner.html.markdown index cb73cccd2..a06940dac 100644 --- a/website/source/docs/extend/provisioner.html.markdown +++ b/website/source/docs/extend/provisioner.html.markdown @@ -1,90 +1,95 @@ --- -layout: "docs" -page_title: "Custom Provisioner Development" -description: |- - Packer Provisioners are the components of Packer that install and configure software into a running machine prior to turning that machine into an image. An example of a provisioner is the shell provisioner, which runs shell scripts within the machines. ---- +description: | + Packer Provisioners are the components of Packer that install and configure + software into a running machine prior to turning that machine into an image. An + example of a provisioner is the shell provisioner, which runs shell scripts + within the machines. +layout: docs +page_title: Custom Provisioner Development +... # Custom Provisioner Development Packer Provisioners are the components of Packer that install and configure -software into a running machine prior to turning that machine into an -image. An example of a provisioner is the [shell provisioner](/docs/provisioners/shell.html), -which runs shell scripts within the machines. +software into a running machine prior to turning that machine into an image. An +example of a provisioner is the [shell +provisioner](/docs/provisioners/shell.html), which runs shell scripts within the +machines. -Prior to reading this page, it is assumed you have read the page on -[plugin development basics](/docs/extend/developing-plugins.html). +Prior to reading this page, it is assumed you have read the page on [plugin +development basics](/docs/extend/developing-plugins.html). -Provisioner plugins implement the `packer.Provisioner` interface and -are served using the `plugin.ServeProvisioner` function. +Provisioner plugins implement the `packer.Provisioner` interface and are served +using the `plugin.ServeProvisioner` function. -~> **Warning!** This is an advanced topic. If you're new to Packer, we +\~> **Warning!** This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins. ## The Interface The interface that must be implemented for a provisioner is the -`packer.Provisioner` interface. It is reproduced below for easy reference. -The actual interface in the source code contains some basic documentation as well explaining -what each method should do. +`packer.Provisioner` interface. It is reproduced below for easy reference. The +actual interface in the source code contains some basic documentation as well +explaining what each method should do. -```go +``` {.go} type Provisioner interface { - Prepare(...interface{}) error - Provision(Ui, Communicator) error + Prepare(...interface{}) error + Provision(Ui, Communicator) error } ``` ### The "Prepare" Method -The `Prepare` method for each provisioner is called prior to any runs with -the configuration that was given in the template. This is passed in as -an array of `interface{}` types, but is generally `map[string]interface{}`. The prepare +The `Prepare` method for each provisioner is called prior to any runs with the +configuration that was given in the template. This is passed in as an array of +`interface{}` types, but is generally `map[string]interface{}`. The prepare method is responsible for translating this configuration into an internal structure, validating it, and returning any errors. For multiple parameters, they should be merged together into the final -configuration, with later parameters overwriting any previous configuration. -The exact semantics of the merge are left to the builder author. +configuration, with later parameters overwriting any previous configuration. The +exact semantics of the merge are left to the builder author. For decoding the `interface{}` into a meaningful structure, the -[mapstructure](https://github.com/mitchellh/mapstructure) library is recommended. -Mapstructure will take an `interface{}` and decode it into an arbitrarily -complex struct. If there are any errors, it generates very human friendly -errors that can be returned directly from the prepare method. +[mapstructure](https://github.com/mitchellh/mapstructure) library is +recommended. Mapstructure will take an `interface{}` and decode it into an +arbitrarily complex struct. If there are any errors, it generates very human +friendly errors that can be returned directly from the prepare method. -While it is not actively enforced, **no side effects** should occur from -running the `Prepare` method. Specifically, don't create files, don't launch -virtual machines, etc. Prepare's purpose is solely to configure the builder -and validate the configuration. +While it is not actively enforced, **no side effects** should occur from running +the `Prepare` method. Specifically, don't create files, don't launch virtual +machines, etc. Prepare's purpose is solely to configure the builder and validate +the configuration. -The `Prepare` method is called very early in the build process so that -errors may be displayed to the user before anything actually happens. +The `Prepare` method is called very early in the build process so that errors +may be displayed to the user before anything actually happens. ### The "Provision" Method -The `Provision` method is called when a machine is running and ready -to be provisioned. The provisioner should do its real work here. +The `Provision` method is called when a machine is running and ready to be +provisioned. The provisioner should do its real work here. -The method takes two parameters: a `packer.Ui` and a `packer.Communicator`. -The UI can be used to communicate with the user what is going on. The -communicator is used to communicate with the running machine, and is -guaranteed to be connected at this point. +The method takes two parameters: a `packer.Ui` and a `packer.Communicator`. The +UI can be used to communicate with the user what is going on. The communicator +is used to communicate with the running machine, and is guaranteed to be +connected at this point. The provision method should not return until provisioning is complete. ## Using the Communicator -The `packer.Communicator` parameter and interface is used to communicate -with running machine. The machine may be local (in a virtual machine or -container of some sort) or it may be remote (in a cloud). The communicator -interface abstracts this away so that communication is the same overall. +The `packer.Communicator` parameter and interface is used to communicate with +running machine. The machine may be local (in a virtual machine or container of +some sort) or it may be remote (in a cloud). The communicator interface +abstracts this away so that communication is the same overall. -The documentation around the [code itself](https://github.com/mitchellh/packer/blob/master/packer/communicator.go) -is really great as an overview of how to use the interface. You should begin -by reading this. Once you have read it, you can see some example usage below: +The documentation around the [code +itself](https://github.com/mitchellh/packer/blob/master/packer/communicator.go) +is really great as an overview of how to use the interface. You should begin by +reading this. Once you have read it, you can see some example usage below: -```go +``` {.go} // Build the remote command. var cmd packer.RemoteCmd cmd.Command = "echo foo" diff --git a/website/source/docs/index.html.markdown b/website/source/docs/index.html.markdown index 5894d17db..cf924d688 100644 --- a/website/source/docs/index.html.markdown +++ b/website/source/docs/index.html.markdown @@ -1,13 +1,16 @@ --- -layout: "docs" -page_title: "Packer Documentation" -description: |- - Welcome to the Packer documentation! This documentation is more of a reference guide for all available features and options in Packer. If you're just getting started with Packer, please start with the introduction and getting started guide instead. ---- +description: | + Welcome to the Packer documentation! This documentation is more of a reference + guide for all available features and options in Packer. If you're just getting + started with Packer, please start with the introduction and getting started + guide instead. +layout: docs +page_title: Packer Documentation +... # Packer Documentation Welcome to the Packer documentation! This documentation is more of a reference guide for all available features and options in Packer. If you're just getting -started with Packer, please start with the -[introduction and getting started guide](/intro) instead. +started with Packer, please start with the [introduction and getting started +guide](/intro) instead. diff --git a/website/source/docs/installation.html.markdown b/website/source/docs/installation.html.markdown index b24078729..35af3ed93 100644 --- a/website/source/docs/installation.html.markdown +++ b/website/source/docs/installation.html.markdown @@ -1,44 +1,48 @@ --- -layout: "docs" -page_title: "Install Packer" -description: |- - Packer must first be installed on the machine you want to run it on. To make installation easy, Packer is distributed as a binary package for all supported platforms and architectures. This page will not cover how to compile Packer from source, as that is covered in the README and is only recommended for advanced users. ---- +description: | + Packer must first be installed on the machine you want to run it on. To make + installation easy, Packer is distributed as a binary package for all supported + platforms and architectures. This page will not cover how to compile Packer from + source, as that is covered in the README and is only recommended for advanced + users. +layout: docs +page_title: Install Packer +... # Install Packer -Packer must first be installed on the machine you want to run it on. -To make installation easy, Packer is distributed as a [binary package](/downloads.html) -for all supported platforms and architectures. This page will not cover how -to compile Packer from source, as that is covered in the +Packer must first be installed on the machine you want to run it on. To make +installation easy, Packer is distributed as a [binary package](/downloads.html) +for all supported platforms and architectures. This page will not cover how to +compile Packer from source, as that is covered in the [README](https://github.com/mitchellh/packer/blob/master/README.md) and is only recommended for advanced users. ## Installing Packer -To install packer, first find the [appropriate package](/downloads.html) -for your system and download it. Packer is packaged as a "zip" file. +To install packer, first find the [appropriate package](/downloads.html) for +your system and download it. Packer is packaged as a "zip" file. Next, unzip the downloaded package into a directory where Packer will be installed. On Unix systems, `~/packer` or `/usr/local/packer` is generally good, -depending on whether you want to restrict the install to just your user -or install it system-wide. On Windows systems, you can put it wherever you'd -like. +depending on whether you want to restrict the install to just your user or +install it system-wide. On Windows systems, you can put it wherever you'd like. After unzipping the package, the directory should contain a set of binary -programs, such as `packer`, `packer-build-amazon-ebs`, etc. The final step -to installation is to make sure the directory you installed Packer to -is on the PATH. See [this page](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux) -for instructions on setting the PATH on Linux and Mac. -[This page](http://stackoverflow.com/questions/1618280/where-can-i-set-path-to-make-exe-on-windows) +programs, such as `packer`, `packer-build-amazon-ebs`, etc. The final step to +installation is to make sure the directory you installed Packer to is on the +PATH. See [this +page](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux) +for instructions on setting the PATH on Linux and Mac. [This +page](http://stackoverflow.com/questions/1618280/where-can-i-set-path-to-make-exe-on-windows) contains instructions for setting the PATH on Windows. ## Verifying the Installation -After installing Packer, verify the installation worked by opening -a new command prompt or console, and checking that `packer` is available: +After installing Packer, verify the installation worked by opening a new command +prompt or console, and checking that `packer` is available: -```text +``` {.text} $ packer usage: packer [--version] [--help] [] @@ -50,8 +54,8 @@ Available commands are: ``` If you get an error that `packer` could not be found, then your PATH -environmental variable was not setup properly. Please go back and ensure -that your PATH variable contains the directory which has Packer installed. +environmental variable was not setup properly. Please go back and ensure that +your PATH variable contains the directory which has Packer installed. Otherwise, Packer is installed and you're ready to go! @@ -59,24 +63,24 @@ Otherwise, Packer is installed and you're ready to go! Installation from binary packages is currently the only officially supported installation method. The binary packages are guaranteed to be the latest -available version and match the proper checksums. However, in addition to -the official binaries, there are other unofficial 3rd party methods of -installation managed by the Packer community: +available version and match the proper checksums. However, in addition to the +official binaries, there are other unofficial 3rd party methods of installation +managed by the Packer community: ### Homebrew If you're using OS X and [Homebrew](http://brew.sh), you can install Packer: -```text +``` {.text} $ brew install packer ``` ### Chocolatey -If you're using Windows and [Chocolatey](http://chocolatey.org), you can install Packer from -Windows command line (cmd). Remember that this is updated by a 3rd party, so -it may not be the latest available version. +If you're using Windows and [Chocolatey](http://chocolatey.org), you can install +Packer from Windows command line (cmd). Remember that this is updated by a 3rd +party, so it may not be the latest available version. -```text +``` {.text} $ choco install packer ``` diff --git a/website/source/docs/machine-readable/command-build.html.markdown b/website/source/docs/machine-readable/command-build.html.markdown index 3320f43f1..7472b7bfc 100644 --- a/website/source/docs/machine-readable/command-build.html.markdown +++ b/website/source/docs/machine-readable/command-build.html.markdown @@ -1,163 +1,165 @@ --- -layout: "docs_machine_readable" -page_title: "Command: build - Machine-Readable Reference" -description: |- - These are the machine-readable types that exist as part of the output of `packer build`. ---- +description: | + These are the machine-readable types that exist as part of the output of + `packer build`. +layout: 'docs\_machine\_readable' +page_title: 'Command: build - Machine-Readable Reference' +... # Build Command Types -These are the machine-readable types that exist as part of the output -of `packer build`. +These are the machine-readable types that exist as part of the output of +`packer build`.
-
artifact (>= 2)
-
-

- Information about an artifact of the targeted item. This is a - fairly complex (but uniform!) machine-readable type that contains - subtypes. The subtypes are documented within this page in the - syntax of "artifact subtype: SUBTYPE". The number of arguments within - that subtype is in addition to the artifact args. -

+
artifact (>= 2)
+
+

+ Information about an artifact of the targeted item. This is a + fairly complex (but uniform!) machine-readable type that contains + subtypes. The subtypes are documented within this page in the + syntax of "artifact subtype: SUBTYPE". The number of arguments within + that subtype is in addition to the artifact args. +

-

- Data 1: index - The zero-based index of the - artifact being described. This goes up to "artifact-count" (see - below). -

-

- Data 2: subtype - The subtype that describes - the remaining arguments. See the documentation for the - subtype docs throughout this page. -

-

- Data 3..n: subtype data - Zero or more additional - data points related to the subtype. The exact count and meaning - of this subtypes comes from the subtype documentation. -

-
+

+ Data 1: index - The zero-based index of the + artifact being described. This goes up to "artifact-count" (see + below). +

+

+ Data 2: subtype - The subtype that describes + the remaining arguments. See the documentation for the + subtype docs throughout this page. +

+

+ Data 3..n: subtype data - Zero or more additional + data points related to the subtype. The exact count and meaning + of this subtypes comes from the subtype documentation. +

+ -
artifact-count (1)
-
-

- The number of artifacts associated with the given target. This - will always be outputted _before_ any other artifact information, - so you're able to know how many upcoming artifacts to look for. -

+
artifact-count (1)
+
+

+ The number of artifacts associated with the given target. This + will always be outputted _before_ any other artifact information, + so you're able to know how many upcoming artifacts to look for. +

-

- Data 1: count - The number of artifacts as - a base 10 integer. -

-
+

+ Data 1: count - The number of artifacts as + a base 10 integer. +

+ -
artifact subtype: builder-id (1)
-
-

- The unique ID of the builder that created this artifact. -

+
artifact subtype: builder-id (1)
+
+

+ The unique ID of the builder that created this artifact. +

-

- Data 1: id - The unique ID of the builder. -

-
+

+ Data 1: id - The unique ID of the builder. +

+ -
artifact subtype: end (0)
-
-

- The last machine-readable output line outputted for an artifact. - This is a sentinel value so you know that no more data related to - the targetted artifact will be outputted. -

-
+
artifact subtype: end (0)
+
+

+ The last machine-readable output line outputted for an artifact. + This is a sentinel value so you know that no more data related to + the targetted artifact will be outputted. +

+
-
artifact subtype: file (2)
-
-

- A single file associated with the artifact. There are 0 to - "files-count" of these entries to describe every file that is - part of the artifact. -

+
artifact subtype: file (2)
+
+

+ A single file associated with the artifact. There are 0 to + "files-count" of these entries to describe every file that is + part of the artifact. +

-

- Data 1: index - Zero-based index of the file. - This goes from 0 to "files-count" minus one. -

+

+ Data 1: index - Zero-based index of the file. + This goes from 0 to "files-count" minus one. +

-

- Data 2: filename - The filename. -

-
+

+ Data 2: filename - The filename. +

+ -
artifact subtype: files-count (1)
-
-

- The number of files associated with this artifact. Not all - artifacts have files associated with it. -

+
artifact subtype: files-count (1)
+
+

+ The number of files associated with this artifact. Not all + artifacts have files associated with it. +

-

- Data 1: count - The number of files. -

-
+

+ Data 1: count - The number of files. +

+ -
artifact subtype: id (1)
-
-

- The ID (if any) of the artifact that was built. Not all artifacts - have associated IDs. For example, AMIs built have IDs associated - with them, but VirtualBox images do not. The exact format of the ID - is specific to the builder. -

+
artifact subtype: id (1)
+
+

+ The ID (if any) of the artifact that was built. Not all artifacts + have associated IDs. For example, AMIs built have IDs associated + with them, but VirtualBox images do not. The exact format of the ID + is specific to the builder. +

-

- Data 1: id - The ID of the artifact. -

-
+

+ Data 1: id - The ID of the artifact. +

+ -
artifact subtype: nil (0)
-
-

- If present, this means that the artifact was nil, or that the targeted - build completed successfully but no artifact was created. -

-
+
artifact subtype: nil (0)
+
+

+ If present, this means that the artifact was nil, or that the targeted + build completed successfully but no artifact was created. +

+
-
artifact subtype: string (1)
-
-

- The human-readable string description of the artifact provided by - the artifact itself. -

+
artifact subtype: string (1)
+
+

+ The human-readable string description of the artifact provided by + the artifact itself. +

-

- Data 1: string - The string output for the artifact. -

-
+

+ Data 1: string - The string output for the artifact. +

+ -
error-count (1)
-
-

- The number of errors that occurred during the build. This will - always be outputted before any errors so you know how many are coming. -

+
error-count (1)
+
+

+ The number of errors that occurred during the build. This will + always be outputted before any errors so you know how many are coming. +

-

- Data 1: count - The number of build errors as - a base 10 integer. -

-
+

+ Data 1: count - The number of build errors as + a base 10 integer. +

+ -
error (1)
-
-

- A build error that occurred. The target of this output will be - the build that had the error. -

+
error (1)
+
+

+ A build error that occurred. The target of this output will be + the build that had the error. +

+ +

+ Data 1: error - The error message as a string. +

+
-

- Data 1: error - The error message as a string. -

-
diff --git a/website/source/docs/machine-readable/command-inspect.html.markdown b/website/source/docs/machine-readable/command-inspect.html.markdown index 3f8bbb852..4a5d68876 100644 --- a/website/source/docs/machine-readable/command-inspect.html.markdown +++ b/website/source/docs/machine-readable/command-inspect.html.markdown @@ -1,63 +1,65 @@ --- -layout: "docs_machine_readable" -page_title: "Command: inspect - Machine-Readable Reference" -description: |- - These are the machine-readable types that exist as part of the output of `packer inspect`. ---- +description: | + These are the machine-readable types that exist as part of the output of + `packer inspect`. +layout: 'docs\_machine\_readable' +page_title: 'Command: inspect - Machine-Readable Reference' +... # Inspect Command Types -These are the machine-readable types that exist as part of the output -of `packer inspect`. +These are the machine-readable types that exist as part of the output of +`packer inspect`.
-
template-variable (3)
-
-

- A user variable - defined within the template. -

+
template-variable (3)
+
+

+ A user variable + defined within the template. +

-

- Data 1: name - Name of the variable. -

+

+ Data 1: name - Name of the variable. +

-

- Data 2: default - The default value of the - variable. -

+

+ Data 2: default - The default value of the + variable. +

-

- Data 3: required - If non-zero, then this variable - is required. -

-
+

+ Data 3: required - If non-zero, then this variable + is required. +

+ -
template-builder (2)
-
-

- A builder defined within the template -

+
template-builder (2)
+
+

+ A builder defined within the template +

-

- Data 1: name - The name of the builder. -

-

- Data 2: type - The type of the builder. This will - generally be the same as the name unless you explicitly override - the name. -

-
+

+ Data 1: name - The name of the builder. +

+

+ Data 2: type - The type of the builder. This will + generally be the same as the name unless you explicitly override + the name. +

+ -
template-provisioner (1)
-
-

- A provisioner defined within the template. Multiple of these may - exist. If so, they are outputted in the order they would run. -

+
template-provisioner (1)
+
+

+ A provisioner defined within the template. Multiple of these may + exist. If so, they are outputted in the order they would run. +

+ +

+ Data 1: name - The name/type of the provisioner. +

+
-

- Data 1: name - The name/type of the provisioner. -

-
diff --git a/website/source/docs/machine-readable/command-version.html.markdown b/website/source/docs/machine-readable/command-version.html.markdown index a7029b627..8b32b2540 100644 --- a/website/source/docs/machine-readable/command-version.html.markdown +++ b/website/source/docs/machine-readable/command-version.html.markdown @@ -1,47 +1,49 @@ --- -layout: "docs_machine_readable" -page_title: "Command: version - Machine-Readable Reference" -description: |- - These are the machine-readable types that exist as part of the output of `packer version`. ---- +description: | + These are the machine-readable types that exist as part of the output of + `packer version`. +layout: 'docs\_machine\_readable' +page_title: 'Command: version - Machine-Readable Reference' +... # Version Command Types -These are the machine-readable types that exist as part of the output -of `packer version`. +These are the machine-readable types that exist as part of the output of +`packer version`.
-
version (1)
-
-

The version number of Packer running.

+
version (1)
+
+

The version number of Packer running.

-

- Data 1: version - The version of Packer running, - only including the major, minor, and patch versions. Example: - "0.2.4". -

-
+

+ Data 1: version - The version of Packer running, + only including the major, minor, and patch versions. Example: + "0.2.4". +

+ -
version-commit (1)
-
-

The SHA1 of the Git commit that built this version of Packer.

+
version-commit (1)
+
+

The SHA1 of the Git commit that built this version of Packer.

-

- Data 1: commit SHA1 - The SHA1 of the commit. -

-
+

+ Data 1: commit SHA1 - The SHA1 of the commit. +

+ -
version-prerelease (1)
-
-

- The prerelease tag (if any) for the running version of Packer. This - can be "beta", "dev", "alpha", etc. If this is empty, you can assume - it is a release version running. -

+
version-prerelease (1)
+
+

+ The prerelease tag (if any) for the running version of Packer. This + can be "beta", "dev", "alpha", etc. If this is empty, you can assume + it is a release version running. +

+ +

+ Data 1: prerelease name - The name of the + prerelease tag. +

+
-

- Data 1: prerelease name - The name of the - prerelease tag. -

-
diff --git a/website/source/docs/machine-readable/general.html.markdown b/website/source/docs/machine-readable/general.html.markdown index 1f08be4d2..b29ae053f 100644 --- a/website/source/docs/machine-readable/general.html.markdown +++ b/website/source/docs/machine-readable/general.html.markdown @@ -1,9 +1,10 @@ --- -layout: "docs_machine_readable" -page_title: "General Types - Machine-Readable Reference" -description: |- - These are the machine-readable types that can appear in almost any machine-readable output and are provided by Packer core itself. ---- +description: | + These are the machine-readable types that can appear in almost any + machine-readable output and are provided by Packer core itself. +layout: 'docs\_machine\_readable' +page_title: 'General Types - Machine-Readable Reference' +... # General Types @@ -11,21 +12,22 @@ These are the machine-readable types that can appear in almost any machine-readable output and are provided by Packer core itself.
-
ui (2)
-
-

- Specifies the output and type of output that would've normally - gone to the console if Packer were running in human-readable - mode. -

+
ui (2)
+
+

+ Specifies the output and type of output that would've normally + gone to the console if Packer were running in human-readable + mode. +

+ +

+ Data 1: type - The type of UI message that would've + been outputted. Can be "say", "message", or "error". +

+

+ Data 2: output - The UI message that would have + been outputted. +

+
-

- Data 1: type - The type of UI message that would've - been outputted. Can be "say", "message", or "error". -

-

- Data 2: output - The UI message that would have - been outputted. -

-
diff --git a/website/source/docs/machine-readable/index.html.markdown b/website/source/docs/machine-readable/index.html.markdown index d26106b15..161bda001 100644 --- a/website/source/docs/machine-readable/index.html.markdown +++ b/website/source/docs/machine-readable/index.html.markdown @@ -1,32 +1,35 @@ --- -layout: "docs_machine_readable" -page_title: "Machine-Readable Reference" -description: |- - This is the reference for the various message categories for Packer machine-readable output. Please read that page if you're unfamiliar with the general format and usage for the machine-readable output. ---- +description: | + This is the reference for the various message categories for Packer + machine-readable output. Please read that page if you're unfamiliar with the + general format and usage for the machine-readable output. +layout: 'docs\_machine\_readable' +page_title: 'Machine-Readable Reference' +... # Machine-Readable Reference This is the reference for the various message categories for Packer -[machine-readable output](/docs/command-line/machine-readable.html). -Please read that page if you're unfamiliar with the general format and -usage for the machine-readable output. +[machine-readable output](/docs/command-line/machine-readable.html). Please read +that page if you're unfamiliar with the general format and usage for the +machine-readable output. -The layout of this reference is split into where the types come from. -There are a set of core types that are from Packer core itself. Then -there are types that come from various components of Packer such as the -builders, provisioners, and more. +The layout of this reference is split into where the types come from. There are +a set of core types that are from Packer core itself. Then there are types that +come from various components of Packer such as the builders, provisioners, and +more. Within each section, the format of the documentation is the following:
-
type-name (data-count)
-
-

Description of the type.

-

- Data 1: name - Description. -

-
+
type-name (data-count)
+
+

Description of the type.

+

+ Data 1: name - Description. +

+
+
diff --git a/website/source/docs/other/core-configuration.html.markdown b/website/source/docs/other/core-configuration.html.markdown index 3727af061..db1f75ab7 100644 --- a/website/source/docs/other/core-configuration.html.markdown +++ b/website/source/docs/other/core-configuration.html.markdown @@ -1,25 +1,29 @@ --- -layout: "docs" -page_title: "Core Configuration" -description: |- - There are a few configuration settings that affect Packer globally by configuring the core of Packer. These settings all have reasonable defaults, so you generally don't have to worry about it until you want to tweak a configuration. If you're just getting started with Packer, don't worry about core configuration for now. ---- +description: | + There are a few configuration settings that affect Packer globally by + configuring the core of Packer. These settings all have reasonable defaults, so + you generally don't have to worry about it until you want to tweak a + configuration. If you're just getting started with Packer, don't worry about + core configuration for now. +layout: docs +page_title: Core Configuration +... # Core Configuration There are a few configuration settings that affect Packer globally by configuring the core of Packer. These settings all have reasonable defaults, so -you generally don't have to worry about it until you want to tweak -a configuration. If you're just getting started with Packer, don't worry -about core configuration for now. +you generally don't have to worry about it until you want to tweak a +configuration. If you're just getting started with Packer, don't worry about +core configuration for now. -The default location where Packer looks for this file depends on the -platform. For all non-Windows platforms, Packer looks for `$HOME/.packerconfig`. -For Windows, Packer looks for `%APPDATA%/packer.config`. If the file -doesn't exist, then Packer ignores it and just uses the default configuration. +The default location where Packer looks for this file depends on the platform. +For all non-Windows platforms, Packer looks for `$HOME/.packerconfig`. For +Windows, Packer looks for `%APPDATA%/packer.config`. If the file doesn't exist, +then Packer ignores it and just uses the default configuration. -The location of the core configuration file can be modified by setting -the `PACKER_CONFIG` environmental variable to be the path to another file. +The location of the core configuration file can be modified by setting the +`PACKER_CONFIG` environmental variable to be the path to another file. The format of the configuration file is basic JSON. @@ -28,12 +32,13 @@ 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` (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 - wide range here, since Packer can easily use over 25 ports on a single run. +- `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 wide range + here, since Packer can easily use over 25 ports on a single run. -* `builders`, `commands`, `post-processors`, and `provisioners` are objects that are used to - install plugins. The details of how exactly these are set is covered - in more detail in the [installing plugins documentation page](/docs/extend/plugins.html). +- `builders`, `commands`, `post-processors`, and `provisioners` are objects that + are used to install plugins. The details of how exactly these are set is + covered in more detail in the [installing plugins documentation + page](/docs/extend/plugins.html). diff --git a/website/source/docs/other/debugging.html.markdown b/website/source/docs/other/debugging.html.markdown index eabf56533..8c8012bc8 100644 --- a/website/source/docs/other/debugging.html.markdown +++ b/website/source/docs/other/debugging.html.markdown @@ -1,9 +1,12 @@ --- -layout: "docs" -page_title: "Debugging Packer" -description: |- - Packer strives to be stable and bug-free, but issues inevitably arise where certain things may not work entirely correctly, or may not appear to work correctly. In these cases, it is sometimes helpful to see more details about what Packer is actually doing. ---- +description: | + Packer strives to be stable and bug-free, but issues inevitably arise where + certain things may not work entirely correctly, or may not appear to work + correctly. In these cases, it is sometimes helpful to see more details about + what Packer is actually doing. +layout: docs +page_title: Debugging Packer +... # Debugging Packer Builds @@ -17,39 +20,40 @@ usually will stop between each step, waiting for keyboard input before continuing. This will allow you to inspect state and so on. In debug mode once the remote instance is instantiated, Packer will emit to the -current directory an emphemeral private ssh key as a .pem file. Using that you +current directory an emphemeral private ssh key as a .pem file. Using that you can `ssh -i ` into the remote build instance and see what is going on -for debugging. The emphemeral key will be deleted at the end of the packer run +for debugging. The emphemeral key will be deleted at the end of the packer run during cleanup. ### Windows + As of Packer 0.8.1 the default WinRM communicator will emit the password for a Remote Desktop Connection into your instance. This happens following the several minute pause as the instance is booted. Note a .pem key is still created for securely transmitting the password. Packer automatically decrypts the password for you in debug mode. -## Debugging Packer +## Debugging Packer Issues occasionally arise where certain things may not work entirely correctly, or may not appear to work correctly. In these cases, it is sometimes helpful to see more details about what Packer is actually doing. Packer has detailed logs which can be enabled by setting the `PACKER_LOG` -environmental variable to any value like this `PACKER_LOG=1 packer build -`. This will cause detailed logs to appear on stderr. The logs -contain log messages from Packer as well as any plugins that are being used. Log -messages from plugins are prefixed by their application name. +environmental variable to any value like this +`PACKER_LOG=1 packer build `. This will cause detailed logs to +appear on stderr. The logs contain log messages from Packer as well as any +plugins that are being used. Log messages from plugins are prefixed by their +application name. -Note that because Packer is highly parallelized, log messages sometimes -appear out of order, especially with respect to plugins. In this case, -it is important to pay attention to the timestamp of the log messages -to determine order. +Note that because Packer is highly parallelized, log messages sometimes appear +out of order, especially with respect to plugins. In this case, it is important +to pay attention to the timestamp of the log messages to determine order. In addition to simply enabling the log, you can set `PACKER_LOG_PATH` in order -to force the log to always go to a specific file when logging is enabled. -Note that even when `PACKER_LOG_PATH` is set, `PACKER_LOG` must be set in -order for any logging to be enabled. +to force the log to always go to a specific file when logging is enabled. Note +that even when `PACKER_LOG_PATH` is set, `PACKER_LOG` must be set in order for +any logging to be enabled. -If you find a bug with Packer, please include the detailed log by using -a service such as [gist](http://gist.github.com). +If you find a bug with Packer, please include the detailed log by using a +service such as [gist](http://gist.github.com). diff --git a/website/source/docs/other/environmental-variables.html.markdown b/website/source/docs/other/environmental-variables.html.markdown index 318e25e25..7d455c708 100644 --- a/website/source/docs/other/environmental-variables.html.markdown +++ b/website/source/docs/other/environmental-variables.html.markdown @@ -1,34 +1,36 @@ --- -layout: "docs" -page_title: "Environmental Variables for Packer" -description: |- - Packer uses a variety of environmental variables. ---- +description: 'Packer uses a variety of environmental variables.' +layout: docs +page_title: Environmental Variables for Packer +... # Environmental Variables for Packer -Packer uses a variety of environmental variables. A listing and description of each can be found below: +Packer uses a variety of environmental variables. A listing and description of +each can be found below: -* `PACKER_CACHE_DIR` - The location of the packer cache. +- `PACKER_CACHE_DIR` - The location of the packer cache. -* `PACKER_CONFIG` - The location of the core configuration file. The format - of the configuration file is basic JSON. - See the [core configuration page](/docs/other/core-configuration.html). +- `PACKER_CONFIG` - The location of the core configuration file. The format of + the configuration file is basic JSON. See the [core configuration + page](/docs/other/core-configuration.html). -* `PACKER_LOG` - Setting this to any value will enable the logger. - See the [debugging page](/docs/other/debugging.html). +- `PACKER_LOG` - Setting this to any value will enable the logger. See the + [debugging page](/docs/other/debugging.html). -* `PACKER_LOG_PATH` - The location of the log file. Note: `PACKER_LOG` must - be set for any logging to occur. See the [debugging page](/docs/other/debugging.html). +- `PACKER_LOG_PATH` - The location of the log file. Note: `PACKER_LOG` must be + set for any logging to occur. See the [debugging + page](/docs/other/debugging.html). -* `PACKER_NO_COLOR` - Setting this to any value will disable color in the terminal. +- `PACKER_NO_COLOR` - Setting this to any value will disable color in + the terminal. -* `PACKER_PLUGIN_MAX_PORT` - The maximum port that Packer uses for - communication with plugins, since plugin communication happens over - TCP connections on your local host. The default is 25,000. - See the [core configuration page](/docs/other/core-configuration.html). +- `PACKER_PLUGIN_MAX_PORT` - The maximum port that Packer uses for communication + with plugins, since plugin communication happens over TCP connections on your + local host. The default is 25,000. See the [core configuration + page](/docs/other/core-configuration.html). -* `PACKER_PLUGIN_MIN_PORT` - The minimum port that Packer uses for - communication with plugins, since plugin communication happens - over TCP connections on your local host. The default is 10,000. - See the [core configuration page](/docs/other/core-configuration.html). +- `PACKER_PLUGIN_MIN_PORT` - The minimum port that Packer uses for communication + with plugins, since plugin communication happens over TCP connections on your + local host. The default is 10,000. See the [core configuration + page](/docs/other/core-configuration.html). diff --git a/website/source/docs/post-processors/atlas.html.markdown b/website/source/docs/post-processors/atlas.html.markdown index 91b78e766..c038a119a 100644 --- a/website/source/docs/post-processors/atlas.html.markdown +++ b/website/source/docs/post-processors/atlas.html.markdown @@ -1,27 +1,38 @@ --- -layout: "docs" -page_title: "Atlas Post-Processor" -description: |- - The Atlas post-processor for Packer receives an artifact from a Packer build and uploads it to Atlas. Atlas hosts and serves artifacts, allowing you to version and distribute them in a simple way. ---- +description: | + The Atlas post-processor for Packer receives an artifact from a Packer build and + uploads it to Atlas. Atlas hosts and serves artifacts, allowing you to version + and distribute them in a simple way. +layout: docs +page_title: 'Atlas Post-Processor' +... # Atlas Post-Processor Type: `atlas` -The Atlas post-processor for Packer receives an artifact from a Packer build and uploads it to Atlas. [Atlas](https://atlas.hashicorp.com) hosts and serves artifacts, allowing you to version and distribute them in a simple way. +The Atlas post-processor for Packer receives an artifact from a Packer build and +uploads it to Atlas. [Atlas](https://atlas.hashicorp.com) hosts and serves +artifacts, allowing you to version and distribute them in a simple way. ## Workflow To take full advantage of Packer and Atlas, it's important to understand the -workflow for creating artifacts with Packer and storing them in Atlas using this post-processor. The goal of the Atlas post-processor is to streamline the distribution of public or private artifacts by hosting them in a central location in Atlas. +workflow for creating artifacts with Packer and storing them in Atlas using this +post-processor. The goal of the Atlas post-processor is to streamline the +distribution of public or private artifacts by hosting them in a central +location in Atlas. Here is an example workflow: -1. Packer builds an AMI with the [Amazon AMI builder](/docs/builders/amazon.html) -2. The `atlas` post-processor takes the resulting AMI and uploads it to Atlas. The `atlas` post-processor is configured with the name of the AMI, for example `hashicorp/foobar`, to create the artifact in Atlas or update the version if the artifact already exists -3. The new version is ready and available to be used in deployments with a tool like [Terraform](https://terraform.io) - +1. Packer builds an AMI with the [Amazon AMI + builder](/docs/builders/amazon.html) +2. The `atlas` post-processor takes the resulting AMI and uploads it to Atlas. + The `atlas` post-processor is configured with the name of the AMI, for example + `hashicorp/foobar`, to create the artifact in Atlas or update the version if + the artifact already exists +3. The new version is ready and available to be used in deployments with a tool + like [Terraform](https://terraform.io) ## Configuration @@ -29,32 +40,36 @@ The configuration allows you to specify and access the artifact in Atlas. ### Required: -* `token` (string) - Your access token for the Atlas API. - This can be generated on your [tokens page](https://atlas.hashicorp.com/settings/tokens). Alternatively you can export your Atlas token as an environmental variable and remove it from the configuration. +- `token` (string) - Your access token for the Atlas API. This can be generated + on your [tokens page](https://atlas.hashicorp.com/settings/tokens). + Alternatively you can export your Atlas token as an environmental variable and + remove it from the configuration. -* `artifact` (string) - The shorthand tag for your artifact that maps to - Atlas, i.e `hashicorp/foobar` for `atlas.hashicorp.com/hashicorp/foobar`. You must - have access to the organization, hashicorp in this example, in order to add an artifact to - the organization in Atlas. +- `artifact` (string) - The shorthand tag for your artifact that maps to Atlas, + i.e `hashicorp/foobar` for `atlas.hashicorp.com/hashicorp/foobar`. You must + have access to the organization, hashicorp in this example, in order to add an + artifact to the organization in Atlas. -* `artifact_type` (string) - For uploading AMIs to Atlas, `artifact_type` will always be `amazon.ami`. - This field must be defined because Atlas can host other artifact types, such as Vagrant boxes. +- `artifact_type` (string) - For uploading AMIs to Atlas, `artifact_type` will + always be `amazon.ami`. This field must be defined because Atlas can host + other artifact types, such as Vagrant boxes. --> **Note:** If you want to upload Vagrant boxes to Atlas, use the [Atlas post-processor](/docs/post-processors/atlas.html). +-> **Note:** If you want to upload Vagrant boxes to Atlas, use the [Atlas +post-processor](/docs/post-processors/atlas.html). ### Optional: -* `atlas_url` (string) - Override the base URL for Atlas. This -is useful if you're using Atlas Enterprise in your own network. Defaults -to `https://atlas.hashicorp.com/api/v1`. +- `atlas_url` (string) - Override the base URL for Atlas. This is useful if + you're using Atlas Enterprise in your own network. Defaults to + `https://atlas.hashicorp.com/api/v1`. -* `metadata` (map) - Send metadata about the artifact. If the artifact - type is "vagrant.box", you must specify a "provider" metadata about - what provider to use. +- `metadata` (map) - Send metadata about the artifact. If the artifact type is + "vagrant.box", you must specify a "provider" metadata about what provider + to use. ### Example Configuration -```javascript +``` {.javascript} { "variables": { "aws_access_key": "ACCESS_KEY_HERE", diff --git a/website/source/docs/post-processors/compress.html.markdown b/website/source/docs/post-processors/compress.html.markdown index e6a1237e9..716e4e866 100644 --- a/website/source/docs/post-processors/compress.html.markdown +++ b/website/source/docs/post-processors/compress.html.markdown @@ -1,9 +1,10 @@ --- -layout: "docs" -page_title: "compress Post-Processor" -description: |- - The Packer compress post-processor takes an artifact with files (such as from VMware or VirtualBox) and compresses the artifact into a single archive. ---- +description: | + The Packer compress post-processor takes an artifact with files (such as from + VMware or VirtualBox) and compresses the artifact into a single archive. +layout: docs +page_title: 'compress Post-Processor' +... # Compress Post-Processor @@ -16,49 +17,55 @@ VMware or VirtualBox) and compresses the artifact into a single archive. ### Required: -You must specify the output filename. The archive format is derived from the filename. +You must specify the output filename. The archive format is derived from the +filename. -* `output` (string) - The path to save the compressed archive. The archive - format is inferred from the filename. E.g. `.tar.gz` will be a gzipped - 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. +- `output` (string) - The path to save the compressed archive. The archive + format is inferred from the filename. E.g. `.tar.gz` will be a + gzipped 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. If you are executing multiple builders in parallel you should make sure - `output` is unique for each one. For example `packer_{{.BuildName}}_{{.Provider}}.zip`. + `output` is unique for each one. For example + `packer_{{.BuildName}}_{{.Provider}}.zip`. ### Optional: -If you want more control over how the archive is created you can specify the following settings: +If you want more control over how the archive is created you can specify the +following settings: -* `compression_level` (integer) - Specify the compression level, for algorithms +- `compression_level` (integer) - Specify the compression level, for algorithms that support it, from 1 through 9 inclusive. Typically higher compression levels take longer but produce smaller files. Defaults to `6` -* `keep_input_artifact` (boolean) - Keep source files; defaults to `false` +- `keep_input_artifact` (boolean) - Keep source files; defaults to `false` ### Supported Formats -Supported file extensions include `.zip`, `.tar`, `.gz`, `.tar.gz`, `.lz4` and `.tar.lz4`. Note that `.gz` and `.lz4` will fail if you have multiple files to compress. +Supported file extensions include `.zip`, `.tar`, `.gz`, `.tar.gz`, `.lz4` and +`.tar.lz4`. Note that `.gz` and `.lz4` will fail if you have multiple files to +compress. ## Examples -Some minimal examples are shown below, showing only the post-processor configuration: +Some minimal examples are shown below, showing only the post-processor +configuration: -```json +``` {.json} { "type": "compress", "output": "archive.tar.lz4" } ``` -```json +``` {.json} { "type": "compress", "output": "archive.zip" } ``` -```json +``` {.json} { "type": "compress", "output": "archive.gz", diff --git a/website/source/docs/post-processors/docker-import.html.markdown b/website/source/docs/post-processors/docker-import.html.markdown index c2d7bba80..0c3855622 100644 --- a/website/source/docs/post-processors/docker-import.html.markdown +++ b/website/source/docs/post-processors/docker-import.html.markdown @@ -1,36 +1,38 @@ --- -layout: "docs" -page_title: "docker-import Post-Processor" -description: |- - The Packer Docker import post-processor takes an artifact from the docker builder and imports it with Docker locally. This allows you to apply a repository and tag to the image and lets you use the other Docker post-processors such as docker-push to push the image to a registry. ---- +description: | + The Packer Docker import post-processor takes an artifact from the docker + builder and imports it with Docker locally. This allows you to apply a + repository and tag to the image and lets you use the other Docker + post-processors such as docker-push to push the image to a registry. +layout: docs +page_title: 'docker-import Post-Processor' +... # Docker Import Post-Processor Type: `docker-import` -The Packer Docker import post-processor takes an artifact from the -[docker builder](/docs/builders/docker.html) and imports it with Docker -locally. This allows you to apply a repository and tag to the image -and lets you use the other Docker post-processors such as -[docker-push](/docs/post-processors/docker-push.html) to push the image -to a registry. +The Packer Docker import post-processor takes an artifact from the [docker +builder](/docs/builders/docker.html) and imports it with Docker locally. This +allows you to apply a repository and tag to the image and lets you use the other +Docker post-processors such as +[docker-push](/docs/post-processors/docker-push.html) to push the image to a +registry. ## Configuration -The configuration for this post-processor is extremely simple. At least -a repository is required. +The configuration for this post-processor is extremely simple. At least a +repository is required. -* `repository` (string) - The repository of the imported image. +- `repository` (string) - The repository of the imported image. -* `tag` (string) - The tag for the imported image. By default this is not - set. +- `tag` (string) - The tag for the imported image. By default this is not set. ## Example An example is shown below, showing only the post-processor configuration: -```javascript +``` {.javascript} { "type": "docker-import", "repository": "mitchellh/packer", @@ -38,9 +40,9 @@ An example is shown below, showing only the post-processor configuration: } ``` -This example would take the image created by the Docker builder -and import it into the local Docker process with a name of `mitchellh/packer:0.7`. +This example would take the image created by the Docker builder and import it +into the local Docker process with a name of `mitchellh/packer:0.7`. Following this, you can use the -[docker-push](/docs/post-processors/docker-push.html) -post-processor to push it to a registry, if you want. +[docker-push](/docs/post-processors/docker-push.html) post-processor to push it +to a registry, if you want. diff --git a/website/source/docs/post-processors/docker-push.html.markdown b/website/source/docs/post-processors/docker-push.html.markdown index 2f7ae3e92..72793b735 100644 --- a/website/source/docs/post-processors/docker-push.html.markdown +++ b/website/source/docs/post-processors/docker-push.html.markdown @@ -1,38 +1,38 @@ --- -layout: "docs" -page_title: "Docker Push Post-Processor" -description: |- - The Packer Docker push post-processor takes an artifact from the docker-import post-processor and pushes it to a Docker registry. ---- +description: | + The Packer Docker push post-processor takes an artifact from the docker-import + post-processor and pushes it to a Docker registry. +layout: docs +page_title: 'Docker Push Post-Processor' +... # Docker Push Post-Processor Type: `docker-push` The Packer Docker push post-processor takes an artifact from the -[docker-import](/docs/post-processors/docker-import.html) post-processor -and pushes it to a Docker registry. +[docker-import](/docs/post-processors/docker-import.html) post-processor and +pushes it to a Docker registry. ## Configuration This post-processor has only optional configuration: -* `login` (boolean) - Defaults to false. If true, the post-processor will - login prior to pushing. +- `login` (boolean) - Defaults to false. If true, the post-processor will login + prior to pushing. -* `login_email` (string) - The email to use to authenticate to login. +- `login_email` (string) - The email to use to authenticate to login. -* `login_username` (string) - The username to use to authenticate to login. +- `login_username` (string) - The username to use to authenticate to login. -* `login_password` (string) - The password to use to authenticate to login. +- `login_password` (string) - The password to use to authenticate to login. -* `login_server` (string) - The server address to login to. +- `login_server` (string) - The server address to login to. --> **Note:** If you login using the credentials above, the -post-processor will automatically log you out afterwards (just the server -specified). +-> **Note:** If you login using the credentials above, the post-processor +will automatically log you out afterwards (just the server specified). ## Example -For an example of using docker-push, see the section on using -generated artifacts from the [docker builder](/docs/builders/docker.html). +For an example of using docker-push, see the section on using generated +artifacts from the [docker builder](/docs/builders/docker.html). diff --git a/website/source/docs/post-processors/docker-save.html.markdown b/website/source/docs/post-processors/docker-save.html.markdown index ca03dfcf6..8f758755c 100644 --- a/website/source/docs/post-processors/docker-save.html.markdown +++ b/website/source/docs/post-processors/docker-save.html.markdown @@ -1,35 +1,37 @@ --- -layout: "docs" -page_title: "docker-save Post-Processor" -description: |- - The Packer Docker Save post-processor takes an artifact from the docker builder that was committed and saves it to a file. This is similar to exporting the Docker image directly from the builder, except that it preserves the hierarchy of images and metadata. ---- +description: | + The Packer Docker Save post-processor takes an artifact from the docker builder + that was committed and saves it to a file. This is similar to exporting the + Docker image directly from the builder, except that it preserves the hierarchy + of images and metadata. +layout: docs +page_title: 'docker-save Post-Processor' +... # Docker Save Post-Processor Type: `docker-save` -The Packer Docker Save post-processor takes an artifact from the -[docker builder](/docs/builders/docker.html) that was committed -and saves it to a file. This is similar to exporting the Docker image -directly from the builder, except that it preserves the hierarchy of -images and metadata. +The Packer Docker Save post-processor takes an artifact from the [docker +builder](/docs/builders/docker.html) that was committed and saves it to a file. +This is similar to exporting the Docker image directly from the builder, except +that it preserves the hierarchy of images and metadata. -We understand the terminology can be a bit confusing, but we've -adopted the terminology from Docker, so if you're familiar with that, then -you'll be familiar with this and vice versa. +We understand the terminology can be a bit confusing, but we've adopted the +terminology from Docker, so if you're familiar with that, then you'll be +familiar with this and vice versa. ## Configuration The configuration for this post-processor is extremely simple. -* `path` (string) - The path to save the image. +- `path` (string) - The path to save the image. ## Example An example is shown below, showing only the post-processor configuration: -```javascript +``` {.javascript} { "type": "docker-save", "path": "foo.tar" diff --git a/website/source/docs/post-processors/docker-tag.html.markdown b/website/source/docs/post-processors/docker-tag.html.markdown index d3925d1fa..42c480676 100644 --- a/website/source/docs/post-processors/docker-tag.html.markdown +++ b/website/source/docs/post-processors/docker-tag.html.markdown @@ -1,43 +1,44 @@ --- -layout: "docs" -page_title: "docker-tag Post-Processor" -description: |- - The Packer Docker Tag post-processor takes an artifact from the docker builder that was committed and tags it into a repository. This allows you to use the other Docker post-processors such as docker-push to push the image to a registry. ---- +description: | + The Packer Docker Tag post-processor takes an artifact from the docker builder + that was committed and tags it into a repository. This allows you to use the + other Docker post-processors such as docker-push to push the image to a + registry. +layout: docs +page_title: 'docker-tag Post-Processor' +... # Docker Tag Post-Processor Type: `docker-tag` -The Packer Docker Tag post-processor takes an artifact from the -[docker builder](/docs/builders/docker.html) that was committed -and tags it into a repository. This allows you to use the other -Docker post-processors such as -[docker-push](/docs/post-processors/docker-push.html) to push the image -to a registry. +The Packer Docker Tag post-processor takes an artifact from the [docker +builder](/docs/builders/docker.html) that was committed and tags it into a +repository. This allows you to use the other Docker post-processors such as +[docker-push](/docs/post-processors/docker-push.html) to push the image to a +registry. -This is very similar to the [docker-import](/docs/post-processors/docker-import.html) -post-processor except that this works with committed resources, rather -than exported. +This is very similar to the +[docker-import](/docs/post-processors/docker-import.html) post-processor except +that this works with committed resources, rather than exported. ## Configuration -The configuration for this post-processor is extremely simple. At least -a repository is required. +The configuration for this post-processor is extremely simple. At least a +repository is required. -* `repository` (string) - The repository of the image. +- `repository` (string) - The repository of the image. -* `tag` (string) - The tag for the image. By default this is not - set. +- `tag` (string) - The tag for the image. By default this is not set. -* `force` (boolean) - If true, this post-processor forcibly tag the image - even if tag name is collided. Default to `false`. +- `force` (boolean) - If true, this post-processor forcibly tag the image even + if tag name is collided. Default to `false`. ## Example An example is shown below, showing only the post-processor configuration: -```javascript +``` {.javascript} { "type": "docker-tag", "repository": "mitchellh/packer", @@ -45,9 +46,9 @@ An example is shown below, showing only the post-processor configuration: } ``` -This example would take the image created by the Docker builder -and tag it into the local Docker process with a name of `mitchellh/packer:0.7`. +This example would take the image created by the Docker builder and tag it into +the local Docker process with a name of `mitchellh/packer:0.7`. Following this, you can use the -[docker-push](/docs/post-processors/docker-push.html) -post-processor to push it to a registry, if you want. +[docker-push](/docs/post-processors/docker-push.html) post-processor to push it +to a registry, if you want. diff --git a/website/source/docs/post-processors/vagrant-cloud.html.markdown b/website/source/docs/post-processors/vagrant-cloud.html.markdown index 451ed087b..e049552da 100644 --- a/website/source/docs/post-processors/vagrant-cloud.html.markdown +++ b/website/source/docs/post-processors/vagrant-cloud.html.markdown @@ -1,81 +1,88 @@ --- -layout: "docs" -page_title: "Vagrant Cloud Post-Processor" -description: |- - The Packer Vagrant Cloud post-processor receives a Vagrant box from the `vagrant` post-processor and pushes it to Vagrant Cloud. Vagrant Cloud hosts and serves boxes to Vagrant, allowing you to version and distribute boxes to an organization in a simple way. ---- +description: | + The Packer Vagrant Cloud post-processor receives a Vagrant box from the + `vagrant` post-processor and pushes it to Vagrant Cloud. Vagrant Cloud hosts and + serves boxes to Vagrant, allowing you to version and distribute boxes to an + organization in a simple way. +layout: docs +page_title: 'Vagrant Cloud Post-Processor' +... # Vagrant Cloud Post-Processor -~> Vagrant Cloud has been superseded by Atlas. Please use the [Atlas post-processor](/docs/post-processors/atlas.html) instead. Learn more about [Atlas](https://atlas.hashicorp.com/). +\~> Vagrant Cloud has been superseded by Atlas. Please use the [Atlas +post-processor](/docs/post-processors/atlas.html) instead. Learn more about +[Atlas](https://atlas.hashicorp.com/). Type: `vagrant-cloud` -The Packer Vagrant Cloud post-processor receives a Vagrant box from the `vagrant` -post-processor and pushes it to Vagrant Cloud. [Vagrant Cloud](https://vagrantcloud.com) -hosts and serves boxes to Vagrant, allowing you to version and distribute -boxes to an organization in a simple way. +The Packer Vagrant Cloud post-processor receives a Vagrant box from the +`vagrant` post-processor and pushes it to Vagrant Cloud. [Vagrant +Cloud](https://vagrantcloud.com) hosts and serves boxes to Vagrant, allowing you +to version and distribute boxes to an organization in a simple way. -You'll need to be familiar with Vagrant Cloud, have an upgraded account -to enable box hosting, and be distributing your box via the [shorthand name](http://docs.vagrantup.com/v2/cli/box.html) -configuration. +You'll need to be familiar with Vagrant Cloud, have an upgraded account to +enable box hosting, and be distributing your box via the [shorthand +name](http://docs.vagrantup.com/v2/cli/box.html) configuration. ## Workflow It's important to understand the workflow that using this post-processor enforces in order to take full advantage of Vagrant and Vagrant Cloud. -The use of this processor assume that you currently distribute, or plan -to distribute, boxes via Vagrant Cloud. It also assumes you create Vagrant -Boxes and deliver them to your team in some fashion. +The use of this processor assume that you currently distribute, or plan to +distribute, boxes via Vagrant Cloud. It also assumes you create Vagrant Boxes +and deliver them to your team in some fashion. Here is an example workflow: -1. You use Packer to build a Vagrant Box for the `virtualbox` provider -2. The `vagrant-cloud` post-processor is configured to point to the box `hashicorp/foobar` on Vagrant Cloud -via the `box_tag` configuration -2. The post-processor receives the box from the `vagrant` post-processor -3. It then creates the configured version, or verifies the existence of it, on Vagrant Cloud -4. A provider matching the name of the Vagrant provider is then created -5. The box is uploaded to Vagrant Cloud -6. The upload is verified -7. The version is released and available to users of the box - +1. You use Packer to build a Vagrant Box for the `virtualbox` provider +2. The `vagrant-cloud` post-processor is configured to point to the box + `hashicorp/foobar` on Vagrant Cloud via the `box_tag` configuration +3. The post-processor receives the box from the `vagrant` post-processor +4. It then creates the configured version, or verifies the existence of it, on + Vagrant Cloud +5. A provider matching the name of the Vagrant provider is then created +6. The box is uploaded to Vagrant Cloud +7. The upload is verified +8. The version is released and available to users of the box ## Configuration -The configuration allows you to specify the target box that you have -access to on Vagrant Cloud, as well as authentication and version information. +The configuration allows you to specify the target box that you have access to +on Vagrant Cloud, as well as authentication and version information. ### Required: -* `access_token` (string) - Your access token for the Vagrant Cloud API. - This can be generated on your [tokens page](https://vagrantcloud.com/account/tokens). +- `access_token` (string) - Your access token for the Vagrant Cloud API. This + can be generated on your [tokens + page](https://vagrantcloud.com/account/tokens). -* `box_tag` (string) - The shorthand tag for your box that maps to - Vagrant Cloud, i.e `hashicorp/precise64` for `vagrantcloud.com/hashicorp/precise64` - -* `version` (string) - The version number, typically incrementing a previous version. - The version string is validated based on [Semantic Versioning](http://semver.org/). The string must match - a pattern that could be semver, and doesn't validate that the version comes after - your previous versions. +- `box_tag` (string) - The shorthand tag for your box that maps to Vagrant + Cloud, i.e `hashicorp/precise64` for `vagrantcloud.com/hashicorp/precise64` +- `version` (string) - The version number, typically incrementing a + previous version. The version string is validated based on [Semantic + Versioning](http://semver.org/). The string must match a pattern that could be + semver, and doesn't validate that the version comes after your + previous versions. ### Optional: -* `no_release` (string) - If set to true, does not release the version -on Vagrant Cloud, making it active. You can manually release the version -via the API or Web UI. Defaults to false. +- `no_release` (string) - If set to true, does not release the version on + Vagrant Cloud, making it active. You can manually release the version via the + API or Web UI. Defaults to false. -* `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` +- `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` -* `version_description` (string) - Optionally markdown text used as a full-length - and in-depth description of the version, typically for denoting changes introduced +- `version_description` (string) - Optionally markdown text used as a + full-length and in-depth description of the version, typically for denoting + changes introduced -* `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. +- `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. ## Use with Vagrant Post-Processor @@ -84,7 +91,7 @@ An example configuration is below. Note the use of a doubly-nested array, which ensures that the Vagrant Cloud post-processor is run after the Vagrant post-processor. -```javascript +``` {.javascript} { "variables": { "version": "", diff --git a/website/source/docs/post-processors/vagrant.html.markdown b/website/source/docs/post-processors/vagrant.html.markdown index 7ed19d665..da1b8daa9 100644 --- a/website/source/docs/post-processors/vagrant.html.markdown +++ b/website/source/docs/post-processors/vagrant.html.markdown @@ -1,91 +1,90 @@ --- -layout: "docs" -page_title: "Vagrant Post-Processor" -description: |- - The Packer Vagrant post-processor takes a build and converts the artifact into a valid Vagrant box, if it can. This lets you use Packer to automatically create arbitrarily complex Vagrant boxes, and is in fact how the official boxes distributed by Vagrant are created. ---- +description: | + The Packer Vagrant post-processor takes a build and converts the artifact into a + valid Vagrant box, if it can. This lets you use Packer to automatically create + arbitrarily complex Vagrant boxes, and is in fact how the official boxes + distributed by Vagrant are created. +layout: docs +page_title: 'Vagrant Post-Processor' +... # Vagrant Post-Processor Type: `vagrant` -The Packer Vagrant post-processor takes a build and converts the artifact -into a valid [Vagrant](http://www.vagrantup.com) box, if it can. -This lets you use Packer to automatically create arbitrarily complex -Vagrant boxes, and is in fact how the official boxes distributed by -Vagrant are created. +The Packer Vagrant post-processor takes a build and converts the artifact into a +valid [Vagrant](http://www.vagrantup.com) box, if it can. This lets you use +Packer to automatically create arbitrarily complex Vagrant boxes, and is in fact +how the official boxes distributed by Vagrant are created. -If you've never used a post-processor before, please read the -documentation on [using post-processors](/docs/templates/post-processors.html) -in templates. This knowledge will be expected for the remainder of -this document. +If you've never used a post-processor before, please read the documentation on +[using post-processors](/docs/templates/post-processors.html) in templates. This +knowledge will be expected for the remainder of this document. -Because Vagrant boxes are [provider-specific](http://docs.vagrantup.com/v2/boxes/format.html), -the Vagrant post-processor is hardcoded to understand how to convert -the artifacts of certain builders into proper boxes for their -respective providers. +Because Vagrant boxes are +[provider-specific](http://docs.vagrantup.com/v2/boxes/format.html), the Vagrant +post-processor is hardcoded to understand how to convert the artifacts of +certain builders into proper boxes for their respective providers. Currently, the Vagrant post-processor can create boxes for the following providers. -* AWS -* DigitalOcean -* Hyper-V -* Parallels -* QEMU -* VirtualBox -* VMware +- AWS +- DigitalOcean +- Hyper-V +- Parallels +- QEMU +- VirtualBox +- VMware --> **Support for additional providers** is planned. If the -Vagrant post-processor doesn't support creating boxes for a provider you -care about, please help by contributing to Packer and adding support for it. +-> **Support for additional providers** is planned. If the Vagrant +post-processor doesn't support creating boxes for a provider you care about, +please help by contributing to Packer and adding support for it. ## Configuration The simplest way to use the post-processor is to just enable it. No -configuration is required by default. This will mostly do what you expect -and will build functioning boxes for many of the built-in builders of -Packer. +configuration is required by default. This will mostly do what you expect and +will build functioning boxes for many of the built-in builders of Packer. -However, if you want to configure things a bit more, the post-processor -does expose some configuration options. The available options are listed -below, with more details about certain options in following sections. +However, if you want to configure things a bit more, the post-processor does +expose some configuration options. The available options are listed below, with +more details about certain options in following sections. -* `compression_level` (integer) - An integer representing the - compression level to use when creating the Vagrant box. Valid - values range from 0 to 9, with 0 being no compression and 9 being - the best compression. By default, compression is enabled at level 6. +- `compression_level` (integer) - An integer representing the compression level + to use when creating the Vagrant box. Valid values range from 0 to 9, with 0 + being no compression and 9 being the best compression. By default, compression + is enabled at level 6. -* `include` (array of strings) - Paths to files to include in the - Vagrant box. These files will each be copied into the top level directory - of the Vagrant box (regardless of their paths). They can then be used - from the Vagrantfile. +- `include` (array of strings) - Paths to files to include in the Vagrant box. + These files will each be copied into the top level directory 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 +- `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). - 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`. +- `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). 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`. -* `vagrantfile_template` (string) - Path to a template to use for the +- `vagrantfile_template` (string) - Path to a template to use for the Vagrantfile that is packaged with the box. ## Provider-Specific Overrides -If you have a Packer template with multiple builder types within it, -you may want to configure the box creation for each type a little differently. -For example, the contents of the Vagrantfile for a Vagrant box for AWS might -be different from the contents of the Vagrantfile you want for VMware. -The post-processor lets you do this. +If you have a Packer template with multiple builder types within it, you may +want to configure the box creation for each type a little differently. For +example, the contents of the Vagrantfile for a Vagrant box for AWS might be +different from the contents of the Vagrantfile you want for VMware. The +post-processor lets you do this. Specify overrides within the `override` configuration by provider name: -```javascript +``` {.javascript} { "type": "vagrant", "compression_level": 1, @@ -97,18 +96,18 @@ Specify overrides within the `override` configuration by provider name: } ``` -In the example above, the compression level will be set to 1 except for -VMware, where it will be set to 0. +In the example above, the compression level will be set to 1 except for VMware, +where it will be set to 0. -The available provider names are: `aws`, `digitalocean`, `virtualbox`, -`vmware`, and `parallels`. +The available provider names are: `aws`, `digitalocean`, `virtualbox`, `vmware`, +and `parallels`. ## Input Artifacts -By default, Packer will delete the original input artifact, assuming -you only want the final Vagrant box as the result. If you wish to keep the -input artifact (the raw virtual machine, for example), then you must -configure Packer to keep it. +By default, Packer will delete the original input artifact, assuming you only +want the final Vagrant box as the result. If you wish to keep the input artifact +(the raw virtual machine, for example), then you must configure Packer to keep +it. -Please see the [documentation on input artifacts](/docs/templates/post-processors.html#toc_2) -for more information. +Please see the [documentation on input +artifacts](/docs/templates/post-processors.html#toc_2) for more information. diff --git a/website/source/docs/post-processors/vsphere.html.markdown b/website/source/docs/post-processors/vsphere.html.markdown index ca3f3f54a..f0fd9588e 100644 --- a/website/source/docs/post-processors/vsphere.html.markdown +++ b/website/source/docs/post-processors/vsphere.html.markdown @@ -1,16 +1,17 @@ --- -layout: "docs" -page_title: "vSphere Post-Processor" -description: |- - The Packer vSphere post-processor takes an artifact from the VMware builder and uploads it to a vSphere endpoint. ---- +description: | + The Packer vSphere post-processor takes an artifact from the VMware builder and + uploads it to a vSphere endpoint. +layout: docs +page_title: 'vSphere Post-Processor' +... # vSphere Post-Processor Type: `vsphere` -The Packer vSphere post-processor takes an artifact from the VMware builder -and uploads it to a vSphere endpoint. +The Packer vSphere post-processor takes an artifact from the VMware builder and +uploads it to a vSphere endpoint. ## Configuration @@ -20,37 +21,35 @@ each category, the available configuration keys are alphabetized. Required: -* `cluster` (string) - The cluster to upload the VM to. +- `cluster` (string) - The cluster to upload the VM to. -* `datacenter` (string) - The name of the datacenter within vSphere to - add the VM to. +- `datacenter` (string) - The name of the datacenter within vSphere to add the + VM to. -* `datastore` (string) - The name of the datastore to store this VM. - This is _not required_ if `resource_pool` is specified. +- `datastore` (string) - The name of the datastore to store this VM. This is + *not required* if `resource_pool` is specified. -* `host` (string) - The vSphere host that will be contacted to perform - the VM upload. +- `host` (string) - The vSphere host that will be contacted to perform the + VM upload. -* `password` (string) - Password to use to authenticate to the vSphere - endpoint. +- `password` (string) - Password to use to authenticate to the vSphere endpoint. -* `resource_pool` (string) - The resource pool to upload the VM to. - This is _not required_. +- `resource_pool` (string) - The resource pool to upload the VM to. This is *not + required*. -* `username` (string) - The username to use to authenticate to the vSphere - endpoint. +- `username` (string) - The username to use to authenticate to the + vSphere endpoint. -* `vm_name` (string) - The name of the VM once it is uploaded. +- `vm_name` (string) - The name of the VM once it is uploaded. Optional: -* `disk_mode` (string) - Target disk format. See `ovftool` manual for +- `disk_mode` (string) - Target disk format. See `ovftool` manual for available options. By default, "thick" will be used. -* `insecure` (boolean) - 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. +- `vm_folder` (string) - The folder within the datastore to store the VM. -* `vm_network` (string) - The name of the VM network this VM will be - added to. +- `vm_network` (string) - The name of the VM network this VM will be added to. diff --git a/website/source/docs/provisioners/ansible-local.html.markdown b/website/source/docs/provisioners/ansible-local.html.markdown index a2550b7bd..5682043c9 100644 --- a/website/source/docs/provisioners/ansible-local.html.markdown +++ b/website/source/docs/provisioners/ansible-local.html.markdown @@ -1,23 +1,28 @@ --- -layout: "docs" -page_title: "Ansible (Local) Provisioner" -description: |- - The `ansible-local` Packer provisioner configures Ansible to run on the machine by Packer from local Playbook and Role files. Playbooks and Roles can be uploaded from your local machine to the remote machine. Ansible is run in local mode via the `ansible-playbook` command. ---- +description: | + The `ansible-local` Packer provisioner configures Ansible to run on the machine + by Packer from local Playbook and Role files. Playbooks and Roles can be + uploaded from your local machine to the remote machine. Ansible is run in local + mode via the `ansible-playbook` command. +layout: docs +page_title: 'Ansible (Local) Provisioner' +... # Ansible Local Provisioner Type: `ansible-local` -The `ansible-local` Packer provisioner configures Ansible to run on the machine by -Packer from local Playbook and Role files. Playbooks and Roles can be uploaded -from your local machine to the remote machine. Ansible is run in [local mode](http://docs.ansible.com/playbooks_delegation.html#local-playbooks) via the `ansible-playbook` command. +The `ansible-local` Packer provisioner configures Ansible to run on the machine +by Packer from local Playbook and Role files. Playbooks and Roles can be +uploaded from your local machine to the remote machine. Ansible is run in [local +mode](http://docs.ansible.com/playbooks_delegation.html#local-playbooks) via the +`ansible-playbook` command. ## Basic Example The example below is fully functional. -```javascript +``` {.javascript} { "type": "ansible-local", "playbook_file": "local.yml" @@ -30,39 +35,40 @@ The reference of available configuration options is listed below. Required: -* `playbook_file` (string) - The playbook file to be executed by ansible. - This file must exist on your local system and will be uploaded to the +- `playbook_file` (string) - The playbook file to be executed by ansible. This + file must exist on your local system and will be uploaded to the remote machine. Optional: -* `command` (string) - The command to invoke ansible. Defaults to "ansible-playbook". +- `command` (string) - The command to invoke ansible. Defaults + to "ansible-playbook". -* `extra_arguments` (array of strings) - An array of extra arguments to pass to the - ansible command. By default, this is empty. +- `extra_arguments` (array of strings) - An array of extra arguments to pass to + the ansible command. By default, this is empty. -* `inventory_groups` (string) - A comma-separated list of groups to which - packer will assign the host `127.0.0.1`. A value of `my_group_1,my_group_2` - will generate an Ansible inventory like: +- `inventory_groups` (string) - A comma-separated list of groups to which packer + will assign the host `127.0.0.1`. A value of `my_group_1,my_group_2` will + generate an Ansible inventory like: - ```text + ``` {.text} [my_group_1] 127.0.0.1 [my_group_2] 127.0.0.1 ``` -* `inventory_file` (string) - The inventory file to be used by ansible. - This file must exist on your local system and will be uploaded to the +- `inventory_file` (string) - The inventory file to be used by ansible. This + file must exist on your local system and will be uploaded to the remote machine. - When using an inventory file, it's also required to `--limit` the hosts to - the specified host you're buiding. The `--limit` argument can be provided in - the `extra_arguments` option. + When using an inventory file, it's also required to `--limit` the hosts to the + specified host you're buiding. The `--limit` argument can be provided in the + `extra_arguments` option. An example inventory file may look like: - ```text + ``` {.text} [chi-dbservers] db-01 ansible_connection=local db-02 ansible_connection=local @@ -82,29 +88,30 @@ Optional: chi-appservers ``` -* `playbook_dir` (string) - a path to the complete ansible directory - structure on your local system to be copied to the remote machine - as the `staging_directory` before all other files and directories. +- `playbook_dir` (string) - a path to the complete ansible directory structure + on your local system to be copied to the remote machine as the + `staging_directory` before all other files and directories. -* `playbook_paths` (array of strings) - An array of paths to playbook files on +- `playbook_paths` (array of strings) - An array of paths to playbook files on your local system. These will be uploaded to the remote machine under `staging_directory`/playbooks. By default, this is empty. -* `group_vars` (string) - a path to the directory containing ansible - group variables on your local system to be copied to the - remote machine. By default, this is empty. +- `group_vars` (string) - a path to the directory containing ansible group + variables on your local system to be copied to the remote machine. By default, + this is empty. -* `host_vars` (string) - a path to the directory containing ansible - host variables on your local system to be copied to the - remote machine. By default, this is empty. +- `host_vars` (string) - a path to the directory containing ansible host + variables on your local system to be copied to the remote machine. By default, + this is empty. -* `role_paths` (array of strings) - An array of paths to role directories on +- `role_paths` (array of strings) - An array of paths to role directories on your local system. These will be uploaded to the remote machine under `staging_directory`/roles. By default, this is empty. -* `staging_directory` (string) - The directory where all the configuration of - Ansible by Packer will be placed. By default this is "/tmp/packer-provisioner-ansible-local". - This directory doesn't need to exist but must have proper permissions so that - the SSH user that Packer uses is able to create directories and write into - this folder. If the permissions are not correct, use a shell provisioner prior - to this to configure it properly. +- `staging_directory` (string) - The directory where all the configuration of + Ansible by Packer will be placed. By default this + is "/tmp/packer-provisioner-ansible-local". This directory doesn't need to + exist but must have proper permissions so that the SSH user that Packer uses + is able to create directories and write into this folder. If the permissions + are not correct, use a shell provisioner prior to this to configure + it properly. diff --git a/website/source/docs/provisioners/chef-client.html.markdown b/website/source/docs/provisioners/chef-client.html.markdown index 3e56eecb2..81d097b7e 100644 --- a/website/source/docs/provisioners/chef-client.html.markdown +++ b/website/source/docs/provisioners/chef-client.html.markdown @@ -1,115 +1,120 @@ --- -layout: "docs" -page_title: "Chef-Client Provisioner" -description: |- - The Chef Client Packer provisioner installs and configures software on machines built by Packer using chef-client. Packer configures a Chef client to talk to a remote Chef Server to provision the machine. ---- +description: | + The Chef Client Packer provisioner installs and configures software on machines + built by Packer using chef-client. Packer configures a Chef client to talk to a + remote Chef Server to provision the machine. +layout: docs +page_title: 'Chef-Client Provisioner' +... # Chef Client Provisioner Type: `chef-client` -The Chef Client Packer provisioner installs and configures software on machines built -by Packer using [chef-client](http://docs.opscode.com/chef_client.html). -Packer configures a Chef client to talk to a remote Chef Server to -provision the machine. +The Chef Client Packer provisioner installs and configures software on machines +built by Packer using [chef-client](http://docs.opscode.com/chef_client.html). +Packer configures a Chef client to talk to a remote Chef Server to provision the +machine. The provisioner will even install Chef onto your machine if it isn't already installed, using the official Chef installers provided by Opscode. ## Basic Example -The example below is fully functional. It will install Chef onto the -remote machine and run Chef client. +The example below is fully functional. It will install Chef onto the remote +machine and run Chef client. -```javascript +``` {.javascript} { "type": "chef-client", "server_url": "https://mychefserver.com/" } ``` -Note: to properly clean up the Chef node and client the machine on which -packer is running must have knife on the path and configured globally, -i.e, ~/.chef/knife.rb must be present and configured for the target chef server +Note: to properly clean up the Chef node and client the machine on which packer +is running must have knife on the path and configured globally, i.e, +\~/.chef/knife.rb must be present and configured for the target chef server ## Configuration Reference The reference of available configuration options is listed below. No configuration is actually required. -* `chef_environment` (string) - The name of the chef_environment sent to the +- `chef_environment` (string) - The name of the chef\_environment sent to the Chef server. By default this is empty and will not use an environment. -* `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 set configurations that the Packer provisioner doesn't support, - then you should use a custom configuration template. See the dedicated - "Chef Configuration" section below for more details. +- `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 set + configurations that the Packer provisioner doesn't support, then you should + use a custom configuration template. See the dedicated "Chef Configuration" + section below for more details. -* `execute_command` (string) - The command used to execute Chef. This has - various [configuration template variables](/docs/templates/configuration-templates.html) - available. See below for more information. +- `execute_command` (string) - The command used to execute Chef. This has + various [configuration template + variables](/docs/templates/configuration-templates.html) available. See below + for more information. -* `install_command` (string) - The command used to install Chef. This has - various [configuration template variables](/docs/templates/configuration-templates.html) - available. See below for more information. +- `install_command` (string) - The command used to install Chef. This has + various [configuration template + variables](/docs/templates/configuration-templates.html) available. See below + for more information. -* `json` (object) - An arbitrary mapping of JSON that will be available as - node attributes while running Chef. +- `json` (object) - An arbitrary mapping of JSON that will be available as node + attributes while running Chef. -* `node_name` (string) - The name of the node to register with the Chef - Server. This is optional and by default is packer-{{uuid}}. +- `node_name` (string) - The name of the node to register with the Chef Server. + This is optional and by default is packer-{{uuid}}. -* `prevent_sudo` (boolean) - By default, the configured commands that are +- `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. -* `run_list` (array of strings) - The [run list](http://docs.opscode.com/essentials_node_object_run_lists.html) - for Chef. By default this is empty, and will use the run list sent - down by the Chef Server. +- `run_list` (array of strings) - The [run + list](http://docs.opscode.com/essentials_node_object_run_lists.html) for Chef. + By default this is empty, and will use the run list sent down by the + Chef Server. -* `server_url` (string) - The URL to the Chef server. This is required. +- `server_url` (string) - The URL to the Chef server. This is required. -* `skip_clean_client` (boolean) - If true, Packer won't remove the client - from the Chef server after it is done running. By default, this is false. +- `skip_clean_client` (boolean) - If true, Packer won't remove the client from + the Chef server after it is done running. By default, this is false. -* `skip_clean_node` (boolean) - If true, Packer won't remove the node - from the Chef server after it is done running. By default, this is false. +- `skip_clean_node` (boolean) - If true, Packer won't remove the node from the + Chef server after it is done running. By default, this is false. -* `skip_install` (boolean) - If true, Chef will not automatically be installed +- `skip_install` (boolean) - If true, Chef will not automatically be installed on the machine using the Opscode omnibus installers. -* `staging_directory` (string) - This is the directory where all the configuration - of Chef by Packer will be placed. By default this is "/tmp/packer-chef-client". - This directory doesn't need to exist but must have proper permissions so that - the SSH user that Packer uses is able to create directories and write into - this folder. If the permissions are not correct, use a shell provisioner - prior to this to configure it properly. +- `staging_directory` (string) - This is the directory where all the + configuration of Chef by Packer will be placed. By default this + is "/tmp/packer-chef-client". This directory doesn't need to exist but must + have proper permissions so that the SSH user that Packer uses is able to + create directories and write into this folder. If the permissions are not + correct, use a shell provisioner prior to this to configure it properly. -* `client_key` (string) - Path to client key. If not set, this defaults to a file - named client.pem in `staging_directory`. +- `client_key` (string) - Path to client key. If not set, this defaults to a + file named client.pem in `staging_directory`. -* `validation_client_name` (string) - Name of the validation client. If - not set, this won't be set in the configuration and the default that Chef - uses will be used. +- `validation_client_name` (string) - Name of the validation client. If not set, + this won't be set in the configuration and the default that Chef uses will + be used. -* `validation_key_path` (string) - Path to the validation key for communicating - with the Chef Server. This will be uploaded to the remote machine. If this - is NOT set, then it is your responsibility via other means (shell provisioner, - etc.) to get a validation key to where Chef expects it. +- `validation_key_path` (string) - Path to the validation key for communicating + with the Chef Server. This will be uploaded to the remote machine. If this is + NOT set, then it is your responsibility via other means (shell + provisioner, etc.) to get a validation key to where Chef expects it. ## Chef Configuration -By default, Packer uses a simple Chef configuration file in order to set -the options specified for the provisioner. But Chef is a complex tool that -supports many configuration options. Packer allows you to specify a custom -configuration template if you'd like to set custom configurations. +By default, Packer uses a simple Chef configuration file in order to set the +options specified for the provisioner. But Chef is a complex tool that supports +many configuration options. Packer allows you to specify a custom configuration +template if you'd like to set custom configurations. The default value for the configuration template is: -```liquid +``` {.liquid} log_level :info log_location STDOUT chef_server_url "{{.ServerUrl}}" @@ -126,42 +131,42 @@ node_name "{{.NodeName}}" {{end}} ``` -This template is a [configuration template](/docs/templates/configuration-templates.html) -and has a set of variables available to use: +This template is a [configuration +template](/docs/templates/configuration-templates.html) and has a set of +variables available to use: -* `NodeName` - The node name set in the configuration. -* `ServerUrl` - The URL of the Chef Server set in the configuration. -* `ValidationKeyPath` - Path to the validation key, if it is set. +- `NodeName` - The node name set in the configuration. +- `ServerUrl` - The URL of the Chef Server set in the configuration. +- `ValidationKeyPath` - Path to the validation key, if it is set. ## Execute Command -By default, Packer uses the following command (broken across multiple lines -for readability) to execute Chef: +By default, Packer uses the following command (broken across multiple lines for +readability) to execute Chef: -```liquid +``` {.liquid} {{if .Sudo}}sudo {{end}}chef-client \ --no-color \ -c {{.ConfigPath}} \ -j {{.JsonPath}} ``` -This command can be customized using the `execute_command` configuration. -As you can see from the default value above, the value of this configuration -can contain various template variables, defined below: +This command can be customized using the `execute_command` configuration. As you +can see from the default value above, the value of this configuration can +contain various template variables, defined below: -* `ConfigPath` - The path to the Chef configuration file. - file. -* `JsonPath` - The path to the JSON attributes file for the node. -* `Sudo` - A boolean of whether to `sudo` the command or not, depending on - the value of the `prevent_sudo` configuration. +- `ConfigPath` - The path to the Chef configuration file. file. +- `JsonPath` - The path to the JSON attributes file for the node. +- `Sudo` - A boolean of whether to `sudo` the command or not, depending on the + value of the `prevent_sudo` configuration. ## Install Command -By default, Packer uses the following command (broken across multiple lines -for readability) to install Chef. This command can be customized if you want -to install Chef in another way. +By default, Packer uses the following command (broken across multiple lines for +readability) to install Chef. This command can be customized if you want to +install Chef in another way. -```text +``` {.text} curl -L https://www.opscode.com/chef/install.sh | \ {{if .Sudo}}sudo{{end}} bash ``` @@ -170,9 +175,8 @@ This command can be customized using the `install_command` configuration. ## Folder Permissions -!> The `chef-client` provisioner will chmod the directory with your Chef -keys to 777. This is to ensure that Packer can upload and make use of that -directory. However, once the machine is created, you usually don't -want to keep these directories with those permissions. To change the -permissions on the directories, append a shell provisioner after Chef -to modify them. +!> The `chef-client` provisioner will chmod the directory with your Chef keys +to 777. This is to ensure that Packer can upload and make use of that directory. +However, once the machine is created, you usually don't want to keep these +directories with those permissions. To change the permissions on the +directories, append a shell provisioner after Chef to modify them. diff --git a/website/source/docs/provisioners/chef-solo.html.markdown b/website/source/docs/provisioners/chef-solo.html.markdown index 3a76c5514..03b55c066 100644 --- a/website/source/docs/provisioners/chef-solo.html.markdown +++ b/website/source/docs/provisioners/chef-solo.html.markdown @@ -1,28 +1,30 @@ --- -layout: "docs" -page_title: "Chef-Solo Provisioner" -description: |- - The Chef solo Packer provisioner installs and configures software on machines built by Packer using chef-solo. Cookbooks can be uploaded from your local machine to the remote machine or remote paths can be used. ---- +description: | + The Chef solo Packer provisioner installs and configures software on machines + built by Packer using chef-solo. Cookbooks can be uploaded from your local + machine to the remote machine or remote paths can be used. +layout: docs +page_title: 'Chef-Solo Provisioner' +... # Chef Solo Provisioner Type: `chef-solo` -The Chef solo Packer provisioner installs and configures software on machines built -by Packer using [chef-solo](https://docs.chef.io/chef_solo.html). Cookbooks -can be uploaded from your local machine to the remote machine or remote paths -can be used. +The Chef solo Packer provisioner installs and configures software on machines +built by Packer using [chef-solo](https://docs.chef.io/chef_solo.html). +Cookbooks can be uploaded from your local machine to the remote machine or +remote paths can be used. The provisioner will even install Chef onto your machine if it isn't already installed, using the official Chef installers provided by Chef Inc. ## Basic Example -The example below is fully functional and expects cookbooks in the -"cookbooks" directory relative to your working directory. +The example below is fully functional and expects cookbooks in the "cookbooks" +directory relative to your working directory. -```javascript +``` {.javascript} { "type": "chef-solo", "cookbook_paths": ["cookbooks"] @@ -34,124 +36,126 @@ The example below is fully functional and expects cookbooks in the The reference of available configuration options is listed below. No configuration is actually required, but at least `run_list` is recommended. -* `chef_environment` (string) - The name of the `chef_environment` sent to the +- `chef_environment` (string) - The name of the `chef_environment` sent to the Chef server. By default this is empty and will not use an environment -* `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 set configurations that the Packer provisioner doesn't support, - then you should use a custom configuration template. See the dedicated - "Chef Configuration" section below for more details. +- `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 set + configurations that the Packer provisioner doesn't support, then you should + use a custom configuration template. See the dedicated "Chef Configuration" + section below for more details. -* `cookbook_paths` (array of strings) - This is an array of paths to - "cookbooks" directories 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. +- `cookbook_paths` (array of strings) - This is an array of paths to "cookbooks" + directories 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. -* `data_bags_path` (string) - The path to the "data\_bags" 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. +- `data_bags_path` (string) - The path to the "data\_bags" 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. -* `encrypted_data_bag_secret_path` (string) - The path to the file containing - the secret for encrypted data bags. By default, this is empty, so no - secret will be available. +- `encrypted_data_bag_secret_path` (string) - The path to the file containing + the secret for encrypted data bags. By default, this is empty, so no secret + will be available. -* `environments_path` (string) - The path to the "environments" 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. +- `environments_path` (string) - The path to the "environments" 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. -* `execute_command` (string) - The command used to execute Chef. This has - various [configuration template variables](/docs/templates/configuration-templates.html) - available. See below for more information. +- `execute_command` (string) - The command used to execute Chef. This has + various [configuration template + variables](/docs/templates/configuration-templates.html) available. See below + for more information. -* `install_command` (string) - The command used to install Chef. This has - various [configuration template variables](/docs/templates/configuration-templates.html) - available. See below for more information. +- `install_command` (string) - The command used to install Chef. This has + various [configuration template + variables](/docs/templates/configuration-templates.html) available. See below + for more information. -* `json` (object) - An arbitrary mapping of JSON that will be available as - node attributes while running Chef. +- `json` (object) - An arbitrary mapping of JSON that will be available as node + attributes while running Chef. -* `prevent_sudo` (boolean) - By default, the configured commands that are +- `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 +- `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. +- `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. -* `run_list` (array of strings) - The [run list](https://docs.chef.io/run_lists.html) - for Chef. By default this is empty. +- `run_list` (array of strings) - The [run + list](https://docs.chef.io/run_lists.html) for Chef. By default this is empty. -* `skip_install` (boolean) - If true, Chef will not automatically be installed +- `skip_install` (boolean) - If true, Chef will not automatically be installed on the machine using the Chef omnibus installers. -* `staging_directory` (string) - This is the directory where all the configuration - of Chef by Packer will be placed. By default this is "/tmp/packer-chef-solo". - This directory doesn't need to exist but must have proper permissions so that - the SSH user that Packer uses is able to create directories and write into - this folder. If the permissions are not correct, use a shell provisioner - prior to this to configure it properly. +- `staging_directory` (string) - This is the directory where all the + configuration of Chef by Packer will be placed. By default this + is "/tmp/packer-chef-solo". This directory doesn't need to exist but must have + proper permissions so that the SSH user that Packer uses is able to create + directories and write into this folder. If the permissions are not correct, + use a shell provisioner prior to this to configure it properly. ## Chef Configuration -By default, Packer uses a simple Chef configuration file in order to set -the options specified for the provisioner. But Chef is a complex tool that -supports many configuration options. Packer allows you to specify a custom -configuration template if you'd like to set custom configurations. +By default, Packer uses a simple Chef configuration file in order to set the +options specified for the provisioner. But Chef is a complex tool that supports +many configuration options. Packer allows you to specify a custom configuration +template if you'd like to set custom configurations. The default value for the configuration template is: -```liquid +``` {.liquid} cookbook_path [{{.CookbookPaths}}] ``` -This template is a [configuration template](/docs/templates/configuration-templates.html) -and has a set of variables available to use: +This template is a [configuration +template](/docs/templates/configuration-templates.html) and has a set of +variables available to use: -* `ChefEnvironment` - The current enabled environment. Only non-empty - if the environment path is set. -* `CookbookPaths` is the set of cookbook paths ready to embedded directly - into a Ruby array to configure Chef. -* `DataBagsPath` is the path to the data bags folder. -* `EncryptedDataBagSecretPath` - The path to the encrypted data bag secret -* `EnvironmentsPath` - The path to the environments folder. -* `RolesPath` - The path to the roles folder. +- `ChefEnvironment` - The current enabled environment. Only non-empty if the + environment path is set. +- `CookbookPaths` is the set of cookbook paths ready to embedded directly into a + Ruby array to configure Chef. +- `DataBagsPath` is the path to the data bags folder. +- `EncryptedDataBagSecretPath` - The path to the encrypted data bag secret +- `EnvironmentsPath` - The path to the environments folder. +- `RolesPath` - The path to the roles folder. ## Execute Command -By default, Packer uses the following command (broken across multiple lines -for readability) to execute Chef: +By default, Packer uses the following command (broken across multiple lines for +readability) to execute Chef: -```liquid +``` {.liquid} {{if .Sudo}}sudo {{end}}chef-solo \ --no-color \ -c {{.ConfigPath}} \ -j {{.JsonPath}} ``` -This command can be customized using the `execute_command` configuration. -As you can see from the default value above, the value of this configuration -can contain various template variables, defined below: +This command can be customized using the `execute_command` configuration. As you +can see from the default value above, the value of this configuration can +contain various template variables, defined below: -* `ConfigPath` - The path to the Chef configuration file. - file. -* `JsonPath` - The path to the JSON attributes file for the node. -* `Sudo` - A boolean of whether to `sudo` the command or not, depending on - the value of the `prevent_sudo` configuration. +- `ConfigPath` - The path to the Chef configuration file. file. +- `JsonPath` - The path to the JSON attributes file for the node. +- `Sudo` - A boolean of whether to `sudo` the command or not, depending on the + value of the `prevent_sudo` configuration. ## Install Command -By default, Packer uses the following command (broken across multiple lines -for readability) to install Chef. This command can be customized if you want -to install Chef in another way. +By default, Packer uses the following command (broken across multiple lines for +readability) to install Chef. This command can be customized if you want to +install Chef in another way. -```text +``` {.text} curl -L https://www.chef.io/chef/install.sh | \ {{if .Sudo}}sudo{{end}} bash ``` diff --git a/website/source/docs/provisioners/custom.html.markdown b/website/source/docs/provisioners/custom.html.markdown index 08df184fd..673ff3441 100644 --- a/website/source/docs/provisioners/custom.html.markdown +++ b/website/source/docs/provisioners/custom.html.markdown @@ -1,13 +1,16 @@ --- -layout: "docs" -page_title: "Custom Provisioner" -description: |- - Packer is extensible, allowing you to write new provisioners without having to modify the core source code of Packer itself. Documentation for creating new provisioners is covered in the custom provisioners page of the Packer plugin section. ---- +description: | + Packer is extensible, allowing you to write new provisioners without having to + modify the core source code of Packer itself. Documentation for creating new + provisioners is covered in the custom provisioners page of the Packer plugin + section. +layout: docs +page_title: Custom Provisioner +... # Custom Provisioner Packer is extensible, allowing you to write new provisioners without having to -modify the core source code of Packer itself. Documentation for creating -new provisioners is covered in the [custom provisioners](/docs/extend/provisioner.html) -page of the Packer plugin section. +modify the core source code of Packer itself. Documentation for creating new +provisioners is covered in the [custom +provisioners](/docs/extend/provisioner.html) page of the Packer plugin section. diff --git a/website/source/docs/provisioners/file.html.markdown b/website/source/docs/provisioners/file.html.markdown index 19fcce9be..3439b4dd6 100644 --- a/website/source/docs/provisioners/file.html.markdown +++ b/website/source/docs/provisioners/file.html.markdown @@ -1,24 +1,26 @@ --- -layout: "docs" -page_title: "File Provisioner" -description: |- - The file Packer provisioner uploads files to machines built by Packer. The recommended usage of the file provisioner is to use it to upload files, and then use shell provisioner to move them to the proper place, set permissions, etc. ---- +description: | + The file Packer provisioner uploads files to machines built by Packer. The + recommended usage of the file provisioner is to use it to upload files, and then + use shell provisioner to move them to the proper place, set permissions, etc. +layout: docs +page_title: File Provisioner +... # File Provisioner Type: `file` The file Packer provisioner uploads files to machines built by Packer. The -recommended usage of the file provisioner is to use it to upload files, -and then use [shell provisioner](/docs/provisioners/shell.html) to move -them to the proper place, set permissions, etc. +recommended usage of the file provisioner is to use it to upload files, and then +use [shell provisioner](/docs/provisioners/shell.html) to move them to the +proper place, set permissions, etc. The file provisioner can upload both single files and complete directories. ## Basic Example -```javascript +``` {.javascript} { "type": "file", "source": "app.tar.gz", @@ -30,42 +32,42 @@ The file provisioner can upload both single files and complete directories. The available configuration options are listed below. All elements are required. -* `source` (string) - The path to a local file or directory to upload to the - machine. The path can be absolute or relative. If it is relative, it is +- `source` (string) - The path to a local file or directory to upload to + the machine. The path can be absolute or relative. If it is relative, it is relative to the working directory when Packer is executed. If this is a directory, the existence of a trailing slash is important. Read below on uploading directories. -* `destination` (string) - The path where the file will be uploaded to in the - machine. This value must be a writable location and any parent directories +- `destination` (string) - The path where the file will be uploaded to in + the machine. This value must be a writable location and any parent directories must already exist. -* `direction` (string) - The direction of the file transfer. This defaults - to "upload." If it is set to "download" then the file "source" in - the machine wll be downloaded locally to "destination" +- `direction` (string) - The direction of the file transfer. This defaults to + "upload." If it is set to "download" then the file "source" in the machine wll + be downloaded locally to "destination" ## Directory Uploads -The file provisioner is also able to upload a complete directory to the -remote machine. When uploading a directory, there are a few important things -you should know. +The file provisioner is also able to upload a complete directory to the remote +machine. When uploading a directory, there are a few important things you should +know. -First, the destination directory must already exist. If you need to -create it, use a shell provisioner just prior to the file provisioner -in order to create the directory. +First, the destination directory must already exist. If you need to create it, +use a shell provisioner just prior to the file provisioner in order to create +the directory. Next, the existence of a trailing slash on the source path will determine -whether the directory name will be embedded within the destination, or -whether the destination will be created. An example explains this best: +whether the directory name will be embedded within the destination, or whether +the destination will be created. An example explains this best: -If the source is `/foo` (no trailing slash), and the destination is -`/tmp`, then the contents of `/foo` on the local machine will be uploaded -to `/tmp/foo` on the remote machine. The `foo` directory on the remote -machine will be created by Packer. +If the source is `/foo` (no trailing slash), and the destination is `/tmp`, then +the contents of `/foo` on the local machine will be uploaded to `/tmp/foo` on +the remote machine. The `foo` directory on the remote machine will be created by +Packer. -If the source, however, is `/foo/` (a trailing slash is present), and -the destination is `/tmp`, then the contents of `/foo` will be uploaded -into `/tmp` directly. +If the source, however, is `/foo/` (a trailing slash is present), and the +destination is `/tmp`, then the contents of `/foo` will be uploaded into `/tmp` +directly. -This behavior was adopted from the standard behavior of rsync. Note that -under the covers, rsync may or may not be used. +This behavior was adopted from the standard behavior of rsync. Note that under +the covers, rsync may or may not be used. diff --git a/website/source/docs/provisioners/powershell.html.markdown b/website/source/docs/provisioners/powershell.html.markdown index 69cb90b9a..ebc56ec4c 100644 --- a/website/source/docs/provisioners/powershell.html.markdown +++ b/website/source/docs/provisioners/powershell.html.markdown @@ -1,9 +1,11 @@ --- -layout: "docs" -page_title: "PowerShell Provisioner" -description: |- - The shell Packer provisioner provisions machines built by Packer using shell scripts. Shell provisioning is the easiest way to get software installed and configured on a machine. ---- +description: | + The shell Packer provisioner provisions machines built by Packer using shell + scripts. Shell provisioning is the easiest way to get software installed and + configured on a machine. +layout: docs +page_title: PowerShell Provisioner +... # PowerShell Provisioner @@ -16,7 +18,7 @@ It assumes that the communicator in use is WinRM. The example below is fully functional. -```javascript +``` {.javascript} { "type": "powershell", "inline": ["dir c:\\"] @@ -28,55 +30,54 @@ The example below is fully functional. The reference of available configuration options is listed below. The only required element is either "inline" or "script". Every other option is optional. -Exactly _one_ of the following is required: +Exactly *one* of the following is required: -* `inline` (array of strings) - This is an array of commands to execute. - The commands are concatenated by newlines and turned into a single file, - so they are all executed within the same context. This allows you to - change directories in one command and use something in the directory in - the next and so on. Inline scripts are the easiest way to pull off simple - tasks within the machine. +- `inline` (array of strings) - This is an array of commands to execute. The + commands are concatenated by newlines and turned into a single file, so they + are all executed within the same context. This allows you to change + directories in one command and use something in the directory in the next and + so on. Inline scripts are the easiest way to pull off simple tasks within + the machine. -* `script` (string) - The path to a script to upload and execute in the machine. - This path can be absolute or relative. If it is relative, it is relative - to the working directory when Packer is executed. +- `script` (string) - The path to a script to upload and execute in the machine. + This path can be absolute or relative. If it is relative, it is relative to + the working directory when Packer is executed. -* `scripts` (array of strings) - An array of scripts to execute. The scripts +- `scripts` (array of strings) - An array of scripts to execute. The scripts will be uploaded and executed in the order specified. Each script is executed in isolation, so state such as variables from one script won't carry on to the next. Optional parameters: -* `binary` (boolean) - If true, specifies that the script(s) are binary - files, and Packer should therefore not convert Windows line endings to - Unix line endings (if there are any). By default this is false. +- `binary` (boolean) - If true, specifies that the script(s) are binary files, + and Packer should therefore not convert Windows line endings to Unix line + endings (if there are any). By default this is false. -* `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. +- `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. -* `execute_command` (string) - The command to use to execute the script. - By default this is `powershell "& { {{.Vars}}{{.Path}}; exit $LastExitCode}"`. - The value of this is treated as [configuration template](/docs/templates/configuration-templates.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. +- `execute_command` (string) - The command to use to execute the script. By + default this is `powershell "& { {{.Vars}}{{.Path}}; exit $LastExitCode}"`. + The value of this is treated as [configuration + template](/docs/templates/configuration-templates.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. -* `elevated_user` and `elevated_password` (string) - If specified, - the PowerShell script will be run with elevated privileges using - the given Windows user. +- `elevated_user` and `elevated_password` (string) - If specified, the + PowerShell script will be run with elevated privileges using the given + Windows user. -* `remote_path` (string) - The path where the script will be uploaded to - in the machine. This defaults to "/tmp/script.sh". This value must be - a writable location and any parent directories must already exist. +- `remote_path` (string) - The path where the script will be uploaded to in + the machine. This defaults to "/tmp/script.sh". This value must be a writable + location and any parent directories must already exist. -* `start_retry_timeout` (string) - The amount of time to attempt to - _start_ the remote process. By default this is "5m" or 5 minutes. This - setting exists in order to deal with times when SSH may restart, such as - a system reboot. Set this to a higher value if reboots take a longer - amount of time. +- `start_retry_timeout` (string) - The amount of time to attempt to *start* the + remote process. By default this is "5m" or 5 minutes. This setting exists in + order to deal with times when SSH may restart, such as a system reboot. Set + this to a higher value if reboots take a longer amount of time. -* `valid_exit_codes` (list of ints) - Valid exit codes for the script. - By default this is just 0. +- `valid_exit_codes` (list of ints) - Valid exit codes for the script. By + default this is just 0. diff --git a/website/source/docs/provisioners/puppet-masterless.html.markdown b/website/source/docs/provisioners/puppet-masterless.html.markdown index 8fd05e4f2..ac5f4f628 100644 --- a/website/source/docs/provisioners/puppet-masterless.html.markdown +++ b/website/source/docs/provisioners/puppet-masterless.html.markdown @@ -1,33 +1,38 @@ --- -layout: "docs" -page_title: "Puppet (Masterless) Provisioner" -description: |- - The masterless Puppet Packer provisioner configures Puppet to run on the machines by Packer from local modules and manifest files. Modules and manifests can be uploaded from your local machine to the remote machine or can simply use remote paths (perhaps obtained using something like the shell provisioner). Puppet is run in masterless mode, meaning it never communicates to a Puppet master. ---- +description: | + The masterless Puppet Packer provisioner configures Puppet to run on the + machines by Packer from local modules and manifest files. Modules and manifests + can be uploaded from your local machine to the remote machine or can simply use + remote paths (perhaps obtained using something like the shell provisioner). + Puppet is run in masterless mode, meaning it never communicates to a Puppet + master. +layout: docs +page_title: 'Puppet (Masterless) Provisioner' +... # Puppet (Masterless) Provisioner Type: `puppet-masterless` -The masterless Puppet Packer provisioner configures Puppet to run on the machines -by Packer from local modules and manifest files. Modules and manifests -can be uploaded from your local machine to the remote machine or can simply -use remote paths (perhaps obtained using something like the shell provisioner). +The masterless Puppet Packer provisioner configures Puppet to run on the +machines by Packer from local modules and manifest files. Modules and manifests +can be uploaded from your local machine to the remote machine or can simply use +remote paths (perhaps obtained using something like the shell provisioner). Puppet is run in masterless mode, meaning it never communicates to a Puppet master. --> **Note:** Puppet will _not_ be installed automatically -by this provisioner. This provisioner expects that Puppet is already -installed on the machine. It is common practice to use the -[shell provisioner](/docs/provisioners/shell.html) before the -Puppet provisioner to do this. +-> **Note:** Puppet will *not* be installed automatically by this +provisioner. This provisioner expects that Puppet is already installed on the +machine. It is common practice to use the [shell +provisioner](/docs/provisioners/shell.html) before the Puppet provisioner to do +this. ## Basic Example -The example below is fully functional and expects the configured manifest -file to exist relative to your working directory: +The example below is fully functional and expects the configured manifest file +to exist relative to your working directory: -```javascript +``` {.javascript} { "type": "puppet-masterless", "manifest_file": "site.pp" @@ -40,63 +45,66 @@ The reference of available configuration options is listed below. Required parameters: -* `manifest_file` (string) - This is either a path to a puppet manifest (`.pp` - file) _or_ a directory containing multiple manifests that puppet will apply - (the ["main manifest"][1]). These file(s) must exist on your local system and - will be uploaded to the remote machine. - - [1]: https://docs.puppetlabs.com/puppet/latest/reference/dirs_manifest.html +- `manifest_file` (string) - This is either a path to a puppet manifest + (`.pp` file) *or* a directory containing multiple manifests that puppet will + apply (the ["main + manifest"](https://docs.puppetlabs.com/puppet/latest/reference/dirs_manifest.html)). + These file(s) must exist on your local system and will be uploaded to the + remote machine. Optional parameters: -* `execute_command` (string) - The command used to execute Puppet. This has - various [configuration template variables](/docs/templates/configuration-templates.html) - available. See below for more information. +- `execute_command` (string) - The command used to execute Puppet. This has + various [configuration template + variables](/docs/templates/configuration-templates.html) available. See below + for more information. -* `facter` (object of key/value strings) - Additional +- `facter` (object of key/value strings) - Additional [facts](http://puppetlabs.com/puppet/related-projects/facter) to make available when Puppet is running. -* `hiera_config_path` (string) - The path to a local file with hiera +- `hiera_config_path` (string) - The path to a local file with hiera configuration to be uploaded to the remote machine. Hiera data directories must be uploaded using the file provisioner separately. -* `manifest_dir` (string) - The path to a local directory with manifests - to be uploaded to the remote machine. This is useful if your main - manifest file uses imports. This directory doesn't necessarily contain - the `manifest_file`. It is a separate directory that will be set as - the "manifestdir" setting on Puppet. +- `manifest_dir` (string) - The path to a local directory with manifests to be + uploaded to the remote machine. This is useful if your main manifest file + uses imports. This directory doesn't necessarily contain the `manifest_file`. + It is a separate directory that will be set as the "manifestdir" setting + on Puppet. - ~> `manifest_dir` is passed to `puppet apply` as the `--manifestdir` option. - This option was deprecated in puppet 3.6, and removed in puppet 4.0. If you - have multiple manifests you should use `manifest_file` instead. + \~> `manifest_dir` is passed to `puppet apply` as the + `--manifestdir` option. This option was deprecated in puppet 3.6, and removed + in puppet 4.0. If you have multiple manifests you should use + `manifest_file` instead. -* `module_paths` (array of strings) - This is an array of paths to module - directories on your local filesystem. These will be uploaded to the remote - machine. By default, this is empty. +- `module_paths` (array of strings) - This is an array of paths to module + directories on your local filesystem. These will be uploaded to the + remote machine. By default, this is empty. -* `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. +- `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-masterless". - This directory doesn't need to exist but must have proper permissions so that - the SSH user that Packer uses is able to create directories and write into - this folder. If the permissions are not correct, use a shell provisioner - prior to this to configure it properly. +- `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-masterless". This directory doesn't need to exist but + must have proper permissions so that the SSH user that Packer uses is able to + create directories and write into this folder. If the permissions are not + correct, use a shell provisioner prior to this to configure it properly. -* `working_directory` (string) - This is the directory from which the puppet command - will be run. When using hiera with a relative path, this option allows to ensure - that the paths are working properly. If not specified, defaults to the value of - specified `staging_directory` (or its default value if not specified either). +- `working_directory` (string) - This is the directory from which the puppet + command will be run. When using hiera with a relative path, this option allows + to ensure that the paths are working properly. If not specified, defaults to + the value of specified `staging_directory` (or its default value if not + specified either). ## Execute Command -By default, Packer uses the following command (broken across multiple lines -for readability) to execute Puppet: +By default, Packer uses the following command (broken across multiple lines for +readability) to execute Puppet: -```liquid +``` {.liquid} cd {{.WorkingDir}} && \ {{.FacterVars}}{{if .Sudo}} sudo -E {{end}}puppet apply \ --verbose \ @@ -107,19 +115,19 @@ cd {{.WorkingDir}} && \ {{.ManifestFile}} ``` -This command can be customized using the `execute_command` configuration. -As you can see from the default value above, the value of this configuration -can contain various template variables, defined below: +This command can be customized using the `execute_command` configuration. As you +can see from the default value above, the value of this configuration can +contain various template variables, defined below: -* `WorkingDir` - The path from which Puppet will be executed. -* `FacterVars` - Shell-friendly string of environmental variables used - to set custom facts configured for this provisioner. -* `HieraConfigPath` - The path to a hiera configuration file. -* `ManifestFile` - The path on the remote machine to the manifest file - for Puppet to use. -* `ModulePath` - The paths to the module directories. -* `Sudo` - A boolean of whether to `sudo` the command or not, depending on - the value of the `prevent_sudo` configuration. +- `WorkingDir` - The path from which Puppet will be executed. +- `FacterVars` - Shell-friendly string of environmental variables used to set + custom facts configured for this provisioner. +- `HieraConfigPath` - The path to a hiera configuration file. +- `ManifestFile` - The path on the remote machine to the manifest file for + Puppet to use. +- `ModulePath` - The paths to the module directories. +- `Sudo` - A boolean of whether to `sudo` the command or not, depending on the + value of the `prevent_sudo` configuration. ## Default Facts @@ -127,10 +135,10 @@ In addition to being able to specify custom Facter facts using the `facter` configuration, the provisioner automatically defines certain commonly useful facts: -* `packer_build_name` is set to the name of the build that Packer is running. +- `packer_build_name` is set to the name of the build that Packer is running. This is most useful when Packer is making multiple builds and you want to distinguish them in your Hiera hierarchy. -* `packer_builder_type` is the type of the builder that was used to create the +- `packer_builder_type` is the type of the builder that was used to create the machine that Puppet is running on. This is useful if you want to run only certain parts of your Puppet code on systems built with certain builders. diff --git a/website/source/docs/provisioners/puppet-server.html.markdown b/website/source/docs/provisioners/puppet-server.html.markdown index 803ae22cf..32bcadbe8 100644 --- a/website/source/docs/provisioners/puppet-server.html.markdown +++ b/website/source/docs/provisioners/puppet-server.html.markdown @@ -1,29 +1,30 @@ --- -layout: "docs" -page_title: "Puppet Server Provisioner" -description: |- - The `puppet-server` Packer provisioner provisions Packer machines with Puppet by connecting to a Puppet master. ---- +description: | + The `puppet-server` Packer provisioner provisions Packer machines with Puppet by + connecting to a Puppet master. +layout: docs +page_title: Puppet Server Provisioner +... # Puppet Server Provisioner Type: `puppet-server` -The `puppet-server` Packer provisioner provisions Packer machines with Puppet -by connecting to a Puppet master. +The `puppet-server` Packer provisioner provisions Packer machines with Puppet by +connecting to a Puppet master. --> **Note:** Puppet will _not_ be installed automatically -by this provisioner. This provisioner expects that Puppet is already -installed on the machine. It is common practice to use the -[shell provisioner](/docs/provisioners/shell.html) before the -Puppet provisioner to do this. +-> **Note:** Puppet will *not* be installed automatically by this +provisioner. This provisioner expects that Puppet is already installed on the +machine. It is common practice to use the [shell +provisioner](/docs/provisioners/shell.html) before the Puppet provisioner to do +this. ## Basic Example -The example below is fully functional and expects a Puppet server to be accessible -from your network.: +The example below is fully functional and expects a Puppet server to be +accessible from your network.: -```javascript +``` {.javascript} { "type": "puppet-server", "options": "--test --pluginsync", @@ -37,39 +38,39 @@ from your network.: The reference of available configuration options is listed below. -The provisioner takes various options. None are strictly -required. They are listed below: +The provisioner takes various options. None are strictly required. They are +listed below: -* `client_cert_path` (string) - Path to the client certificate for the - node on your disk. This defaults to nothing, in which case a client - cert won't be uploaded. +- `client_cert_path` (string) - Path to the client certificate for the node on + your disk. This defaults to nothing, in which case a client cert won't + be uploaded. -* `client_private_key_path` (string) - Path to the client private key for - the node on your disk. This defaults to nothing, in which case a client - private key won't be uploaded. +- `client_private_key_path` (string) - Path to the client private key for the + node on your disk. This defaults to nothing, in which case a client private + key won't be uploaded. -* `facter` (object of key/value strings) - Additional Facter facts to make available to the - Puppet run. +- `facter` (object of key/value strings) - Additional Facter facts to make + available to the Puppet run. -* `ignore_exit_codes` (boolean) - If true, Packer will never consider the +- `ignore_exit_codes` (boolean) - If true, Packer will never consider the provisioner a failure. -* `options` (string) - Additional command line options to pass - to `puppet agent` when Puppet is ran. +- `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. +- `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_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. +- `puppet_server` (string) - Hostname of the Puppet server. By default "puppet" + will be used. -* `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 - the SSH user that Packer uses is able to create directories and write into - this folder. If the permissions are not correct, use a shell provisioner - prior to this to configure it properly. +- `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 the SSH user that Packer uses is able to + create directories and write into this folder. If the permissions are not + correct, use a shell provisioner prior to this to configure it properly. diff --git a/website/source/docs/provisioners/salt-masterless.html.markdown b/website/source/docs/provisioners/salt-masterless.html.markdown index a298bb28d..cc1ab1f7b 100644 --- a/website/source/docs/provisioners/salt-masterless.html.markdown +++ b/website/source/docs/provisioners/salt-masterless.html.markdown @@ -1,22 +1,23 @@ --- -layout: "docs" -page_title: "Salt (Masterless) Provisioner" -description: |- - The `salt-masterless` Packer provisioner provisions machines built by Packer using Salt states, without connecting to a Salt master. ---- +description: | + The `salt-masterless` Packer provisioner provisions machines built by Packer + using Salt states, without connecting to a Salt master. +layout: docs +page_title: 'Salt (Masterless) Provisioner' +... # Salt Masterless Provisioner Type: `salt-masterless` -The `salt-masterless` Packer provisioner provisions machines built by Packer using -[Salt](http://saltstack.com/) states, without connecting to a Salt master. +The `salt-masterless` Packer provisioner provisions machines built by Packer +using [Salt](http://saltstack.com/) states, without connecting to a Salt master. ## Basic Example The example below is fully functional. -```javascript +``` {.javascript} { "type": "salt-masterless", "local_state_tree": "/Users/me/salt" @@ -25,31 +26,33 @@ The example below is fully functional. ## Configuration Reference -The reference of available configuration options is listed below. The only required argument is the path to your local salt state tree. +The reference of available configuration options is listed below. The only +required argument is the path to your local salt state tree. Optional: -* `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) +- `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). +- `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). +- `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. +- `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. +- `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`. +- `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/provisioners/shell.html.markdown b/website/source/docs/provisioners/shell.html.markdown index dec270841..97015a847 100644 --- a/website/source/docs/provisioners/shell.html.markdown +++ b/website/source/docs/provisioners/shell.html.markdown @@ -1,27 +1,29 @@ --- -layout: "docs" -page_title: "Shell Provisioner" -description: |- - The shell Packer provisioner provisions machines built by Packer using shell scripts. Shell provisioning is the easiest way to get software installed and configured on a machine. ---- +description: | + The shell Packer provisioner provisions machines built by Packer using shell + scripts. Shell provisioning is the easiest way to get software installed and + configured on a machine. +layout: docs +page_title: Shell Provisioner +... # Shell Provisioner Type: `shell` -The shell Packer provisioner provisions machines built by Packer using shell scripts. -Shell provisioning is the easiest way to get software installed and configured -on a machine. +The shell Packer provisioner provisions machines built by Packer using shell +scripts. Shell provisioning is the easiest way to get software installed and +configured on a machine. --> **Building Windows images?** You probably want to use the -[PowerShell](/docs/provisioners/powershell.html) or -[Windows Shell](/docs/provisioners/windows-shell.html) provisioners. +-> **Building Windows images?** You probably want to use the +[PowerShell](/docs/provisioners/powershell.html) or [Windows +Shell](/docs/provisioners/windows-shell.html) provisioners. ## Basic Example The example below is fully functional. -```javascript +``` {.javascript} { "type": "shell", "inline": ["echo foo"] @@ -33,83 +35,82 @@ The example below is fully functional. The reference of available configuration options is listed below. The only required element is either "inline" or "script". Every other option is optional. -Exactly _one_ of the following is required: +Exactly *one* of the following is required: -* `inline` (array of strings) - This is an array of commands to execute. - The commands are concatenated by newlines and turned into a single file, - so they are all executed within the same context. This allows you to - change directories in one command and use something in the directory in - the next and so on. Inline scripts are the easiest way to pull off simple - tasks within the machine. +- `inline` (array of strings) - This is an array of commands to execute. The + commands are concatenated by newlines and turned into a single file, so they + are all executed within the same context. This allows you to change + directories in one command and use something in the directory in the next and + so on. Inline scripts are the easiest way to pull off simple tasks within + the machine. -* `script` (string) - The path to a script to upload and execute in the machine. - This path can be absolute or relative. If it is relative, it is relative - to the working directory when Packer is executed. +- `script` (string) - The path to a script to upload and execute in the machine. + This path can be absolute or relative. If it is relative, it is relative to + the working directory when Packer is executed. -* `scripts` (array of strings) - An array of scripts to execute. The scripts +- `scripts` (array of strings) - An array of scripts to execute. The scripts will be uploaded and executed in the order specified. Each script is executed in isolation, so state such as variables from one script won't carry on to the next. Optional parameters: -* `binary` (boolean) - If true, specifies that the script(s) are binary - files, and Packer should therefore not convert Windows line endings to - Unix line endings (if there are any). By default this is false. +- `binary` (boolean) - If true, specifies that the script(s) are binary files, + and Packer should therefore not convert Windows line endings to Unix line + endings (if there are any). By default this is false. -* `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. +- `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. -* `execute_command` (string) - The command to use to execute the script. - By default this is `chmod +x {{ .Path }}; {{ .Vars }} {{ .Path }}`. The value of this is - treated as [configuration template](/docs/templates/configuration-templates.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. +- `execute_command` (string) - The command to use to execute the script. By + default this is `chmod +x {{ .Path }}; {{ .Vars }} {{ .Path }}`. The value of + this is treated as [configuration + template](/docs/templates/configuration-templates.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. -* `inline_shebang` (string) - The +- `inline_shebang` (string) - The [shebang](http://en.wikipedia.org/wiki/Shebang_%28Unix%29) value to use when - running commands specified by `inline`. By default, this is `/bin/sh -e`. - If you're not using `inline`, then this configuration has no effect. - **Important:** If you customize this, be sure to include something like - the `-e` flag, otherwise individual steps failing won't fail the provisioner. + running commands specified by `inline`. By default, this is `/bin/sh -e`. If + you're not using `inline`, then this configuration has no effect. + **Important:** If you customize this, be sure to include something like the + `-e` flag, otherwise individual steps failing won't fail the provisioner. -* `remote_path` (string) - The path where the script will be uploaded to - in the machine. This defaults to "/tmp/script.sh". This value must be - a writable location and any parent directories must already exist. +- `remote_path` (string) - The path where the script will be uploaded to in + the machine. This defaults to "/tmp/script.sh". This value must be a writable + location and any parent directories must already exist. -* `start_retry_timeout` (string) - The amount of time to attempt to - _start_ the remote process. By default this is "5m" or 5 minutes. This - setting exists in order to deal with times when SSH may restart, such as - a system reboot. Set this to a higher value if reboots take a longer - amount of time. +- `start_retry_timeout` (string) - The amount of time to attempt to *start* the + remote process. By default this is "5m" or 5 minutes. This setting exists in + order to deal with times when SSH may restart, such as a system reboot. Set + this to a higher value if reboots take a longer amount of time. ## Execute Command Example -To many new users, the `execute_command` is puzzling. However, it provides -an important function: customization of how the command is executed. The -most common use case for this is dealing with **sudo password prompts**. You may -also need to customize this if you use a non-POSIX shell, such as `tcsh` on -FreeBSD. +To many new users, the `execute_command` is puzzling. However, it provides an +important function: customization of how the command is executed. The most +common use case for this is dealing with **sudo password prompts**. You may also +need to customize this if you use a non-POSIX shell, such as `tcsh` on FreeBSD. ### Sudo Example -Some operating systems default to a non-root user. For example if you login -as `ubuntu` and can sudo using the password `packer`, then you'll want to -change `execute_command` to be: +Some operating systems default to a non-root user. For example if you login as +`ubuntu` and can sudo using the password `packer`, then you'll want to change +`execute_command` to be: -```text +``` {.text} "echo 'packer' | {{ .Vars }} sudo -E -S sh '{{ .Path }}'" ``` -The `-S` flag tells `sudo` to read the password from stdin, which in this -case is being piped in with the value of `packer`. The `-E` flag tells `sudo` -to preserve the environment, allowing our environmental variables to work -within the script. +The `-S` flag tells `sudo` to read the password from stdin, which in this case +is being piped in with the value of `packer`. The `-E` flag tells `sudo` to +preserve the environment, allowing our environmental variables to work within +the script. -By setting the `execute_command` to this, your script(s) can run with -root privileges without worrying about password prompts. +By setting the `execute_command` to this, your script(s) can run with root +privileges without worrying about password prompts. ### FreeBSD Example @@ -123,44 +124,44 @@ Note the addition of `env` before `{{ .Vars }}`. ## Default Environmental Variables -In addition to being able to specify custom environmental variables using -the `environment_vars` configuration, the provisioner automatically -defines certain commonly useful environmental variables: +In addition to being able to specify custom environmental variables using the +`environment_vars` configuration, the provisioner automatically defines certain +commonly useful environmental variables: -* `PACKER_BUILD_NAME` is set to the name of the build that Packer is running. +- `PACKER_BUILD_NAME` is set to the name of the build that Packer is running. This is most useful when Packer is making multiple builds and you want to distinguish them slightly from a common provisioning script. -* `PACKER_BUILDER_TYPE` is the type of the builder that was used to create - the machine that the script is running on. This is useful if you want to - run only certain parts of the script on systems built with certain builders. +- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create the + machine that the script is running on. This is useful if you want to run only + certain parts of the script on systems built with certain builders. ## Handling Reboots Provisioning sometimes involves restarts, usually when updating the operating system. Packer is able to tolerate restarts via the shell provisioner. -Packer handles this by retrying to start scripts for a period of time -before failing. This allows time for the machine to start up and be ready -to run scripts. The amount of time the provisioner will wait is configured -using `start_retry_timeout`, which defaults to a few minutes. +Packer handles this by retrying to start scripts for a period of time before +failing. This allows time for the machine to start up and be ready to run +scripts. The amount of time the provisioner will wait is configured using +`start_retry_timeout`, which defaults to a few minutes. -Sometimes, when executing a command like `reboot`, the shell script will -return and Packer will start executing the next one before SSH actually -quits and the machine restarts. For this, put a long `sleep` after the -reboot so that SSH will eventually be killed automatically: +Sometimes, when executing a command like `reboot`, the shell script will return +and Packer will start executing the next one before SSH actually quits and the +machine restarts. For this, put a long `sleep` after the reboot so that SSH will +eventually be killed automatically: -```text +``` {.text} reboot sleep 60 ``` -Some OS configurations don't properly kill all network connections on -reboot, causing the provisioner to hang despite a reboot occurring. -In this case, make sure you shut down the network interfaces -on reboot or in your shell script. For example, on Gentoo: +Some OS configurations don't properly kill all network connections on reboot, +causing the provisioner to hang despite a reboot occurring. In this case, make +sure you shut down the network interfaces on reboot or in your shell script. For +example, on Gentoo: -```text +``` {.text} /etc/init.d/net.eth0 stop ``` @@ -170,59 +171,58 @@ Some provisioning requires connecting to remote SSH servers from within the packer instance. The below example is for pulling code from a private git repository utilizing openssh on the client. Make sure you are running `ssh-agent` and add your git repo ssh keys into it using `ssh-add /path/to/key`. -When the packer instance needs access to the ssh keys the agent will forward -the request back to your `ssh-agent`. +When the packer instance needs access to the ssh keys the agent will forward the +request back to your `ssh-agent`. -Note: when provisioning via git you should add the git server keys into -the `~/.ssh/known_hosts` file otherwise the git command could hang awaiting -input. This can be done by copying the file in via the -[file provisioner](/docs/provisioners/file.html) (more secure) -or using `ssh-keyscan` to populate the file (less secure). An example of the -latter accessing github would be: +Note: when provisioning via git you should add the git server keys into the +`~/.ssh/known_hosts` file otherwise the git command could hang awaiting input. +This can be done by copying the file in via the [file +provisioner](/docs/provisioners/file.html) (more secure) or using `ssh-keyscan` +to populate the file (less secure). An example of the latter accessing github +would be: -``` -{ - "type": "shell", - "inline": [ - "sudo apt-get install -y git", - "ssh-keyscan github.com >> ~/.ssh/known_hosts", - "git clone git@github.com:exampleorg/myprivaterepo.git" - ] -} -``` + { + "type": "shell", + "inline": [ + "sudo apt-get install -y git", + "ssh-keyscan github.com >> ~/.ssh/known_hosts", + "git clone git@github.com:exampleorg/myprivaterepo.git" + ] + } ## Troubleshooting *My shell script doesn't work correctly on Ubuntu* -* On Ubuntu, the `/bin/sh` shell is -[dash](http://en.wikipedia.org/wiki/Debian_Almquist_shell). If your script has -[bash](http://en.wikipedia.org/wiki/Bash_(Unix_shell))-specific commands in it, -then put `#!/bin/bash` at the top of your script. Differences -between dash and bash can be found on the [DashAsBinSh](https://wiki.ubuntu.com/DashAsBinSh) Ubuntu wiki page. +- On Ubuntu, the `/bin/sh` shell is + [dash](http://en.wikipedia.org/wiki/Debian_Almquist_shell). If your script has + [bash](http://en.wikipedia.org/wiki/Bash_(Unix_shell))-specific commands in + it, then put `#!/bin/bash` at the top of your script. Differences between dash + and bash can be found on the + [DashAsBinSh](https://wiki.ubuntu.com/DashAsBinSh) Ubuntu wiki page. *My shell works when I login but fails with the shell provisioner* -* See the above tip. More than likely, your login shell is using `/bin/bash` -while the provisioner is using `/bin/sh`. +- See the above tip. More than likely, your login shell is using `/bin/bash` + while the provisioner is using `/bin/sh`. *My installs hang when using `apt-get` or `yum`* -* Make sure you add a `-y` to the command to prevent it from requiring -user input before proceeding. +- Make sure you add a `-y` to the command to prevent it from requiring user + input before proceeding. *How do I tell what my shell script is doing?* -* Adding a `-x` flag to the shebang at the top of the script (`#!/bin/sh -x`) -will echo the script statements as it is executing. +- Adding a `-x` flag to the shebang at the top of the script (`#!/bin/sh -x`) + will echo the script statements as it is executing. *My builds don't always work the same* -* Some distributions start the SSH daemon before other core services which -can create race conditions. Your first provisioner can tell the machine to -wait until it completely boots. +- Some distributions start the SSH daemon before other core services which can + create race conditions. Your first provisioner can tell the machine to wait + until it completely boots. -```javascript +``` {.javascript} { "type": "shell", "inline": [ "sleep 10" ] diff --git a/website/source/docs/templates/builders.html.markdown b/website/source/docs/templates/builders.html.markdown index 2afb0a95c..594ed59e4 100644 --- a/website/source/docs/templates/builders.html.markdown +++ b/website/source/docs/templates/builders.html.markdown @@ -1,27 +1,28 @@ --- -layout: "docs" -page_title: "Templates: Builders" -description: |- - Within the template, the builders section contains an array of all the builders that Packer should use to generate a machine images for the template. ---- +description: | + Within the template, the builders section contains an array of all the builders + that Packer should use to generate a machine images for the template. +layout: docs +page_title: 'Templates: Builders' +... # Templates: Builders -Within the template, the builders section contains an array of all the -builders that Packer should use to generate a machine images for the template. +Within the template, the builders section contains an array of all the builders +that Packer should use to generate a machine images for the template. -Builders are responsible for creating machines and generating images from -them for various platforms. For example, there are separate builders for -EC2, VMware, VirtualBox, etc. Packer comes with many builders by default, -and can also be extended to add new builders. +Builders are responsible for creating machines and generating images from them +for various platforms. For example, there are separate builders for EC2, VMware, +VirtualBox, etc. Packer comes with many builders by default, and can also be +extended to add new builders. -This documentation page will cover how to configure a builder in a template. -The specific configuration options available for each builder, however, -must be referenced from the documentation for that specific builder. +This documentation page will cover how to configure a builder in a template. The +specific configuration options available for each builder, however, must be +referenced from the documentation for that specific builder. Within a template, a section of builder definitions looks like this: -```javascript +``` {.javascript} { "builders": [ // ... one or more builder definitions here @@ -31,19 +32,19 @@ Within a template, a section of builder definitions looks like this: ## Builder Definition -A single builder definition maps to exactly one [build](/docs/basics/terminology.html#term-build). -A builder definition is a JSON object that requires at least a `type` key. The -`type` is the name of the builder that will be used to create a machine image -for the build. +A single builder definition maps to exactly one +[build](/docs/basics/terminology.html#term-build). A builder definition is a +JSON object that requires at least a `type` key. The `type` is the name of the +builder that will be used to create a machine image for the build. -In addition to the `type`, other keys configure the builder itself. For -example, the AWS builder requires an `access_key`, `secret_key`, and -some other settings. These are placed directly within the builder definition. +In addition to the `type`, other keys configure the builder itself. For example, +the AWS builder requires an `access_key`, `secret_key`, and some other settings. +These are placed directly within the builder definition. -An example builder definition is shown below, in this case configuring -the AWS builder: +An example builder definition is shown below, in this case configuring the AWS +builder: -```javascript +``` {.javascript} { "type": "amazon-ebs", "access_key": "...", @@ -53,23 +54,22 @@ the AWS builder: ## Named Builds -Each build in Packer has a name. By default, the name is just the name -of the builder being used. In general, this is good enough. Names only serve -as an indicator in the output of what is happening. If you want, however, -you can specify a custom name using the `name` key within the builder definition. +Each build in Packer has a name. By default, the name is just the name of the +builder being used. In general, this is good enough. Names only serve as an +indicator in the output of what is happening. If you want, however, you can +specify a custom name using the `name` key within the builder definition. -This is particularly useful if you have multiple builds defined that use -the same underlying builder. In this case, you must specify a name for at least -one of them since the names must be unique. +This is particularly useful if you have multiple builds defined that use the +same underlying builder. In this case, you must specify a name for at least one +of them since the names must be unique. ## Communicators Every build is associated with a single -[communicator](/docs/templates/communicator.html). Communicators are -used to establish a connection for provisioning a remote machine (such -as an AWS instance or local virtual machine). +[communicator](/docs/templates/communicator.html). Communicators are used to +establish a connection for provisioning a remote machine (such as an AWS +instance or local virtual machine). -All the examples for the various builders show some communicator (usually -SSH), but the communicators are highly customizable so we recommend -reading the +All the examples for the various builders show some communicator (usually SSH), +but the communicators are highly customizable so we recommend reading the [communicator documentation](/docs/templates/communicator.html). diff --git a/website/source/docs/templates/configuration-templates.html.markdown b/website/source/docs/templates/configuration-templates.html.markdown index cef1385d3..9bc8f835e 100644 --- a/website/source/docs/templates/configuration-templates.html.markdown +++ b/website/source/docs/templates/configuration-templates.html.markdown @@ -1,40 +1,42 @@ --- -layout: "docs" -page_title: "Configuration Templates" -description: |- - All strings within templates are processed by a common Packer templating engine, where variables and functions can be used to modify the value of a configuration parameter at runtime. ---- +description: | + All strings within templates are processed by a common Packer templating engine, + where variables and functions can be used to modify the value of a configuration + parameter at runtime. +layout: docs +page_title: Configuration Templates +... # Configuration Templates -All strings within templates are processed by a common Packer templating -engine, where variables and functions can be used to modify the value of -a configuration parameter at runtime. +All strings within templates are processed by a common Packer templating engine, +where variables and functions can be used to modify the value of a configuration +parameter at runtime. -For example, the `{{timestamp}}` function can be used in any string to -generate the current timestamp. This is useful for configurations that require -unique keys, such as AMI names. By setting the AMI name to something like +For example, the `{{timestamp}}` function can be used in any string to generate +the current timestamp. This is useful for configurations that require unique +keys, such as AMI names. By setting the AMI name to something like `My Packer AMI {{timestamp}}`, the AMI name will be unique down to the second. -In addition to globally available functions like timestamp shown before, -some configurations have special local variables that are available only -for that configuration. These are recognizable because they're prefixed by -a period, such as `{{.Name}}`. +In addition to globally available functions like timestamp shown before, some +configurations have special local variables that are available only for that +configuration. These are recognizable because they're prefixed by a period, such +as `{{.Name}}`. -The complete syntax is covered in the next section, followed by a reference -of globally available functions. +The complete syntax is covered in the next section, followed by a reference of +globally available functions. ## Syntax -The syntax of templates is extremely simple. Anything template related -happens within double-braces: `{{ }}`. Variables are prefixed with a period -and capitalized, such as `{{.Variable}}` and functions are just directly -within the braces, such as `{{timestamp}}`. +The syntax of templates is extremely simple. Anything template related happens +within double-braces: `{{ }}`. Variables are prefixed with a period and +capitalized, such as `{{.Variable}}` and functions are just directly within the +braces, such as `{{timestamp}}`. Here is an example from the VMware VMX template that shows configuration templates in action: -```liquid +``` {.liquid} .encoding = "UTF-8" displayName = "{{ .Name }}" guestOS = "{{ .GuestOS }}" @@ -43,7 +45,7 @@ guestOS = "{{ .GuestOS }}" In this case, the "Name" and "GuestOS" variables will be replaced, potentially resulting in a VMX that looks like this: -```liquid +``` {.liquid} .encoding = "UTF-8" displayName = "packer" guestOS = "otherlinux" @@ -52,70 +54,126 @@ guestOS = "otherlinux" ## Global Functions While some configuration settings have local variables specific to only that -configuration, a set of functions are available globally for use in _any string_ +configuration, a set of functions are available globally for use in *any string* in Packer templates. These are listed below for reference. -* `build_name` - The name of the build being run. -* `build_type` - The type of the builder being used currently. -* `isotime [FORMAT]` - UTC time, which can be [formatted](http://golang.org/pkg/time/#example_Time_Format). - See more examples below. -* `lower` - Lowercases the string. -* `pwd` - The working directory while executing Packer. -* `template_dir` - The directory to the template for the build. -* `timestamp` - The current Unix timestamp in UTC. -* `uuid` - Returns a random UUID. -* `upper` - Uppercases the string. +- `build_name` - The name of the build being run. +- `build_type` - The type of the builder being used currently. +- `isotime [FORMAT]` - UTC time, which can be + [formatted](http://golang.org/pkg/time/#example_Time_Format). See more + examples below. +- `lower` - Lowercases the string. +- `pwd` - The working directory while executing Packer. +- `template_dir` - The directory to the template for the build. +- `timestamp` - The current Unix timestamp in UTC. +- `uuid` - Returns a random UUID. +- `upper` - Uppercases the string. ### isotime Format -Formatting for the function `isotime` uses the magic reference date -**Mon Jan 2 15:04:05 -0700 MST 2006**, which breaks down to the following: +Formatting for the function `isotime` uses the magic reference date **Mon Jan 2 +15:04:05 -0700 MST 2006**, which breaks down to the following:
+ - - - - - - - - - + + + + + + + + + - - - - - - - - - + + + + + + + + + - - - - - - - - - + + + + + + + + +
Day of WeekMonthDateHourMinuteSecondYearTimezone + +Day of Week + +Month + +Date + +Hour + +Minute + +Second + +Year + +Timezone +
Numeric-010203 (15)040506-0700 +Numeric + +- + +01 + +02 + +03 (15) + +04 + +05 + +06 + +-0700 +
TextualMonday (Mon)January (Jan)-----MST +Textual + +Monday (Mon) + +January (Jan) + +- + +- + +- + +- + +- + +MST +
+
- _The values in parentheses are the abbreviated, or 24-hour clock values_ +*The values in parentheses are the abbreviated, or 24-hour clock values* - Here are some example formated time, using the above format options: +Here are some example formated time, using the above format options: -```liquid +``` {.liquid} isotime = June 7, 7:22:43pm 2014 {{isotime "2006-01-02"}} = 2014-06-07 @@ -126,7 +184,7 @@ isotime = June 7, 7:22:43pm 2014 Please note that double quote characters need escaping inside of templates: -```javascript +``` {.javascript} { "builders": [ { @@ -147,6 +205,6 @@ Please note that double quote characters need escaping inside of templates: Specific to Amazon builders: -* ``clean_ami_name`` - AMI names can only contain certain characters. This +- `clean_ami_name` - AMI names can only contain certain characters. This function will replace illegal characters with a '-" character. Example usage since ":" is not a legal AMI name is: `{{isotime | clean_ami_name}}`. diff --git a/website/source/docs/templates/introduction.html.markdown b/website/source/docs/templates/introduction.html.markdown index 3dc363916..1d67ea196 100644 --- a/website/source/docs/templates/introduction.html.markdown +++ b/website/source/docs/templates/introduction.html.markdown @@ -1,21 +1,25 @@ --- -layout: "docs" -page_title: "Templates" -description: |- - Templates are JSON files that configure the various components of Packer in order to create one or more machine images. Templates are portable, static, and readable and writable by both humans and computers. This has the added benefit of being able to not only create and modify templates by hand, but also write scripts to dynamically create or modify templates. ---- +description: | + Templates are JSON files that configure the various components of Packer in + order to create one or more machine images. Templates are portable, static, and + readable and writable by both humans and computers. This has the added benefit + of being able to not only create and modify templates by hand, but also write + scripts to dynamically create or modify templates. +layout: docs +page_title: Templates +... # Templates -Templates are JSON files that configure the various components of Packer -in order to create one or more machine images. Templates are portable, static, -and readable and writable by both humans and computers. This has the added -benefit of being able to not only create and modify templates by hand, but -also write scripts to dynamically create or modify templates. +Templates are JSON files that configure the various components of Packer in +order to create one or more machine images. Templates are portable, static, and +readable and writable by both humans and computers. This has the added benefit +of being able to not only create and modify templates by hand, but also write +scripts to dynamically create or modify templates. -Templates are given to commands such as `packer build`, which will -take the template and actually run the builds within it, producing -any resulting machine images. +Templates are given to commands such as `packer build`, which will take the +template and actually run the builds within it, producing any resulting machine +images. ## Template Structure @@ -23,64 +27,64 @@ 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. -* `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). +- `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). -* `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). +- `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 - ensure that proper versions of Packer are used with the template. A - max version can't be specified because Packer retains backwards - compatibility with `packer fix`. +- `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 ensure that proper + versions of Packer are used with the template. A 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). +- `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). +- `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). +- `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). ## Comments JSON doesn't support comments and Packer reports unknown keys as validation -errors. If you'd like to comment your template, you can prefix a _root level_ +errors. If you'd like to comment your template, you can prefix a *root level* key with an underscore. Example: -```javascript +``` {.javascript} { "_comment": "This is a comment", "builders": [{}] } ``` -**Important:** Only _root level_ keys can be underscore prefixed. Keys within +**Important:** Only *root level* keys can be underscore prefixed. Keys within builders, provisioners, etc. will still result in validation errors. ## Example Template -Below is an example of a basic template that is nearly fully functional. It is just -missing valid AWS access keys. Otherwise, it would work properly with +Below is an example of a basic template that is nearly fully functional. It is +just missing valid AWS access keys. Otherwise, it would work properly with `packer build`. -```javascript +``` {.javascript} { "builders": [ { diff --git a/website/source/docs/templates/post-processors.html.markdown b/website/source/docs/templates/post-processors.html.markdown index 7a7ba4664..2c71e6664 100644 --- a/website/source/docs/templates/post-processors.html.markdown +++ b/website/source/docs/templates/post-processors.html.markdown @@ -1,27 +1,30 @@ --- -layout: "docs" -page_title: "Templates: Post-Processors" -description: |- - The post-processor section within a template configures any post-processing that will be done to images built by the builders. Examples of post-processing would be compressing files, uploading artifacts, etc. ---- +description: | + The post-processor section within a template configures any post-processing that + will be done to images built by the builders. Examples of post-processing would + be compressing files, uploading artifacts, etc. +layout: docs +page_title: 'Templates: Post-Processors' +... # Templates: Post-Processors -The post-processor section within a template configures any post-processing -that will be done to images built by the builders. Examples of post-processing -would be compressing files, uploading artifacts, etc. +The post-processor section within a template configures any post-processing that +will be done to images built by the builders. Examples of post-processing would +be compressing files, uploading artifacts, etc. -Post-processors are _optional_. If no post-processors are defined within a template, -then no post-processing will be done to the image. The resulting artifact of -a build is just the image outputted by the builder. +Post-processors are *optional*. If no post-processors are defined within a +template, then no post-processing will be done to the image. The resulting +artifact of a build is just the image outputted by the builder. This documentation page will cover how to configure a post-processor in a template. The specific configuration options available for each post-processor, -however, must be referenced from the documentation for that specific post-processor. +however, must be referenced from the documentation for that specific +post-processor. Within a template, a section of post-processor definitions looks like this: -```javascript +``` {.javascript} { "post-processors": [ // ... one or more post-processor definitions here @@ -38,29 +41,29 @@ apply to, if you wish. ## Post-Processor Definition -Within the `post-processors` array in a template, there are three ways to -define a post-processor. There are _simple_ definitions, _detailed_ definitions, -and _sequence_ definitions. Don't worry, they're all very easy to understand, -and the "simple" and "detailed" definitions are simply shortcuts for the -"sequence" definition. +Within the `post-processors` array in a template, there are three ways to define +a post-processor. There are *simple* definitions, *detailed* definitions, and +*sequence* definitions. Don't worry, they're all very easy to understand, and +the "simple" and "detailed" definitions are simply shortcuts for the "sequence" +definition. A **simple definition** is just a string; the name of the post-processor. An -example is shown below. Simple definitions are used when no additional configuration -is needed for the post-processor. +example is shown below. Simple definitions are used when no additional +configuration is needed for the post-processor. -```javascript +``` {.javascript} { "post-processors": ["compress"] } ``` -A **detailed definition** is a JSON object. It is very similar to a builder -or provisioner definition. It contains a `type` field to denote the type of -the post-processor, but may also contain additional configuration for the -post-processor. A detailed definition is used when additional configuration -is needed beyond simply the type for the post-processor. An example is shown below. +A **detailed definition** is a JSON object. It is very similar to a builder or +provisioner definition. It contains a `type` field to denote the type of the +post-processor, but may also contain additional configuration for the +post-processor. A detailed definition is used when additional configuration is +needed beyond simply the type for the post-processor. An example is shown below. -```javascript +``` {.javascript} { "post-processors": [ { @@ -72,14 +75,14 @@ is needed beyond simply the type for the post-processor. An example is shown bel ``` A **sequence definition** is a JSON array comprised of other **simple** or -**detailed** definitions. The post-processors defined in the array are run -in order, with the artifact of each feeding into the next, and any intermediary +**detailed** definitions. The post-processors defined in the array are run in +order, with the artifact of each feeding into the next, and any intermediary artifacts being discarded. A sequence definition may not contain another sequence definition. Sequence definitions are used to chain together multiple post-processors. An example is shown below, where the artifact of a build is compressed then uploaded, but the compressed result is not kept. -```javascript +``` {.javascript} { "post-processors": [ [ @@ -90,21 +93,21 @@ compressed then uploaded, but the compressed result is not kept. } ``` -As you may be able to imagine, the **simple** and **detailed** definitions -are simply shortcuts for a **sequence** definition of only one element. +As you may be able to imagine, the **simple** and **detailed** definitions are +simply shortcuts for a **sequence** definition of only one element. ## Input Artifacts -When using post-processors, the input artifact (coming from a builder or -another post-processor) is discarded by default after the post-processor runs. -This is because generally, you don't want the intermediary artifacts on the -way to the final artifact created. +When using post-processors, the input artifact (coming from a builder or another +post-processor) is discarded by default after the post-processor runs. This is +because generally, you don't want the intermediary artifacts on the way to the +final artifact created. -In some cases, however, you may want to keep the intermediary artifacts. -You can tell Packer to keep these artifacts by setting the -`keep_input_artifact` configuration to `true`. An example is shown below: +In some cases, however, you may want to keep the intermediary artifacts. You can +tell Packer to keep these artifacts by setting the `keep_input_artifact` +configuration to `true`. An example is shown below: -```javascript +``` {.javascript} { "post-processors": [ { @@ -115,39 +118,37 @@ You can tell Packer to keep these artifacts by setting the } ``` -This setting will only keep the input artifact to _that specific_ -post-processor. If you're specifying a sequence of post-processors, then -all intermediaries are discarded by default except for the input artifacts -to post-processors that explicitly state to keep the input artifact. +This setting will only keep the input artifact to *that specific* +post-processor. If you're specifying a sequence of post-processors, then all +intermediaries are discarded by default except for the input artifacts to +post-processors that explicitly state to keep the input artifact. --> **Note:** The intuitive reader may be wondering what happens -if multiple post-processors are specified (not in a sequence). Does Packer require the -configuration to keep the input artifact on all the post-processors? -The answer is no, of course not. Packer is smart enough to figure out -that at least one post-processor requested that the input be kept, so it will keep -it around. +-> **Note:** The intuitive reader may be wondering what happens if multiple +post-processors are specified (not in a sequence). Does Packer require the +configuration to keep the input artifact on all the post-processors? The answer +is no, of course not. Packer is smart enough to figure out that at least one +post-processor requested that the input be kept, so it will keep it around. ## Run on Specific Builds -You can use the `only` or `except` configurations to run a post-processor -only with specific builds. These two configurations do what you expect: -`only` will only run the post-processor on the specified builds and -`except` will run the post-processor on anything other than the specified -builds. +You can use the `only` or `except` configurations to run a post-processor only +with specific builds. These two configurations do what you expect: `only` will +only run the post-processor on the specified builds and `except` will run the +post-processor on anything other than the specified builds. -An example of `only` being used is shown below, but the usage of `except` -is effectively the same. `only` and `except` can only be specified on "detailed" -configurations. If you have a sequence of post-processors to run, `only` -and `except` will only affect that single post-processor in the sequence. +An example of `only` being used is shown below, but the usage of `except` is +effectively the same. `only` and `except` can only be specified on "detailed" +configurations. If you have a sequence of post-processors to run, `only` and +`except` will only affect that single post-processor in the sequence. -```javascript +``` {.javascript} { "type": "vagrant", "only": ["virtualbox-iso"] } ``` -The values within `only` or `except` are _build names_, not builder -types. If you recall, build names by default are just their builder type, -but if you specify a custom `name` parameter, then you should use that -as the value instead of the type. +The values within `only` or `except` are *build names*, not builder types. If +you recall, build names by default are just their builder type, but if you +specify a custom `name` parameter, then you should use that as the value instead +of the type. diff --git a/website/source/docs/templates/provisioners.html.markdown b/website/source/docs/templates/provisioners.html.markdown index 00578bb86..9f4acc9cb 100644 --- a/website/source/docs/templates/provisioners.html.markdown +++ b/website/source/docs/templates/provisioners.html.markdown @@ -1,9 +1,11 @@ --- -layout: "docs" -page_title: "Templates: Provisioners" -description: |- - Within the template, the provisioners section contains an array of all the provisioners that Packer should use to install and configure software within running machines prior to turning them into machine images. ---- +description: | + Within the template, the provisioners section contains an array of all the + provisioners that Packer should use to install and configure software within + running machines prior to turning them into machine images. +layout: docs +page_title: 'Templates: Provisioners' +... # Templates: Provisioners @@ -11,19 +13,18 @@ Within the template, the provisioners section contains an array of all the provisioners that Packer should use to install and configure software within running machines prior to turning them into machine images. -Provisioners are _optional_. If no provisioners are defined within a template, -then no software other than the defaults will be installed within the -resulting machine images. This is not typical, however, since much of the -value of Packer is to produce multiple identical images -of pre-configured software. +Provisioners are *optional*. If no provisioners are defined within a template, +then no software other than the defaults will be installed within the resulting +machine images. This is not typical, however, since much of the value of Packer +is to produce multiple identical images of pre-configured software. This documentation page will cover how to configure a provisioner in a template. -The specific configuration options available for each provisioner, however, -must be referenced from the documentation for that specific provisioner. +The specific configuration options available for each provisioner, however, must +be referenced from the documentation for that specific provisioner. Within a template, a section of provisioner definitions looks like this: -```javascript +``` {.javascript} { "provisioners": [ // ... one or more provisioner definitions here @@ -31,25 +32,24 @@ Within a template, a section of provisioner definitions looks like this: } ``` -For each of the definitions, Packer will run the provisioner for each -of the configured builds. The provisioners will be run in the order -they are defined within the template. +For each of the definitions, Packer will run the provisioner for each of the +configured builds. The provisioners will be run in the order they are defined +within the template. ## Provisioner Definition -A provisioner definition is a JSON object that must contain at least -the `type` key. This key specifies the name of the provisioner to use. -Additional keys within the object are used to configure the provisioner, -with the exception of a handful of special keys, covered later. +A provisioner definition is a JSON object that must contain at least the `type` +key. This key specifies the name of the provisioner to use. Additional keys +within the object are used to configure the provisioner, with the exception of a +handful of special keys, covered later. -As an example, the "shell" provisioner requires a key such as `script` -which specifies a path to a shell script to execute within the machines -being created. +As an example, the "shell" provisioner requires a key such as `script` which +specifies a path to a shell script to execute within the machines being created. An example provisioner definition is shown below, configuring the shell provisioner to run a local script within the machines: -```javascript +``` {.javascript} { "type": "shell", "script": "script.sh" @@ -58,16 +58,15 @@ provisioner to run a local script within the machines: ## Run on Specific Builds -You can use the `only` or `except` configurations to run a provisioner -only with specific builds. These two configurations do what you expect: -`only` will only run the provisioner on the specified builds and -`except` will run the provisioner on anything other than the specified -builds. +You can use the `only` or `except` configurations to run a provisioner only with +specific builds. These two configurations do what you expect: `only` will only +run the provisioner on the specified builds and `except` will run the +provisioner on anything other than the specified builds. -An example of `only` being used is shown below, but the usage of `except` -is effectively the same: +An example of `only` being used is shown below, but the usage of `except` is +effectively the same: -```javascript +``` {.javascript} { "type": "shell", "script": "script.sh", @@ -75,21 +74,21 @@ is effectively the same: } ``` -The values within `only` or `except` are _build names_, not builder -types. If you recall, build names by default are just their builder type, -but if you specify a custom `name` parameter, then you should use that -as the value instead of the type. +The values within `only` or `except` are *build names*, not builder types. If +you recall, build names by default are just their builder type, but if you +specify a custom `name` parameter, then you should use that as the value instead +of the type. ## Build-Specific Overrides -While the goal of Packer is to produce identical machine images, it -sometimes requires periods of time where the machines are different before -they eventually converge to be identical. In these cases, different configurations -for provisioners may be necessary depending on the build. This can be done -using build-specific overrides. +While the goal of Packer is to produce identical machine images, it sometimes +requires periods of time where the machines are different before they eventually +converge to be identical. In these cases, different configurations for +provisioners may be necessary depending on the build. This can be done using +build-specific overrides. -An example of where this might be necessary is when building both an EC2 AMI -and a VMware machine. The source EC2 AMI may setup a user with administrative +An example of where this might be necessary is when building both an EC2 AMI and +a VMware machine. The source EC2 AMI may setup a user with administrative privileges by default, whereas the VMware machine doesn't have these privileges. In this case, the shell script may need to be executed differently. Of course, the goal is that hopefully the shell script converges these two images to be @@ -97,7 +96,7 @@ identical. However, they may initially need to be run differently. This example is shown below: -```javascript +``` {.javascript} { "type": "shell", "script": "script.sh", @@ -111,24 +110,23 @@ This example is shown below: ``` As you can see, the `override` key is used. The value of this key is another -JSON object where the key is the name of a [builder definition](/docs/templates/builders.html). -The value of this is in turn another JSON object. This JSON object simply -contains the provisioner configuration as normal. This configuration is merged -into the default provisioner configuration. +JSON object where the key is the name of a [builder +definition](/docs/templates/builders.html). The value of this is in turn another +JSON object. This JSON object simply contains the provisioner configuration as +normal. This configuration is merged into the default provisioner configuration. ## Pausing Before Running -With certain provisioners it is sometimes desirable to pause for some period -of time before running it. Specifically, in cases where a provisioner reboots -the machine, you may want to wait for some period of time before starting -the next provisioner. +With certain provisioners it is sometimes desirable to pause for some period of +time before running it. Specifically, in cases where a provisioner reboots the +machine, you may want to wait for some period of time before starting the next +provisioner. Every provisioner definition in a Packer template can take a special -configuration `pause_before` that is the amount of time to pause before -running that provisioner. By default, there is no pause. An example -is shown below: +configuration `pause_before` that is the amount of time to pause before running +that provisioner. By default, there is no pause. An example is shown below: -```javascript +``` {.javascript} { "type": "shell", "script": "script.sh", @@ -136,5 +134,5 @@ is shown below: } ``` -For the above provisioner, Packer will wait 10 seconds before uploading -and executing the shell script. +For the above provisioner, Packer will wait 10 seconds before uploading and +executing the shell script. diff --git a/website/source/docs/templates/push.html.markdown b/website/source/docs/templates/push.html.markdown index 568b45ec1..3ca2c2de2 100644 --- a/website/source/docs/templates/push.html.markdown +++ b/website/source/docs/templates/push.html.markdown @@ -1,19 +1,19 @@ --- -layout: "docs" -page_title: "Templates: Push" -description: |- - Within the template, the push section configures how a template can be - pushed to a remote build service. ---- +description: | + Within the template, the push section configures how a template can be pushed to + a remote build service. +layout: docs +page_title: 'Templates: Push' +... # Templates: Push Within the template, the push section configures how a template can be [pushed](/docs/command-line/push.html) to a remote build service. -Push configuration is responsible for defining what files are required -to build this template, what the name of build configuration is in the -build service, etc. +Push configuration is responsible for defining what files are required to build +this template, what the name of build configuration is in the build service, +etc. The only build service that Packer can currently push to is [Atlas](https://atlas.hashicorp.com) by HashiCorp. Support for other build @@ -21,7 +21,7 @@ services will come in the form of plugins in the future. Within a template, a push configuration section looks like this: -```javascript +``` {.javascript} { "push": { // ... push configuration here @@ -37,37 +37,37 @@ each category, the available configuration keys are alphabetized. ### Required -* `name` (string) - Name of the build configuration in the build service. - If this doesn't exist, it will be created (by default). +- `name` (string) - Name of the build configuration in the build service. If + this doesn't exist, it will be created (by default). ### Optional -* `address` (string) - The address of the build service to use. By default - this is `https://atlas.hashicorp.com`. +- `address` (string) - The address of the build service to use. By default this + is `https://atlas.hashicorp.com`. -* `base_dir` (string) - The base directory of the files to upload. This - will be the current working directory when the build service executes your - template. This path is relative to the template. +- `base_dir` (string) - The base directory of the files to upload. This will be + the current working directory when the build service executes your template. + This path is relative to the template. -* `include` (array of strings) - Glob patterns to include relative to - the `base_dir`. If this is specified, only files that match the include - pattern are included. +- `include` (array of strings) - Glob patterns to include relative to the + `base_dir`. If this is specified, only files that match the include pattern + are included. -* `exclude` (array of strings) - Glob patterns to exclude relative to - the `base_dir`. +- `exclude` (array of strings) - Glob patterns to exclude relative to the + `base_dir`. -* `token` (string) - An access token to use to authenticate to the build - service. +- `token` (string) - An access token to use to authenticate to the + build service. -* `vcs` (boolean) - If true, Packer will detect your VCS (if there is one) - and only upload the files that are tracked by the VCS. This is useful - for automatically excluding ignored files. This defaults to false. +- `vcs` (boolean) - If true, Packer will detect your VCS (if there is one) and + only upload the files that are tracked by the VCS. This is useful for + automatically excluding ignored files. This defaults to false. ## Examples A push configuration section with minimal options: -```javascript +``` {.javascript} { "push": { "name": "hashicorp/precise64" @@ -78,7 +78,7 @@ A push configuration section with minimal options: A push configuration specifying Packer to inspect the VCS and list individual files to include: -```javascript +``` {.javascript} { "push": { "name": "hashicorp/precise64", diff --git a/website/source/docs/templates/user-variables.html.markdown b/website/source/docs/templates/user-variables.html.markdown index d80662dea..30c9555bf 100644 --- a/website/source/docs/templates/user-variables.html.markdown +++ b/website/source/docs/templates/user-variables.html.markdown @@ -1,35 +1,38 @@ --- -layout: "docs" -page_title: "User Variables in Templates" -description: |- - User variables allow your templates to be further configured with variables from the command-line, environmental variables, or files. This lets you parameterize your templates so that you can keep secret tokens, environment-specific data, and other types of information out of your templates. This maximizes the portability and shareability of the template. ---- +description: | + User variables allow your templates to be further configured with variables from + the command-line, environmental variables, or files. This lets you parameterize + your templates so that you can keep secret tokens, environment-specific data, + and other types of information out of your templates. This maximizes the + portability and shareability of the template. +layout: docs +page_title: User Variables in Templates +... # User Variables -User variables allow your templates to be further configured with variables -from the command-line, environmental variables, or files. This lets you -parameterize your templates so that you can keep secret tokens, -environment-specific data, and other types of information out of your -templates. This maximizes the portability and shareability of the template. +User variables allow your templates to be further configured with variables from +the command-line, environmental variables, or files. This lets you parameterize +your templates so that you can keep secret tokens, environment-specific data, +and other types of information out of your templates. This maximizes the +portability and shareability of the template. -Using user variables expects you know how -[configuration templates](/docs/templates/configuration-templates.html) work. -If you don't know how configuration templates work yet, please read that -page first. +Using user variables expects you know how [configuration +templates](/docs/templates/configuration-templates.html) work. If you don't know +how configuration templates work yet, please read that page first. ## Usage User variables must first be defined in a `variables` section within your -template. Even if you want a variable to default to an empty string, it -must be defined. This explicitness makes it easy for newcomers to your -template to understand what can be modified using variables in your template. +template. Even if you want a variable to default to an empty string, it must be +defined. This explicitness makes it easy for newcomers to your template to +understand what can be modified using variables in your template. -The `variables` section is a simple key/value mapping of the variable -name to a default value. A default value can be the empty string. An -example is shown below: +The `variables` section is a simple key/value mapping of the variable name to a +default value. A default value can be the empty string. An example is shown +below: -```javascript +``` {.javascript} { "variables": { "aws_access_key": "", @@ -46,28 +49,27 @@ example is shown below: ``` In the above example, the template defines two variables: `aws_access_key` and -`aws_secret_key`. They default to empty values. -Later, the variables are used within the builder we defined in order to -configure the actual keys for the Amazon builder. +`aws_secret_key`. They default to empty values. Later, the variables are used +within the builder we defined in order to configure the actual keys for the +Amazon builder. -If the default value is `null`, then the user variable will be _required_. -This means that the user must specify a value for this variable or template +If the default value is `null`, then the user variable will be *required*. This +means that the user must specify a value for this variable or template validation will fail. -Using the variables is extremely easy. Variables are used by calling -the user function in the form of {{user `variable`}}. -This function can be used in _any value_ within the template, in -builders, provisioners, _anything_. The user variable is available globally -within the template. +Using the variables is extremely easy. Variables are used by calling the user +function in the form of {{user \`variable\`}}. This function can be +used in *any value* within the template, in builders, provisioners, *anything*. +The user variable is available globally within the template. ## Environmental Variables -Environmental variables can be used within your template using user -variables. The `env` function is available _only_ within the default value -of a user variable, allowing you to default a user variable to an -environmental variable. An example is shown below: +Environmental variables can be used within your template using user variables. +The `env` function is available *only* within the default value of a user +variable, allowing you to default a user variable to an environmental variable. +An example is shown below: -```javascript +``` {.javascript} { "variables": { "my_secret": "{{env `MY_SECRET`}}", @@ -77,73 +79,69 @@ environmental variable. An example is shown below: } ``` -This will default "my\_secret" to be the value of the "MY\_SECRET" -environmental variable (or the empty string if it does not exist). +This will default "my\_secret" to be the value of the "MY\_SECRET" environmental +variable (or the empty string if it does not exist). --> **Why can't I use environmental variables elsewhere?** -User variables are the single source of configurable input to a template. -We felt that having environmental variables used _anywhere_ in a -template would confuse the user about the possible inputs to a template. -By allowing environmental variables only within default values for user -variables, user variables remain as the single source of input to a template -that a user can easily discover using `packer inspect`. +-> **Why can't I use environmental variables elsewhere?** User variables are +the single source of configurable input to a template. We felt that having +environmental variables used *anywhere* in a template would confuse the user +about the possible inputs to a template. By allowing environmental variables +only within default values for user variables, user variables remain as the +single source of input to a template that a user can easily discover using +`packer inspect`. ## Setting Variables -Now that we covered how to define and use variables within a template, -the next important point is how to actually set these variables. Packer -exposes two methods for setting variables: from the command line or -from a file. +Now that we covered how to define and use variables within a template, the next +important point is how to actually set these variables. Packer exposes two +methods for setting variables: from the command line or from a file. ### From the Command Line -To set variables from the command line, the `-var` flag is used as -a parameter to `packer build` (and some other commands). Continuing our example -above, we could build our template using the command below. The command -is split across multiple lines for readability, but can of course be a single -line. +To set variables from the command line, the `-var` flag is used as a parameter +to `packer build` (and some other commands). Continuing our example above, we +could build our template using the command below. The command is split across +multiple lines for readability, but can of course be a single line. -```text +``` {.text} $ packer build \ -var 'aws_access_key=foo' \ -var 'aws_secret_key=bar' \ template.json ``` -As you can see, the `-var` flag can be specified multiple times in order -to set multiple variables. Also, variables set later on the command-line -override earlier set variables if it has already been set. +As you can see, the `-var` flag can be specified multiple times in order to set +multiple variables. Also, variables set later on the command-line override +earlier set variables if it has already been set. -Finally, variables set from the command-line override all other methods -of setting variables. So if you specify a variable in a file (the next -method shown), you can override it using the command-line. +Finally, variables set from the command-line override all other methods of +setting variables. So if you specify a variable in a file (the next method +shown), you can override it using the command-line. ### From a File -Variables can also be set from an external JSON file. The `-var-file` -flag reads a file containing a basic key/value mapping of variables to -values and sets those variables. The JSON file is simple: +Variables can also be set from an external JSON file. The `-var-file` flag reads +a file containing a basic key/value mapping of variables to values and sets +those variables. The JSON file is simple: -```javascript +``` {.javascript} { "aws_access_key": "foo", "aws_secret_key": "bar" } ``` -It is a single JSON object where the keys are variables and the values are -the variable values. Assuming this file is in `variables.json`, we can -build our template using the following command: +It is a single JSON object where the keys are variables and the values are the +variable values. Assuming this file is in `variables.json`, we can build our +template using the following command: -```text +``` {.text} $ packer build -var-file=variables.json template.json ``` -The `-var-file` flag can be specified multiple times and variables from -multiple files will be read and applied. As you'd expect, variables read -from files specified later override a variable set earlier if it has -already been set. +The `-var-file` flag can be specified multiple times and variables from multiple +files will be read and applied. As you'd expect, variables read from files +specified later override a variable set earlier if it has already been set. -And as mentioned above, no matter where a `-var-file` is specified, a -`-var` flag on the command line will always override any variables from -a file. +And as mentioned above, no matter where a `-var-file` is specified, a `-var` +flag on the command line will always override any variables from a file. diff --git a/website/source/docs/templates/veewee-to-packer.html.markdown b/website/source/docs/templates/veewee-to-packer.html.markdown index 81a06de71..ecc257f14 100644 --- a/website/source/docs/templates/veewee-to-packer.html.markdown +++ b/website/source/docs/templates/veewee-to-packer.html.markdown @@ -1,35 +1,39 @@ --- -layout: "docs" -page_title: "Convert Veewee Definitions to Packer Templates" -description: |- - If you are or were a user of Veewee, then there is an official tool called veewee-to-packer that will convert your Veewee definition into an equivalent Packer template. Even if you're not a Veewee user, Veewee has a large library of templates that can be readily used with Packer by simply converting them. ---- +description: | + If you are or were a user of Veewee, then there is an official tool called + veewee-to-packer that will convert your Veewee definition into an equivalent + Packer template. Even if you're not a Veewee user, Veewee has a large library of + templates that can be readily used with Packer by simply converting them. +layout: docs +page_title: Convert Veewee Definitions to Packer Templates +... # Veewee-to-Packer -If you are or were a user of [Veewee](https://github.com/jedi4ever/veewee), -then there is an official tool called [veewee-to-packer](https://github.com/mitchellh/veewee-to-packer) -that will convert your Veewee definition into an equivalent Packer template. -Even if you're not a Veewee user, Veewee has a -[large library](https://github.com/jedi4ever/veewee/tree/master/templates) -of templates that can be readily used with Packer by simply converting them. +If you are or were a user of [Veewee](https://github.com/jedi4ever/veewee), then +there is an official tool called +[veewee-to-packer](https://github.com/mitchellh/veewee-to-packer) that will +convert your Veewee definition into an equivalent Packer template. Even if +you're not a Veewee user, Veewee has a [large +library](https://github.com/jedi4ever/veewee/tree/master/templates) of templates +that can be readily used with Packer by simply converting them. ## Installation and Usage Since Veewee itself is a Ruby project, so too is the veewee-to-packer -application so that it can read the Veewee configurations. Install it using RubyGems: +application so that it can read the Veewee configurations. Install it using +RubyGems: -```text +``` {.text} $ gem install veewee-to-packer ... ``` -Once installed, usage is easy! Just point `veewee-to-packer` -at the `definition.rb` file of any template. The converter will output -any warnings or messages about the conversion. The example below converts -a CentOS template: +Once installed, usage is easy! Just point `veewee-to-packer` at the +`definition.rb` file of any template. The converter will output any warnings or +messages about the conversion. The example below converts a CentOS template: -```text +``` {.text} $ veewee-to-packer templates/CentOS-6.4/definition.rb Success! Your Veewee definition was converted to a Packer template! The template can be found in the `template.json` file @@ -41,22 +45,21 @@ first, since the template has relative paths that expect you to use it from the same working directory. ``` -***Voila!*** By default, `veewee-to-packer` will output a template that -contains a builder for both VirtualBox and VMware. You can use the -`-only` flag on `packer build` to only build one of them. Otherwise -you can use the `--builder` flag on `veewee-to-packer` to only output -specific builder configurations. +***Voila!*** By default, `veewee-to-packer` will output a template that contains +a builder for both VirtualBox and VMware. You can use the `-only` flag on +`packer build` to only build one of them. Otherwise you can use the `--builder` +flag on `veewee-to-packer` to only output specific builder configurations. ## Limitations -None, really. The tool will tell you if it can't convert a part of a -template, and whether that is a critical error or just a warning. -Most of Veewee's functions translate perfectly over to Packer. There are -still a couple missing features in Packer, but they're minimal. +None, really. The tool will tell you if it can't convert a part of a template, +and whether that is a critical error or just a warning. Most of Veewee's +functions translate perfectly over to Packer. There are still a couple missing +features in Packer, but they're minimal. ## Bugs -If you find any bugs, please report them to the -[veewee-to-packer issue tracker](https://github.com/mitchellh/veewee-to-packer). -I haven't been able to exhaustively test every Veewee template, so there -are certainly some edge cases out there. +If you find any bugs, please report them to the [veewee-to-packer issue +tracker](https://github.com/mitchellh/veewee-to-packer). I haven't been able to +exhaustively test every Veewee template, so there are certainly some edge cases +out there. diff --git a/website/source/intro/getting-started/build-image.html.markdown b/website/source/intro/getting-started/build-image.html.markdown index 4bf8eda57..ec1d851a9 100644 --- a/website/source/intro/getting-started/build-image.html.markdown +++ b/website/source/intro/getting-started/build-image.html.markdown @@ -1,29 +1,32 @@ --- -layout: "intro" -page_title: "Build an Image" -prev_url: "/intro/getting-started/setup.html" -next_url: "/intro/getting-started/provision.html" -next_title: "Provision" -description: |- - With Packer installed, let's just dive right into it and build our first image. Our first image will be an Amazon EC2 AMI with Redis pre-installed. This is just an example. Packer can create images for many platforms with anything pre-installed. ---- +description: | + With Packer installed, let's just dive right into it and build our first image. + Our first image will be an Amazon EC2 AMI with Redis pre-installed. This is just + an example. Packer can create images for many platforms with anything + pre-installed. +layout: intro +next_title: Provision +next_url: '/intro/getting-started/provision.html' +page_title: Build an Image +prev_url: '/intro/getting-started/setup.html' +... # Build an Image -With Packer installed, let's just dive right into it and build our first -image. Our first image will be an [Amazon EC2 AMI](http://aws.amazon.com/ec2/) -with Redis pre-installed. This is just an example. Packer can create images -for [many platforms](/intro/platforms.html) with anything pre-installed. +With Packer installed, let's just dive right into it and build our first image. +Our first image will be an [Amazon EC2 AMI](http://aws.amazon.com/ec2/) with +Redis pre-installed. This is just an example. Packer can create images for [many +platforms](/intro/platforms.html) with anything pre-installed. If you don't have an AWS account, [create one now](http://aws.amazon.com/free/). For the example, we'll use a "t2.micro" instance to build our image, which -qualifies under the AWS [free-tier](http://aws.amazon.com/free/), meaning -it will be free. If you already have an AWS account, you may be charged some -amount of money, but it shouldn't be more than a few cents. +qualifies under the AWS [free-tier](http://aws.amazon.com/free/), meaning it +will be free. If you already have an AWS account, you may be charged some amount +of money, but it shouldn't be more than a few cents. --> **Note:** If you're not using an account that qualifies under the AWS -free-tier, you may be charged to run these examples. The charge should only be -a few cents, but we're not responsible if it ends up being more. +-> **Note:** If you're not using an account that qualifies under the AWS +free-tier, you may be charged to run these examples. The charge should only be a +few cents, but we're not responsible if it ends up being more. Packer can build images for [many platforms](/intro/platforms.html) other than AWS, but AWS requires no additional software installed on your computer and @@ -34,16 +37,16 @@ apply to the other platforms as well. ## The Template -The configuration file used to define what image we want built and how -is called a _template_ in Packer terminology. The format of a template -is simple [JSON](http://www.json.org/). JSON struck the best balance between +The configuration file used to define what image we want built and how is called +a *template* in Packer terminology. The format of a template is simple +[JSON](http://www.json.org/). JSON struck the best balance between human-editable and machine-editable, allowing both hand-made templates as well as machine generated templates to easily be made. We'll start by creating the entire template, then we'll go over each section briefly. Create a file `example.json` and fill it with the following contents: -```javascript +``` {.javascript} { "variables": { "aws_access_key": "", @@ -62,55 +65,55 @@ briefly. Create a file `example.json` and fill it with the following contents: } ``` -When building, you'll pass in the `aws_access_key` and `aws_secret_key` as -a [user variable](/docs/templates/user-variables.html), keeping your secret -keys out of the template. You can create security credentials -on [this page](https://console.aws.amazon.com/iam/home?#security_credential). -An example IAM policy document can be found in the [Amazon EC2 builder docs](/docs/builders/amazon.html). +When building, you'll pass in the `aws_access_key` and `aws_secret_key` as a +[user variable](/docs/templates/user-variables.html), keeping your secret keys +out of the template. You can create security credentials on [this +page](https://console.aws.amazon.com/iam/home?#security_credential). An example +IAM policy document can be found in the [Amazon EC2 builder +docs](/docs/builders/amazon.html). -This is a basic template that is ready-to-go. It should be immediately recognizable -as a normal, basic JSON object. Within the object, the `builders` section -contains an array of JSON objects configuring a specific _builder_. A -builder is a component of Packer that is responsible for creating a machine -and turning that machine into an image. +This is a basic template that is ready-to-go. It should be immediately +recognizable as a normal, basic JSON object. Within the object, the `builders` +section contains an array of JSON objects configuring a specific *builder*. A +builder is a component of Packer that is responsible for creating a machine and +turning that machine into an image. -In this case, we're only configuring a single builder of type `amazon-ebs`. -This is the Amazon EC2 AMI builder that ships with Packer. This builder -builds an EBS-backed AMI by launching a source AMI, provisioning on top of -that, and re-packaging it into a new AMI. +In this case, we're only configuring a single builder of type `amazon-ebs`. This +is the Amazon EC2 AMI builder that ships with Packer. This builder builds an +EBS-backed AMI by launching a source AMI, provisioning on top of that, and +re-packaging it into a new AMI. -The additional keys within the object are configuration for this builder, specifying things -such as access keys, the source AMI to build from, and more. -The exact set of configuration variables available for a builder are -specific to each builder and can be found within the [documentation](/docs). +The additional keys within the object are configuration for this builder, +specifying things such as access keys, the source AMI to build from, and more. +The exact set of configuration variables available for a builder are specific to +each builder and can be found within the [documentation](/docs). -Before we take this template and build an image from it, let's validate the template -by running `packer validate example.json`. This command checks the syntax -as well as the configuration values to verify they look valid. The output should -look similar to below, because the template should be valid. If there are +Before we take this template and build an image from it, let's validate the +template by running `packer validate example.json`. This command checks the +syntax as well as the configuration values to verify they look valid. The output +should look similar to below, because the template should be valid. If there are any errors, this command will tell you. -```text +``` {.text} $ packer validate example.json Template validated successfully. ``` Next, let's build the image from this template. -An astute reader may notice that we said earlier we'd be building an -image with Redis pre-installed, and yet the template we made doesn't reference -Redis anywhere. In fact, this part of the documentation will only cover making -a first basic, non-provisioned image. The next section on provisioning will -cover installing Redis. +An astute reader may notice that we said earlier we'd be building an image with +Redis pre-installed, and yet the template we made doesn't reference Redis +anywhere. In fact, this part of the documentation will only cover making a first +basic, non-provisioned image. The next section on provisioning will cover +installing Redis. ## Your First Image -With a properly validated template. It is time to build your first image. -This is done by calling `packer build` with the template file. The output -should look similar to below. Note that this process typically takes a -few minutes. +With a properly validated template. It is time to build your first image. This +is done by calling `packer build` with the template file. The output should look +similar to below. Note that this process typically takes a few minutes. -```text +``` {.text} $ packer build \ -var 'aws_access_key=YOUR ACCESS KEY' \ -var 'aws_secret_key=YOUR SECRET KEY' \ @@ -139,38 +142,36 @@ $ packer build \ us-east-1: ami-19601070 ``` -At the end of running `packer build`, Packer outputs the _artifacts_ -that were created as part of the build. Artifacts are the results of a -build, and typically represent an ID (such as in the case of an AMI) or -a set of files (such as for a VMware virtual machine). In this example, -we only have a single artifact: the AMI in us-east-1 that was created. +At the end of running `packer build`, Packer outputs the *artifacts* that were +created as part of the build. Artifacts are the results of a build, and +typically represent an ID (such as in the case of an AMI) or a set of files +(such as for a VMware virtual machine). In this example, we only have a single +artifact: the AMI in us-east-1 that was created. -This AMI is ready to use. If you wanted you can go and launch this AMI -right now and it would work great. +This AMI is ready to use. If you wanted you can go and launch this AMI right now +and it would work great. --> **Note:** Your AMI ID will surely be different than the -one above. If you try to launch the one in the example output above, you -will get an error. If you want to try to launch your AMI, get the ID from -the Packer output. +-> **Note:** Your AMI ID will surely be different than the one above. If you +try to launch the one in the example output above, you will get an error. If you +want to try to launch your AMI, get the ID from the Packer output. ## Managing the Image -Packer only builds images. It does not attempt to manage them in any way. -After they're built, it is up to you to launch or destroy them as you see -fit. If you want to store and namespace images for easy reference, you -can use [Atlas by HashiCorp](https://atlas.hashicorp.com). We'll cover -remotely building and storing images at the end of this getting started guide. +Packer only builds images. It does not attempt to manage them in any way. After +they're built, it is up to you to launch or destroy them as you see fit. If you +want to store and namespace images for easy reference, you can use [Atlas by +HashiCorp](https://atlas.hashicorp.com). We'll cover remotely building and +storing images at the end of this getting started guide. -After running the above example, your AWS account -now has an AMI associated with it. AMIs are stored in S3 by Amazon, -so unless you want to be charged about $0.01 -per month, you'll probably want to remove it. Remove the AMI by -first deregistering it on the [AWS AMI management page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Images). -Next, delete the associated snapshot on the -[AWS snapshot management page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Snapshots). +After running the above example, your AWS account now has an AMI associated with +it. AMIs are stored in S3 by Amazon, so unless you want to be charged about +\$0.01 per month, you'll probably want to remove it. Remove the AMI by first +deregistering it on the [AWS AMI management +page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Images). Next, +delete the associated snapshot on the [AWS snapshot management +page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Snapshots). -Congratulations! You've just built your first image with Packer. Although -the image was pretty useless in this case (nothing was changed about it), -this page should've given you a general idea of how Packer works, what -templates are, and how to validate and build templates into machine -images. +Congratulations! You've just built your first image with Packer. Although the +image was pretty useless in this case (nothing was changed about it), this page +should've given you a general idea of how Packer works, what templates are, and +how to validate and build templates into machine images. diff --git a/website/source/intro/getting-started/next.html.markdown b/website/source/intro/getting-started/next.html.markdown index 262b84bb9..e1e7cc2ae 100644 --- a/website/source/intro/getting-started/next.html.markdown +++ b/website/source/intro/getting-started/next.html.markdown @@ -1,25 +1,29 @@ --- -layout: "intro" -page_title: "Next Steps" -description: |- - That concludes the getting started guide for Packer. You should now be comfortable with basic Packer usage, should understand templates, defining builds, provisioners, etc. At this point you're ready to begin playing with and using Packer in real scenarios. ---- +description: | + That concludes the getting started guide for Packer. You should now be + comfortable with basic Packer usage, should understand templates, defining + builds, provisioners, etc. At this point you're ready to begin playing with and + using Packer in real scenarios. +layout: intro +page_title: Next Steps +... # Next Steps -That concludes the getting started guide for Packer. You should now be comfortable -with basic Packer usage, should understand templates, defining builds, provisioners, -etc. At this point you're ready to begin playing with and using Packer -in real scenarios. +That concludes the getting started guide for Packer. You should now be +comfortable with basic Packer usage, should understand templates, defining +builds, provisioners, etc. At this point you're ready to begin playing with and +using Packer in real scenarios. -From this point forward, the most important reference for you will be -the [documentation](/docs). The documentation is less of a guide and -more of a reference of all the overall features and options of Packer. +From this point forward, the most important reference for you will be the +[documentation](/docs). The documentation is less of a guide and more of a +reference of all the overall features and options of Packer. -If you're interested in learning more about how Packer fits into the -HashiCorp ecosystem of tools, read our [Atlas getting started overview](https://atlas.hashicorp.com/help/intro/getting-started). +If you're interested in learning more about how Packer fits into the HashiCorp +ecosystem of tools, read our [Atlas getting started +overview](https://atlas.hashicorp.com/help/intro/getting-started). -As you use Packer more, please voice your comments and concerns on -the [mailing list or IRC](/community). Additionally, Packer is -[open source](https://github.com/mitchellh/packer) so please contribute -if you'd like to. Contributions are very welcome. +As you use Packer more, please voice your comments and concerns on the [mailing +list or IRC](/community). Additionally, Packer is [open +source](https://github.com/mitchellh/packer) so please contribute if you'd like +to. Contributions are very welcome. diff --git a/website/source/intro/getting-started/parallel-builds.html.markdown b/website/source/intro/getting-started/parallel-builds.html.markdown index 90554dacc..626033ef2 100644 --- a/website/source/intro/getting-started/parallel-builds.html.markdown +++ b/website/source/intro/getting-started/parallel-builds.html.markdown @@ -1,57 +1,59 @@ --- -layout: "intro" -page_title: "Parallel Builds" -prev_url: "/intro/getting-started/provision.html" -next_url: "/intro/getting-started/vagrant.html" -next_title: "Vagrant Boxes" -description: |- - So far we've shown how Packer can automatically build an image and provision it. This on its own is already quite powerful. But Packer can do better than that. Packer can create multiple images for multiple platforms in parallel, all configured from a single template. ---- +description: | + So far we've shown how Packer can automatically build an image and provision it. + This on its own is already quite powerful. But Packer can do better than that. + Packer can create multiple images for multiple platforms in parallel, all + configured from a single template. +layout: intro +next_title: Vagrant Boxes +next_url: '/intro/getting-started/vagrant.html' +page_title: Parallel Builds +prev_url: '/intro/getting-started/provision.html' +... # Parallel Builds So far we've shown how Packer can automatically build an image and provision it. This on its own is already quite powerful. But Packer can do better than that. -Packer can create multiple images for multiple platforms _in parallel_, all +Packer can create multiple images for multiple platforms *in parallel*, all configured from a single template. -This is a very useful and important feature of Packer. As an example, -Packer is able to make an AMI and a VMware virtual machine -in parallel provisioned with the _same scripts_, resulting in near-identical -images. The AMI can be used for production, the VMware machine can be used -for development. Or, another example, if you're using Packer to build -[software appliances](http://en.wikipedia.org/wiki/Software_appliance), -then you can build the appliance for every supported platform all in -parallel, all configured from a single template. +This is a very useful and important feature of Packer. As an example, Packer is +able to make an AMI and a VMware virtual machine in parallel provisioned with +the *same scripts*, resulting in near-identical images. The AMI can be used for +production, the VMware machine can be used for development. Or, another example, +if you're using Packer to build [software +appliances](http://en.wikipedia.org/wiki/Software_appliance), then you can build +the appliance for every supported platform all in parallel, all configured from +a single template. -Once you start taking advantage of this feature, the possibilities begin -to unfold in front of you. +Once you start taking advantage of this feature, the possibilities begin to +unfold in front of you. -Continuing on the example in this getting started guide, we'll build -a [DigitalOcean](http://www.digitalocean.com) image as well as an AMI. Both -will be near-identical: bare bones Ubuntu OS with Redis pre-installed. -However, since we're building for both platforms, you have the option of -whether you want to use the AMI, or the DigitalOcean snapshot. Or use both. +Continuing on the example in this getting started guide, we'll build a +[DigitalOcean](http://www.digitalocean.com) image as well as an AMI. Both will +be near-identical: bare bones Ubuntu OS with Redis pre-installed. However, since +we're building for both platforms, you have the option of whether you want to +use the AMI, or the DigitalOcean snapshot. Or use both. ## Setting Up DigitalOcean -[DigitalOcean](https://www.digitalocean.com/) is a relatively new, but -very popular VPS provider that has popped up. They have a quality offering -of high performance, low cost VPS servers. We'll be building a DigitalOcean -snapshot for this example. +[DigitalOcean](https://www.digitalocean.com/) is a relatively new, but very +popular VPS provider that has popped up. They have a quality offering of high +performance, low cost VPS servers. We'll be building a DigitalOcean snapshot for +this example. -In order to do this, you'll need an account with DigitalOcean. -[Sign up for an account now](https://www.digitalocean.com/). It is free -to sign up. Because the "droplets" (servers) are charged hourly, you -_will_ be charged $0.01 for every image you create with Packer. If -you're not okay with this, just follow along. +In order to do this, you'll need an account with DigitalOcean. [Sign up for an +account now](https://www.digitalocean.com/). It is free to sign up. Because the +"droplets" (servers) are charged hourly, you *will* be charged \$0.01 for every +image you create with Packer. If you're not okay with this, just follow along. -!> **Warning!** You _will_ be charged $0.01 by DigitalOcean per image +!> **Warning!** You *will* be charged \$0.01 by DigitalOcean per image created with Packer because of the time the "droplet" is running. -Once you sign up for an account, grab your API token from -the [DigitalOcean API access page](https://cloud.digitalocean.com/settings/applications). -Save these values somewhere; you'll need them in a second. +Once you sign up for an account, grab your API token from the [DigitalOcean API +access page](https://cloud.digitalocean.com/settings/applications). Save these +values somewhere; you'll need them in a second. ## Modifying the Template @@ -59,20 +61,20 @@ We now have to modify the template to add DigitalOcean to it. Modify the template we've been using and add the following JSON object to the `builders` array. -```javascript +``` {.javascript} { "type": "digitalocean", "api_token": "{{user `do_api_token`}}", - "image": "ubuntu-14-04-x64", - "region": "nyc3", - "size": "512mb", + "image": "ubuntu-14-04-x64", + "region": "nyc3", + "size": "512mb", } ``` -You'll also need to modify the `variables` section of the template -to include the access keys for DigitalOcean. +You'll also need to modify the `variables` section of the template to include +the access keys for DigitalOcean. -```javascript +``` {.javascript} "variables": { "do_api_token": "", // ... @@ -81,61 +83,61 @@ to include the access keys for DigitalOcean. The entire template should now look like this: -```javascript +``` {.javascript} { - "variables": { - "aws_access_key": "", - "aws_secret_key": "", - "do_api_token": "" - }, - "builders": [{ - "type": "amazon-ebs", - "access_key": "{{user `aws_access_key`}}", - "secret_key": "{{user `aws_secret_key`}}", - "region": "us-east-1", - "source_ami": "ami-de0d9eb7", - "instance_type": "t1.micro", - "ssh_username": "ubuntu", - "ami_name": "packer-example {{timestamp}}" - },{ - "type": "digitalocean", - "api_token": "{{user `do_api_token`}}", - "image": "ubuntu-14-04-x64", - "region": "nyc3", - "size": "512mb" - }], - "provisioners": [{ - "type": "shell", - "inline": [ - "sleep 30", - "sudo apt-get update", - "sudo apt-get install -y redis-server" - ] - }] + "variables": { + "aws_access_key": "", + "aws_secret_key": "", + "do_api_token": "" + }, + "builders": [{ + "type": "amazon-ebs", + "access_key": "{{user `aws_access_key`}}", + "secret_key": "{{user `aws_secret_key`}}", + "region": "us-east-1", + "source_ami": "ami-de0d9eb7", + "instance_type": "t1.micro", + "ssh_username": "ubuntu", + "ami_name": "packer-example {{timestamp}}" + },{ + "type": "digitalocean", + "api_token": "{{user `do_api_token`}}", + "image": "ubuntu-14-04-x64", + "region": "nyc3", + "size": "512mb" + }], + "provisioners": [{ + "type": "shell", + "inline": [ + "sleep 30", + "sudo apt-get update", + "sudo apt-get install -y redis-server" + ] + }] } ``` Additional builders are simply added to the `builders` array in the template. -This tells Packer to build multiple images. The builder `type` values don't -even need to be different! In fact, if you wanted to build multiple AMIs, -you can do that as long as you specify a unique `name` for each build. +This tells Packer to build multiple images. The builder `type` values don't even +need to be different! In fact, if you wanted to build multiple AMIs, you can do +that as long as you specify a unique `name` for each build. Validate the template with `packer validate`. This is always a good practice. --> **Note:** If you're looking for more **DigitalOcean configuration options**, -you can find them on the -[DigitalOcean Builder page](/docs/builders/digitalocean.html) in the -documentation. The documentation is more of a reference manual that contains a -listing of all the available configuration options. +-> **Note:** If you're looking for more **DigitalOcean configuration +options**, you can find them on the [DigitalOcean Builder +page](/docs/builders/digitalocean.html) in the documentation. The documentation +is more of a reference manual that contains a listing of all the available +configuration options. ## Build -Now run `packer build` with your user variables. The output is too verbose to include -all of it, but a portion of it is reproduced below. Note that the ordering -and wording of the lines may be slightly different, but the effect is the -same. +Now run `packer build` with your user variables. The output is too verbose to +include all of it, but a portion of it is reproduced below. Note that the +ordering and wording of the lines may be slightly different, but the effect is +the same. -```text +``` {.text} $ packer build \ -var 'aws_access_key=YOUR ACCESS KEY' \ -var 'aws_secret_key=YOUR SECRET KEY' \ @@ -162,10 +164,10 @@ us-east-1: ami-376d1d5e --> digitalocean: A snapshot was created: packer-1371870364 ``` -As you can see, Packer builds both the Amazon and DigitalOcean images -in parallel. It outputs information about each in different colors -(although you can't see that in the block above) so that it is easy to identify. +As you can see, Packer builds both the Amazon and DigitalOcean images in +parallel. It outputs information about each in different colors (although you +can't see that in the block above) so that it is easy to identify. -At the end of the build, Packer outputs both of the artifacts created -(an AMI and a DigitalOcean snapshot). Both images created are bare bones -Ubuntu installations with Redis pre-installed. +At the end of the build, Packer outputs both of the artifacts created (an AMI +and a DigitalOcean snapshot). Both images created are bare bones Ubuntu +installations with Redis pre-installed. diff --git a/website/source/intro/getting-started/provision.html.markdown b/website/source/intro/getting-started/provision.html.markdown index bedb63b69..eda1f0346 100644 --- a/website/source/intro/getting-started/provision.html.markdown +++ b/website/source/intro/getting-started/provision.html.markdown @@ -1,43 +1,45 @@ --- -layout: "intro" -page_title: "Provision" -prev_url: "/intro/getting-started/build-image.html" -next_url: "/intro/getting-started/parallel-builds.html" -next_title: "Parallel Builds" -description: |- - In the previous page of this guide, you created your first image with Packer. The image you just built, however, was basically just a repackaging of a previously existing base AMI. The real utility of Packer comes from being able to install and configure software into the images as well. This stage is also known as the _provision_ step. Packer fully supports automated provisioning in order to install software onto the machines prior to turning them into images. ---- +description: | + In the previous page of this guide, you created your first image with Packer. + The image you just built, however, was basically just a repackaging of a + previously existing base AMI. The real utility of Packer comes from being able + to install and configure software into the images as well. This stage is also + known as the *provision* step. Packer fully supports automated provisioning in + order to install software onto the machines prior to turning them into images. +layout: intro +next_title: Parallel Builds +next_url: '/intro/getting-started/parallel-builds.html' +page_title: Provision +prev_url: '/intro/getting-started/build-image.html' +... # Provision -In the previous page of this guide, you created your first image with -Packer. The image you just built, however, was basically just a repackaging -of a previously existing base AMI. The real utility of Packer comes from -being able to install and configure software into the images as well. -This stage is also known as the _provision_ step. Packer fully supports -automated provisioning in order to install software onto the machines prior -to turning them into images. +In the previous page of this guide, you created your first image with Packer. +The image you just built, however, was basically just a repackaging of a +previously existing base AMI. The real utility of Packer comes from being able +to install and configure software into the images as well. This stage is also +known as the *provision* step. Packer fully supports automated provisioning in +order to install software onto the machines prior to turning them into images. -In this section, we're going to complete our image by installing -Redis on it. This way, the image we end up building actually contains -Redis pre-installed. Although Redis is a small, simple example, this should -give you an idea of what it may be like to install many more packages into -the image. +In this section, we're going to complete our image by installing Redis on it. +This way, the image we end up building actually contains Redis pre-installed. +Although Redis is a small, simple example, this should give you an idea of what +it may be like to install many more packages into the image. -Historically, pre-baked images have been frowned upon because changing -them has been so tedious and slow. Because Packer is completely automated, -including provisioning, images can be changed quickly and integrated with -modern configuration management tools such as Chef or Puppet. +Historically, pre-baked images have been frowned upon because changing them has +been so tedious and slow. Because Packer is completely automated, including +provisioning, images can be changed quickly and integrated with modern +configuration management tools such as Chef or Puppet. ## Configuring Provisioners Provisioners are configured as part of the template. We'll use the built-in shell provisioner that comes with Packer to install Redis. Modify the -`example.json` template we made previously and add the following. We'll -explain the various parts of the new configuration following the code -block below. +`example.json` template we made previously and add the following. We'll explain +the various parts of the new configuration following the code block below. -```javascript +``` {.javascript} { "variables": ["..."], "builders": ["..."], @@ -53,51 +55,51 @@ block below. } ``` --> **Note:** The `sleep 30` in the example above is -very important. Because Packer is able to detect and SSH into the instance -as soon as SSH is available, Ubuntu actually doesn't get proper amounts -of time to initialize. The sleep makes sure that the OS properly initializes. +-> **Note:** The `sleep 30` in the example above is very important. Because +Packer is able to detect and SSH into the instance as soon as SSH is available, +Ubuntu actually doesn't get proper amounts of time to initialize. The sleep +makes sure that the OS properly initializes. -Hopefully it is obvious, but the `builders` section shouldn't actually -contain "...", it should be the contents setup in the previous page -of the getting started guide. Also note the comma after the `"builders": [...]` -section, which was not present in the previous lesson. +Hopefully it is obvious, but the `builders` section shouldn't actually contain +"...", it should be the contents setup in the previous page of the getting +started guide. Also note the comma after the `"builders": [...]` section, which +was not present in the previous lesson. To configure the provisioners, we add a new section `provisioners` to the -template, alongside the `builders` configuration. The provisioners section -is an array of provisioners to run. If multiple provisioners are specified, they -are run in the order given. +template, alongside the `builders` configuration. The provisioners section is an +array of provisioners to run. If multiple provisioners are specified, they are +run in the order given. -By default, each provisioner is run for every builder defined. So if we had -two builders defined in our template, such as both Amazon and DigitalOcean, then -the shell script would run as part of both builds. There are ways to restrict +By default, each provisioner is run for every builder defined. So if we had two +builders defined in our template, such as both Amazon and DigitalOcean, then the +shell script would run as part of both builds. There are ways to restrict provisioners to certain builds, but it is outside the scope of this getting started guide. It is covered in more detail in the complete [documentation](/docs). -The one provisioner we defined has a type of `shell`. This provisioner -ships with Packer and runs shell scripts on the running machine. In our -case, we specify two inline commands to run in order to install Redis. +The one provisioner we defined has a type of `shell`. This provisioner ships +with Packer and runs shell scripts on the running machine. In our case, we +specify two inline commands to run in order to install Redis. ## Build With the provisioner configured, give it a pass once again through `packer validate` to verify everything is okay, then build it using -`packer build example.json`. The output should look similar to when you -built your first image, except this time there will be a new step where -the provisioning is run. +`packer build example.json`. The output should look similar to when you built +your first image, except this time there will be a new step where the +provisioning is run. -The output from the provisioner is too verbose to include in this -guide, since it contains all the output from the shell scripts. But you -should see Redis successfully install. After that, Packer once again -turns the machine into an AMI. +The output from the provisioner is too verbose to include in this guide, since +it contains all the output from the shell scripts. But you should see Redis +successfully install. After that, Packer once again turns the machine into an +AMI. If you were to launch this AMI, Redis would be pre-installed. Cool! This is just a basic example. In a real world use case, you may be provisioning -an image with the entire stack necessary to run your application. Or maybe -just the web stack so that you can have an image for web servers pre-built. -This saves tons of time later as you launch these images since everything -is pre-installed. Additionally, since everything is pre-installed, you -can test the images as they're built and know that when they go into -production, they'll be functional. +an image with the entire stack necessary to run your application. Or maybe just +the web stack so that you can have an image for web servers pre-built. This +saves tons of time later as you launch these images since everything is +pre-installed. Additionally, since everything is pre-installed, you can test the +images as they're built and know that when they go into production, they'll be +functional. diff --git a/website/source/intro/getting-started/remote-builds.html.markdown b/website/source/intro/getting-started/remote-builds.html.markdown index e5d1b48ff..f37a5a5ad 100644 --- a/website/source/intro/getting-started/remote-builds.html.markdown +++ b/website/source/intro/getting-started/remote-builds.html.markdown @@ -1,23 +1,41 @@ --- -layout: "intro" -page_title: "Remote Builds and Storage" -prev_url: "/intro/getting-started/vagrant.html" -next_url: "/intro/getting-started/next.html" -next_title: "Next Steps" -description: |- - Up to this point in the guide, you have been running Packer on your local machine to build and provision images on AWS and DigitalOcean. However, you can use Atlas by HashiCorp to both run Packer builds remotely and store the output of builds. ---- +description: | + Up to this point in the guide, you have been running Packer on your local + machine to build and provision images on AWS and DigitalOcean. However, you can + use Atlas by HashiCorp to both run Packer builds remotely and store the output + of builds. +layout: intro +next_title: Next Steps +next_url: '/intro/getting-started/next.html' +page_title: Remote Builds and Storage +prev_url: '/intro/getting-started/vagrant.html' +... # Remote Builds and Storage -Up to this point in the guide, you have been running Packer on your local machine to build and provision images on AWS and DigitalOcean. However, you can use [Atlas by HashiCorp](https://atlas.hashicorp.com) to run Packer builds remotely and store the output of builds. + +Up to this point in the guide, you have been running Packer on your local +machine to build and provision images on AWS and DigitalOcean. However, you can +use [Atlas by HashiCorp](https://atlas.hashicorp.com) to run Packer builds +remotely and store the output of builds. ## Why Build Remotely? -By building remotely, you can move access credentials off of developer machines, release local machines from long-running Packer processes, and automatically start Packer builds from trigger sources such as `vagrant push`, a version control system, or CI tool. + +By building remotely, you can move access credentials off of developer machines, +release local machines from long-running Packer processes, and automatically +start Packer builds from trigger sources such as `vagrant push`, a version +control system, or CI tool. ## Run Packer Builds Remotely -To run Packer remotely, there are two changes that must be made to the Packer template. The first is the addition of the `push` [configuration](https://www.packer.io/docs/templates/push.html), which sends the Packer template to Atlas so it can run Packer remotely. The second modification is updating the variables section to read variables from the Atlas environment rather than the local environment. Remove the `post-processors` section for now if it is still in your template. -```javascript +To run Packer remotely, there are two changes that must be made to the Packer +template. The first is the addition of the `push` +[configuration](https://www.packer.io/docs/templates/push.html), which sends the +Packer template to Atlas so it can run Packer remotely. The second modification +is updating the variables section to read variables from the Atlas environment +rather than the local environment. Remove the `post-processors` section for now +if it is still in your template. + +``` {.javascript} { "variables": { "aws_access_key": "{{env `aws_access_key`}}", @@ -45,31 +63,35 @@ To run Packer remotely, there are two changes that must be made to the Packer te "name": "ATLAS_USERNAME/packer-tutorial" } } -``` - -To get an Atlas username, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started&utm_campaign=packer). Replace "ATLAS_USERNAME" with your username, then run `packer push -create example.json` to send the configuration to Atlas, which automatically starts the build. - -This build will fail since neither `aws_access_key` or `aws_secret_key` are set in the Atlas environment. To set environment variables in Atlas, navigate to the [operations tab](https://atlas.hashicorp.com/operations), click the "packer-tutorial" build configuration that was just created, and then click 'variables' in the left navigation. Set `aws_access_key` and `aws_secret_key` with their respective values. Now restart the Packer build by either clicking 'rebuild' in the Atlas UI or by running `packer push example.json` again. Now when you click on the active build, you can view the logs in real-time. - --> **Note:** Whenever a change is made to the Packer template, you must `packer push` to update the configuration in Atlas. - -## Store Packer Outputs -Now we have Atlas building an AMI with Redis pre-configured. This is great, but it's even better to store and version the AMI output so it can be easily deployed by a tool like [Terraform](https://terraform.io). The `atlas` [post-processor](/docs/post-processors/atlas.html) makes this process simple: - - ```javascript -{ - "variables": ["..."], - "builders": ["..."], - "provisioners": ["..."], - "push": ["..."], - "post-processors": [ - { - "type": "atlas", - "artifact": "ATLAS_USERNAME/packer-tutorial", - "artifact_type": "amazon.ami" - } - ] -} ``` -Update the `post-processors` block with your Atlas username, then `packer push example.json` and watch the build kick off in Atlas! When the build completes, the resulting artifact will be saved and stored in Atlas. \ No newline at end of file +To get an Atlas username, [create an account +here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started&utm_campaign=packer). +Replace "ATLAS\_USERNAME" with your username, then run +`packer push -create example.json` to send the configuration to Atlas, which +automatically starts the build. + +This build will fail since neither `aws_access_key` or `aws_secret_key` are set +in the Atlas environment. To set environment variables in Atlas, navigate to the +[operations tab](https://atlas.hashicorp.com/operations), click the +"packer-tutorial" build configuration that was just created, and then click +'variables' in the left navigation. Set `aws_access_key` and `aws_secret_key` +with their respective values. Now restart the Packer build by either clicking +'rebuild' in the Atlas UI or by running `packer push example.json` again. Now +when you click on the active build, you can view the logs in real-time. + +-> **Note:** Whenever a change is made to the Packer template, you must +`packer push` to update the configuration in Atlas. + +## Store Packer Outputs + +Now we have Atlas building an AMI with Redis pre-configured. This is great, but +it's even better to store and version the AMI output so it can be easily +deployed by a tool like [Terraform](https://terraform.io). The `atlas` +[post-processor](/docs/post-processors/atlas.html) makes this process simple: + +`javascript { "variables": ["..."], "builders": ["..."], "provisioners": ["..."], "push": ["..."], "post-processors": [ { "type": "atlas", "artifact": "ATLAS_USERNAME/packer-tutorial", "artifact_type": "amazon.ami" } ] }` + +Update the `post-processors` block with your Atlas username, then +`packer push example.json` and watch the build kick off in Atlas! When the build +completes, the resulting artifact will be saved and stored in Atlas. diff --git a/website/source/intro/getting-started/setup.html.markdown b/website/source/intro/getting-started/setup.html.markdown index ae14c2748..a24d023e2 100644 --- a/website/source/intro/getting-started/setup.html.markdown +++ b/website/source/intro/getting-started/setup.html.markdown @@ -1,47 +1,51 @@ --- -layout: "intro" -page_title: "Install Packer" -prev_url: "/intro/platforms.html" -next_url: "/intro/getting-started/build-image.html" -next_title: "Build an Image" -description: |- - Packer must first be installed on the machine you want to run it on. To make installation easy, Packer is distributed as a binary package for all supported platforms and architectures. This page will not cover how to compile Packer from source, as that is covered in the README and is only recommended for advanced users. ---- +description: | + Packer must first be installed on the machine you want to run it on. To make + installation easy, Packer is distributed as a binary package for all supported + platforms and architectures. This page will not cover how to compile Packer from + source, as that is covered in the README and is only recommended for advanced + users. +layout: intro +next_title: Build an Image +next_url: '/intro/getting-started/build-image.html' +page_title: Install Packer +prev_url: '/intro/platforms.html' +... # Install Packer -Packer must first be installed on the machine you want to run it on. -To make installation easy, Packer is distributed as a [binary package](/downloads.html) -for all supported platforms and architectures. This page will not cover how -to compile Packer from source, as that is covered in the +Packer must first be installed on the machine you want to run it on. To make +installation easy, Packer is distributed as a [binary package](/downloads.html) +for all supported platforms and architectures. This page will not cover how to +compile Packer from source, as that is covered in the [README](https://github.com/mitchellh/packer/blob/master/README.md) and is only recommended for advanced users. ## Installing Packer -To install packer, first find the [appropriate package](/downloads.html) -for your system and download it. Packer is packaged as a "zip" file. +To install packer, first find the [appropriate package](/downloads.html) for +your system and download it. Packer is packaged as a "zip" file. Next, unzip the downloaded package into a directory where Packer will be installed. On Unix systems, `~/packer` or `/usr/local/packer` is generally good, -depending on whether you want to restrict the install to just your user -or install it system-wide. On Windows systems, you can put it wherever you'd -like. +depending on whether you want to restrict the install to just your user or +install it system-wide. On Windows systems, you can put it wherever you'd like. After unzipping the package, the directory should contain a set of binary -programs, such as `packer`, `packer-build-amazon-ebs`, etc. The final step -to installation is to make sure the directory you installed Packer to -is on the PATH. See [this page](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux) -for instructions on setting the PATH on Linux and Mac. -[This page](http://stackoverflow.com/questions/1618280/where-can-i-set-path-to-make-exe-on-windows) +programs, such as `packer`, `packer-build-amazon-ebs`, etc. The final step to +installation is to make sure the directory you installed Packer to is on the +PATH. See [this +page](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux) +for instructions on setting the PATH on Linux and Mac. [This +page](http://stackoverflow.com/questions/1618280/where-can-i-set-path-to-make-exe-on-windows) contains instructions for setting the PATH on Windows. ## Verifying the Installation -After installing Packer, verify the installation worked by opening -a new command prompt or console, and checking that `packer` is available: +After installing Packer, verify the installation worked by opening a new command +prompt or console, and checking that `packer` is available: -```text +``` {.text} $ packer usage: packer [--version] [--help] [] @@ -54,21 +58,21 @@ Available commands are: version Prints the Packer version ``` -If you get an error that `packer` could not be found, then your PATH -environment variable was not setup properly. Please go back and ensure -that your PATH variable contains the directory which has Packer installed. +If you get an error that `packer` could not be found, then your PATH environment +variable was not setup properly. Please go back and ensure that your PATH +variable contains the directory which has Packer installed. Otherwise, Packer is installed and you're ready to go! ## Alternative Installation Methods -While the binary packages is the only official method of installation, there -are alternatives available. +While the binary packages is the only official method of installation, there are +alternatives available. ### Homebrew If you're using OS X and [Homebrew](http://brew.sh), you can install Packer: -```text +``` {.text} $ brew install packer ``` diff --git a/website/source/intro/getting-started/vagrant.html.markdown b/website/source/intro/getting-started/vagrant.html.markdown index 4d6e20caf..c671095e7 100644 --- a/website/source/intro/getting-started/vagrant.html.markdown +++ b/website/source/intro/getting-started/vagrant.html.markdown @@ -1,33 +1,34 @@ --- -layout: "intro" -page_title: "Vagrant Boxes" -prev_url: "/intro/getting-started/parallel-builds.html" -next_url: "/intro/getting-started/remote-builds.html" -next_title: "Remote Builds and Storage" -description: |- - Packer also has the ability to take the results of a builder (such as an AMI or plain VMware image) and turn it into a Vagrant box. ---- +description: | + Packer also has the ability to take the results of a builder (such as an AMI or + plain VMware image) and turn it into a Vagrant box. +layout: intro +next_title: Remote Builds and Storage +next_url: '/intro/getting-started/remote-builds.html' +page_title: Vagrant Boxes +prev_url: '/intro/getting-started/parallel-builds.html' +... # Vagrant Boxes -Packer also has the ability to take the results of a builder (such as -an AMI or plain VMware image) and turn it into a [Vagrant](http://www.vagrantup.com) -box. +Packer also has the ability to take the results of a builder (such as an AMI or +plain VMware image) and turn it into a [Vagrant](http://www.vagrantup.com) box. This is done using [post-processors](/docs/templates/post-processors.html). These take an artifact created by a previous builder or post-processor and transforms it into a new one. In the case of the Vagrant post-processor, it takes an artifact from a builder and transforms it into a Vagrant box file. -Post-processors are a generally very useful concept. While the example on -this getting-started page will be creating Vagrant images, post-processors -have many interesting use cases. For example, you can write a post-processor -to compress artifacts, upload them, test them, etc. +Post-processors are a generally very useful concept. While the example on this +getting-started page will be creating Vagrant images, post-processors have many +interesting use cases. For example, you can write a post-processor to compress +artifacts, upload them, test them, etc. -Let's modify our template to use the Vagrant post-processor to turn our -AWS AMI into a Vagrant box usable with the [vagrant-aws plugin](https://github.com/mitchellh/vagrant-aws). If you followed along in the previous page and setup DigitalOcean, -Packer can't currently make Vagrant boxes for DigitalOcean, but will be able -to soon. +Let's modify our template to use the Vagrant post-processor to turn our AWS AMI +into a Vagrant box usable with the [vagrant-aws +plugin](https://github.com/mitchellh/vagrant-aws). If you followed along in the +previous page and setup DigitalOcean, Packer can't currently make Vagrant boxes +for DigitalOcean, but will be able to soon. ## Enabling the Post-Processor @@ -35,7 +36,7 @@ Post-processors are added in the `post-processors` section of a template, which we haven't created yet. Modify your `example.json` template and add the section. Your template should look like the following: -```javascript +``` {.javascript} { "builders": ["..."], "provisioners": ["..."], @@ -44,8 +45,8 @@ Your template should look like the following: ``` In this case, we're enabling a single post-processor named "vagrant". This -post-processor is built-in to Packer and will create Vagrant boxes. You -can always create [new post-processors](/docs/extend/post-processor.html), however. +post-processor is built-in to Packer and will create Vagrant boxes. You can +always create [new post-processors](/docs/extend/post-processor.html), however. The details on configuring post-processors is covered in the [post-processors](/docs/templates/post-processors.html) documentation. @@ -53,27 +54,26 @@ Validate the configuration using `packer validate`. ## Using the Post-Processor -Just run a normal `packer build` and it will now use the post-processor. -Since Packer can't currently make a Vagrant box for DigitalOcean anyways, -I recommend passing the `-only=amazon-ebs` flag to `packer build` so it only -builds the AMI. The command should look like the following: +Just run a normal `packer build` and it will now use the post-processor. Since +Packer can't currently make a Vagrant box for DigitalOcean anyways, I recommend +passing the `-only=amazon-ebs` flag to `packer build` so it only builds the AMI. +The command should look like the following: -```text +``` {.text} $ packer build -only=amazon-ebs example.json ``` -As you watch the output, you'll notice at the end in the artifact listing -that a Vagrant box was made (by default at `packer_aws.box` in the current -directory). Success! +As you watch the output, you'll notice at the end in the artifact listing that a +Vagrant box was made (by default at `packer_aws.box` in the current directory). +Success! But where did the AMI go? When using post-processors, Vagrant removes -intermediary artifacts since they're usually not wanted. Only the final -artifact is preserved. This behavior can be changed, of course. Changing -this behavior is covered [in the documentation](/docs/templates/post-processors.html). +intermediary artifacts since they're usually not wanted. Only the final artifact +is preserved. This behavior can be changed, of course. Changing this behavior is +covered [in the documentation](/docs/templates/post-processors.html). -Typically when removing intermediary artifacts, the actual underlying -files or resources of the artifact are also removed. For example, when -building a VMware image, if you turn it into a Vagrant box, the files of -the VMware image will be deleted since they were compressed into the Vagrant -box. With creating AWS images, however, the AMI is kept around, since Vagrant -needs it to function. +Typically when removing intermediary artifacts, the actual underlying files or +resources of the artifact are also removed. For example, when building a VMware +image, if you turn it into a Vagrant box, the files of the VMware image will be +deleted since they were compressed into the Vagrant box. With creating AWS +images, however, the AMI is kept around, since Vagrant needs it to function. diff --git a/website/source/intro/hashicorp-ecosystem.html.markdown b/website/source/intro/hashicorp-ecosystem.html.markdown index 37c26b9ad..034d02a65 100644 --- a/website/source/intro/hashicorp-ecosystem.html.markdown +++ b/website/source/intro/hashicorp-ecosystem.html.markdown @@ -1,32 +1,63 @@ --- -layout: "intro" -page_title: "Packer and the HashiCorp Ecosystem" -prev_url: "/intro/platforms.html" -next_url: "/intro/getting-started/setup.html" -next_title: "Getting Started: Install Packer" -description: |- - Learn how Packer fits in with the rest of the HashiCorp ecosystem of tools ---- +description: Learn how Packer fits in with the rest of the HashiCorp ecosystem of tools +layout: intro +next_title: 'Getting Started: Install Packer' +next_url: '/intro/getting-started/setup.html' +page_title: Packer and the HashiCorp Ecosystem +prev_url: '/intro/platforms.html' +... # Packer and the HashiCorp Ecosystem -HashiCorp is the creator of the open source projects Vagrant, Packer, Terraform, Serf, and Consul, and the commercial product Atlas. Packer is just one piece of the ecosystem HashiCorp has built to make application delivery a versioned, auditable, repeatable, and collaborative process. To learn more about our beliefs on the qualities of the modern datacenter and responsible application delivery, read [The Atlas Mindset: Version Control for Infrastructure](https://hashicorp.com/blog/atlas-mindset.html/?utm_source=packer&utm_campaign=HashicorpEcosystem). +HashiCorp is the creator of the open source projects Vagrant, Packer, Terraform, +Serf, and Consul, and the commercial product Atlas. Packer is just one piece of +the ecosystem HashiCorp has built to make application delivery a versioned, +auditable, repeatable, and collaborative process. To learn more about our +beliefs on the qualities of the modern datacenter and responsible application +delivery, read [The Atlas Mindset: Version Control for +Infrastructure](https://hashicorp.com/blog/atlas-mindset.html/?utm_source=packer&utm_campaign=HashicorpEcosystem). -If you are using Packer to build machine images and deployable artifacts, it's likely that you need a solution for deploying those artifacts. Terraform is our tool for creating, combining, and modifying infrastructure. +If you are using Packer to build machine images and deployable artifacts, it's +likely that you need a solution for deploying those artifacts. Terraform is our +tool for creating, combining, and modifying infrastructure. -Below are summaries of HashiCorp's open source projects and a graphic showing how Atlas connects them to create a full application delivery workflow. +Below are summaries of HashiCorp's open source projects and a graphic showing +how Atlas connects them to create a full application delivery workflow. # HashiCorp Ecosystem + ![Atlas Workflow](docs/atlas-workflow.png) -[Atlas](https://atlas.hashicorp.com/?utm_source=packer&utm_campaign=HashicorpEcosystem) is HashiCorp's only commercial product. It unites Packer, Terraform, and Consul to make application delivery a versioned, auditable, repeatable, and collaborative process. +[Atlas](https://atlas.hashicorp.com/?utm_source=packer&utm_campaign=HashicorpEcosystem) +is HashiCorp's only commercial product. It unites Packer, Terraform, and Consul +to make application delivery a versioned, auditable, repeatable, and +collaborative process. -[Packer](https://packer.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) is a HashiCorp tool for creating machine images and deployable artifacts such as AMIs, OpenStack images, Docker containers, etc. +[Packer](https://packer.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) +is a HashiCorp tool for creating machine images and deployable artifacts such as +AMIs, OpenStack images, Docker containers, etc. -[Terraform](https://terraform.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) is a HashiCorp tool for creating, combining, and modifying infrastructure. In the Atlas workflow Terraform reads from the artifact registry and provisions infrastructure. +[Terraform](https://terraform.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) +is a HashiCorp tool for creating, combining, and modifying infrastructure. In +the Atlas workflow Terraform reads from the artifact registry and provisions +infrastructure. -[Consul](https://consul.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) is a HashiCorp tool for service discovery, service registry, and health checks. In the Atlas workflow Consul is configured at the Packer build stage and identifies the service(s) contained in each artifact. Since Consul is configured at the build phase with Packer, when the artifact is deployed with Terraform, it is fully configured with dependencies and service discovery pre-baked. This greatly reduces the risk of an unhealthy node in production due to configuration failure at runtime. +[Consul](https://consul.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) +is a HashiCorp tool for service discovery, service registry, and health checks. +In the Atlas workflow Consul is configured at the Packer build stage and +identifies the service(s) contained in each artifact. Since Consul is configured +at the build phase with Packer, when the artifact is deployed with Terraform, it +is fully configured with dependencies and service discovery pre-baked. This +greatly reduces the risk of an unhealthy node in production due to configuration +failure at runtime. -[Serf](https://serfdom.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) is a HashiCorp tool for cluster membership and failure detection. Consul uses Serf's gossip protocol as the foundation for service discovery. +[Serf](https://serfdom.io/?utm_source=packer&utm_campaign=HashicorpEcosystem) is +a HashiCorp tool for cluster membership and failure detection. Consul uses +Serf's gossip protocol as the foundation for service discovery. -[Vagrant](https://www.vagrantup.com/?utm_source=packer&utm_campaign=HashicorpEcosystem) is a HashiCorp tool for managing development environments that mirror production. Vagrant environments reduce the friction of developing a project and reduce the risk of unexpected behavior appearing after deployment. Vagrant boxes can be built in parallel with production artifacts with Packer to maintain parity between development and production. +[Vagrant](https://www.vagrantup.com/?utm_source=packer&utm_campaign=HashicorpEcosystem) +is a HashiCorp tool for managing development environments that mirror +production. Vagrant environments reduce the friction of developing a project and +reduce the risk of unexpected behavior appearing after deployment. Vagrant boxes +can be built in parallel with production artifacts with Packer to maintain +parity between development and production. diff --git a/website/source/intro/index.html.markdown b/website/source/intro/index.html.markdown index 147cc51ee..c9abcebe4 100644 --- a/website/source/intro/index.html.markdown +++ b/website/source/intro/index.html.markdown @@ -1,31 +1,34 @@ --- -layout: "intro" -page_title: "Introduction" -prev_url: "#" -next_url: "/intro/why.html" -next_title: "Why Use Packer?" -description: |- - Welcome to the world of Packer! This introduction guide will show you what Packer is, explain why it exists, the benefits it has to offer, and how you can get started with it. If you're already familiar with Packer, the documentation provides more of a reference for all available features. ---- +description: | + Welcome to the world of Packer! This introduction guide will show you what + Packer is, explain why it exists, the benefits it has to offer, and how you can + get started with it. If you're already familiar with Packer, the documentation + provides more of a reference for all available features. +layout: intro +next_title: 'Why Use Packer?' +next_url: '/intro/why.html' +page_title: Introduction +prev_url: '# ' +... # Introduction to Packer Welcome to the world of Packer! This introduction guide will show you what -Packer is, explain why it exists, the benefits it has to offer, and how -you can get started with it. If you're already familiar with Packer, the +Packer is, explain why it exists, the benefits it has to offer, and how you can +get started with it. If you're already familiar with Packer, the [documentation](/docs) provides more of a reference for all available features. ## What is Packer? -Packer is an open source tool for creating identical machine images for multiple platforms -from a single source configuration. Packer is lightweight, runs on every major -operating system, and is highly performant, creating machine images for -multiple platforms in parallel. Packer does not replace configuration management -like Chef or Puppet. In fact, when building images, Packer is able to use tools -like Chef or Puppet to install software onto the image. +Packer is an open source tool for creating identical machine images for multiple +platforms from a single source configuration. Packer is lightweight, runs on +every major operating system, and is highly performant, creating machine images +for multiple platforms in parallel. Packer does not replace configuration +management like Chef or Puppet. In fact, when building images, Packer is able to +use tools like Chef or Puppet to install software onto the image. -A _machine image_ is a single static unit that contains a pre-configured operating -system and installed software which is used to quickly create new running machines. -Machine image formats change for each platform. Some examples include -[AMIs](http://en.wikipedia.org/wiki/Amazon_Machine_Image) for EC2, +A *machine image* is a single static unit that contains a pre-configured +operating system and installed software which is used to quickly create new +running machines. Machine image formats change for each platform. Some examples +include [AMIs](http://en.wikipedia.org/wiki/Amazon_Machine_Image) for EC2, VMDK/VMX files for VMware, OVF exports for VirtualBox, etc. diff --git a/website/source/intro/platforms.html.markdown b/website/source/intro/platforms.html.markdown index d97756fd7..586c0c4ec 100644 --- a/website/source/intro/platforms.html.markdown +++ b/website/source/intro/platforms.html.markdown @@ -1,65 +1,73 @@ --- -layout: "intro" -page_title: "Supported Platforms" -prev_url: "/intro/use-cases.html" -next_url: "/intro/hashicorp-ecosystem.html" -next_title: "Packer & the HashiCorp Ecosystem" -description: |- - Packer can create machine images for any platform. Packer ships with support for a set of platforms, but can be extended through plugins to support any platform. This page documents the list of supported image types that Packer supports creating. ---- +description: | + Packer can create machine images for any platform. Packer ships with support for + a set of platforms, but can be extended through plugins to support any platform. + This page documents the list of supported image types that Packer supports + creating. +layout: intro +next_title: 'Packer & the HashiCorp Ecosystem' +next_url: '/intro/hashicorp-ecosystem.html' +page_title: Supported Platforms +prev_url: '/intro/use-cases.html' +... # Supported Platforms -Packer can create machine images for any platform. Packer ships with -support for a set of platforms, but can be [extended through plugins](/docs/extend/builder.html) -to support any platform. This page documents the list of supported image -types that Packer supports creating. +Packer can create machine images for any platform. Packer ships with support for +a set of platforms, but can be [extended through +plugins](/docs/extend/builder.html) to support any platform. This page documents +the list of supported image types that Packer supports creating. -If you were looking to see what platforms Packer is able to run on, see -the page on [installing Packer](/intro/getting-started/setup.html). +If you were looking to see what platforms Packer is able to run on, see the page +on [installing Packer](/intro/getting-started/setup.html). --> **Note:** We're always looking to officially support more -target platforms. If you're interested in adding support for another -platform, please help by opening an issue or pull request within -[GitHub](https://github.com/mitchellh/packer) so we can discuss -how to make it happen. +-> **Note:** We're always looking to officially support more target +platforms. If you're interested in adding support for another platform, please +help by opening an issue or pull request within +[GitHub](https://github.com/mitchellh/packer) so we can discuss how to make it +happen. -Packer supports creating images for the following platforms or targets. -The format of the resulting image and any high-level information about the -platform is noted. They are listed in alphabetical order. For more detailed -information on supported configuration parameters and usage, please see -the appropriate [documentation page within the documentation section](/docs). +Packer supports creating images for the following platforms or targets. The +format of the resulting image and any high-level information about the platform +is noted. They are listed in alphabetical order. For more detailed information +on supported configuration parameters and usage, please see the appropriate +[documentation page within the documentation section](/docs). -* ***Amazon EC2 (AMI)***. Both EBS-backed and instance-store AMIs within +- ***Amazon EC2 (AMI)***. Both EBS-backed and instance-store AMIs within [EC2](http://aws.amazon.com/ec2/), optionally distributed to multiple regions. -* ***DigitalOcean***. Snapshots for [DigitalOcean](http://www.digitalocean.com/) +- ***DigitalOcean***. Snapshots for [DigitalOcean](http://www.digitalocean.com/) that can be used to start a pre-configured DigitalOcean instance of any size. -* ***Docker***. Snapshots for [Docker](http://www.docker.io/) - that can be used to start a pre-configured Docker instance. +- ***Docker***. Snapshots for [Docker](http://www.docker.io/) that can be used + to start a pre-configured Docker instance. -* ***Google Compute Engine***. Snapshots for [Google Compute Engine](https://cloud.google.com/products/compute-engine) - that can be used to start a pre-configured Google Compute Engine instance. +- ***Google Compute Engine***. Snapshots for [Google Compute + Engine](https://cloud.google.com/products/compute-engine) that can be used to + start a pre-configured Google Compute Engine instance. -* ***OpenStack***. Images for [OpenStack](http://www.openstack.org/) - that can be used to start pre-configured OpenStack servers. +- ***OpenStack***. Images for [OpenStack](http://www.openstack.org/) that can be + used to start pre-configured OpenStack servers. -* ***Parallels (PVM)***. Exported virtual machines for [Parallels](http://www.parallels.com/downloads/desktop/), - including virtual machine metadata such as RAM, CPUs, etc. These virtual - machines are portable and can be started on any platform Parallels runs on. +- ***Parallels (PVM)***. Exported virtual machines for + [Parallels](http://www.parallels.com/downloads/desktop/), including virtual + machine metadata such as RAM, CPUs, etc. These virtual machines are portable + and can be started on any platform Parallels runs on. -* ***QEMU***. Images for [KVM](http://www.linux-kvm.org/) or [Xen](http://www.xenproject.org/) - that can be used to start pre-configured KVM or Xen instances. +- ***QEMU***. Images for [KVM](http://www.linux-kvm.org/) or + [Xen](http://www.xenproject.org/) that can be used to start pre-configured KVM + or Xen instances. -* ***VirtualBox (OVF)***. Exported virtual machines for [VirtualBox](https://www.virtualbox.org/), - including virtual machine metadata such as RAM, CPUs, etc. These virtual - machines are portable and can be started on any platform VirtualBox runs on. +- ***VirtualBox (OVF)***. Exported virtual machines for + [VirtualBox](https://www.virtualbox.org/), including virtual machine metadata + such as RAM, CPUs, etc. These virtual machines are portable and can be started + on any platform VirtualBox runs on. -* ***VMware (VMX)***. Exported virtual machines for [VMware](http://www.vmware.com/) - that can be run within any desktop products such as Fusion, Player, or - Workstation, as well as server products such as vSphere. +- ***VMware (VMX)***. Exported virtual machines for + [VMware](http://www.vmware.com/) that can be run within any desktop products + such as Fusion, Player, or Workstation, as well as server products such + as vSphere. -As previously mentioned, these are just the target image types that Packer -ships with out of the box. You can always [extend Packer through plugins](/docs/extend/builder.html) -to support more. +As previously mentioned, these are just the target image types that Packer ships +with out of the box. You can always [extend Packer through +plugins](/docs/extend/builder.html) to support more. diff --git a/website/source/intro/use-cases.html.markdown b/website/source/intro/use-cases.html.markdown index 0b73ea32c..2cd38d967 100644 --- a/website/source/intro/use-cases.html.markdown +++ b/website/source/intro/use-cases.html.markdown @@ -1,20 +1,24 @@ --- -layout: "intro" -page_title: "Use Cases" -prev_url: "/intro/why.html" -next_url: "/intro/platforms.html" -next_title: "Supported Platforms" -description: |- - By now you should know what Packer does and what the benefits of image creation are. In this section, we'll enumerate _some_ of the use cases for Packer. Note that this is not an exhaustive list by any means. There are definitely use cases for Packer not listed here. This list is just meant to give you an idea of how Packer may improve your processes. ---- +description: | + By now you should know what Packer does and what the benefits of image creation + are. In this section, we'll enumerate *some* of the use cases for Packer. Note + that this is not an exhaustive list by any means. There are definitely use cases + for Packer not listed here. This list is just meant to give you an idea of how + Packer may improve your processes. +layout: intro +next_title: Supported Platforms +next_url: '/intro/platforms.html' +page_title: Use Cases +prev_url: '/intro/why.html' +... # Use Cases -By now you should know what Packer does and what the benefits of image -creation are. In this section, we'll enumerate _some_ of the use cases -for Packer. Note that this is not an exhaustive list by any means. There are -definitely use cases for Packer not listed here. This list is just meant -to give you an idea of how Packer may improve your processes. +By now you should know what Packer does and what the benefits of image creation +are. In this section, we'll enumerate *some* of the use cases for Packer. Note +that this is not an exhaustive list by any means. There are definitely use cases +for Packer not listed here. This list is just meant to give you an idea of how +Packer may improve your processes. ### Continuous Delivery @@ -24,30 +28,31 @@ can be used to generate new machine images for multiple platforms on every change to Chef/Puppet. As part of this pipeline, the newly created images can then be launched and -tested, verifying the infrastructure changes work. If the tests pass, you can -be confident that that image will work when deployed. This brings a new level -of stability and testability to infrastructure changes. +tested, verifying the infrastructure changes work. If the tests pass, you can be +confident that that image will work when deployed. This brings a new level of +stability and testability to infrastructure changes. ### Dev/Prod Parity -Packer helps [keep development, staging, and production as similar as possible](http://www.12factor.net/dev-prod-parity). -Packer can be used to generate images for multiple platforms at the same time. -So if you use AWS for production and VMware (perhaps with [Vagrant](http://www.vagrantup.com)) -for development, you can generate both an AMI and a VMware machine using -Packer at the same time from the same template. +Packer helps [keep development, staging, and production as similar as +possible](http://www.12factor.net/dev-prod-parity). Packer can be used to +generate images for multiple platforms at the same time. So if you use AWS for +production and VMware (perhaps with [Vagrant](http://www.vagrantup.com)) for +development, you can generate both an AMI and a VMware machine using Packer at +the same time from the same template. Mix this in with the continuous delivery use case above, and you have a pretty -slick system for consistent work environments from development all the -way through to production. +slick system for consistent work environments from development all the way +through to production. ### Appliance/Demo Creation -Since Packer creates consistent images for multiple platforms in parallel, -it is perfect for creating [appliances](http://en.wikipedia.org/wiki/Software_appliance) -and disposable product demos. As your software changes, you can automatically -create appliances with the software pre-installed. Potential users can then -get started with your software by deploying it to the environment of their -choice. +Since Packer creates consistent images for multiple platforms in parallel, it is +perfect for creating +[appliances](http://en.wikipedia.org/wiki/Software_appliance) and disposable +product demos. As your software changes, you can automatically create appliances +with the software pre-installed. Potential users can then get started with your +software by deploying it to the environment of their choice. -Packaging up software with complex requirements has never been so easy. -Or enjoyable, if you ask me. +Packaging up software with complex requirements has never been so easy. Or +enjoyable, if you ask me. diff --git a/website/source/intro/why.html.markdown b/website/source/intro/why.html.markdown index 98de7855f..ee6b5ad9e 100644 --- a/website/source/intro/why.html.markdown +++ b/website/source/intro/why.html.markdown @@ -1,24 +1,29 @@ --- -layout: "intro" -page_title: "Why Use Packer?" -prev_url: "/intro/index.html" -next_url: "/intro/use-cases.html" -next_title: "Packer Use Cases" -description: |- - Pre-baked machine images have a lot of advantages, but most have been unable to benefit from them because images have been too tedious to create and manage. There were either no existing tools to automate the creation of machine images or they had too high of a learning curve. The result is that, prior to Packer, creating machine images threatened the agility of operations teams, and therefore aren't used, despite the massive benefits. ---- +description: | + Pre-baked machine images have a lot of advantages, but most have been unable to + benefit from them because images have been too tedious to create and manage. + There were either no existing tools to automate the creation of machine images + or they had too high of a learning curve. The result is that, prior to Packer, + creating machine images threatened the agility of operations teams, and + therefore aren't used, despite the massive benefits. +layout: intro +next_title: Packer Use Cases +next_url: '/intro/use-cases.html' +page_title: 'Why Use Packer?' +prev_url: '/intro/index.html' +... # Why Use Packer? -Pre-baked machine images have a lot of advantages, but most have been unable -to benefit from them because images have been too tedious to create and manage. -There were either no existing tools to automate the creation of machine images or -they had too high of a learning curve. The result is that, prior to Packer, -creating machine images threatened the agility of operations teams, and therefore -aren't used, despite the massive benefits. +Pre-baked machine images have a lot of advantages, but most have been unable to +benefit from them because images have been too tedious to create and manage. +There were either no existing tools to automate the creation of machine images +or they had too high of a learning curve. The result is that, prior to Packer, +creating machine images threatened the agility of operations teams, and +therefore aren't used, despite the massive benefits. -Packer changes all of this. Packer is easy to use and automates the creation -of any type of machine image. It embraces modern configuration management by +Packer changes all of this. Packer is easy to use and automates the creation of +any type of machine image. It embraces modern configuration management by encouraging you to use a framework such as Chef or Puppet to install and configure the software within your Packer-made images. @@ -28,25 +33,26 @@ untapped potential and opening new opportunities. ## Advantages of Using Packer ***Super fast infrastructure deployment***. Packer images allow you to launch -completely provisioned and configured machines in seconds, rather than -several minutes or hours. This benefits not only production, but development as well, -since development virtual machines can also be launched in seconds, without waiting -for a typically much longer provisioning time. +completely provisioned and configured machines in seconds, rather than several +minutes or hours. This benefits not only production, but development as well, +since development virtual machines can also be launched in seconds, without +waiting for a typically much longer provisioning time. ***Multi-provider portability***. Because Packer creates identical images for -multiple platforms, you can run production in AWS, staging/QA in a private -cloud like OpenStack, and development in desktop virtualization solutions -such as VMware or VirtualBox. Each environment is running an identical -machine image, giving ultimate portability. +multiple platforms, you can run production in AWS, staging/QA in a private cloud +like OpenStack, and development in desktop virtualization solutions such as +VMware or VirtualBox. Each environment is running an identical machine image, +giving ultimate portability. -***Improved stability***. Packer installs and configures all the software for -a machine at the time the image is built. If there are bugs in these scripts, -they'll be caught early, rather than several minutes after a machine is launched. +***Improved stability***. Packer installs and configures all the software for a +machine at the time the image is built. If there are bugs in these scripts, +they'll be caught early, rather than several minutes after a machine is +launched. ***Greater testability***. After a machine image is built, that machine image can be quickly launched and smoke tested to verify that things appear to be -working. If they are, you can be confident that any other machines launched -from that image will function properly. +working. If they are, you can be confident that any other machines launched from +that image will function properly. Packer makes it extremely easy to take advantage of all these benefits.