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

# Connecting databases using SSH

> SSH tunnels allow you to connect to a database in a private network or add another layer of network encryption.

In this configuration, Omni establishes an encrypted connection to an SSH server on your network, and then uses SSH's Local Forwarding feature to route traffic through the SSH connection to the database in your network.

<Danger>
  Modifying a connection with an established SSH tunnel may result in disruptions **if you don't contact Omni support beforehand**.

  Changes include modifying the connection's `host` or `port` as well as rebuilding the SSH server and thus changing the SSH host keys. Refer to [Maintaining host keys](#maintaining-host-keys) for how to avoid this.
</Danger>

## Setup

<Steps>
  <Step title="Set up the SSH server in your network" titleSize="h3">
    Omni recommends using OpenSSH server to complete this step, as it's guaranteed to be compatible with the OpenSSH client Omni uses to establish a connection. Most Linux distributions come with OpenSSH installed or easily installable through a package manager.

    Your SSH server must:

    * Be in a network that accepts traffic on the SSH port from Omni's [outbound IP addresses](/administration/security/omni-ip-addresses)
    * Be able to route traffic to the network that the database resides in
    * Be configured so that the database's firewall accepts traffic from the SSH server
  </Step>

  <Step title="Contact Omni support" titleSize="h3">
    After you set up the SSH server, contact Omni support with the following information:

    * **For the SSH server** - The host, port, and user needed to connect
    * **For the database you want to connect to Omni** - The type of database, along with its host and port. The host should be a private IP address or a DNS entry that resolves to a private IP.
  </Step>

  <Step title="Authorize the public key" titleSize="h3">
    After Omni support receives the required information, we will generate an authentication keypair and send you the public key to authorize on your SSH server.
  </Step>

  <Step title="Confirm the connection" titleSize="h3">
    Once this is complete, Omni support will confirm the SSH connection can be established and add the new database connection to your Omni instance. The connection can then be used like any other database connection.
  </Step>
</Steps>

## Maintaining host keys

Omni verifies your SSH server's host key on every connection. If that key changes, connections will fail until you contact Omni support to update the key we have on file.

If your patching process replaces SSH servers instead of upgrading them in place, Omni highly recommends maintaining constant host keys across replacements. Otherwise, every patch cycle generates a new host key and breaks the tunnel.

The typical approach is to generate the host keys once, store them in a secrets manager - such as [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html), [Google Secret Manager](https://cloud.google.com/secret-manager/docs/overview), or [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/secrets/kv) - and write them to `/etc/ssh/` while provisioning the new server, before `sshd` starts.

On cloud images, [cloud-init's SSH module](https://docs.cloud-init.io/en/latest/reference/yaml_examples/ssh.html) supports this directly through the [`ssh_keys` config key](https://docs.cloud-init.io/en/latest/reference/modules.html#ssh), which installs the host keys you provide instead of generating new ones on first boot.

<Note>
  If you use a load balancer or autoscaling group in front of multiple SSH servers, all servers behind it must present the same host key.
</Note>