The Group Replication plugin has a configuration option to
determine from which hosts an incoming Group Communication
connection can be accepted. This option is called
If you set this option on a server s1, then when server s2 is
establishing a connection to s1 for the purpose of engaging group
communication, then s1 first checks the whitelist before accepting
the connection from s2. If s2 is in the whitelist, then s1 accepts
the connection, otherwise s1 rejects the connection attempt by s2.
If you do not specify a whitelist explicitly, the group
communication engine (XCom) automatically scans active interfaces
on the host, and identifies those with addresses on private
subnetworks. These addresses and the
IP address for IPv4 and (from MySQL 8.0.14) IPv6 are used to
create an automatic Group Replication whitelist. The automatic
whitelist therefore includes any IP addresses found for the host
in the following ranges:
IPv4 (as defined in RFC 1918) 10/8 prefix (10.0.0.0 - 10.255.255.255) - Class A 172.16/12 prefix (172.16.0.0 - 172.31.255.255) - Class B 192.168/16 prefix (192.168.0.0 - 192.168.255.255) - Class C IPv6 (as defined in RFC 4193 and RFC 5156) fc00:/7 prefix - unique-local addresses fe80::/10 prefix - link-local unicast addresses 127.0.0.1 - localhost for IPv4 ::1 - localhost for IPv6
An entry is added to the error log stating the addresses that have been whitelisted automatically for the host.
The automatic whitelist of private addresses cannot be used for
connections from servers outside the private network, so a server,
even if it has interfaces on public IPs, does not by default allow
Group Replication connections from external hosts. For Group
Replication connections between server instances that are on
different machines, you must provide public IP addresses and
specify these as an explicit whitelist. If you specify any entries
for the whitelist, the private and
addresses are not added automatically, so if you use any of these,
you must specify them explicitly.
To specify a whitelist manually, use the
option. You cannot change the whitelist on a server while it is an
active member of a replication group. If the member is active, you
must issue a
statement before changing the whitelist, and a
START GROUP_REPLICATION statement
In the whitelist, you can specify host names, simple IP addresses, or CIDR notation, in any combination. A comma must separate each entry. From MySQL 8.0.14, IPv6 addresses (or host names that resolve to them) can be used as well as IPv4 addresses. For example:
mysql> STOP GROUP_REPLICATION; mysql> SET GLOBAL group_replication_ip_whitelist="192.0.2.21/24,198.51.100.44,203.0.113.0/24,2001:db8:85a3:8d3:1319:8a2e:370:7348,example.org,www.example.com/24"; mysql> START GROUP_REPLICATION;
The whitelist must contain the IP address or host name that is
specified in each member's
system variable. This address is not the same as the MySQL server
SQL protocol host and port, and is not specified in the
bind_address system variable for
the server instance. If a host name used as the Group Replication
local address for a server instance resolves to both an IPv4 and
an IPv6 address, the IPv4 address is preferred for Group
To join a replication group, a server needs to be whitelisted on
the seed member to which it makes the request to join the group.
Typically, this would be the bootstrap member for the replication
group, but it can be any of the servers listed by the
option in the configuration for the server joining the group. If
any of the seed members for the group are listed in the
option with an IPv6 address when a joining member has an IPv4
or the reverse, you must also set up and whitelist an alternative
address for the joining member for the protocol offered by the
seed member (or a host name that resolves to an address for that
protocol). This is because when a server joins a replication
group, it must make the initial contact with the seed member using
the protocol that the seed member advertises in the
option, whether that is IPv4 or IPv6. If a joining member does not
have a whitelisted address for the appropriate protocol, its
connection attempt is refused. For more information on managing
mixed IPv4 and IPv6 replication groups, see
Section 18.4.5, “Support For IPv6 And For Mixed IPv6 And IPv4 Groups”.
When a replication group is reconfigured (for example, when a new primary is elected or a member joins or leaves), the group members re-establish connections between themselves. If a group member is only whitelisted by servers that are no longer part of the replication group after the reconfiguration, it is unable to reconnect to the remaining servers in the replication group that do not whitelist it. To avoid this scenario entirely, specify the same whitelist for all servers that are members of the replication group.
It is possible to configure different whitelists on different group members according to your security requirements, for example, in order to keep different subnets separate. If you need to configure different whitelists to meet your security requirements, ensure that there is sufficient overlap between the whitelists in the replication group to maximize the possibility of servers being able to reconnect in the absence of their original seed member.
For host names, name resolution takes place only when a connection request is made by another server. A host name that cannot be resolved is not considered for whitelist validation, and a warning message is written to the error log. Forward-confirmed reverse DNS (FCrDNS) verification is carried out for resolved host names.
Host names are inherently less secure than IP addresses in a whitelist. FCrDNS verification provides a good level of protection, but can be compromised by certain types of attack. Specify host names in your whitelist 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.