website: communicator section

website/source/docs/templates/builders.html.markdown

@@ -61,3 +61,15 @@ 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.
+
+## 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).
+
+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).

website/source/docs/templates/communicator.html.md

@@ -0,0 +1,103 @@
+---
+layout: "docs"
+page_title: "Templates: Communicators"
+description: |-
+  Communicators are the mechanism Packer uses to upload files, execute scripts, etc. with the machine being created.
+---
+
+# Templates: Communicators
+
+Communicators are the mechanism Packer uses to upload files, execute
+scripts, etc. with the machine being created.
+
+Communicators are configured within the [builder](/docs/templates/builders.html)
+section. Packer currently supports three kinds of communicators:
+
+  * `none` - No communicator will be used. If this is set, most provisioners
+      also can't be used.
+
+  * `ssh` - An SSH connection will be established to the machine. This is
+      usually the default.
+
+  * `winrm` - A WinRM connection will be established.
+
+In addition to the above, some builders have custom communicators they can
+use. For example, the Docker builder has a "docker" communicator that uses
+`docker exec` and `docker cp` to execute scripts and copy files.
+
+## Using a Communicator
+
+By default, the SSH communicator is usually used. Additional configuration
+may not even be necesssary, since some builders such as Amazon automatically
+configure everything.
+
+However, to specify a communicator, you set the `communicator` key within
+a build. Multiple builds can have different communicators. Example:
+
+```javascript
+{
+    "builders": [{
+        "type": "amazon-ebs",
+        "communicator": "ssh"
+    }]
+}
+```
+
+After specifying the `communicator`, you can specify a number of other
+configuration parameters for that communicator. These are documented below.
+
+## SSH Communicator
+
+The SSH communicator has the following options:
+
+  * `ssh_host` (string) - The address to SSH to. This usually is automatically
+    configured by the builder.
+
+  * `ssh_port` (int) - The port to connect to SSH. This defaults to 22.
+
+  * `ssh_username` (string) - The username to connect to SSH with.
+
+  * `ssh_password` (string) - A plaintext password to use to authenticate
+    with SSH.
+
+  * `ssh_private_key_file` (string) - Path to a PEM encoded private key
+    file to use to authentiate with SSH.
+
+  * `ssh_pty` (bool) - If true, a PTY will be requested for the SSH connection.
+    This defaults to false.
+
+  * `ssh_timeout` (string) - The time to wait for SSH to become available.
+    Packer uses this to determine when the machine has booted so this is usually
+    quite long. Example value: "10m"
+
+  * `ssh_handshake_attempts` (int) - The number of handshakes to attempt with
+    SSH once it can connect. This defaults to 10.
+
+  * `ssh_bastion_host` (string) - A bastion host to use for the actual
+    SSH connection.
+
+  * `ssh_bastion_port` (int) - The port of the bastion host. Defaults to 22.
+
+  * `ssh_bastion_username` (string) - The username to connect to the bastion host.
+
+  * `ssh_bastion_password` (string) - The password to use to authenticate
+    with the bastion host.
+
+  * `ssh_bastion_private_key_file` (string) - A private key file to use
+    to authenticate with the bastion host.
+
+## WinRM Communicator
+
+The WinRM communicator has the following options.
+
+  * `winrm_host` (string) - The address for WinRM to connect to.
+
+  * `winrm_port` (int) - The WinRM port to connect to. This defaults to 5985.
+
+  * `winrm_username` (string) - The username to use to connect to WinRM.
+
+  * `winrm_password` (string) - The password to use to connect to WinRM.
+
+  * `winrm_timeout` (string) - The amount of time to wait for WinRM to
+    become available. This defaults to "30m" since setting up a Windows
+    machine generally takes a long time.

website/source/layouts/docs.erb

@@ -25,6 +25,7 @@
 			<li><a href="/docs/templates/provisioners.html">Provisioners</a></li>
 			<li><a href="/docs/templates/post-processors.html">Post-Processors</a></li>
 			<li><a href="/docs/templates/push.html">Push</a></li>
+			<li><a href="/docs/templates/communicator.html">Communicators</a></li>
 			<li><a href="/docs/templates/configuration-templates.html">Configuration Templates</a></li>
 			<li><a href="/docs/templates/user-variables.html">User Variables</a></li>
 			<li><a href="/docs/templates/veewee-to-packer.html">Veewee-to-Packer</a></li>