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.

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​

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.

Connection settings can be configured using ephemeral values, such as attributes from ephemeral resources, and ephemeral input variables.

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:

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:

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:

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.