github.com/ratanraj/packer@v1.3.2/website/source/docs/templates/communicator.html.md (about)

     1  ---
     2  description: |
     3      Communicators are the mechanism Packer uses to upload files, execute scripts,
     4      etc. with the machine being created.
     5  layout: docs
     6  page_title: 'Communicators - Templates'
     7  sidebar_current: 'docs-templates-communicators'
     8  ---
     9  
    10  # Template Communicators
    11  
    12  Communicators are the mechanism Packer uses to upload files, execute
    13  scripts, etc. with the machine being created.
    14  
    15  Communicators are configured within the [builder](/docs/templates/builders.html)
    16  section. Packer currently supports three kinds of communicators:
    17  
    18  -   `none` - No communicator will be used. If this is set, most provisioners
    19      also can't be used.
    20  
    21  -   `ssh` - An SSH connection will be established to the machine. This is
    22      usually the default.
    23  
    24  -   `winrm` - A WinRM connection will be established.
    25  
    26  In addition to the above, some builders have custom communicators they can
    27  use. For example, the Docker builder has a "docker" communicator that uses
    28  `docker exec` and `docker cp` to execute scripts and copy files.
    29  
    30  ## Using a Communicator
    31  
    32  By default, the SSH communicator is usually used. Additional configuration
    33  may not even be necessary, since some builders such as Amazon automatically
    34  configure everything.
    35  
    36  However, to specify a communicator, you set the `communicator` key within
    37  a build. Multiple builds can have different communicators. Example:
    38  
    39  ``` json
    40  {
    41    "builders": [
    42      {
    43        "type": "amazon-ebs",
    44        "communicator": "ssh"
    45      }
    46    ]
    47  }
    48  ```
    49  
    50  After specifying the `communicator`, you can specify a number of other
    51  configuration parameters for that communicator. These are documented below.
    52  
    53  ## SSH Communicator
    54  
    55  The SSH communicator connects to the host via SSH. If you have an SSH agent
    56  configured on the host running Packer, and SSH agent authentication is enabled
    57  in the communicator config, Packer will automatically forward the SSH agent
    58  to the remote host.
    59  
    60  The SSH communicator has the following options:
    61  
    62  -   `ssh_agent_auth` (boolean) - If `true`, the local SSH agent will be used to
    63      authenticate connections to the remote host. Defaults to `false`.
    64  
    65  -   `ssh_bastion_agent_auth` (boolean) - If `true`, the local SSH agent will
    66      be used to authenticate with the bastion host. Defaults to `false`.
    67  
    68  -   `ssh_bastion_host` (string) - A bastion host to use for the actual
    69      SSH connection.
    70  
    71  -   `ssh_bastion_password` (string) - The password to use to authenticate
    72      with the bastion host.
    73  
    74  -   `ssh_bastion_port` (number) - The port of the bastion host. Defaults to `22`.
    75  
    76  -   `ssh_bastion_private_key_file` (string) - A private key file to use
    77      to authenticate with the bastion host.
    78  
    79  -   `ssh_bastion_username` (string) - The username to connect to the bastion
    80      host.
    81  
    82  -   `ssh_clear_authorized_keys` (boolean) - If true, Packer will attempt to
    83      remove its temporary key from `~/.ssh/authorized_keys` and
    84      `/root/.ssh/authorized_keys`. This is a mostly cosmetic option, since Packer
    85      will delete the temporary private key from the host system regardless of
    86      whether this is set to true (unless the user has set the `-debug` flag).
    87      Defaults to "false"; currently only works on guests with `sed` installed.
    88  
    89  -   `ssh_disable_agent_forwarding` (boolean) - If true, SSH agent forwarding
    90      will be disabled. Defaults to `false`.
    91  
    92  -   `ssh_file_transfer_method` (`scp` or `sftp`) - How to transfer files, Secure
    93      copy (default) or SSH File Transfer Protocol.
    94  
    95  -   `ssh_handshake_attempts` (number) - The number of handshakes to attempt
    96      with SSH once it can connect. This defaults to `10`.
    97  
    98  -   `ssh_host` (string) - The address to SSH to. This usually is automatically
    99      configured by the builder.
   100  
   101  *   `ssh_keep_alive_interval` (string) - How often to send "keep alive"
   102      messages to the server. Set to a negative value (`-1s`) to disable. Example
   103      value: `10s`. Defaults to `5s`.
   104  
   105  -   `ssh_password` (string) - A plaintext password to use to authenticate
   106      with SSH.
   107  
   108  -   `ssh_port` (number) - The port to connect to SSH. This defaults to `22`.
   109  
   110  -   `ssh_private_key_file` (string) - Path to a PEM encoded private key
   111      file to use to authenticate with SSH.
   112  
   113  -   `ssh_proxy_host` (string) - A SOCKS proxy host to use for SSH connection
   114  
   115  -   `ssh_proxy_password` (string) - The password to use to authenticate with
   116      the proxy server. Optional.
   117  
   118  -   `ssh_proxy_port` (number) - A port of the SOCKS proxy. Defaults to `1080`.
   119  
   120  -   `ssh_proxy_username` (string) - The username to authenticate with the proxy
   121      server. Optional.
   122  
   123  -   `ssh_pty` (boolean) - If `true`, a PTY will be requested for the SSH
   124      connection. This defaults to `false`.
   125  
   126  *   `ssh_read_write_timeout` (string) - The amount of time to wait for a remote
   127      command to end. This might be useful if, for example, packer hangs on
   128      a connection after a reboot. Example: `5m`. Disabled by default.
   129  
   130  -   `ssh_timeout` (string) - The time to wait for SSH to become available.
   131      Packer uses this to determine when the machine has booted so this is
   132      usually quite long. Example value: `10m`.
   133  
   134  -   `ssh_username` (string) - The username to connect to SSH with. Required
   135      if using SSH.
   136  
   137  ### SSH Communicator Details
   138  
   139  Packer will only use one authentication method, either `publickey` or if
   140  `ssh_password` is used packer will offer `password` and `keyboard-interactive`
   141  both sending the password. In other words Packer will not work with _sshd_
   142  configured with more than one configured authentication method using
   143  `AuthenticationMethods`.
   144  
   145  Packer supports the following ciphers:
   146  
   147  - aes128-ctr
   148  - aes192-ctr
   149  - aes256-ctr
   150  - arcfour128
   151  - arcfour256
   152  - arcfour
   153  - es128-gcm@openssh.com
   154  - acha20-poly1305@openssh.com
   155  
   156  And the following MACs:
   157  
   158  - hmac-sha1
   159  - hmac-sha1-96
   160  - hmac-sha2-256
   161  - hmac-sha2-256-etm@openssh.com
   162  
   163  ## WinRM Communicator
   164  
   165  The WinRM communicator has the following options.
   166  
   167  -   `winrm_host` (string) - The address for WinRM to connect to.
   168  
   169  -   `winrm_insecure` (boolean) - If `true`, do not check server certificate
   170      chain and host name.
   171  
   172  -   `winrm_password` (string) - The password to use to connect to WinRM.
   173  
   174  -   `winrm_port` (number) - The WinRM port to connect to. This defaults to
   175      `5985` for plain unencrypted connection and `5986` for SSL when
   176      `winrm_use_ssl` is set to true.
   177  
   178  -   `winrm_timeout` (string) - The amount of time to wait for WinRM to
   179      become available. This defaults to `30m` since setting up a Windows
   180      machine generally takes a long time.
   181  
   182  -   `winrm_use_ntlm` (boolean) - If `true`, NTLMv2 authentication (with
   183      session security) will be used for WinRM, rather than
   184      default (basic authentication), removing the requirement for basic
   185      authentication to be enabled within the target guest. Further reading
   186      for remote connection authentication can be found
   187      [here](https://msdn.microsoft.com/en-us/library/aa384295(v=vs.85).aspx).
   188  
   189  -   `winrm_use_ssl` (boolean) - If `true`, use HTTPS for WinRM.
   190  
   191  -   `winrm_username` (string) - The username to use to connect to WinRM.