MySQL Connector/NET Developer Guide

5.3 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:

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 the 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).

The examples in the next sections show connections made using standard TCP/IP over SSH:

Basic SSH Connection with Defaults (Classic Protocol)

This example shows the most basic form of the SSH tunnel connection. The MySQL port defaults to 3306 and the SSH port defaults to 22, because the values are not configured. Also, only a password is provided to authenticate to the SSH server. In this example, the connection is made using a MySqlConnectionStringBuilder object.

var builder = new MySqlConnectionStringBuilder();
builder.UserID = "myUser";
builder.Password = "test";
builder.Server = "localhost";
builder.SshHostName = "10.0.0.2";
builder.SshUserName = "mySshUser";
builder.SshPassword = "sshtest";
using (var connection = new MySqlConnection(builder.ConnectionString))
{
  connection.Open();
  connection.Close();
}  

SSH Connection With Ports (Classic Protocol)

In this SSH tunneling example, the MySQL and SSH ports are configured to override the default values. Only a password is provided to authenticate to the SSH server. Note that the connection is made using a connection string.

using (var connection = new MySqlConnection("uid=myUser;password=test;server=localhost;port=3307;
          sshHostName=10.0.0.2;sshUserName=mySshUser;sshPassword=sshtest;sshPort=23"))
{
  connection.Open();
  connection.Close();
}    

SSH Connection With Key File (Classic Protocol)

In addition to making the connection with a password, this example also includes a key file and pass phrase. Like the previous example, both the MySQL and SSH ports are configured.

using (var connection = new MySqlConnection("uid=myUser;password=test;server=localhost;port=3307;
          sshHostName=10.0.0.2;sshUserName=mySshUser;sshKeyFile=C:\\keys\\myOpenSshKeyFile.ppk;sshPassPhrase=sshTest;sshPort=23"))
{
  connection.Open();
  connection.Close();
}      

SSH Connection with Fallback (Classic Protocol)

This example includes the SSH key file (without a pass phrase) and the SSH password. Because the key file is valid and the pass phrase is not required, the connection can fall back to the SSH password value if authentication with the SSH key file encounters an error on the server.

var builder = new MySqlConnectionStringBuilder();
builder.UserID = "myUser";
builder.Password = "test";
builder.Server = "localhost";
builder.Port = 3307;
builder.SshHostName = "10.0.0.2";
builder.SshUserName = "mySshUser";
builder.SshKeyFile = @"C:\keys\noPassPhraseOpenSshKeyFile.ppk";
builder.SshPassword = "sshtest";
using (var connection = new MySqlConnection(builder.ConnectionString))
{
  connection.Open();
  connection.Close();
}      

Basic SSH Connection with Defaults (X Protocol)

This example configures the SSH connection with a default value for the SSH port (22). However, because the connection uses X Protocol to establish the SSH tunnel, the default MySQL port (33060) is provided in the URI-like connection string.

using (var session = MySQLX.GetSession("mysqlx://myUser:test@localhost:33060?sshHostName=10.0.0.2;
                      sshUserName=mySshUser;sshPassword=sshTest"))
{
    session.Close();
}     

SSH Connection With SSL Mode (X Protocol)

This example creates the SSH tunnel for an anonymous object and it ensures that the use of SSL by denying the connection explicitly if the server does not support SSL.

var sessionOptions = {
    UserID = "myUser",
    Password = "test",
    Server = "127.0.0.1",
    Port = 3307,
    SshHostName = "10.0.0.2",
    SshUserName = "mySshUser",
    SshKeyFile = @"C:\keys\myOpenSshKeyFile.ppk",
    SshPassPhrase = "sshtest",
    SslMode = MySqlSslMode.Required
  };
using (var session = MySQLX.GetSession(sessionOptions))
{
    session.Close();
}