github.com/kcburge/terraform@v0.11.12-beta1/website/docs/provisioners/connection.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Provisioner Connections"
     4  sidebar_current: "docs-provisioners-connection"
     5  description: |-
     6    Managing connection defaults for SSH and WinRM using the `connection` block.
     7  ---
     8  
     9  # Provisioner Connections
    10  
    11  Many provisioners require access to the remote resource. For example,
    12  a provisioner may need to use SSH or WinRM to connect to the resource.
    13  
    14  Terraform uses a number of defaults when connecting to a resource, but these can
    15  be overridden using a `connection` block in either a `resource` or
    16  `provisioner`. Any `connection` information provided in a `resource` will apply
    17  to all the provisioners, but it can be scoped to a single provisioner as well.
    18  One use case is to have an initial provisioner connect as the `root` user to
    19  setup user accounts, and have subsequent provisioners connect as a user with
    20  more limited permissions.
    21  
    22  ## Example usage
    23  
    24  ```hcl
    25  # Copies the file as the root user using SSH
    26  provisioner "file" {
    27    source      = "conf/myapp.conf"
    28    destination = "/etc/myapp.conf"
    29  
    30    connection {
    31      type     = "ssh"
    32      user     = "root"
    33      password = "${var.root_password}"
    34    }
    35  }
    36  
    37  # Copies the file as the Administrator user using WinRM
    38  provisioner "file" {
    39    source      = "conf/myapp.conf"
    40    destination = "C:/App/myapp.conf"
    41  
    42    connection {
    43      type     = "winrm"
    44      user     = "Administrator"
    45      password = "${var.admin_password}"
    46    }
    47  }
    48  ```
    49  
    50  ## Argument Reference
    51  
    52  **The following arguments are supported by all connection types:**
    53  
    54  * `type` - The connection type that should be used. Valid types are `ssh` and `winrm`
    55    Defaults to `ssh`.
    56  
    57  * `user` - The user that we should use for the connection. Defaults to `root` when
    58    using type `ssh` and defaults to `Administrator` when using type `winrm`.
    59  
    60  * `password` - The password we should use for the connection. In some cases this is
    61    specified by the provider.
    62  
    63  * `host` - The address of the resource to connect to. This is usually specified by the provider.
    64  
    65  * `port` - The port to connect to. Defaults to `22` when using type `ssh` and defaults
    66    to `5985` when using type `winrm`.
    67  
    68  * `timeout` - The timeout to wait for the connection to become available. This defaults
    69    to 5 minutes. Should be provided as a string like `30s` or `5m`.
    70  
    71  * `script_path` - The path used to copy scripts meant for remote execution.
    72  
    73  **Additional arguments only supported by the `ssh` connection type:**
    74  
    75  * `private_key` - The contents of an SSH key to use for the connection. These can
    76    be loaded from a file on disk using the [`file()` interpolation
    77    function](/docs/configuration/interpolation.html#file_path_). This takes
    78    preference over the password if provided.
    79  
    80  * `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the
    81    only supported SSH authentication agent is
    82    [Pageant](http://the.earth.li/~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant).
    83  
    84  * `agent_identity` - The preferred identity from the ssh agent for authentication.
    85  
    86  * `host_key` - The public key from the remote host or the signing CA, used to
    87    verify the connection.
    88  
    89  **Additional arguments only supported by the `winrm` connection type:**
    90  
    91  * `https` - Set to `true` to connect using HTTPS instead of HTTP.
    92  
    93  * `insecure` - Set to `true` to not validate the HTTPS certificate chain.
    94  
    95  * `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).
    96  
    97  * `cacert` - The CA certificate to validate against.
    98  
    99  <a id="bastion"></a>
   100  ## Connecting through a Bastion Host with SSH
   101  
   102  The `ssh` connection also supports the following fields to facilitate connnections via a
   103  [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
   104  
   105  * `bastion_host` - Setting this enables the bastion Host connection. This host
   106    will be connected to first, and then the `host` connection will be made from there.
   107  
   108  * `bastion_host_key` - The public key from the remote host or the signing CA,
   109    used to verify the host connection.
   110  
   111  * `bastion_port` - The port to use connect to the bastion host. Defaults to the
   112    value of the `port` field.
   113  
   114  * `bastion_user` - The user for the connection to the bastion host. Defaults to
   115    the value of the `user` field.
   116  
   117  * `bastion_password` - The password we should use for the bastion host.
   118    Defaults to the value of the `password` field.
   119  
   120  * `bastion_private_key` - The contents of an SSH key file to use for the bastion
   121    host. These can be loaded from a file on disk using the [`file()`
   122    interpolation function](/docs/configuration/interpolation.html#file_path_).
   123    Defaults to the value of the `private_key` field.