> ## Documentation Index
> Fetch the complete documentation index at: https://artie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH Tunnel

> An SSH tunnel is a secure method of forwarding network traffic between your local machine and a remote server through an encrypted SSH (Secure Shell) connection.

```mermaid theme={null}
flowchart LR
  A[Artie] -->|SSH tunnel| B

  subgraph Public subnet
    direction TB
    B[Bastion host]
    SG1[Security group]
  end

  B -->|Private network| C

  subgraph Private subnet
    direction TB
    C[Database]
    SG2[Security group]
  end
```

## Prerequisites

* A server (e.g. EC2 instance) that can reach your database over the private network
* SSH access to that server (port 22 open from Artie's IP range)
* Your database must be reachable from the SSH tunnel host

<Info>
  SSH tunnels are supported for all source and destination connectors that use a direct database connection.
</Info>

## How to set up an SSH tunnel

<Steps>
  <Step title="Create a tunnel host">
    Create a new EC2 instance (or equivalent) that has network access to your database. Record the **public IP address** and **SSH port** (default: 22).
  </Step>

  <Step title="Create an SSH tunnel in Artie">
    Go to **Settings > [SSH tunnels tab](https://app.artie.com/settings?tab=sshTunnels)** and click **New SSH tunnel**. Enter the public IP address and port from the previous step, then click **Save**.
  </Step>

  <Step title="Copy the public key">
    After saving, Artie generates a public key for the tunnel. Copy this key, you will add it to your tunnel host in the next step.

    <Frame>
      <img src="https://mintcdn.com/artie/U1X4YPuSejD95U42/assets/connections/public-key.png?fit=max&auto=format&n=U1X4YPuSejD95U42&q=85&s=b6b0237ad6a85faad53b9f9b593cc9d8" alt="Public key in the pipeline creation form" width="712" height="660" data-path="assets/connections/public-key.png" />
    </Frame>
  </Step>

  <Step title="Add the public key to your tunnel host">
    SSH into your tunnel host and add the public key to `~/.ssh/authorized_keys`. We recommend creating a dedicated service account for Artie.

    ```bash theme={null}
    sudo adduser -m artie
    sudo su artie
    mkdir -p ~/.ssh

    # Paste the public key from Artie into authorized_keys
    vi ~/.ssh/authorized_keys

    chmod 700 ~/.ssh
    chmod 600 ~/.ssh/authorized_keys
    ```
  </Step>

  <Step title="Use the tunnel in your pipeline">
    When creating or editing a source or destination, select the SSH tunnel you created from the **SSH tunnel** dropdown.
  </Step>
</Steps>

<Warning>
  Make sure the SSH tunnel host's security group allows inbound SSH traffic (port 22) from Artie's IP range. If your tunnel host cannot be reached, the pipeline will fail to connect.
</Warning>

## FAQ

<Accordion title="Can I use an existing bastion host?">
  Yes. You don't need to create a new instance - any server that can reach your database and accepts SSH connections will work. Just add the Artie public key to the `authorized_keys` file on that host.
</Accordion>

<Accordion title="Which port does Artie connect on?">
  Artie connects to the SSH tunnel host on the port you specify during setup (default: 22). The tunnel then forwards traffic to your database on its private port.
</Accordion>

<Accordion title="How do I rotate the SSH key?">
  Delete the existing SSH tunnel in Artie and create a new one. This generates a new key pair. Then replace the old public key in `~/.ssh/authorized_keys` on your tunnel host with the new one.
</Accordion>

<Accordion title="Can I use SSH tunnels with PrivateLink?">
  SSH tunnels and PrivateLink are separate connection methods. You typically only need one. If your database is in AWS and you want a fully private connection without managing an SSH host, consider [PrivateLink](/connection-options/privatelink) instead.
</Accordion>