terraform/website/docs/provisioners/connection.html.markdown

---
layout: "docs"
page_title: "Provisioner Connections"
sidebar_current: "docs-provisioners-connection"
description: |-
  Managing connection defaults for SSH and WinRM using the `connection` block.
---

# Provisioner Connections

Many provisioners require access to the remote resource. For example,
a provisioner may need to use SSH or WinRM to connect to the resource.

-> **Note:** Provisioners should only be used as a last resort. For most
common situations there are better alternatives. For more information, see
[the main Provisioners page](./).

Terraform uses a number of defaults when connecting to a resource, but these can
be overridden using a `connection` block in either a `resource` or
`provisioner`. Any `connection` information provided in a `resource` will apply
to all the provisioners, but it can be scoped to a single provisioner as well.
One use case is to have an initial provisioner connect as the `root` user to
setup user accounts, and have subsequent provisioners connect as a user with
more limited permissions.

## Example usage

```hcl
# Copies the file as the root user using SSH
provisioner "file" {
  source      = "conf/myapp.conf"
  destination = "/etc/myapp.conf"

  connection {
    type     = "ssh"
    user     = "root"
    password = "${var.root_password}"
    host     = "${var.host}"
  }
}

# Copies the file as the Administrator user using WinRM
provisioner "file" {
  source      = "conf/myapp.conf"
  destination = "C:/App/myapp.conf"

  connection {
    type     = "winrm"
    user     = "Administrator"
    password = "${var.admin_password}"
    host     = "${var.host}"
  }
}
```

## Argument Reference

**The following arguments are supported by all connection types:**

* `type` - The connection type that should be used. Valid types are `ssh` and `winrm`.  
           Defaults to `ssh`.

* `user` - The user that we should use for the connection.  
           Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`.

* `password` - The password we should use for the connection. In some cases this is
  specified by the provider.

* `host` - (Required) The address of the resource to connect to.

* `port` - The port to connect to.  
           Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`.

* `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`.   
              Defaults to 5 minutes.

* `script_path` - The path used to copy scripts meant for remote execution.

**Additional arguments only supported by the `ssh` connection type:**

* `private_key` - The contents of an SSH key to use for the connection. These can
  be loaded from a file on disk using
  [the `file` function](/docs/configuration/functions/file.html). This takes
  preference over the password if provided.

* `certificate` - The contents of a signed CA Certificate. The certificate argument must be
  used in conjunction with a `private_key`. These can
  be loaded from a file on disk using the [the `file` function](/docs/configuration/functions/file.html).

* `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the
  only supported SSH authentication agent is
  [Pageant](http://the.earth.li/~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant).

* `agent_identity` - The preferred identity from the ssh agent for authentication.

* `host_key` - The public key from the remote host or the signing CA, used to
  verify the connection.

**Additional arguments only supported by the `winrm` connection type:**

* `https` - Set to `true` to connect using HTTPS instead of HTTP.

* `insecure` - Set to `true` to not validate the HTTPS certificate chain.

* `use_ntlm` - Set to `true` to use NTLM authentication, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. Further reading for remote connection authentication can be found [here](https://msdn.microsoft.com/en-us/library/aa384295(v=vs.85).aspx).

* `cacert` - The CA certificate to validate against.

<a id="bastion"></a>

## Connecting through a Bastion Host with SSH

The `ssh` connection also supports the following fields to facilitate connnections via a
[bastion host](https://en.wikipedia.org/wiki/Bastion_host).

* `bastion_host` - Setting this enables the bastion Host connection. This host
  will be connected to first, and then the `host` connection will be made from there.

* `bastion_host_key` - The public key from the remote host or the signing CA,
  used to verify the host connection.

* `bastion_port` - The port to use connect to the bastion host. Defaults to the
  value of the `port` field.

* `bastion_user` - The user for the connection to the bastion host. Defaults to
  the value of the `user` field.

* `bastion_password` - The password we should use for the bastion host.
  Defaults to the value of the `password` field.

* `bastion_private_key` - The contents of an SSH key file to use for the bastion
  host. These can be loaded from a file on disk using
  [the `file` function](/docs/configuration/functions/file.html).
  Defaults to the value of the `private_key` field.

* `bastion_certificate` - The contents of a signed CA Certificate. The certificate argument
  must be used in conjunction with a `bastion_private_key`. These can be loaded from
  a file on disk using the [the `file` function](/docs/configuration/functions/file.html).