Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 43.1Mb
PDF (A4) - 43.2Mb
Man Pages (TGZ) - 295.4Kb
Man Pages (Zip) - 400.6Kb
Info (Gzip) - 4.3Mb
Info (Zip) - 4.3Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Communication Stack for Connection Security Management

20.6.1 Communication Stack for Connection Security Management

From MySQL 8.0.27, Group Replication can secure group communication connections between members by one of the following methods:

  • Using its own implementation of the security protocols, including TLS/SSL and the use of an allowlist for incoming Group Communication System (GCS) connections. This is the only option for MySQL 8.0.26 and earlier.

  • Using MySQL Server’s own connection security in place of Group Replication’s implementation. Using the MySQL protocol means that standard methods of user authentication can be used for granting (or revoking) access to the group in place of the allowlist, and the latest functionality of the server’s protocol is always available on release. This option is available from MySQL 8.0.27.

The choice is made by setting the system variable group_replication_communication_stack to XCOM to use Group Replication's own implementation (this is the default choice), or to MYSQL to use MySQL Server's connection security.

The following additional configuration is required for a replication group to use the MySQL communication stack. It is especially important to make sure these requirements are all fulfilled when you switch from using the XCom communication stack to the MySQL communication stack for your group.

Group Replication Requirements For The MySQL Communication Stack

  • The network address configured by the group_replication_local_address system variable for each group member must be set to one of the IP addresses and ports that MySQL Server is listening on, as specified by the bind_address system variable for the server. The combination of IP address and port for each member must be unique in the group. It is recommended that the group_replication_group_seeds system variable for each group member be configured to contain all the local addresses for all the group members.

  • The MySQL communication stack supports network namespaces, which the XCom communication stack does not support. If network namespaces are used with the Group Replication local addresses for the group members (group_replication_local_address), these must be configured for each group member using the CHANGE REPLICATION SOURCE TO statement. Also, the report_host server system variable for each group member must be set to report the namespace. All group members must use the same namespace to avoid possible issues with address resolution during distributed recovery.

  • The group_replication_ssl_mode system variable must be set to the required setting for group communications. This system variable controls whether TLS/SSL is enabled or disabled for group communications. For MySQL 8.0.26 and earlier, the TLS/SSL configuration is always taken from the server’s SSL settings; for MySQL 8.0.27 and later, when the MySQL communication stack is used, the TLS/SSL configuration is taken from Group Replication’s distributed recovery settings. This setting should be the same on all the group members, to avoid potential conflicts.

  • The settings for the --ssl or --skip-ssl server option and for the require_secure_transport server system variable should be the same on all the group members, to avoid potential conflicts. If group_replication_ssl_mode is set to REQUIRED, VERIFY_CA, or VERIFY_IDENTITY, use --ssl and require_secure_transport=ON. If group_replication_ssl_mode is set to DISABLED, use require_secure_transport=OFF.

  • If TLS/SSL is enabled for group communications, Group Replication’s settings for securing distributed recovery must be configured if they are not already in place, or validated if they already are. The MySQL communication stack uses these settings not just for member-to-member distributed recovery connections, but also for TLS/SSL configuration in general group communications. group_replication_recovery_use_ssl and the other group_replication_recovery_* system variables are explained in Section 20.6.3.2, “Secure Socket Layer (SSL) Connections for Distributed Recovery”.

  • The Group Replication allowlist is not used when the group is using the MySQL communication stack, so the group_replication_ip_allowlist and group_replication_ip_whitelist system variables are ignored and need not be configured.

  • The replication user account that Group Replication uses for distributed recovery, as configured using the CHANGE REPLICATION SOURCE TO statement, is used for authentication by the MySQL communication stack when setting up Group Replication connections. This user account, which is the same on all group members, must be given the following privileges:

    • GROUP_REPLICATION_STREAM. This privilege is required for the user account to be able to establish connections for Group Replication using the MySQL communication stack.

    • CONNECTION_ADMIN. This privilege is required so that Group Replication connections are not terminated if one of the servers involved is placed in offline mode. If the MySQL communication stack is in use without this privilege, a member that is placed in offline mode is expelled from the group.

    These are in addition to the privileges REPLICATION SLAVE and BACKUP_ADMIN that all replication user accounts must have (see Section 20.2.1.3, “User Credentials For Distributed Recovery”). When you add the new privileges, ensure that you skip binary logging on each group member by issuing SET SQL_LOG_BIN=0 before you issue the GRANT statements, and SET SQL_LOG_BIN=1 after them, so that the local transaction does not interfere with restarting Group Replication.

