PXC-5194 [DOCS] - clean up expected outcomes 8.4

docs/configure-cluster-rhel.md

@@ -32,9 +32,9 @@ to ports 3306, 4444, 4567 and 4568.
 
 * SELinux on all nodes is disabled.
 
-!!! admonition "Different from previous versions"
+Percona XtraDB Cluster {{vers}} creates the internal MySQL account [`mysql.pxc.internal.session`](glossary.md#mysqlpxcinternalsession), which the SST process uses to run the SQL needed for node synchronization.
 
-   The variable `wsrep_sst_auth` has been removed. Percona XtraDB Cluster {{vers}} automatically creates the system user [`mysql.pxc.internal.session`](glossary.md#mysqlpxcinternalsession). During [SST](glossary.md#sst), the user `mysql.pxc.sst.user` and the role [`mysql.pxc.sst.role`](glossary.md#mysqlpxcsstrole) are created on the donor node.
+During [SST](glossary.md#sst), that account creates the user `mysql.pxc.sst.user` on the donor node and assigns it the role [`mysql.pxc.sst.role`](glossary.md#mysqlpxcsstrole).
 
 ## Step 1. Install 
 

docs/data-at-rest-encryption.md

@@ -231,11 +231,9 @@ Run the migration server:
 --component_keyring_vault_config=/dev/shm/pxc80/vault/component_keyring_vault.cnf &
 ```
 
-??? example "Expected output"
+??? example "Expected log output"
 
     ```{.text .no-copy}
-    ... [Warning] TIMESTAMP with implicit DEFAULT value is deprecated. Please use
-        --explicit_defaults_for_timestamp server option (see documentation for more details).
     ... [Note] --secure-file-priv is set to NULL. Operations related to importing and
         exporting data are disabled
     ... [Warning] WSREP: Node is not a cluster node. Disabling pxc_strict_mode

docs/faq.md

@@ -159,7 +159,7 @@ To be precise, the commits are “virtually” synchronous, which means that the
 
 ## Does Percona XtraDB Cluster work with regular MySQL replication?
 
-Yes. On the node you are going to use as source, enable binary logging and replica updates: set `log_bin` and `log_replica_updates` (or the deprecated `log_slave_updates`) in your configuration.
+Yes. On the node you are going to use as source, set a unique non-zero `server_id`, enable binary logging (`log_bin`), and enable `log_replica_updates` (or the deprecated `log_slave_updates`) so cluster-applied writes are recorded in the binary log for downstream replicas.
 
 ## Why the MySQL init script does not start?
 

docs/garbd-howto.md

@@ -38,39 +38,50 @@ On RHEL 8 and later, you can use `dnf install percona-xtradb-cluster-garbd` inst
 
     On **Percona XtraDB Cluster** {{vers}}, SSL is enabled by default. To run the Galera Arbitrator, you must copy the SSL certificates and configure `garbd` to use the certificates.
 
-    It is necessary to specify the cipher. In this example, it is `AES128-SHA256`. If you do not specify the cipher, an error occurs with a “Terminate called after throwing an instance of ‘gnu::NotSet’” message.
+    You must specify a cipher. This document uses `AES128-SHA256` as an example.
+    Choose a cipher that matches your security policy and OpenSSL configuration.
+    If no cipher is specified, startup can fail with a “Terminate called after
+    throwing an instance of ‘gnu::NotSet’” message.
 
     For more information, see [socket.ssl_cipher :octicons-link-external-16:](https://mariadb.com/docs/galera-cluster/reference/wsrep-variable-details/wsrep_provider_options#socket.ssl_cipher)
 
 When starting from the shell, you can set the parameters from the command line or edit the configuration file. This is an example of starting from the command line:
 
 ```shell
-garbd --group=my_ubuntu_cluster \
---address="gcomm://192.168.70.61:4567, 192.168.70.62:4567, 192.168.70.63:4567" \
---option="socket.ssl=YES; socket.ssl_key=/etc/ssl/mysql/server-key.pem; \
-socket.ssl_cert=/etc/ssl/mysql/server-cert.pem; \
-socket.ssl_ca=/etc/ssl/mysql/ca.pem; \
+garbd --group=<CLUSTER_NAME> \
+--address="gcomm://<NODE1_IP>:4567,<NODE2_IP>:4567,<NODE3_IP>:4567" \
+--option="socket.ssl=YES; socket.ssl_key=<SSL_KEY_PATH>; \
+socket.ssl_cert=<SSL_CERT_PATH>; \
+socket.ssl_ca=<SSL_CA_PATH>; \
 socket.ssl_cipher=AES128-SHA256"
 ```
 
 To avoid entering the options each time you start `garbd`, edit the options in the configuration file. To configure *Galera Arbitrator* on *Ubuntu/Debian*, edit the `/etc/default/garb` file. On RedHat or derivative distributions, the configuration can be found in `/etc/sysconfig/garb` file.
 
-The configuration file should look like this after the installation and before you have added your parameters:
+Replace placeholder values such as `<CLUSTER_NAME>`, `<NODE1_IP>`,
+`<NODE2_IP>`, `<NODE3_IP>`, `<SSL_KEY_PATH>`, `<SSL_CERT_PATH>`, and
+`<SSL_CA_PATH>` with values from your environment.
+
+After installation, before you add your cluster settings, **`/etc/default/garb`** (Debian/Ubuntu) from **Percona XtraDB Cluster** {{vers}} packages matches the following template:
 
 ```{.text .no-copy}
-Copyright (C) 2013-2015 Codership Oy
-This config file is to be sourced by garb service script.
-REMOVE THIS AFTER CONFIGURATION
-A comma-separated list of node addresses (address[:port]) in the cluster
-GALERA_NODES=""
-Galera cluster name, should be the same as on the rest of the nodes.
-GALERA_GROUP=""
-Optional Galera internal options string (e.g. SSL settings)
-see http://galeracluster.com/documentation-webpages/galeraparameters.html
-GALERA_OPTIONS=""
-Log file for garbd. Optional, by default logs to syslog
-Deprecated for CentOS7, use journalctl to query the log for garbd
-LOG_FILE=""
+# Copyright (C) 2012 Codership Oy
+# This config file is to be sourced by garb service script.
+
+# REMOVE THIS AFTER CONFIGURATION
+
+# A comma-separated list of node addresses (address[:port]) in the cluster
+# GALERA_NODES=""
+
+# Galera cluster name, should be the same as on the rest of the nodes.
+# GALERA_GROUP=""
+
+# Optional Galera internal options string (e.g. SSL settings)
+# see http://galeracluster.com/documentation-webpages/galeraparameters.html
+# GALERA_OPTIONS=""
+
+# Log file for garbd. Optional, by default logs to syslog
+# LOG_FILE=""
 ```
 
 Add the parameter information about the cluster. For this document, we use the cluster information from [Configuring Percona XtraDB Cluster on Ubuntu](configure-cluster-ubuntu.md#configure-a-cluster-on-debian-or-ubuntu).
@@ -83,73 +94,121 @@ Add the parameter information about the cluster. For this document, we use the c
 ```{.text .no-copy}
 This config file is to be sourced by garb service script.
 A comma-separated list of node addresses (address[:port]) in the cluster
-GALERA_NODES="192.168.70.61:4567, 192.168.70.62:4567, 192.168.70.63:4567"
+GALERA_NODES="<NODE1_IP>:4567,<NODE2_IP>:4567,<NODE3_IP>:4567"
 Galera cluster name, should be the same as on the rest of the nodes.
-GALERA_GROUP="my_ubuntu_cluster"
+GALERA_GROUP="<CLUSTER_NAME>"
 Optional Galera internal options string (e.g. SSL settings)
 see http://galeracluster.com/documentation-webpages/galeraparameters.html
-GALERA_OPTIONS="socket.ssl_key=/etc/ssl/mysql/server-key.pem;socket.ssl_cert=/etc/ssl/mysql/server-cert.pem;socket.ssl_ca=/etc/ssl/mysql/ca.pem;socket.ssl_cipher=AES128-SHA256"
+GALERA_OPTIONS="socket.ssl_key=<SSL_KEY_PATH>;socket.ssl_cert=<SSL_CERT_PATH>;socket.ssl_ca=<SSL_CA_PATH>;socket.ssl_cipher=AES128-SHA256"
 Log file for garbd. Optional, by default logs to syslog
-Deprecated for CentOS7, use journalctl to query the log for garbd
 LOG_FILE="/var/log/garbd.log"
 ```
 
 You can now start the *Galera Arbitrator* daemon (`garbd`). Run the following commands as root.
 
+!!! note
+
+    The systemd service name is `garb`, while the daemon binary name is `garbd`.
+
 === "On Debian or Ubuntu"
 
     ```shell
-    service garbd start
+    systemctl start garb
     ```
 
     ??? example "Expected output"
 
         ```{.text .no-copy}
-        [ ok ] Starting /usr/bin/garbd: :.
+        # No output on success
         ```
 
-    !!! note 
+=== "On Red Hat Enterprise Linux"
+
+    ```shell
+    systemctl start garb
+    ```
 
-        On systems that run `systemd` as the default system and service manager, use `systemctl` instead of `service` to invoke the command. Currently, both are supported.
+    ??? example "Expected output"
 
-        ```shell
-        systemctl start garb
+        ```{.text .no-copy}
+        # No output on success
         ```
 
-=== "On Red Hat Enterprise Linux or CentOS"
+Additionally, you can check the `arbitrator` status by running:
+
+=== "On Debian or Ubuntu"
 
     ```shell
-    service garb start
+    systemctl is-active garb
     ```
 
     ??? example "Expected output"
 
         ```{.text .no-copy}
-        [ ok ] Starting /usr/bin/garbd: :.
+        active
         ```
 
-Additionally, you can check the `arbitrator` status by running:
+## Verify arbitrator participation
 
-=== "On Debian or Ubuntu"
+1. Check the arbitrator service state:
+
+    ```shell
+    systemctl is-active garb
+    ```
+
+    ??? example "Expected output"
+
+        ```{.text .no-copy}
+        active
+        ```
+
+2. Check recent arbitrator logs for successful cluster communication:
+
+    ```shell
+    journalctl -u garb --no-pager -n 20
+    ```
+
+    ??? example "Expected output"
+
+        ```{.text .no-copy}
+        ... WSREP: ...
+        ... connected ...
+        ```
+
+3. On a Percona XtraDB Cluster node, confirm that the cluster remains in `Primary` state:
 
     ```shell
-    service garbd status
+    mysql -e "SHOW STATUS LIKE 'wsrep_cluster_status';"
     ```
 
     ??? example "Expected output"
 
         ```{.text .no-copy}
-        [ ok ] garb is running.
+        +----------------------+---------+
+        | Variable_name        | Value   |
+        +----------------------+---------+
+        | wsrep_cluster_status | Primary |
+        +----------------------+---------+
         ```
 
-=== "On Red Hat Enterprise Linux or CentOS"
+## Troubleshooting
+
+* `gnu::NotSet` at startup: set `socket.ssl_cipher` in `GALERA_OPTIONS`.
+
+* Arbitrator cannot join cluster: verify `GALERA_NODES` format (`IP:4567` entries separated by commas, no missing ports).
+
+* No connectivity to cluster nodes: verify firewall and routing for port `4567` between arbitrator and all cluster nodes.
+
+* Service starts then exits: review `journalctl -u garb --no-pager` and validate certificate file paths in `GALERA_OPTIONS`.
+
+=== "On Red Hat Enterprise Linux"
 
     ```shell
-    service garb status
+    systemctl is-active garb
     ```
 
     ??? example "Expected output"
 
         ```{.text .no-copy}
-        [ ok ] garb is running.
+        active
         ```