xrpl-dev-portal/content/concepts/networks-and-servers/peer-protocol.md

html, parent, blurb, labels

html	parent	blurb	labels
peer-protocol.html	networks-and-servers.html	The peer protocol specifies the language rippled servers speak to each other.	Core Server Blockchain

Peer Protocol

Servers in the XRP Ledger communicate to each other using the XRP Ledger peer protocol.

The peer protocol is the main mode of communication between servers in the XRP Ledger. All information about the behavior, progress, and connectivity of the XRP Ledger passes through the peer protocol. Examples of peer-to-peer communications include all of the following:

• Requesting a connection to other servers in the peer-to-peer network, or advertising that connection slots are available.
• Sharing candidate transactions with the rest of the network.
• Requesting ledger data from historical ledgers, or providing that data.
• Proposing a set of transactions for consensus, or sharing the calculated outcome of applying a consensus transaction set.

To set up a peer-to-peer connection, one server connects to another using HTTPS and requests an HTTP upgrade to switch to the XRPL/2.0 protocol (formerly RTXP/1.2). (For more information, see the Overlay Network article in the rippled repository.)

Peer Discovery

The XRP Ledger uses a "gossip" protocol to help find servers find others to connect to in the XRP Ledger network. Whenever a server starts up, it reconnects to any other peers it previously connected to. As a fallback, it uses the hardcoded public hubs. After a server successfully connects to a peer, it asks that peer for the contact information (generally, IP address and port) of other XRP Ledger servers that may also be seeking peers. The server can then connect to those servers, and ask them for the contact information of yet more XRP Ledger servers to peer with. Through this process, the server makes enough peer connections that it can remain reliably connected to the rest of the network even if it loses a connection to any single peer.

Typically, a server needs to connect to a public hub only once, for a short amount of time, to find other peers. After doing so, the server may or may not remain connected to the hub, depending on how stable its network connection is, how busy the hub is, and how many other high-quality peers the server finds. The server saves the addresses of these other peers so it can try reconnecting directly to those peers later, after a network outage or a restart.

The [peers method][] shows a list of peers your server is currently connected to.

For certain high-value servers (such as important validators) you may prefer not to have your server connect to untrusted peers through the peer discovery process. In this case, you can configure your server to use private peers only.

Peer Protocol Port

To participate in the XRP Ledger, rippled servers connect to arbitrary peers using the peer protocol. (All peers are treated as untrusted, unless they are clustered with the current server.)

Ideally, the server should be able to send and receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the rippled server.

IANA has assigned port 2459 for the XRP Ledger peer protocol, but for compatibility with legacy systems, the default rippled config file listens for incoming peer protocol connections on port 51235 on all network interfaces. If you run a server, you can configure which port(s) your server listens on using the rippled.cfg file.

Example:

[port_peer]
port = 2459
ip = 0.0.0.0
protocol = peer

The peer protocol port also serves special peer port methods.

Node Key Pair

When a server first starts up, it generates a node key pair to use to identify itself in peer protocol communications. The server uses its key to sign all its peer protocol communications. This makes it possible to reliably identify and verify the integrity of messages from another server in the peer-to-peer network even if that server's messages are being relayed by untrusted peers.

The node key pair is saved in the database and reused when the server restarts. If you delete the server's databases, it creates a new node key pair, effectively coming online with a different identity. To reuse the same key pair even if the databases are deleted, you can configure the server with a [node_seed] stanza. To generate a value suitable for use in the [node_seed] stanza, use the [validation_create method][].

The node key pair also identifies other servers for purposes of clustering or reserving peer slots. If you have a cluster of servers, you should configure each server in the cluster with a unique [node_seed] setting. For more information on setting up a cluster, see Cluster rippled Servers.

Fixed Peers and Peer Reservations

Normally, a rippled server attempts to maintain a healthy number of peers, and automatically connects to untrusted peers up to a maximum number. You can configure a rippled server to remain connected to specific peer servers in several ways:

• Use Fixed Peers to remain always connected to specific other peers based on their IP addresses. This only works if the peers have fixed IP addresses. Use the [ips_fixed] config stanza to configure fixed peers. This is a necessary part of clustering or private peers. Fixed peers are defined in the config file, so changes only apply after restarting the server. Fixed peers are most useful for keeping servers connected if those servers are run by the same person or organization.
• Use Peer Reservations to prioritize specific peers. If your server has a peer reservation for a specific peer, then your server always accepts connection requests from that peer even if your server is already at its maximum number of connected peers. (This can cause your server to go over the maximum number of peers.) You identify a reserved peer by its node key pair, so you can do this even for peers with variable IP addresses. Peer reservations are configured through admin commands and saved in the server databases, so they can be adjusted while the server is online and are saved across restarts. Peer reservations are most useful for connecting servers run by different people or organizations. [New in: rippled 1.4.0][]