group_replication_communication_stack is effectively a group-wide configuration setting, and the setting must be the same on all group members. However, this is not policed by Group Replication’s own checks for group-wide configuration settings. A member with a different value from the rest of the group cannot communicate with the other members at all, because the communication protocols are incompatible, so it cannot exchange information about its configuration settings.

This means that although the value of the system variable can be changed while Group Replication is running, and takes effect after you restart Group Replication on the group member, the member still cannot rejoin the group until the setting has been changed on all the members. You must therefore stop Group Replication on all of the members and change the value of the system variable on them all before you can restart the group. Because all of the members are stopped, a full reboot of the group (a bootstrap by a server with group_replication_bootstrap_group=ON) is required in order for the value change to take effect. You can make the other required changes to settings on the group members while they are stopped.

For a running group, follow this procedure to change the value of group_replication_communication_stack and the other required settings to migrate a group from the XCom communication stack to the MySQL communication stack, or from the MySQL communication stack to the XCom communication stack:

  1. Stop Group Replication on each of the group members, using a STOP GROUP_REPLICATION statement. Stop the primary member last, so that you do not trigger a new primary election and have to wait for that to complete.

  2. On each of the group members, set the system variable group_replication_communication_stack to the new communication stack, MYSQL or XCOM as appropriate. You can do this by editing the MySQL Server configuration file (typically named my.cnf on Linux and Unix systems, or my.ini on Windows systems), or by using a SET statement. For example:

    SET PERSIST group_replication_communication_stack="MYSQL";
  3. If you are migrating the replication group from the XCom communication stack (the default) to the MySQL communication stack, on each of the group members, configure or reconfigure the required system variables to appropriate settings, as described in the listing above. For example, the group_replication_local_address system variable must be set to one of the IP addresses and ports that MySQL Server is listening on. Also configure any network namespaces using a CHANGE REPLICATION SOURCE TO statement.

  4. If you are migrating the replication group from the XCom communication stack (the default) to the MySQL communication stack, on each of the group members, issue GRANT statements to give the replication user account the GROUP_REPLICATION_STREAM and CONNECTION_ADMIN privileges. You will need to take the group members out of the read-only state that is applied when Group Replication is stopped. Also ensure that you skip binary logging on each group member by issuing SET SQL_LOG_BIN=0 before you issue the GRANT statements, and SET SQL_LOG_BIN=1 after them, so that the local transaction does not interfere with restarting Group Replication. For example:

    SET GLOBAL SUPER_READ_ONLY=OFF;
    SET SQL_LOG_BIN=0; 
    GRANT GROUP_REPLICATION_STREAM ON *.* TO rpl_user@'%';
    GRANT CONNECTION_ADMIN ON *.* TO rpl_user@'%';
    SET SQL_LOG_BIN=1;
  5. If you are migrating the replication group from the MySQL communication stack back to the XCom communication stack, on each of the group members, reconfigure the system variables in the requirements listing above to settings suitable for the XCom communication stack. Section 20.9, “Group Replication Variables” lists the system variables with their defaults and requirements for the XCom communication stack.

    Note
  6. To restart the group, follow the process in Section 20.5.2, “Restarting a Group”, which explains how to safely bootstrap a group where transactions have been executed and certified. A bootstrap by a server with group_replication_bootstrap_group=ON is necessary to change the communication stack, because all of the members must be shut down.

  7. Members now connect to each other using the new communication stack. Any server that has group_replication_communication_stack set (or defaulted, in the case of XCom) to the previous communication stack is no longer able to join the group. It is important to note that because Group Replication cannot even see the joining attempt, it does not check and reject the joining member with an error message. Instead, the attempted join fails silently when the previous communication stack gives up trying to contact the new one.