From 3a5b9e8546240bac964875aa25aff9903e77dedd Mon Sep 17 00:00:00 2001
From: Taliesin Sisson <taliesins@yahoo.com>
Date: Tue, 2 Aug 2016 21:58:04 +0100
Subject: [PATCH] Add missing boot_command documentation.

---
 .../docs/builders/virtualbox-ovf.html.md      | 88 +++++++++++++++++++
 .../source/docs/builders/vmware-vmx.html.md   | 88 +++++++++++++++++++
 2 files changed, 176 insertions(+)

diff --git a/website/source/docs/builders/virtualbox-ovf.html.md b/website/source/docs/builders/virtualbox-ovf.html.md
index 0e53b0316..302d94683 100644
--- a/website/source/docs/builders/virtualbox-ovf.html.md
+++ b/website/source/docs/builders/virtualbox-ovf.html.md
@@ -215,6 +215,94 @@ builder.
     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.
+
+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:
+
+-   `<bs>` - Backspace
+
+-   `<del>` - Delete
+
+-   `<enter>` and `<return>` - Simulates an actual "enter" or "return" keypress.
+
+-   `<esc>` - Simulates pressing the escape key.
+
+-   `<tab>` - Simulates pressing the tab key.
+
+-   `<f1>` - `<f12>` - Simulates pressing a function key.
+
+-   `<up>` `<down>` `<left>` `<right>` - Simulates pressing an arrow key.
+
+-   `<spacebar>` - Simulates pressing the spacebar.
+
+-   `<insert>` - Simulates pressing the insert key.
+
+-   `<home>` `<end>` - Simulates pressing the home and end keys.
+
+-   `<pageUp>` `<pageDown>` - Simulates pressing the page up and page down keys.
+
+-   `<leftAlt>` `<rightAlt>`  - Simulates pressing the alt key.
+
+-   `<leftCtrl>` `<rightCtrl>` - Simulates pressing the ctrl key.
+
+-   `<leftShift>` `<rightShift>` - Simulates pressing the shift key.
+
+-   `<leftAltOn>` `<rightAltOn>`  - Simulates pressing and holding the alt key.
+
+-   `<leftCtrlOn>` `<rightCtrlOn>` - Simulates pressing and holding the ctrl key. 
+
+-   `<leftShiftOn>` `<rightShiftOn>` - Simulates pressing and holding the shift key.
+
+-   `<leftAltOff>` `<rightAltOff>`  - Simulates releasing a held alt key.
+
+-   `<leftCtrlOff>` `<rightCtrlOff>` - Simulates releasing a held ctrl key.
+
+-   `<leftShiftOff>` `<rightShiftOff>` - Simulates releasing a held shift key.
+
+-   `<wait>` `<wait5>` `<wait10>` - 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.
+
+When using modifier keys `ctrl`, `alt`, `shift` ensure that you release them, otherwise they will be held down until the machine reboots. Use lowercase characters as well inside modifiers. For example: to simulate ctrl+c use `<leftCtrlOn>c<leftCtrlOff>`.
+
+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:
+
+``` {.text}
+[
+  "<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
diff --git a/website/source/docs/builders/vmware-vmx.html.md b/website/source/docs/builders/vmware-vmx.html.md
index fc30811c7..e26c6f0c4 100644
--- a/website/source/docs/builders/vmware-vmx.html.md
+++ b/website/source/docs/builders/vmware-vmx.html.md
@@ -153,3 +153,91 @@ builder.
     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.
+
+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:
+
+-   `<bs>` - Backspace
+
+-   `<del>` - Delete
+
+-   `<enter>` and `<return>` - Simulates an actual "enter" or "return" keypress.
+
+-   `<esc>` - Simulates pressing the escape key.
+
+-   `<tab>` - Simulates pressing the tab key.
+
+-   `<f1>` - `<f12>` - Simulates pressing a function key.
+
+-   `<up>` `<down>` `<left>` `<right>` - Simulates pressing an arrow key.
+
+-   `<spacebar>` - Simulates pressing the spacebar.
+
+-   `<insert>` - Simulates pressing the insert key.
+
+-   `<home>` `<end>` - Simulates pressing the home and end keys.
+
+-   `<pageUp>` `<pageDown>` - Simulates pressing the page up and page down keys.
+
+-   `<leftAlt>` `<rightAlt>`  - Simulates pressing the alt key.
+
+-   `<leftCtrl>` `<rightCtrl>` - Simulates pressing the ctrl key.
+
+-   `<leftShift>` `<rightShift>` - Simulates pressing the shift key.
+
+-   `<leftAltOn>` `<rightAltOn>`  - Simulates pressing and holding the alt key.
+
+-   `<leftCtrlOn>` `<rightCtrlOn>` - Simulates pressing and holding the ctrl key. 
+
+-   `<leftShiftOn>` `<rightShiftOn>` - Simulates pressing and holding the shift key.
+
+-   `<leftAltOff>` `<rightAltOff>`  - Simulates releasing a held alt key.
+
+-   `<leftCtrlOff>` `<rightCtrlOff>` - Simulates releasing a held ctrl key.
+
+-   `<leftShiftOff>` `<rightShiftOff>` - Simulates releasing a held shift key.
+
+-   `<wait>` `<wait5>` `<wait10>` - 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.
+
+When using modifier keys `ctrl`, `alt`, `shift` ensure that you release them, otherwise they will be held down until the machine reboots. Use lowercase characters as well inside modifiers. For example: to simulate ctrl+c use `<leftCtrlOn>c<leftCtrlOff>`.
+
+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:
+
+``` {.text}
+[
+  "<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>"
+]
+```
\ No newline at end of file