---
description: >-
  The connection block describes connection settings for the remote-exec and file provisioners.
---

# Provisioner Connection Settings

The `remote-exec` and `file` provisioners access a remote system using the
Secure Shell (SSH) protocol. These provisioners must therefore be used with
a `connection` block that describes how to connect.

:::warning Important
Use provisioners as a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](../../../language/resources/provisioners/syntax.mdx) for more details.
:::

## Connection Block

You can create one or more `connection` blocks that describe how to access the remote system.

Connection blocks don't take a block label and can be nested within either a
`resource` or a `provisioner`.

* A `connection` block nested directly within a `resource` affects all of
  that resource's provisioners.
* A `connection` block nested in a `provisioner` block only affects that
  provisioner and overrides any resource-level connection settings.

A `connection` block at the resource level is most common, but overriding the
connection settings for just one of a series of provisioners can be useful if,
for example, the first provisioner uses administrative access to create another
user account and then the remaining provisioners use that new user account.

Remote provisioners are most often used with newly-created servers, and so
validation of host SSH keys is disabled by default. If that is not acceptable
then you can set the `host_key` argument to require the use of a specific key
or of a certificate signed by a specific certificate authority.

### Example usage

```hcl
provisioner "file" {
  source      = "conf/myapp.conf"
  destination = "/etc/myapp.conf"

  connection {
    user     = "root"
    password = var.root_password
    host     = var.host
  }
}
```

### Argument Reference

The `connection` block supports the following arguments.

| Argument | Description | Default |
|----------|-------------|---------|
| `user` | The user to use for the connection. | `root` |
| `password` | The password to use for the connection. | |
| `host` | **Required** - The address of the resource to connect to. | |
| `port` | The port to connect to. | `22` |
| `timeout` | The timeout to wait for the connection to become available. Should be provided as a string (e.g., `"30s"` or `"5m"`.) | `"5m"` |
| `script_path` | The path used to copy scripts meant for remote execution. Refer to [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below for more details. | (details below) |
| `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](../../../language/functions/file.mdx). This takes preference over `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](../../../language/functions/file.mdx). | |
| `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. | |
| `target_platform` | The target platform to connect to. Valid values are `"windows"` and `"unix"`. If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` | `"unix"` |
| `bastion_host` | <a id="bastion"></a>Setting this forces using the given hostname as a [bastion host](https://en.wikipedia.org/wiki/Bastion_host). The provisioner will connect to `bastion_host` first, and then connect from there to `host`. | |
| `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. | The value of the `port` field.|
| `bastion_user`| The user for the connection to the bastion host. | The value of the `user` field. |
| `bastion_password` | The password to use for the bastion host. | 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](../../../language/functions/file.mdx). | 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](../../../language/functions/file.mdx). |
| `proxy_host` | Setting this enables the SSH over HTTP connection. This host will be connected to first, and then the `host` or `bastion_host` connection will be made from there. | |
| `proxy_scheme` | http or https | |
| `proxy_port` | The port to use connect to the proxy host. | |
| `proxy_user_name` | The username to use connect to the private proxy host. This argument should be specified only if authentication is required for the HTTP Proxy server. | |
| `proxy_user_password` | The password to use connect to the private proxy host. This argument should be specified only if authentication is required for the HTTP Proxy server. | |

<a id="ephemeral-usage"></a>

Connection settings can be configured using [ephemeral values](../../ephemerality/index.mdx), such as attributes from ephemeral resources, and ephemeral input variables.

:::warning
Although a connection block's values are not referenceable in other contexts, the provisioner may produce output logs that contain values from it's connection configuration.
:::

### The `self` Object

Expressions in `connection` blocks cannot refer to their parent resource by
name: references create dependencies, and referring to a resource by name within
its own block would create a dependency cycle.

Instead, expressions can use the `self` object, which represents the
resource instance being provisioned and has all of that object's attributes. For
example, use `self.public_ip` to refer to an `aws_instance`'s `public_ip`
attribute.

## How Provisioners Execute Remote Scripts

Provisioners which execute commands on a remote system achieve that by
uploading a script file to the remote system and then asking the default shell
to execute it. Provisioners use this strategy because it then allows you to use
all of the typical scripting techniques supported by that shell, including
preserving environment variable values and other context between script
statements.

However, this approach does have some consequences which can be relevant in
some unusual situations, even though this is just an implementation detail
in typical use.

Most importantly, there must be a suitable location in the remote filesystem
where the provisioner can create the script file. By default, OpenTofu
chooses a path containing a random number using the following patterns
depending on how `target_platform` is set:

* `"unix"`: `/tmp/terraform_%RAND%.sh`
* `"windows"`: `C:/windows/temp/terraform_%RAND%.cmd`

In both cases above, the provisioner replaces the sequence `%RAND%` with
some randomly-chosen decimal digits.

Provisioners cannot react directly to remote environment variables such as
`TMPDIR` or use functions like `mktemp` because they run on the system where
OpenTofu is running, not on the remote system. Therefore if your remote
system doesn't use the filesystem layout expected by these default paths
then you can override it using the `script_path` option in your `connection`
block:

```hcl
connection {
  # ...
  script_path = "H:/tofu-temp/script_%RAND%.sh"
}
```

As with the default patterns, provisioners will replace the sequence `%RAND%`
with randomly-selected decimal digits, to reduce the likelihood of collisions
between multiple provisioners running concurrently.

If your target system is running Windows, we recommend using forward slashes
instead of backslashes, despite the typical convention on Windows, because
the OpenTofu language uses backslash as the quoted string escape character.

Provisioners upload their script files using the Secure Copy Protocol (SCP),
which requires that the remote system have the `scp` service program installed
to act as the server for that protocol.

Provisioners will pass the chosen script path (after `%RAND%`
expansion) directly to the remote `scp` process, which is responsible for
interpreting it. With the default configuration of `scp` as distributed with
OpenSSH, you can place temporary scripts in the home directory of the remote
user by specifying a relative path:

```hcl
connection {
  # ...
  script_path = "tofu_provisioner_%RAND%.sh"
}
```

### WinRM Connections (Deprecated)

OpenTofu v1.11 and earlier allowed connecting to Windows systems using
Microsoft's WinRM protocol, as an alternative to SSH. WinRM support is
deprecated in OpenTofu v1.12, and we expect to remove it completely in
OpenTofu v1.13.

When using WinRM instead of SSH, the `connection` block expects different
arguments:

| Argument | Description | Default |
|----------|-------------|---------|
| `type` | **Required** when using WinRM. Set this to `"winrm"` to activate the other arguments in this table. | |
| `user` | The user to use for the connection. | `Administrator` |
| `password` | The password to use for the connection. | |
| `host` | **Required** - The address of the resource to connect to. | |
| `port` | The port to connect to. | `5985` |
| `timeout` | The timeout to wait for the connection to become available. Should be provided as a string (e.g., `"30s"` or `"5m"`.) | `"5m"` |
| `script_path` | The path used to copy scripts meant for remote execution. Refer to [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) above for more details. | (details above) |
| `https` | Set to `true` to connect using HTTPS instead of HTTP. | |
| `insecure` | Set to `true` to skip validating 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. Refer to [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation for more details. | |
| `cacert` | The CA certificate to validate against. | |

Any `connection` block with `type = "winrm"` will produce a deprecation warning
in OpenTofu v1.12, and will be rejected with an error in OpenTofu v1.13 and
later. We recommend that anyone currently using WinRM begin planning to migrate
to using SSH.
