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 the validation_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 running rippled), $HOME/.local/ripple/rippled.cfg, or the current working directory from where you start rippled.
Add a [node_seed] stanza using the validation_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.