Configure Online Deletion

In its default configuration, the xrpld server deletes history older than the most recent 2000 ledger versions, keeping approximately 15 minutes of ledger history (based on the current rate between ledgers). This page describes how to configure the amount of history your xrpld server stores before deleting.

This tutorial assumes your server meets the following prerequisites:

• You are on a supported operating system: Ubuntu Linux, Red Hat Enterprise Linux (RHEL), or CentOS.

• The xrpld server is already installed and online deletion is enabled.

  If you followed the installation instructions for a recommended platform, online deletion is enabled by default.

• Your server has enough disk space to store your chosen amount of history in its ledger store.

To change the amount of history your server stores, perform the following steps:

1. Decide how many ledger versions' worth of history to store.

   New ledger versions are usually validated 3 to 4 seconds apart, so the number of ledger versions corresponds roughly to the amount of time you want to store. See Capacity Planning for details of how much storage is required for different configurations.

   Online deletion is based on how many ledger versions to keep after deleting history, so you should have enough disk space to store twice as many ledgers as you set it to keep.

2. In your xrpld's config file, edit the online_delete field of the [node_db] stanza.

   [node_db]
   # Other settings unchanged ...
     online_delete=500000
     advisory_delete=0
     # Optional:
     # max_waiting_ledgers=300000

   Set online_delete to the minimum number of ledger versions to keep after running online deletion. With automatic deletion (the default), the server typically runs deletion when it has accumulated about twice this many ledger versions.

   Optionally, you can configure max_waiting_ledgers to limit how long the deletion process waits for the server to resync. If additional ledgers are validated during that time, the process aborts the current attempt and retries later. The minimum is 64, and it defaults to your online_delete value. This limit only includes ledgers validated while waiting on a stalled rotation, not normal forward progress.

   During the deletion process, the validated ledger is verified to ensure it is not older than age_threshold_seconds and that all recent ledgers are available without gaps. If these checks fail, the process waits and retries after a short period (default: 2 seconds).

   The recommended installation uses the config file /etc/xrpld/xrpld.cfg by default. Other places you can put a config file include $HOME/.config/xrpld/xrpld.cfg (where $HOME is the home directory of the user running rippled), $HOME/.local/xrpld/xrpld.cfg, or the current working directory from where you start rippled.

   The config file was renamed from rippled.cfg to xrpld.cfg. During the transition, if xrpld.cfg is not present the server still reads rippled.cfg from the same locations, so existing config files keep working without being renamed.

3. Start (or restart) the xrpld service.

   $ sudo systemctl restart xrpld

4. Wait for your server to sync to the network.

   Depending on your network and system capabilities and how long your server was offline, it may take between 5 and 15 minutes to fully sync.

   When your server is synced with the network, the server_info method reports a server_state value of "full", "proposing", or "validating".

5. Periodically check your server's complete_ledgers range using the server_info method to confirm that ledgers are being deleted.

   After online deletion runs, the complete_ledgers range reflects that older ledgers are no longer available. As your server accumulates history, the total number of ledgers available should slowly increase to twice the online_delete value you configured, then decrease when online deletion runs.

6. Monitor your xrpld logs for messages that begin with SHAMapStore:WRN. This can indicate that online deletion is being interrupted because your server fell out of sync with the network, or because there are gaps in your recent ledger history.

   Normal progress also logs under the same prefix, so the prefix alone doesn't identify an issue. For descriptions of these log messages, see Understanding Log Messages.

   The deletion process waits for the node to fully sync and fill any gaps. If it waits too long (specifically, if the network validates more ledgers than your max_waiting_ledgers limit during this pause), the deletion attempt is aborted and retried later.

   If this happens regularly, your server may not have sufficient specifications to keep up with the ledger while running online deletion. Check that other services on the same hardware (such as scheduled backups or security scans) aren't competing with the xrpld server for resources. You may want to try any of the following:

   • Increase your system specs. See System Requirements for recommendations.
   • Change your configuration to store less history. (Step 2 of this tutorial)
   • Change your server's node_size parameter.
   • Use NuDB instead of RocksDB for the ledger store.
   • Schedule online deletion using Advisory Deletion.

• Concepts:
  • Ledger History
    • Online Deletion
• Tutorials:
  • Configure Advisory Deletion
  • Capacity Planning
• References:
  • server_info method
  • Ledger Data Formats