From 0378f3ad354f7baacd404c96299b4f4cdd1de825 Mon Sep 17 00:00:00 2001
From: Stephen Fox <stephen.j.fox.jr@gmail.com>
Date: Wed, 6 Feb 2019 16:03:40 -0500
Subject: [PATCH] Initial documentation for VirtualBox SSH key pair vars.

---
 .../docs/builders/virtualbox-iso.html.md.erb  |  2 +
 .../docs/builders/virtualbox-ovf.html.md.erb  |  2 +
 .../builders/_virtualbox-ssh-key-pair.html.md | 62 +++++++++++++++++++
 3 files changed, 66 insertions(+)
 create mode 100644 website/source/partials/builders/_virtualbox-ssh-key-pair.html.md

diff --git a/website/source/docs/builders/virtualbox-iso.html.md.erb b/website/source/docs/builders/virtualbox-iso.html.md.erb
index 4337cb7c8..61bf0cdee 100644
--- a/website/source/docs/builders/virtualbox-iso.html.md.erb
+++ b/website/source/docs/builders/virtualbox-iso.html.md.erb
@@ -375,6 +375,8 @@ contention. If you notice missing keys, you can tune this delay by specifying
 
 <%= partial "partials/builders/boot-command" %>
 
+<%= partial "partials/builders/virtualbox-ssh-key-pair" %>
+
 Example boot command. This is actually a working boot command used to start an
 Ubuntu 12.04 installer:
 
diff --git a/website/source/docs/builders/virtualbox-ovf.html.md.erb b/website/source/docs/builders/virtualbox-ovf.html.md.erb
index d3ca4d7ae..e22f677d8 100644
--- a/website/source/docs/builders/virtualbox-ovf.html.md.erb
+++ b/website/source/docs/builders/virtualbox-ovf.html.md.erb
@@ -317,6 +317,8 @@ contention. If you notice missing keys, you can tune this delay by specifying
 
 <%= partial "partials/builders/boot-command" %>
 
+<%= partial "partials/builders/virtualbox-ssh-key-pair" %>
+
 Example boot command. This is actually a working boot command used to start an
 Ubuntu 12.04 installer:
 
diff --git a/website/source/partials/builders/_virtualbox-ssh-key-pair.html.md b/website/source/partials/builders/_virtualbox-ssh-key-pair.html.md
new file mode 100644
index 000000000..f1f8c189c
--- /dev/null
+++ b/website/source/partials/builders/_virtualbox-ssh-key-pair.html.md
@@ -0,0 +1,62 @@
+### SSH key pair automation
+
+The VirtualBox builders can inject the current SSH key pair's public key into
+the template using the following variables:
+
+-   `SSHPublicKey` (*VirtualBox builders only*) - The SSH public key as a line
+    in OpenSSH authorized_keys format.
+-   `EncodedSSHPublicKey` (*VirtualBox builders only*) - The same as
+    `SSHPublicKey`, except it is URL encoded for usage in places
+    like the kernel command line.
+
+When a private key is provided using `ssh_private_key_file`, the key's
+corresponding public key can be accessed using the above variables.
+
+If `ssh_password` and `ssh_private_key_file` are not specified, Packer will
+automatically generate en ephemeral key pair. The key pair's public key can
+be accessed using the template variables.
+
+For example, the public key can be provided in the boot command:
+```json
+{
+    "type": "virtualbox-iso",
+    "boot_command": [
+      "<up><wait><tab> text ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/ks.cfg PACKER_USER={{ user `username` }} PACKER_AUTHORIZED_KEY={{ .EncodedSSHPublicKey }}<enter>"
+    ]
+}
+```
+
+The kickstart can then leverage those fields from the kernel command line:
+```
+%post
+
+# Newly created users need the file/folder framework for SSH key authentication.
+umask 0077
+mkdir /etc/skel/.ssh
+touch /etc/skel/.ssh/authorized_keys
+
+# Loop over the command line. Set interesting variables.
+for x in $(cat /proc/cmdline)
+do
+  case $x in
+    PACKER_USER=*)
+      PACKER_USER="${x#*=}"
+      ;;
+    PACKER_AUTHORIZED_KEY=*)
+      encoded="${x#*=}"
+      # URL decode $encoded into $PACKER_AUTHORIZED_KEY
+      printf -v PACKER_AUTHORIZED_KEY '%b' "${encoded//%/\\x}"
+      ;;
+  esac
+done
+
+# Create/configure packer user, if any.
+if [ -n "$PACKER_USER" ]
+then
+  useradd $PACKER_USER
+  echo "%$PACKER_USER ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers.d/$PACKER_USER
+  [ -n "$PACKER_AUTHORIZED_KEY" ] && echo $PACKER_AUTHORIZED_KEY >> $(eval echo ~"$PACKER_USER")/.ssh/authorized_keys
+fi
+
+%end
+```