From 3ce789e1dabd4e7fbbdf31a9f9c47c5d0ac12cce Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 27 Feb 2019 18:09:48 -0800 Subject: [PATCH] Peer crawler: config tutorial, notes for v1.2.1 uncertainties --- .../references/rippled-api/peer-crawler.md | 10 ++- .../configure-the-peer-crawler.md | 82 +++++++++++++++++++ dactyl-config.yml | 10 +++ 3 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 content/tutorials/manage-the-rippled-server/configuration/configure-the-peer-crawler.md diff --git a/content/references/rippled-api/peer-crawler.md b/content/references/rippled-api/peer-crawler.md index a4b216e5ef..b20b998f1d 100644 --- a/content/references/rippled-api/peer-crawler.md +++ b/content/references/rippled-api/peer-crawler.md @@ -31,7 +31,7 @@ The JSON object has the following fields: | `overlay.active` | Array | Array of Peer Objects, where each member is a peer that is connected to this server. | | `server` | Object | _(May be omitted)_ Information about this server. Contains the public fields from the [server_state method][]. | | `unl` | Object | _(May be omitted)_ Information about the validators and validator list sites this server is configured to trust, similar to the output of the [validators method][] and [validator_list_sites][] method. | -| `version` | Number | Indicates the version of this peer crawler response format. As of rippled v1.2.0, the current peer crawler version number is `1`. | +| `version` | Number | Indicates the version of this peer crawler response format. As of rippled v1.2.1, the current peer crawler version number is `2`. | Each member of the `active` array is a Peer Object with the following fields: @@ -71,3 +71,11 @@ Response: {% include '_code-samples/peer-crawler/crawl.json' %} ``` + +***TODO: Update the example for v1.2.1*** + +## See Also + +- [Peer Protocol](peer-protocol.html) +- [Configure the Peer Crawler](configure-the-peer-crawler.html) +- The [XRPL Network Crawler](https://github.com/ripple/rippled-network-crawler) is an example of a tool that uses the peer crawler data to collect and store information about the XRP Ledger network. diff --git a/content/tutorials/manage-the-rippled-server/configuration/configure-the-peer-crawler.md b/content/tutorials/manage-the-rippled-server/configuration/configure-the-peer-crawler.md new file mode 100644 index 0000000000..d6f68e7deb --- /dev/null +++ b/content/tutorials/manage-the-rippled-server/configuration/configure-the-peer-crawler.md @@ -0,0 +1,82 @@ +# Configure the Peer Crawler + +By default, `rippled` servers provide statistics publicly to anyone who asks using the [peer crawler API](peer-crawler.html), to make it easier to track the health and topology of the XRP Ledger's peer-to-peer network. You can configure your server to provide more or less information, or to reject peer crawler requests entirely. [New in: rippled 1.2.0][] + +This document contains steps for two options: + +- [Change the Information Reported by the Peer Crawler](#change-the-information-reported-by-the-peer-crawler) +- [Disabling the Peer Crawler](#disabling-the-peer-crawler) + +## Change the Information Reported by the Peer Crawler + +***TODO: figure out how the config relates to validators opting out in v1.2.1*** + +To configure how much information your server provides in response to peer crawler requests, complete the following steps: + +1. Edit your `rippled`'s config file. + + vim /etc/opt/ripple/rippled.cfg + + {% include '_snippets/conf-file-location.md' %} + +2. Add or update the `[crawl]` stanza in your config file, and save the changes: + + [crawl] + overlay = 1 + server = 1 + counts = 0 + unl = 1 + + The settings in this example represent the default values. A setting with a value of `1` means to share that type of information. A value of `0` means not to share that information. The information shared by each option is as follows (the types of data described for each option are a sample, not an exhaustive list): + + - **`overlay`** - Information about the peer servers your server is connected to, including: + - Their IP addresses, if they're not [private peers](peer-protocol.html#private-peers). + - The public keys they use for peer-to-peer communications. + - How long your server has been connected to them. + - The [ledger versions](ledger-history.html) they have available. + - **`server`** - Information about your server, including: + - What `rippled` version you are running. + - The [ledger versions](ledger-history.html) your server has available. + - The amount of load your server is experiencing. + - **`counts`** - Information about your server's memory usage, including: + - How large the ledger and transaction databases are + - How many objects of various types are cached in memory. Types of objects include ledgers (`Ledger`), transactions (`STTx`), validation messages (`STValidation`), and more. + - The cache hit rate for the in-application caches. + - **`unl`** - Information about your server's trusted validators, including: + - The URL of the [validator list site(s)](consensus-protections.html#validator-overlap-requirements) your server uses to find validators to trust + - When the validator list your server is using is scheduled to expire. + + The names of the config fields match the names of the fields they control in the [peer crawler response](peer-crawler.html#response-format). + +3. After saving the changes to the config file, restart your `rippled` server to apply the updated configuration: + + systemctl restart rippled + + +## Disabling the Peer Crawler + +To disable the peer crawler API on your server, so it does not respond to peer crawler requests at all, complete the following steps: + +1. Edit your `rippled`'s config file. + + vim /etc/opt/ripple/rippled.cfg + + {% include '_snippets/conf-file-location.md' %} + +2. Add or update the `[crawl]` stanza in your config file, and save the changes: + + [crawl] + 0 + + Remove or comment out all other contents of the crawl stanza. + +3. After saving the changes to the config file, restart your `rippled` server to apply the updated configuration: + + systemctl restart rippled + + + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index 3ad411d152..02a183e29b 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1132,6 +1132,16 @@ pages: targets: - local + - md: tutorials/manage-the-rippled-server/configuration/configure-the-peer-crawler.md + html: configure-the-peer-crawler.html + funnel: Docs + doc_type: Tutorials + category: Manage the rippled Server + subcategory: Configuration + blurb: Configure how much information your server reports publicly about its status and peers. + targets: + - local + - md: tutorials/manage-the-rippled-server/configuration/enable-public-signing.md html: enable-public-signing.html funnel: Docs