Use a Peer Reservation
A peer reservation is a setting that makes a rippled
server always accept connections from a peer matching the reservation. This page describes how to use peer reservations to keep a consistent peer-to-peer connection between two servers, with the cooperation of the administrators of both servers.
Peer reservations are most useful when the two servers are run by different parties, and the server that receives the incoming connection is a hub server with many peers. For clarity, these instructions use the following terms:
- The server making the outgoing connection is the stock server. This server uses the peer reservation on the hub server.
- The server receiving the incoming connection is the hub server. The administrator adds the peer reservation to this server.
However, you can use these instructions to set up a peer reservation regardless of whether one server or both are hubs, validators, or stock servers. It is also possible to use a peer reservation when the busier server is the one making the outgoing connection, but this process does not describe that configuration.
Prerequisites
To complete these steps, you must meet the following prerequisites:
- The administrators both servers must have
rippled
installed and running. - The administrators of both servers must agree to cooperate and must be able to communicate. A public communications channel is fine because you don't need to share any secret information.
- The hub server must be able to receive incoming peer connections. For instructions on how to configure a firewall to allow this, see Forward Ports for Peering.
- Both servers must be configured to sync with the same XRP Ledger network, such as the production XRP Ledger, the Testnet, or the Devnet.
Steps
To use a peer reservation, complete the following steps:
1. (Stock Server) Set up a permanent node key pair
The administrator of the stock server completes this step.
If you have already configured your server with a permanent node key pair value, you can skip ahead to step 2: Communicate your node public key to the peer's admin. (For example, setting up a permanent node key pair for each server is part of the process of setting up a server cluster.)
Tip: Setting up a permanent node key pair is optional, but makes it easier to keep the peer reservation set up if you need to erase your server's databases or move to a new machine. If you don't want to set up a permanent node key pair, you can use your server's automatically-generated node public key as reported in the pubkey_node
field of the server_info method response.
Generate a new, random key pair using the validation_create method. (Omit the
secret
value.)For example:
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
(your node seed value) and thevalidation_public_key
value (your node public key )Edit your
rippled
's config file.vim /etc/opt/ripple/rippled.cfg
The recommended installation uses the config file
/etc/opt/ripple/rippled.cfg
by default. Other places you can put a config file include$HOME/.config/ripple/rippled.cfg
(where$HOME
is the home directory of the user runningrippled
),$HOME/.local/ripple/rippled.cfg
, or the current working directory from where you startrippled
.Add a
[node_seed]
stanza using thevalidation_seed
value you generated earlier.For example:
[node_seed] ssZkdwURFMBXenJPbrpE14b6noJSu
Warning: All servers should have unique
[node_seed]
values. If you copy your config file to another server, be sure to remove or change the[node_seed]
value. Keep your[node_seed]
secret; if a malicious actor gains access to this value, they could use it to impersonate your server in XRP Ledger peer-to-peer communications.Restart your
rippled
server:systemctl restart rippled
2. Communicate the stock server's node public key
The administrator of the stock server tells the administrator of the hub server what the stock server's node public key is. (Use the validation_public_key
from step 1.) The administrator of the hub server needs this value for the next steps.
3. (Hub Server) Add the peer reservation
The administrator of the hub server completes this step.
Use the peer_reservations_add method to add a reservation using the node public key that you got in the previous step. For example:
$ rippled peer_reservations_add n9Mxf6qD4J55XeLSCEpqaePW4GjoCR5U1ZeGZGJUCNe3bQa4yQbG "Description here" Loading: "/etc/opt/ripple/rippled.cfg" Connecting to 127.0.0.1:5005 { "result": { "status": "success" } }
Tip: The description is an optional field that you can provide to add a human-readable note about who this reservation is for.
4. Communicate the hub server's current IP address and peer port
The administrator of the hub server must tell their server's current IP address and peer port to the administrator of the stock server. If the hub server is behind a firewall that does network address translation (NAT), use the server's external IP address. The default config file uses port 51235 for the peer protocol.
5. (Stock Server) Connect to the peer server
The administrator of the stock server completes this step.
Use the connect method to connect your server to the hub server. For example:
{ "command": "connect", "ip": "169.54.2.151", "port": 51235 }
If the hub server's administrator has set up the peer reservation as described in the previous steps, this should automatically connect and remain connected as long as possible.
Next Steps
As a server administrator, you can manage the reservations your server has for other peers. (It is not possible to check which other servers have reservations for yours.) You can:
- Add more peer reservations or update their descriptions, using the peer_reservations_add method.
- Check which servers you have configured reservations for, using the peer_reservations_list method.
- Remove one of your reservations using the peer_reservations_del method.
- Check which peers are currently connected and how much bandwidth they have used, using the peers method.
Tip: Although there is no API method to immediately disconnect from an unwanted peer, you can use a software firewall such as firewalld
to block an unwanted peer from connecting to your server. For examples, see the community-contributed rbh script.