MySQL Shell supports SSH tunneling for connections to MySQL server instances. An SSH tunnel lets unencrypted traffic pass over an encrypted connection, and enables authorized remote access to servers that are protected from outside connections by a firewall.
The use of AdminAPI commands is not supported over connections
made from MySQL Shell using SSH tunneling, with the exception
of the commands to deploy, start, stop, kill, and delete sandbox
dba.deleteSandboxInstance). The sandbox
commands are always executed locally to the MySQL Shell
Once established, an SSH tunnel can be shared between
connections to the same host from the same user connecting from
the same remote server instance. The MySQL Shell function
shell.listSshConnections() lists the
currently connected and active SSH tunnels from the MySQL Shell
session, with the URI of the SSH server and of the connected
MySQL server instance. If you specify the same SSH connection
details, MySQL Shell automatically reuses the existing tunnel.
You can select the SSH configuration file and identity file (private key) that are used for the connection. When you set up an SSH tunnel, MySQL Shell selects an SSH configuration file in the following order of priority:
An SSH configuration file that you specify as a connection option.
An SSH configuration file that you set as a default using the MySQL Shell configuration option
ssh.configFile. For instructions to set this option, see Section 13.4, “Configuring MySQL Shell Options”.
The standard SSH configuration file
The known hosts file is read from the default location
~/.ssh/known_hosts) unless a different
configuration is set in the SSH configuration file.
For the identity file (private key), you can specify a custom
file with the
ssh-identity-file option at
connection time. There is no option to set a custom default for
the identity file. If you do not specify one, the SSH library
uses the following sequence of authentication attempts until one
If an SSH agent is in use, authentication is attempted with the identity files configured there if available.
If an identity file is specified for the target host in the SSH configuration file, authentication is attempted using that file.
If neither of those options is available or the authentication attempt fails, authentication is attempted using the standard private key file in the SSH configuration folder (
The default buffer size for data transfer through the SSH tunnel
is 10240 bytes. You can change this by setting the MySQL Shell
instructions to set this option, see
Section 13.4, “Configuring MySQL Shell Options”.
SSH tunneling is available when you use any of the MySQL Shell
connection methods - the
mysqlsh command parameters, or the
\connect MySQL Shell command.
When you use the
shell.connect()method to connect while MySQL Shell is running, you can specify a URI for connection to the SSH server, or use key-value pairs for the connection data. The following options are available with this method:
ssh: The URI for connection to the SSH server. The URI format is
uri: The URI for the MySQL server instance that is to be accessed through the SSH tunnel. The URI format is
[scheme://] [user@]host:port. Do not use the base connection parameters (
port) to specify the MySQL server connection for SSH tunneling, just use this option. The port must be specified.
ssh-password: The password for the connection to the SSH server.
ssh-config-file: An SSH configuration file for the connection to the SSH server.
ssh-identity-file: An identity file to use for the connection to the SSH server.
ssh-identity-pass: The passphrase for the identity file specified by the
These options are also available when you use the
shell.openSession()method, which works in the same way as
shell.connect()but creates and returns a
sessionobject, rather than setting it as the global session for MySQL Shell. For full instructions to use this connection method and the other options that are available, see Connecting to the Server Using URI-Like Strings or Key-Value Pairs.
When you connect using command-line options while MySQL is starting up, you can specify a URI for connection to the SSH server. The following options are available with this method:
--ssh: The URI for connection to the SSH server. The URI format is
[user@]host[:port]. When you use this option, the port for connection to the MySQL server instance must be specified in the MySQL instance URI.
--ssh-config-file: An SSH configuration file for the connection to the SSH server. If you specify this option with an empty value, the custom default SSH configuration file specified by
--ssh.configFileis ignored, and the
~/.ssh/configfile is used instead.
--ssh-identity-file: An identity file to use for the connection to the SSH server.
For full instructions to use this connection method and the other options that are available, see Section 4.3.1, “Connecting using Individual Parameters”.
\connectMySQL Shell command
When you connect using the
\connectcommand while MySQL Shell is running, you can specify a URI for connection to the SSH server. There are no additional options for the SSH connection, so you must use the default identity file
~/.ssh/id_rsa, and the default SSH configuration file, which can be either the standard file
~/.ssh/configor a custom default that you set using the MySQL Shell configuration option
ssh.configFile(see Section 13.4, “Configuring MySQL Shell Options”).
To get additional setup options you can create an SSH tunnel using the
shell.connect()method or on the command line while MySQL Shell is starting, and then reuse it with the
\connectcommand. When you are in a MySQL Shell session, you can view the currently connected SSH tunnels using the
MySQL Shell’s Secret Store can store passwords and passphrases for connection to the SSH server and for the identity file, to be automatically retrieved for future connections. If you provide a password or passphrase in the connection options it is used instead of any password that is stored in the Secret Store. Note that although there are options to allow it, specifying an explicit password in the connection data is insecure and not recommended. MySQL Shell prompts for a password interactively when one is required, either for the connection to the SSH server or for the identity file. For example:
> ssh:"email@example.com:2222", "ssh-identity-file":"/home/hanna/.ssh/config_pw"})
Creating a Classic session to 'firstname.lastname@example.org:3306'
Opening SSH tunnel to 198.51.100.4:2222...
Please provide key passphrase for /home/hanna/.ssh/config_pw: ********
Save password for 'file:/home/hanna/.ssh/config_pw'?
[Y]es/[N]o/Ne[v]er (default No): y
Fetching schema names for autocompletion... Press ^C to stop.
Your MySQL connection id is 7869
Server version: 8.0.28 MySQL Community Server - GPL
No default schema selected; type \use <schema> to set one.