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

layout	page_title	sidebar_current	description
docs	Provisioner Connections	docs-provisioners-connection	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

# 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. 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.

• agent - Set to false to disable using ssh-agent to authenticate. On Windows the only supported SSH authentication agent is 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.

• cacert - The CA certificate to validate against.

Connecting through a Bastion Host with SSH

The ssh connection also supports the following fields to facilitate connnections via a 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. 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.