website: communicator section

This commit is contained in:
Mitchell Hashimoto 2015-06-23 14:39:29 -07:00
parent 0ed15e039a
commit 4244a6ce8d
3 changed files with 116 additions and 0 deletions

View File

@ -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).

View File

@ -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.

View File

@ -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>