In the following cases, a rippled server does not connect to untrusted peers:

• If the server is configured as a private peer, it connects only to its fixed peers.
• If the server is running in [stand-alone mode][] it does not connect to any peers.

Private Peers

You can configure a rippled server to act as a "private" server to keep its IP address hidden from the general public. This can be a useful precaution against denial of service attacks and intrusion attempts on important rippled servers such as trusted validators. To participate in the peer-to-peer network, a private server must be configured to connect to at least one non-private server, which relays its messages to the rest of the network.

Caution: If you configure a private server without any fixed peers, the server cannot connect to the network, so it cannot know network state, broadcast transactions, or participate in the consensus process.

Configuring a server as a private server has several effects:

• The server does not make outgoing connections to other servers in the peer-to-peer network unless it has been explicitly configured to connect to those servers.

• The server does not accept incoming connections from other servers unless it has been explicitly configured to accept connections from those servers.

• The server asks its direct peers not to reveal its IP address in untrusted communications, including the peer crawler API response. This does not affect trusted communications such as the [peers admin method][peers method].

  Validators always ask their peers to hide the validators' IP addresses, regardless of the private server settings. This helps protect validators from being overloaded by denial of service attacks. [New in: rippled 1.2.1][]

  Caution: It is possible to modify a server's source code so that it ignores this request and shares its immediate peers' IP addresses anyway. You should configure your private server to connect only to servers that you know are not modified in this way.

Pros and Cons of Peering Configurations

To be part of the XRP Ledger, a rippled server must be connected to the rest of the open peer-to-peer network. Roughly speaking, there are three categories of configurations for how a rippled server connects to the network:

• Using discovered peers. The server connects to any untrusted servers it finds and stays connected as long as those servers behave appropriately. (For example, they don't request too much data, their network connections are stable, and they appear to be following the same network.) This is the default.
• As a private server using proxies run by the same person or organization. The proxies are stock rippled servers (also connected to discovered peers) that maintain a fixed peering connection with the private server.
• As a private server using public hubs. This is similar to using proxies, but it relies on specific third parties.

The pros and cons of each configuration are as follows:

Configuration	Pros	Cons
Discovered Peers	Simplest configuration, with a low maintenance burden. Creates the opportunity for a lot of direct peer connections. Having more direct peers comes with several benefits. Your server can fetch history from multiple peers in parallel, both when syncing and when backfilling history. Since not all peers maintain full history, having access to more peers can also provide access to a wider range of historical data. Lowers the possibility of disconnecting from the network because your server can replace disconnected peers with new ones.	Doesn't allow you to select your server's peers, which means that you have no idea whether your peers may decide to act maliciously. Although `rippled` servers are designed to protect against malicious peers, there is always a risk that malicious peers could exploit software flaws to affect your server. Your server's peers may disconnect or change often.
Private Server Using Proxies	Most secure and reliable configuration when implemented effectively. As reliable and as redundant as you make it. Can optimize the private server's performance with clustering. Enables you to create as many direct peer connections as you want. Your private server can fetch history from multiple peers in parallel. Since you run the peers, you also control how much ledger history each peer keeps.	Higher maintenance burden and cost from running multiple servers. Does not completely rule out the possibility of peer connection outages. No matter how many proxies you run, if they all exist on the same server rack, then one network or power outage can affect all of them.
Private Server Using Public Hubs	Low maintenance burden with a small amount of configuration. Provides access to safe connections to the network. Compared to connecting using proxies, may be less likely to cause your private server to disconnect from the network due to a simultaneous peer outage.	Depends on high-reputation third parties to remain reliable. May cause your server to become disconnected from the network if the public hubs you rely on are too busy. Due to the nature of public hubs, they are the most popular and may not be able to keep a steady connection open to everyone. To help avoid this issue, use more public hubs; the more the better. It can also help to use non-default hubs, which are less likely to be busy.

Configuring a Private Server

To configure your server as a private server, set the [peer_private] setting to 1 in the config file. For detailed instructions, see Configure a Private Server.

See Also

• Concepts:
  • Consensus
  • Parallel Networks
• Tutorials:
  • Cluster rippled Servers
  • Configure a Private Server
  • Configure the Peer Crawler
  • Forward Ports for Peering
  • Manually Connect to a Specific Peer
  • Set Maximum Number of Peers
  • Use a Peer Reservation
• References:
  • [peers method][]
  • [peer_reservations_add method][]
  • [peer_reservations_del method][]
  • [peer_reservations_list method][]
  • [connect method][]
  • [fetch_info method][]
  • Peer Crawler

{% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} {% include '_snippets/rippled_versions.md' %}