2014-07-23 18:40:15 +02:00
---
layout: "docs"
2019-08-20 01:33:33 +02:00
page_title: "Provisioner Connection Settings"
2014-07-23 18:40:15 +02:00
sidebar_current: "docs-provisioners-connection"
2014-10-22 05:21:56 +02:00
description: |-
2016-10-09 17:42:43 +02:00
Managing connection defaults for SSH and WinRM using the `connection` block.
2014-07-23 18:40:15 +02:00
---
2019-08-20 01:33:33 +02:00
# Provisioner Connection Settings
2014-07-23 18:40:15 +02:00
2019-08-20 01:33:33 +02:00
Most provisioners require access to the remote resource via SSH or WinRM, and
expect a nested `connection` block with details about how to connect.
2014-07-23 18:40:15 +02:00
2019-09-06 00:50:04 +02:00
-> **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 ](./ ).
2019-08-20 01:33:33 +02:00
-> **Note:** In Terraform 0.11 and earlier, providers could set default values
for some connection settings, so that `connection` blocks could sometimes be
omitted. This feature was removed in 0.12 in order to make Terraform's behavior
more predictable.
2020-06-24 14:09:06 +02:00
-> **Note:** Since the SSH connection type is most often used with
newly-created remote resources, validation of SSH host keys is disabled by
default. In scenarios where this is not acceptable, a separate mechanism for
key distribution could be established and the `host_key` directive documented
below explicitly set to verify against a specific key or signing CA.
2019-08-20 01:33:33 +02:00
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.
One use case for providing multiple connections is to have an initial
provisioner connect as the `root` user to set up user accounts, and have
subsequent provisioners connect as a user with more limited permissions.
2014-07-23 18:40:15 +02:00
## Example usage
2017-04-05 17:29:27 +02:00
```hcl
2015-04-10 21:28:28 +02:00
# Copies the file as the root user using SSH
2014-07-23 18:40:15 +02:00
provisioner "file" {
2017-02-18 23:48:50 +01:00
source = "conf/myapp.conf"
destination = "/etc/myapp.conf"
connection {
type = "ssh"
user = "root"
password = "${var.root_password}"
2019-08-28 21:34:22 +02:00
host = "${var.host}"
2017-02-18 23:48:50 +01:00
}
2014-07-23 18:40:15 +02:00
}
2015-04-10 21:28:28 +02:00
# Copies the file as the Administrator user using WinRM
provisioner "file" {
2017-02-18 23:48:50 +01:00
source = "conf/myapp.conf"
destination = "C:/App/myapp.conf"
connection {
type = "winrm"
user = "Administrator"
password = "${var.admin_password}"
2019-08-28 21:34:22 +02:00
host = "${var.host}"
2017-02-18 23:48:50 +01:00
}
2015-04-10 21:28:28 +02:00
}
2014-07-23 18:40:15 +02:00
```
2019-08-20 01:33:33 +02:00
## The `self` Object
Expressions in `connection` blocks cannot refer to their parent resource by
name. Instead, they can use the special `self` object.
The `self` object represents the connection's parent resource, and has all of
that resource's attributes. For example, use `self.public_ip` to reference an
`aws_instance` 's `public_ip` attribute.
-> **Technical note:** Resource references are restricted here because
references create dependencies. Referring to a resource by name within its own
block would create a dependency cycle.
2014-07-23 18:40:15 +02:00
## Argument Reference
2015-04-10 21:28:28 +02:00
**The following arguments are supported by all connection types:**
2014-07-23 18:40:15 +02:00
2019-08-20 01:33:33 +02:00
* `type` - The connection type that should be used. Valid types are `ssh` and `winrm` .
2019-08-16 17:43:10 +02:00
Defaults to `ssh` .
2014-07-23 18:40:15 +02:00
2019-08-20 01:33:33 +02:00
* `user` - The user that we should use for the connection.
2019-08-16 17:43:10 +02:00
Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm` .
2014-07-23 18:40:15 +02:00
2015-04-10 21:28:28 +02:00
* `password` - The password we should use for the connection. In some cases this is
2016-10-09 17:42:43 +02:00
specified by the provider.
2015-04-10 21:28:28 +02:00
2019-09-06 00:50:04 +02:00
* `host` - (Required) The address of the resource to connect to.
2015-04-10 21:28:28 +02:00
2019-08-20 01:33:33 +02:00
* `port` - The port to connect to.
2019-08-16 17:43:10 +02:00
Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm` .
2015-04-10 21:28:28 +02:00
2019-08-20 01:33:33 +02:00
* `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m` .
2019-08-16 17:43:10 +02:00
Defaults to 5 minutes.
2015-04-10 21:28:28 +02:00
2016-04-16 00:05:49 +02:00
* `script_path` - The path used to copy scripts meant for remote execution.
2015-04-10 21:28:28 +02:00
2016-10-09 17:42:43 +02:00
**Additional arguments only supported by the `ssh` connection type:**
2014-07-23 18:40:15 +02:00
2015-11-12 21:39:41 +01:00
* `private_key` - The contents of an SSH key to use for the connection. These can
2018-05-14 01:59:18 +02:00
be loaded from a file on disk using
[the `file` function ](/docs/configuration/functions/file.html ). This takes
2015-11-12 21:39:41 +01:00
preference over the password if provided.
2014-07-23 18:40:15 +02:00
2018-09-19 02:36:39 +02:00
* `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 ).
2016-10-09 17:42:43 +02:00
* `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the
2015-12-15 16:39:23 +01:00
only supported SSH authentication agent is
2016-10-09 17:42:43 +02:00
[Pageant ](http://the.earth.li/~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant ).
2015-03-16 00:37:33 +01:00
2018-01-08 23:12:55 +01:00
* `agent_identity` - The preferred identity from the ssh agent for authentication.
2018-02-14 21:30:18 +01:00
* `host_key` - The public key from the remote host or the signing CA, used to
verify the connection.
2016-10-09 17:42:43 +02:00
**Additional arguments only supported by the `winrm` connection type:**
2014-07-23 18:40:15 +02:00
2016-10-09 17:42:43 +02:00
* `https` - Set to `true` to connect using HTTPS instead of HTTP.
2014-07-23 18:40:15 +02:00
2016-10-09 17:42:43 +02:00
* `insecure` - Set to `true` to not validate the HTTPS certificate chain.
2014-07-23 18:40:15 +02:00
2018-03-31 03:11:53 +02:00
* `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).
2015-04-10 21:28:28 +02:00
* `cacert` - The CA certificate to validate against.
2015-06-22 18:34:02 +02:00
< a id = "bastion" > < / a >
2018-05-14 01:59:18 +02:00
2015-06-22 18:34:02 +02:00
## Connecting through a Bastion Host with SSH
2016-10-09 17:42:43 +02:00
The `ssh` connection also supports the following fields to facilitate connnections via a
[bastion host ](https://en.wikipedia.org/wiki/Bastion_host ).
2015-06-22 18:34:02 +02:00
* `bastion_host` - Setting this enables the bastion Host connection. This host
2016-10-09 17:42:43 +02:00
will be connected to first, and then the `host` connection will be made from there.
2015-06-22 18:34:02 +02:00
2018-02-14 21:30:18 +01:00
* `bastion_host_key` - The public key from the remote host or the signing CA,
used to verify the host connection.
2015-06-22 18:34:02 +02:00
* `bastion_port` - The port to use connect to the bastion host. Defaults to the
2016-10-09 17:42:43 +02:00
value of the `port` field.
2015-06-22 18:34:02 +02:00
2016-10-09 17:42:43 +02:00
* `bastion_user` - The user for the connection to the bastion host. Defaults to
the value of the `user` field.
2015-06-22 18:34:02 +02:00
* `bastion_password` - The password we should use for the bastion host.
2016-10-09 17:42:43 +02:00
Defaults to the value of the `password` field.
2015-06-22 18:34:02 +02:00
2015-11-12 21:39:41 +01:00
* `bastion_private_key` - The contents of an SSH key file to use for the bastion
2018-05-14 01:59:18 +02:00
host. These can be loaded from a file on disk using
[the `file` function ](/docs/configuration/functions/file.html ).
2016-10-09 17:42:43 +02:00
Defaults to the value of the `private_key` field.
2019-07-21 08:32:48 +02:00
* `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 ).