` - 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:
+
+* `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:
+
+
+[
+ "<esc><esc><enter><wait>",
+ "/install/vmlinuz noapic ",
+ "preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed.cfg ",
+ "debian-installer=en_US auto locale=en_US kbd-chooser/method=us ",
+ "hostname={{ .Name }} ",
+ "fb=false debconf/frontend=noninteractive ",
+ "keyboard-configuration/modelcode=SKIP keyboard-configuration/layout=USA ",
+ "keyboard-configuration/variant=USA console-setup/ask_detect=false ",
+ "initrd=/install/initrd.gz -- <enter>"
+]
+
+
+## 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 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.
+
+## 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.
+
+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:
+
+
+{
+ "vboxmanage": [
+ ["modifyvm", "{{.Name}}", "--memory", "1024"],
+ ["modifyvm", "{{.Name}}", "--cpus", "2"]
+ ]
+}
+
+
+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.
diff --git a/website/source/docs/builders/virtualbox-ovf.html.markdown b/website/source/docs/builders/virtualbox-ovf.html.markdown
new file mode 100644
index 000000000..36299e368
--- /dev/null
+++ b/website/source/docs/builders/virtualbox-ovf.html.markdown
@@ -0,0 +1,193 @@
+---
+layout: "docs"
+page_title: "VirtualBox Builder (from an OVF/OVA)"
+---
+
+# VirtualBox Builder (from an OVF/OVA)
+
+Type: `virtualbox-ovf`
+
+This VirtualBox 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).
+
+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.
+
+
+{
+ "type": "virtualbox-ovf",
+ "source_path": "source.ovf",
+ "ssh_username": "packer",
+ "ssh_password": "packer",
+ "ssh_wait_timeout": "30s",
+ "shutdown_command": "echo 'packer' | sudo -S shutdown -P now"
+}
+
+
+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.
+
+Required:
+
+* `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.
+
+Optional:
+
+* `floppy_files` (array of strings) - A list of files to put onto a floppy
+ disk that is attached when the VM is booted for the first time. This is
+ 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.
+
+* `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". The functions of each of these should be
+ self-explanatory. 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_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.
+
+* `headless` (bool) - 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.
+
+* `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.
+
+* `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.
+
+* `ssh_host_port_min` and `ssh_host_port_max` (uint) - 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_key_path` (string) - Path to a private key to use for authenticating
+ with SSH. By default this is not set (key-based auth won't be used).
+ The associated public key is expected to already be configured on the
+ VM being prepared by some other process (kickstart, etc.).
+
+* `ssh_password` (string) - The password for `ssh_username` to use to
+ authenticate with SSH. By default this is the empty string.
+
+* `ssh_port` (int) - The port that SSH will be listening on in the guest
+ virtual machine. By default this is 22.
+
+* `ssh_wait_timeout` (string) - The duration to wait for SSH to become
+ available. By default this is "20m", or 20 minutes. Note that this should
+ be quite long since the timer begins as soon as the virtual machine is booted.
+
+* `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.
+
+* `virtualbox_version_file` (string) - The path within the virtual machine
+ to upload a file that contains the VirtualBox version that was used to
+ create the machine. This information can be useful for provisioning.
+ By default this is ".vbox_version", which will generally upload it into
+ 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.
+
+## 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 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.
+
+## 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.
+
+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:
+
+
+{
+ "vboxmanage": [
+ ["modifyvm", "{{.Name}}", "--memory", "1024"],
+ ["modifyvm", "{{.Name}}", "--cpus", "2"]
+ ]
+}
+
+
+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.
diff --git a/website/source/docs/builders/virtualbox.html.markdown b/website/source/docs/builders/virtualbox.html.markdown
index b73630358..2e587588b 100644
--- a/website/source/docs/builders/virtualbox.html.markdown
+++ b/website/source/docs/builders/virtualbox.html.markdown
@@ -1,303 +1,25 @@
---
layout: "docs"
+page_title: "Amazon AMI Builder"
---
# VirtualBox Builder
-Type: `virtualbox`
+The VirtualBox builder is able to create [VirtualBox](http://www.virtualbox.org)
+virtual machines and export them in the OVA or OVF format.
-The VirtualBox builder is able to create [VirtualBox](https://www.virtualbox.org/)
-virtual machines and export them in the 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:
-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.
+* [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.
-## 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:
-
-
-{
- "type": "virtualbox",
- "guest_os_type": "Ubuntu_64",
- "iso_url": "http://releases.ubuntu.com/12.04/ubuntu-12.04.3-server-amd64.iso",
- "iso_checksum": "2cbe868812a871242cdcdd8f2fd6feb9",
- "iso_checksum_type": "md5",
- "ssh_username": "packer",
- "ssh_password": "packer",
- "ssh_wait_timeout": "30s",
- "shutdown_command": "echo 'packer' | sudo -S shutdown -P now"
-}
-
-
-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.
-
-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_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.
-
-* `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_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.
-
-* `disk_size` (int) - The size, in megabytes, of the hard disk to create
- for the VM. By default, this is 40000 (40 GB).
-
-* `floppy_files` (array of strings) - A list of files to put onto a floppy
- disk that is attached when the VM is booted for the first time. This is
- most useful for unattended Windows installs, which look for an
- `Autounattend.xml` file on removable media. By default no floppy will
- be attached. The files listed in this configuration will all be put
- into the root directory of the floppy disk; sub-directories are not supported.
-
-* `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". The functions of each of these should be
- self-explanatory. 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_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_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.
-
-* `headless` (bool) - 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_port_min` and `http_port_max` (int) - 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.
-
-* `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
- 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.
-
-* `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.
-
-* `ssh_host_port_min` and `ssh_host_port_max` (uint) - 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_key_path` (string) - Path to a private key to use for authenticating
- with SSH. By default this is not set (key-based auth won't be used).
- The associated public key is expected to already be configured on the
- VM being prepared by some other process (kickstart, etc.).
-
-* `ssh_password` (string) - The password for `ssh_username` to use to
- authenticate with SSH. By default this is the empty string.
-
-* `ssh_port` (int) - The port that SSH will be listening on in the guest
- virtual machine. By default this is 22.
-
-* `ssh_wait_timeout` (string) - The duration to wait for SSH to become
- available. By default this is "20m", or 20 minutes. Note that this should
- be quite long since the timer begins as soon as the virtual machine is booted.
-
-* `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.
-
-* `virtualbox_version_file` (string) - The path within the virtual machine
- to upload a file that contains the VirtualBox version that was used to
- create the machine. This information can be useful for provisioning.
- By default this is ".vbox_version", which will generally upload it into
- the home directory.
-
-* `vm_name` (string) - This is the name of the OVF file for the new virtual
- machine, without the file extension. By default this is "packer-BUILDNAME",
- where "BUILDNAME" is the name of the build.
-
-## 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.
-
-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:
-
-* `` and `` - Simulates an actual "enter" or "return" keypress.
-
-* `` - Simulates pressing the escape key.
-
-* `` - Simulates pressing the tab key.
-
-* `` `` `` - 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:
-
-* `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:
-
-
-[
- "<esc><esc><enter><wait>",
- "/install/vmlinuz noapic ",
- "preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed.cfg ",
- "debian-installer=en_US auto locale=en_US kbd-chooser/method=us ",
- "hostname={{ .Name }} ",
- "fb=false debconf/frontend=noninteractive ",
- "keyboard-configuration/modelcode=SKIP keyboard-configuration/layout=USA ",
- "keyboard-configuration/variant=USA console-setup/ask_detect=false ",
- "initrd=/install/initrd.gz -- <enter>"
-]
-
-
-## 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 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.
-
-## 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.
-
-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:
-
-
-{
- "vboxmanage": [
- ["modifyvm", "{{.Name}}", "--memory", "1024"],
- ["modifyvm", "{{.Name}}", "--cpus", "2"]
- ]
-}
-
-
-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.
+* [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.