github.com/hugorut/terraform@v1.1.3/website/docs/language/resources/provisioners/connection.mdx (about) 1 --- 2 page_title: Provisioner Connection Settings 3 description: >- 4 The connection block allows you to manage provisioner connection defaults for 5 SSH and WinRM. 6 --- 7 8 # Provisioner Connection Settings 9 10 Most provisioners require access to the remote resource via SSH or WinRM, and 11 expect a nested `connection` block with details about how to connect. 12 13 -> **Note:** Provisioners should only be used as a last resort. For most 14 common situations there are better alternatives. For more information, see 15 [the main Provisioners page](/language/resources/provisioners). 16 17 -> **Note:** In Terraform 0.11 and earlier, providers could set default values 18 for some connection settings, so that `connection` blocks could sometimes be 19 omitted. This feature was removed in 0.12 in order to make Terraform's behavior 20 more predictable. 21 22 -> **Note:** Since the SSH connection type is most often used with 23 newly-created remote resources, validation of SSH host keys is disabled by 24 default. In scenarios where this is not acceptable, a separate mechanism for 25 key distribution could be established and the `host_key` directive documented 26 below explicitly set to verify against a specific key or signing CA. 27 28 Connection blocks don't take a block label, and can be nested within either a 29 `resource` or a `provisioner`. 30 31 * A `connection` block nested directly within a `resource` affects all of 32 that resource's provisioners. 33 * A `connection` block nested in a `provisioner` block only affects that 34 provisioner, and overrides any resource-level connection settings. 35 36 One use case for providing multiple connections is to have an initial 37 provisioner connect as the `root` user to set up user accounts, and have 38 subsequent provisioners connect as a user with more limited permissions. 39 40 ## Example usage 41 42 ```hcl 43 # Copies the file as the root user using SSH 44 provisioner "file" { 45 source = "conf/myapp.conf" 46 destination = "/etc/myapp.conf" 47 48 connection { 49 type = "ssh" 50 user = "root" 51 password = "${var.root_password}" 52 host = "${var.host}" 53 } 54 } 55 56 # Copies the file as the Administrator user using WinRM 57 provisioner "file" { 58 source = "conf/myapp.conf" 59 destination = "C:/App/myapp.conf" 60 61 connection { 62 type = "winrm" 63 user = "Administrator" 64 password = "${var.admin_password}" 65 host = "${var.host}" 66 } 67 } 68 ``` 69 70 ## The `self` Object 71 72 Expressions in `connection` blocks cannot refer to their parent resource by 73 name. Instead, they can use the special `self` object. 74 75 The `self` object represents the connection's parent resource, and has all of 76 that resource's attributes. For example, use `self.public_ip` to reference an 77 `aws_instance`'s `public_ip` attribute. 78 79 -> **Technical note:** Resource references are restricted here because 80 references create dependencies. Referring to a resource by name within its own 81 block would create a dependency cycle. 82 83 ## Argument Reference 84 85 **The following arguments are supported by all connection types:** 86 87 * `type` - The connection type that should be used. Valid types are `ssh` and `winrm`. 88 Defaults to `ssh`. 89 90 * `user` - The user that we should use for the connection. 91 Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`. 92 93 * `password` - The password we should use for the connection. In some cases this is 94 specified by the provider. 95 96 * `host` - (Required) The address of the resource to connect to. 97 98 * `port` - The port to connect to. 99 Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`. 100 101 * `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`. 102 Defaults to 5 minutes. 103 104 * `script_path` - The path used to copy scripts meant for remote execution. 105 106 **Additional arguments only supported by the `ssh` connection type:** 107 108 * `private_key` - The contents of an SSH key to use for the connection. These can 109 be loaded from a file on disk using 110 [the `file` function](/language/functions/file). This takes 111 preference over the password if provided. 112 113 * `certificate` - The contents of a signed CA Certificate. The certificate argument must be 114 used in conjunction with a `private_key`. These can 115 be loaded from a file on disk using the [the `file` function](/language/functions/file). 116 117 * `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the 118 only supported SSH authentication agent is 119 [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). 120 121 * `agent_identity` - The preferred identity from the ssh agent for authentication. 122 123 * `host_key` - The public key from the remote host or the signing CA, used to 124 verify the connection. 125 126 * `target_platform` - The target platform to connect to. Valid values are `windows` and `unix`. Defaults to `unix` if not set. 127 128 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"` 129 130 **Additional arguments only supported by the `winrm` connection type:** 131 132 * `https` - Set to `true` to connect using HTTPS instead of HTTP. 133 134 * `insecure` - Set to `true` to not validate the HTTPS certificate chain. 135 136 * `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://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections?redirectedfrom=MSDN). 137 138 * `cacert` - The CA certificate to validate against. 139 140 <a id="bastion"></a> 141 142 ## Connecting through a Bastion Host with SSH 143 144 The `ssh` connection also supports the following fields to facilitate connnections via a 145 [bastion host](https://en.wikipedia.org/wiki/Bastion_host). 146 147 * `bastion_host` - Setting this enables the bastion Host connection. This host 148 will be connected to first, and then the `host` connection will be made from there. 149 150 * `bastion_host_key` - The public key from the remote host or the signing CA, 151 used to verify the host connection. 152 153 * `bastion_port` - The port to use connect to the bastion host. Defaults to the 154 value of the `port` field. 155 156 * `bastion_user` - The user for the connection to the bastion host. Defaults to 157 the value of the `user` field. 158 159 * `bastion_password` - The password we should use for the bastion host. 160 Defaults to the value of the `password` field. 161 162 * `bastion_private_key` - The contents of an SSH key file to use for the bastion 163 host. These can be loaded from a file on disk using 164 [the `file` function](/language/functions/file). 165 Defaults to the value of the `private_key` field. 166 167 * `bastion_certificate` - The contents of a signed CA Certificate. The certificate argument 168 must be used in conjunction with a `bastion_private_key`. These can be loaded from 169 a file on disk using the [the `file` function](/language/functions/file).