Peer reservations: more revs per reviews

content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_del.md

@@ -113,6 +113,13 @@ The response follows the [standard format][], with a successful result containin
 
 **Note:** If the specified reservation did not exist, this command returns success with an empty result object. In this case, the `previous` field is omitted.
 
+#### Peer Reservation Object
+
+If the `previous` field is provided, it shows the previous status of this peer reservation, with the following fields:
+
+{% include '_snippets/peer_reservation_object.md' %}
+<!--_ -->
+
 ### Possible Errors
 
 - Any of the [universal error types][].

content/tutorials/manage-the-rippled-server/configure-peering/use-a-peer-reservation.md

@@ -1,25 +1,34 @@
 # Use a Peer Reservation
 
-A [peer reservation][] is a setting that makes a `rippled` server always accept connections from a peer matching the reservation. The following steps describe how to use peer reservations to maintain a consistent connection from one server to a specific peer, with the permission of the peer server's administrator.
+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](rippled-server-modes.html#public-hubs) 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
 
-These steps describe how to connect `rippled` servers using a peer reservation. This is most useful when the two servers are run by different parties. To complete these steps, you must meet the following prerequisites:
+To complete these steps, you must meet the following prerequisites:
 
-- You have your own `rippled` [installed](install-rippled.html) and running.
-- You must have the cooperation of the administrator for the peer `rippled` server.
-- The peer `rippled` 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](forward-ports-for-peering.html).
-- Both servers must be configured to sync with the same [XRP Ledger network](parallel-networks.html) (such as the production XRP Ledger, the testnet, or the devnet)
+- The administrators both servers must have `rippled` [installed](install-rippled.html) 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](forward-ports-for-peering.html).
+- Both servers must be configured to sync with the same [XRP Ledger network](parallel-networks.html), such as the production XRP Ledger, the Testnet, or the Devnet.
 
 ## Steps
 
 To use a peer reservation, complete the following steps:
 
-### 1. Set up a permanent node key pair
+### 1. (Stock Server) Set up a permanent node key pair
 
-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](#2-communicate-your-node-public-key-to-the-peers-admin). (For example, setting up a permanent node key pair for each server is part of the process of [setting up a server cluster](cluster-rippled-servers.html).)
+The administrator of the stock server completes this step.
 
-**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 its 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.
+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](#2-communicate-the-stock-servers-node-public-key). (For example, setting up a permanent node key pair for each server is part of the process of [setting up a server cluster](cluster-rippled-servers.html).)
+
+**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.
 
 1. Generate a new, random key pair using the [validation_create method][]. (Omit the `secret` value.)
 
@@ -59,13 +68,13 @@ If you have already configured your server with a permanent node key pair value,
 
         systemctl restart rippled
 
-### 2. Communicate your node public key to the peer's admin
+### 2. Communicate the stock server's node public key
 
-Tell the administrator of the peer server what your node public key is. (Use the `validation_public_key` you saved earlier.) The administrator of the peer server needs this value to add the peer reservation for your server.
+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. (Peer administrator) Add the peer reservation
+### 3. (Hub Server) Add the peer reservation
 
-The administrator of the "peer" server (the one receiving the incoming peering connection) must complete this step.
+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:
 
@@ -84,13 +93,15 @@ Connecting to 127.0.0.1:5005
 
 **Tip:** The description is an optional field that you can provide to add a human-readable note about who this reservation is for.
 
-### 4. (Peer administrator) Communicate your current IP address and peer port
+### 4. Communicate the hub server's current IP address and peer port
 
-The administrator of the "peer" server (the one receiving the incoming peering connection) must tell their server's current IP address and peer port to the other administrator (the one whose server will make the outgoing peering connection). If your server is behind a firewall that does network address translation (NAT), you should provide your server's external IP address. The default config file uses port 51235 for the peer protocol.
+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. Connect to the peer server
+### 5. (Stock Server) Connect to the peer server
 
-Use the [connect method][] to connect your server to the peer server. For example:
+The administrator of the stock server completes this step.
+
+Use the [connect method][] to connect your server to the hub server. For example:
 
 <!-- MULTICODE_BLOCK_START -->
 
@@ -127,12 +138,12 @@ rippled connect 169.54.2.151 51235
 
 <!-- MULTICODE_BLOCK_END -->
 
-If the peer 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.
+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 the administrator, you can manage the reservations your server has for other peers. (It is not possible to check which servers have configured reservations for you.) You can:
+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][].