Clustering: improve tutorial, revise related API methods

2025-11-21 12:15:50 +00:00 · 2018-09-13 15:32:32 -07:00
parent 891def5003
commit 582717de76
5 changed files with 87 additions and 29 deletions
--- a/content/tutorials/manage-the-rippled-server/cluster-rippled-servers.md
+++ b/content/tutorials/manage-the-rippled-server/cluster-rippled-servers.md
@@ -1,22 +1,87 @@
 # Cluster rippled Servers

-If you are running multiple `rippled` servers in a single datacenter, you can configure those servers into a cluster to maximize efficiency. Running your `rippled` servers in a cluster provides the following benefits:
+If you run multiple `rippled` servers in the same data center, you can configure them in a [cluster](clustering.html) to maximize efficiency. To configure clustering:

-* Clustered `rippled` servers share the work of cryptography. If one server has verified the authenticity of a message, the other servers in the cluster trust it and do not re-verify.
-* Clustered servers share information about peers and API clients that are misbehaving or abusing the network. This makes it harder to attack all servers of the cluster at once.
-* Clustered servers always propagate transactions throughout the cluster, even if the transaction does not meet the current load-based transaction fee on some of them.
+1. For each of your servers, note the IP address of the server.

-To enable clustering, change the following sections of your [config file](https://github.com/ripple/rippled/blob/master/cfg/rippled-example.cfg) for each server:
+2. For each of your servers, generate a unique seed using the [validation_create method][].

-* List the IP address and port of each other server under the `[ips_fixed]` section. The port should be the one from the other servers' `protocol = peer` setting in their `rippled.cfg`. Example:
+    For example, using the commandline interface:

-        [ips_fixed]
-        192.168.0.1 51235
-        192.168.0.2 51235
+        $ rippled validation_create
+
+        Loading: "/etc/rippled.cfg"
+        Connecting to 127.0.0.1:5005
+        {
+           "result" : {
+              "status" : "success",
+              "validation_key" : "FAWN JAVA JADE HEAL VARY HER REEL SHAW GAIL ARCH BEN IRMA",
+              "validation_public_key" : "n9Mxf6qD4J55XeLSCEpqaePW4GjoCR5U1ZeGZGJUCNe3bQa4yQbG",
+              "validation_seed" : "ssZkdwURFMBXenJPbrpE14b6noJSu"
+           }
+        }
+
+    Save the `validation_seed` and `validation_public_key` parameters from each response somewhere secure.
+
+3. On each server, edit the [config file](https://github.com/ripple/rippled/blob/master/cfg/rippled-example.cfg), modifying the following sections:
+
+    1. List the IP address and port of each other server under the `[ips_fixed]` section. The port should be the one from the other servers' `protocol = peer` setting in their `rippled.cfg` (usually 51235). Each member of the cluster should list all _other_ members of the cluster here. For example:
+
+            [ips_fixed]
+            192.168.0.1 51235
+            192.168.0.2 51235
+
+        This defines specific peer servers to which this server should always attempt to maintain a direct peer-to-peer connection.
+
+    2. Set the server's node seed one of the `validation_seed` values you generated using the [validation_create method][] in step 2. Each server must use a unique node seed. For example:
+
+            [node_seed]
+            ssZkdwURFMBXenJPbrpE14b6noJSu
+
+        This defines the key pair the server uses to sign peer-to-peer communications, excluding validation messages.
+
+    3. Set the members of the server's cluster, identified by their `validation_public_key` values. Each server should list the public keys of all _other_ members of the cluster here. Optionally, add a custom name for each server.
+
+        For example:
+
+            [cluster_nodes]
+            n9McNsnzzXQPbg96PEUrrQ6z3wrvgtU4M7c97tncMpSoDzaQvPar keynes
+            n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa friedman
+
+        This defines the key pairs the server uses to recognize members of its cluster.
+
+4. After saving the config file, restart `rippled` on each server.
+
+        # systemctl restart rippled
+
+5. To confirm that each server is now a member of the cluster, use the [peers method][]. The `cluster` field should list the public keys and (if configured) the custom names for each server.
+
+    For example, using the commandline interface:
+
+        $ rippled peers
+
+        Loading: "/etc/rippled.cfg"
+        Connecting to 127.0.0.1:5005
+        {
+          "result" : {
+            "cluster" : {
+                "n9McNsnzzXQPbg96PEUrrQ6z3wrvgtU4M7c97tncMpSoDzaQvPar": {
+                  "tag": "keynes",
+                  "age": 1
+                },
+                "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa": {
+                  "tag": "friedman",
+                  "age": 1
+                }
+            },
+            "peers" : [
+              ... (omitted) ...
+            ],
+            "status" : "success"
+          }
+        }

-* Generate a unique seed (using the [validation_create method][]) for each of your servers, and configure it under the `[node_seed]` section. The `rippled` server uses this key to sign its messages to other servers in the peer-to-peer network.

-* Add the public keys (for peer communication) of each of your other servers under the `[cluster_nodes]` section.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}