Documentation Home
Connectors and APIs Manual
Download this Manual

Connectors and APIs Manual  /  ...  /  Connecting With TCP/IP Over SSH

4.4.2 Connecting With TCP/IP Over SSH

SSH tunneling (or port forwarding) enables you to create a secure connection between your computer and a remote computer through which you can access MySQL data. SSH tunnels permit you to connect to a MySQL database from behind a firewall when the MySQL server port is blocked.

There are several considerations for connecting with standard TCP/IP over SSH:

  • Your application (client to make the connection) requires authorization on the SSH server.

  • The SSH server communicates with a MySQL server instance in an unencrypted or encrypted mode, based on the value selected for the SslMode connection option (or property). The default value of the option can vary, depending on the version of Connector/NET you use (see Options for Both Classic MySQL Protocol and X Protocol). The MySQL server instance does not require additional configuration for this type of connection.

  • The ConnectionProtocol connection option (or property) must use the default value (socket or tcp) to establish a connection with standard TCP/IP over SSH.

  • The SSH server name and port are configured using the SshHostName and SshPort connection options (or properties). To authenticate the client requesting a connection (specified by the SshUserName connection option or property), you can use one of the following strategies:

    • SshUserName and SshPassword only

    • SshUserName and SshKeyFile only

      Your SSH server may require that you to also provide the SshPassPhrase connection option (or property) when using a key file. An invalid pass phrase generates an exception.

    • SshUserName and SshKeyFile (SshPassPhrase) and SshPassword

      The combination of user name + key file (pass phrase) + password can perform fallback authentication when the key file and pass phrase are valid, but an error occurs on the server. Specifically, the first attempt to connect uses the key file, and if it fails, the next attempt to connect uses the password instead. If the SSH key file is null or empty, but the SSH password is provided, Connector/NET attempts to connect using the SSH password only.

You can configure SSH tunneling by using either Connector/NET 8.0.17 (or higher) connection-string options or class properties: the MySqlConnectionStringBuilder class for use with classic MySQL protocol or the MySqlXConnectionStringBuilder class for X Protocol. SSH tunnels to MySQL are supported with .NET Framework 4.5.2, .NET Standard 1.3 (.NET Core 1.1), and .NET Standard 2.2 (.NET Core 2.0).