MySQL Shell 8.4
Server instances can be configured to use secure connections. For general information on using secure connections with MySQL see Using Encrypted Connections. This section explains how to configure a cluster to use encrypted connections. An additional security possibility is to configure which servers can access the cluster, see Creating an Allowlist of Servers.
If you are using the XCOM
communication
stack, once you have configured a cluster to use encrypted
connections you must add the servers to the
ipAllowlist
. For example, when using the
commercial version of MySQL, SSL is enabled by default and you
need to configure the ipAllowlist
option for
all instances. See Creating an Allowlist of Servers.
When using dba.createCluster()
to set up a
cluster, if the server instance provides encryption then it is
automatically enabled on the seed instance. Pass the
memberSslMode
option to the
dba.createCluster()
method to specify a
different SSL mode. The SSL mode of a cluster can only be set at
the time of creation. The memberSslMode
option
is a string that configures the SSL mode to be used, it defaults
to AUTO
. The following modes are supported:
DISABLED
: Ensure SSL encryption is disabled
for the seed instance in the cluster.
AUTO
: Automatically enable SSL encryption
if the server instance supports it, or disable encryption if
the server does not support it.
REQUIRED
: Enable SSL encryption for the
seed instance in the cluster. If it cannot be enabled, an
error is raised.
VERIFY_CA
: Like
REQUIRED
, but additionally verify the
server Certificate Authority (CA) certificate against the
configured CA certificates. The connection attempt fails if no
valid matching CA certificates are found.
VERIFY_IDENTITY
: Like
VERIFY_CA
, but additionally perform host
name identity verification by checking the host name the
client uses for connecting to the server against the identity
in the certificate that the server sends to the client.
For example, to set the cluster to use
REQUIRED
, issue:
mysql-js> var myCluster = dba.createCluster({memberSslMode: 'REQUIRED'})
If you choose to use the VERIFY_CA
or
VERIFY_IDENTITY
mode, on each cluster instance
you must manually supply the CA certificates using the
ssl_ca
and/or
ssl_capath
option. For more
information on these modes, see
--ssl-mode=
.
mode
When you use the
and
Cluster
.addInstance()
operations, SSL encryption on the instance is enabled or disabled
based on the setting used for the cluster. Use the
Cluster
.rejoinInstance()memberSslMode
option with either of these
operations to set the instance to use a different mode of
encryption.
When using dba.createCluster()
with the
adoptFromGR
option to adopt an existing Group
Replication group, no SSL settings are changed on the adopted
cluster:
memberSslMode
cannot be used with
adoptFromGR
.
If the SSL settings of the adopted cluster are different from the ones supported by the MySQL Shell, in other words SSL for Group Replication recovery and Group Communication, both settings are not modified. This means you are not be able to add new instances to the cluster, unless you change the settings manually for the adopted cluster.
MySQL Shell always enables or disables SSL for the cluster for
both Group Replication recovery and Group Communication, see
Securing Group Communication Connections with Secure Socket Layer (SSL).
A verification is performed and an error issued in case those
settings are different for the seed instance (for example as the
result of a dba.createCluster()
using
adoptFromGR
) when adding a new instance to the
cluster. SSL encryption must be enabled or disabled for all
instances in the cluster. Verifications are performed to ensure
that this invariant holds when adding a new instance to the
cluster.
The dba.deploySandboxInstance()
command
attempts to deploy sandbox instances with SSL encryption support
by default. If it is not possible, the server instance is deployed
without SSL support. See
Section 6.8.1, “Deploying Sandbox Instances”.
It is possible to configure clusters and replica clusters to use SSL to encrypt replication channels, and enable replicas to verify host identity and use SSL certificates for authentication.
When creating a cluster with
dba.createCluster()
you can define the
authentication type used for the internal replication accounts
with the memberAuthType
option. This option
takes one of the following values:
PASSWORD
: Account authenticates with
password only.
CERT_ISSUER
: Account authenticates with a
client certificate, which must match the expected issuer.
This value is equivalent to VERIFY_CA
.
CERT_SUBJECT
: Account authenticates with
a client certificate, which must match the expected issuer
and subject. This value is equivalent to
VERIFY_IDENTITY
.
CERT_ISSUER_PASSWORD
: Account
authenticates with a combination of
PASSWORD
and
CERT_ISSUER
values.
CERT_SUBJECT_PASSWORD
: Account
authenticates with a combination of
PASSWORD
and
CERT_SUBJECT
values.
ClusterSets inherit the memberAuthType
defined on the primary cluster. All replica clusters in a
ClusterSet will also use the memberAuthType
defined on the primary.
SSL certificates are defined using the following options:
CERT_ISSUER
: Defines the certificate
issuer required by all replication accounts in the topology
if memberAuthType
contains
CERT_ISSUER
or
CERT_SUBJECT
.
CERT_SUBJECT
: Defines the certificate
subject of the instance. Required if
memberAuthType
contains
CERT_SUBJECT
.
It is not possible to use adoptFromGR=true
with any option except
memberAuthType=password
.
The following example creates a cluster,
cluster1
which sets client SSL connections
and connections opened by Group Replication from one server to
another to VERIFY_IDENTITY, and sets the authentication of the
internal replication accounts to require a client certificate:
cluster = dba.createCluster("cluster1", { "memberSslMode": "VERIFY_IDENTITY", "memberAuthType":"CERT_SUBJECT", "certIssuer":"/CN=MyCertAuthority", "certSubject": "/CN=mysql-1.local"});
The following example shows how to add an instance to a cluster
using "memberAuthType":"CERT_SUBJECT"
:
cluster.addInstance("mysql-2.local", {"certSubject": "/CN=mysql-2.local"});
For more information on replication and encrypted connections, see Setting Up Replication to Use Encrypted Connections.
This applies only to the XCOM
communication
stack.
createCluster()
,
addInstance()
, and
rejoinInstance()
methods enable you to
optionally specify a list of approved servers, referred to as an
allowlist. By specifying the allowlist explicitly in this way
you can increase the security of your cluster because only
servers in the allowlist can connect to the cluster.
You can also define an allowList on a running cluster, using
to specify the allowList for all members of the cluster, and
Cluster
.setOption()
to specify the allowList for an individual member. See
Section 7.5.1, “Setting Options for InnoDB Cluster”.
Cluster
.setInstanceOption()
Using the ipAllowlist
option configures the
group_replication_ip_allowlist
system variable on the instance. By default, if not specified
explicitly, the allowlist is automatically set to the private
network addresses that the server has network interfaces on. To
configure the allowlist, specify the servers to add with the
ipAllowlist
option when using the method. IP
addresses must be specified in IPv4 format. Pass the servers as
a comma separated list, surrounded by quotes. For example:
mysql-js> cluster.addInstance("icadmin@ic-3:3306", {ipAllowlist: "203.0.113.0/24, 198.51.100.110"})
This configures the instance to only accept connections from
servers at addresses 203.0.113.0/24
and
198.51.100.110
. The allowlist can also
include host names, which are resolved only when a connection
request is made by another server.
Host names are inherently less secure than IP addresses in an allowlist. MySQL carries out FCrDNS verification, which provides a good level of protection, but can be compromised by certain types of attack. Specify host names in your allowlist only when strictly necessary, and ensure that all components used for name resolution, such as DNS servers, are maintained under your control. You can also implement name resolution locally using the hosts file, to avoid the use of external components.