ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 03:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reorg infrastructure folders

Browse Source
This commit is contained in:
mDuo13
2023-11-08 16:33:32 -08:00
parent 99fdb92281
commit 5d0ddceea5
95 changed files with 263 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
content/infrastructure/configuration/configure-amendment-voting.md Normal file
View File

@@ -0,0 +1,74 @@
---
html: configure-amendment-voting.html
parent: configure-rippled.html
blurb: Set your server's votes on protocol amendments.
labels:
- Core Server
- Blockchain
---
# Configure Amendment Voting
Servers configured as validators can vote on [amendments](amendments.html) to the XRP Ledger protocol using the [feature method][]. (This method requires [admin access](get-started-using-http-websocket-apis.html#admin-access).)
For example, to vote against the "SHAMapV2" amendment, run the following command:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": "any_id_here",
"command": "feature",
"feature": "SHAMapV2",
"vetoed": true
}
```
*JSON-RPC*
```json
{
"method": "feature",
"params": [
{
"feature": "SHAMapV2",
"vetoed": true
}
]
}
```
*Commandline*
```sh
rippled feature SHAMapV2 reject
```
<!-- MULTICODE_BLOCK_END -->
**Note:** The short name of the amendment is case-sensitive. You can also use an amendment's ID as hexadecimal, which is not case sensitive.
## Using the Config File
If you prefer to use the config file to configure amendment voting, you can add a line to the `[rpc_startup]` stanza to run the command automatically on startup for each explicit vote. For example:
```
[rpc_startup]
{ "command": "feature", "feature": "SHAMapV2", "vetoed": true }
```
Be sure to restart your server for changes to take effect.
**Caution:** Any commands in the `[rpc_startup]` stanza run each time the server starts up, which can override voting settings you configured while the server was running.
## See Also
- [Amendments](amendments.html)
- [Known Amendments](known-amendments.html)
- [feature method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

56
content/infrastructure/configuration/configure-grpc.md Normal file
View File

@@ -0,0 +1,56 @@
---
html: configure-grpc.html
parent: configure-rippled.html
blurb: Enable and configure the gRPC API.
labels:
- Core Server
---
# Configure gRPC
The `rippled` server has a limited [gRPC API](https://grpc.io/) which [P2P mode servers](rippled-server-modes.html) can provide. Reporting mode servers use this API to retrieve data about the latest validated ledgers and transactions. You can enable the gRPC API on your server with a new configuration stanza.
**Caution:** gRPC support is intended specifically for providing data to reporting mode servers from P2P mode servers. Breaking changes to the gRPC API may occur without warning or it may be removed entirely in future versions of the server.
## Prerequisites
To enable gRPC, you must meet the following prerequisites:
- You must have [installed rippled](install-rippled.html).
- Your server must be able to bind to the port you choose.
## Steps
To enable gRPC on your server, complete the following steps:
1. Ensure the `[port_grpc]` stanza is in your `rippled` config file.
[port_grpc]
port = 50051
ip = 127.0.0.1
- `port` defines the port the server listens on for gRPC connections from client applications. The recommended port is `50051`.
- `ip` defines which interfaces the server listens on. `127.0.0.1` limits connections to the local loopback network (same machine) and is enabled by default. Changing the value to `0.0.0.0` listens on all available network interfaces.
{% include '_snippets/conf-file-location.md' %}
2. Start (or restart) the `rippled` service.
sudo systemctl restart rippled
## See Also
- **Concepts:**
- [XRP Ledger Overview](xrp-ledger-overview.html)
- [`rippled` Server Modes](rippled-server-modes.html)
- **Tutorials:**
- [Get Started Using HTTP / WebSocket APIs](get-started-using-http-websocket-apis.html)
- [Reliable Transaction Submission](reliable-transaction-submission.html)
- [Manage the rippled Server](manage-the-rippled-server.html)
- **References:**
- [HTTP / WebSocket API Reference](http-websocket-apis.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

66
content/infrastructure/configuration/configure-statsd.md Normal file
View File

@@ -0,0 +1,66 @@
---
html: configure-statsd.html
parent: configure-rippled.html
blurb: Monitor your rippled server with StatsD metrics.
labels:
- Core Server
---
# Configure StatsD
`rippled` can export health and behavioral information about itself in [StatsD](https://github.com/statsd/statsd) format. Those metrics can be consumed and visualized through [`rippledmon`](https://github.com/ripple/rippledmon) or any other collector that accepts StatsD formatted metrics.
## Configuration Steps
To enable StatsD on your `rippled` server, perform the following steps:
1. Set up a `rippledmon` instance on another machine to receive and aggregate stats.
$ git clone https://github.com/ripple/rippledmon.git
$ cd rippledmon
$ docker-compose up
Make sure [Docker](https://docs.docker.com/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed on your machine when performing the steps above. For more information about configuring `rippledmon`, see the [`rippledmon` repository](https://github.com/ripple/rippledmon).
0. Add the `[insight]` stanza to your `rippled`'s config file.
[insight]
server=statsd
address=192.0.2.0:8125
prefix=my_rippled
- For the `address`, use the IP address and port where `rippledmon` is listening. By default, this port is 8125.
- For the `prefix`, choose a name that identifies the `rippled` server you are configuring. The prefix must not include whitespace, colons ":", or the vertical bar "|". The prefix appears on all of the StatsD metrics exported from this server.
{% include '_snippets/conf-file-location.md' %}<!--_ -->
0. Restart the `rippled` service.
$ sudo systemctl restart rippled
0. Check that the metrics are being exported:
$ tcpdump -i en0 | grep UDP
Replace `en0` with the appropriate network interface for your machine. For a complete list of the interfaces on your machine use `$ tcpdump -D`.
Sample Output:
00:41:53.066333 IP 192.0.2.2.63409 > 192.0.2.0.8125: UDP, length 196
You should periodically see messages indicating outbound traffic to the configured address and port of your `rippledmon` instance.
For descriptions of each StatsD metric, see the [`rippledmon` repository](https://github.com/ripple/rippledmon).
## See Also
- **Concepts:**
- [XRP Ledger Overview](xrp-ledger-overview.html)
- [The `rippled` Server](xrpl-servers.html)
- **Tutorials:**
- [Install `rippled`](install-rippled.html)
- [Capacity Planning](capacity-planning.html)
- **References:**
- [server_info method](server_info.html)
- [print method](print.html)

234
content/infrastructure/configuration/connect-your-rippled-to-the-xrp-test-net.md Normal file
View File

@@ -0,0 +1,234 @@
---
html: connect-your-rippled-to-the-xrp-test-net.html
parent: configure-rippled.html
blurb: Connect your rippled server to the test net to try out new features or test functionality with fake money.
labels:
- Core Server
- Blockchain
- Development
---
# Connect Your rippled to a Parallel Network
Various [alternative test and development networks](parallel-networks.html) exist for developers to test their apps or experiment with features without risking real money. **The funds used on these networks are not real funds and are intended for testing only.** You can connect your [`rippled` server](xrpl-servers.html) to any of these test networks.
**Caution:** On test networks with new and experimental features, you may need to run a pre-production release of the server to sync with the network. See the [Parallel Networks Page](parallel-networks.html) for information on what code version each network needs.
## Steps
To connect your `rippled` server to the XRP Testnet or Devnet, complete these steps. You can also use these steps to switch back to the production Mainnet after being on the Testnet or Devnet.
## 1. Configure your server to connect to the right hub.
Edit your `rippled.cfg` file.
{% include '_snippets/conf-file-location.md' %}
<!--{_ }-->
1. Set an `[ips]` stanza with the hub for the network you want to connect to:
<!-- MULTICODE_BLOCK_START -->
*Testnet*
[ips]
s.altnet.rippletest.net 51235
*Devnet*
[ips]
s.devnet.rippletest.net 51235
*Mainnet*
# No [ips] stanza. Use the default hubs to connect to Mainnet.
*AMM-Devnet*
[ips]
amm.devnet.rippletest.net 51235
<!-- MULTICODE_BLOCK_END -->
2. Comment out the previous `[ips]` stanza, if there is one:
# [ips]
# r.ripple.com 51235
# zaphod.alloy.ee 51235
# sahyadri.isrdc.in 51235
3. Add a `[network_id]` stanza with the appropriate value:
<!-- MULTICODE_BLOCK_START -->
*Testnet*
[network_id]
testnet
*Devnet*
[network_id]
devnet
*Mainnet*
[network_id]
main
*AMM-Devnet*
[network_id]
25
<!-- MULTICODE_BLOCK_END -->
For custom networks, everyone who connects to the network should use a value unique to that network. When creating a new network, choose a network ID at random from the integers 11 to 4,294,967,295.
**Note:** This setting helps your server find peers who are on the same network, but it is not a hard control on what network your server follows. The UNL / trusted validator settings (in the next step) are what actually define what network the server follows.
## 2. Set your trusted validator list.
Edit your `validators.txt` file. This file is located in the same folder as your `rippled.cfg` file and defines which validators your server trusts not to collude.
1. Uncomment or add the `[validator_list_sites]` and `[validator_list_keys]` stanzas for the network you want to connect to:
<!-- MULTICODE_BLOCK_START -->
*Testnet*
[validator_list_sites]
https://vl.altnet.rippletest.net
[validator_list_keys]
ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860
*Devnet*
[validator_list_sites]
https://vl.devnet.rippletest.net
[validator_list_keys]
EDDF2F53DFEC79358F7BE76BC884AC31048CFF6E2A00C628EAE06DB7750A247B12
*Mainnet*
[validator_list_sites]
https://vl.ripple.com
[validator_list_keys]
ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734
*AMM-Devnet*
[validator_list_sites]
http://vlamm.devnet.rippletest.net/
[validator_list_keys]
03553F67DC5A6FE0EBFE1B3B4742833D14AF7C65E79E5760EC76EC56EAFD254CE9
<!-- MULTICODE_BLOCK_END -->
**Tip:** Preview packages might come with the necessary stanzas pre-configured, but check them just in case.
1. Comment out any previous `[validator_list_sites]`, `[validator_list_keys]`, or `[validators]` stanzas.
For example:
# [validator_list_sites]
# https://vl.ripple.com
#
# [validator_list_keys]
# ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734
# Old hard-coded List of Devnet Validators
# [validators]
# n9Mo4QVGnMrRN9jhAxdUFxwvyM4aeE1RvCuEGvMYt31hPspb1E2c
# n9MEwP4LSSikUnhZJNQVQxoMCgoRrGm6GGbG46AumH2KrRrdmr6B
# n9M1pogKUmueZ2r3E3JnZyM3g6AxkxWPr8Vr3zWtuRLqB7bHETFD
# n9MX7LbfHvPkFYgGrJmCyLh8Reu38wsnnxA4TKhxGTZBuxRz3w1U
# n94aw2fof4xxd8g3swN2qJCmooHdGv1ajY8Ae42T77nAQhZeYGdd
# n9LiE1gpUGws1kFGKCM9rVFNYPVS4QziwkQn281EFXX7TViCp2RC
# n9Jq9w1R8UrvV1u2SQqGhSXLroeWNmPNc3AVszRXhpUr1fmbLyhS
## 3. Enable (or Disable) Features
For some test networks using experimental features, you must also forcefully enable the appropriate feature in the config file. For other networks, you should not use the `[features]` stanza. Add or modify the `[features]` stanza of your config file as follows:
<!-- MULTICODE_BLOCK_START -->
_Testnet_
```
# [features]
# Delete or comment out. Don't force-enable features on Testnet.
```
_Devnet_
```
# [features]
# Delete or comment out. Don't force-enable features on Devnet.
```
_Mainnet_
```
# [features]
# Delete or comment out. Don't force-enable features on Mainnet.
```
_AMM-Devnet_
```
[features]
AMM
```
<!-- MULTICODE_BLOCK_END -->
**Warning:** Do not use the `[features]` stanza when connecting to Mainnet or Testnet. Forcefully enabling different features than the rest of the network could cause your server to diverge from the network.
## 4. Restart the server.
```sh
$ sudo systemctl restart rippled
```
## 5. Verify that your server syncs.
It takes about 5 to 15 minutes to sync to the network after a restart. After your server is synced, the [server_info method][] shows a `validated_ledger` object based on the network you are connected to.
To confirm that your `rippled` is connected to the right network, compare the results from your server to [a public server][public servers] on the Testnet or Devnet. The `seq` field of the `validated_ledger` object should be the same on both servers (possibly off by one or two, if it changed as you were checking).
The following example shows how to check your server's latest validated ledger from the commandline:
```sh
rippled server_info | grep seq
```
You can use [server_info in the WebSocket Tool](websocket-api-tool.html#server_info) to look up the latest ledger index (`seq`) on the intended network.
## See Also
- **Tools:**
- [XRP Faucets](xrp-testnet-faucet.html)
- [WebSocket API Tool](websocket-api-tool.html) - Select 'Testnet Public Server' or 'Devnet Public Server' in the connection options.
- **Concepts:**
- [Parallel Networks](parallel-networks.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Run rippled as a Validator](run-rippled-as-a-validator.html)
- [Test `rippled` Offline in Stand-Alone Mode](use-stand-alone-mode.html)
- [Troubleshooting `rippled`](troubleshoot-the-rippled-server.html)
- **References:**
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

121
content/infrastructure/configuration/data-retention/configure-advisory-deletion.md Normal file
View File

@@ -0,0 +1,121 @@
---
html: configure-advisory-deletion.html
parent: data-retention.html
blurb: Use advisory deletion to delete older ledger history on a schedule rather than as new history becomes available.
labels:
- Core Server
- Data Retention
---
# Configure Advisory Deletion
The default config file sets [`rippled`](xrpl-servers.html) to automatically delete outdated [history](ledger-history.html) of XRP Ledger state and transactions as new ledger versions become available. If your server uses most of its hardware resources during peak hours, you can configure the server to delete ledgers only when prompted by a command scheduled to run during off-peak hours, so that online deletion is less likely to impact [server performance](capacity-planning.html).
## Prerequisites
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 `rippled` server is already [installed](install-rippled.html) and [online deletion](online-deletion.html) is enabled.
The default config file enables online deletion after 2000 ledger versions.
- A `cron` daemon is installed and running.
Ubuntu Linux runs a `cron` daemon by default.
On RHEL or CentOS, you can install the `cronie` package:
$ sudo yum install cronie
- Your server has enough disk space to store your chosen amount of history in its ledger store.
See [Capacity Planning](capacity-planning.html) for details of how much storage is required for different configurations. With advisory deletion enabled, the maximum history a server may accumulate before deletion is equal to the number of ledger versions configured in the `online_delete` setting **plus** the amount of time between online deletion prompts.
- You know which hours are least busy for your server.
## Configuration Steps
To configure advisory deletion with a daily schedule, perform the following steps:
1. Enable `advisory_delete` in the `[node_db]` stanza of your `rippled`'s config file.
[node_db]
# Other settings unchanged ...
online_delete=2000
advisory_delete=1
- Set `advisory_delete` to `1` to run online deletion only when prompted. (Set it to `0` to run online deletion automatically as new ledger versions become available.)
- Set `online_delete` to the minimum number of ledger versions to keep after running online deletion. The server accumulates more history than this until online deletion runs.
{% include '_snippets/conf-file-location.md' %}<!--_ -->
2. Test running the [can_delete method][] to prompt the server to run online deletion.
You can use the [`rippled` commandline interface](get-started-using-http-websocket-apis.html#commandline) to run this command. For example:
$ rippled --conf=/etc/opt/ripple/rippled.cfg can_delete now
The response indicates the maximum ledger index that the server may delete from its ledger store. For example, the following message indicates that ledger versions up to and including ledger index 43633667 can be deleted:
{
"result": {
"can_delete": 43633667,
"status": "success"
}
}
The server only deletes those ledger versions if the number of _newer_ validated ledger versions it has is equal to or greater than the `online_delete` setting.
3. Configure your `cron` daemon to run the `can_delete` method you tested in the previous step at a scheduled time.
Edit your `cron` configuration:
$ crontab -e
The following example sets the server to run deletion at 1:05 AM server time daily:
5 1 * * * rippled --conf /etc/opt/ripple/rippled.cfg can_delete now
Be sure that you schedule the command to run based on your server's configured time zone.
**Tip:** You do not need to schedule a `cron` job to run online deletion if you have `advisory_delete` disabled. In that case, `rippled` runs online deletion automatically when the difference between the server's oldest and current validated ledger versions is at least the value of `online_delete`.
4. Start (or restart) the `rippled` service.
$ sudo systemctl restart rippled
5. Periodically check your server's `complete_ledgers` range using the [server_info method][] to confirm that ledgers are being deleted as scheduled.
The lowest ledger index in `complete_ledgers` should increase after online deletion.
Deletion may take several minutes to complete when it runs, depending on how busy your server is and how much history you delete at a time.
## Troubleshooting
If online deletion does not seem to be running after configuring it, try the following:
- Check that the user who configured the `cron` job has permissions to run the `rippled` server as a commandline client.
- Check the syntax of your `cron` job and the time when it is supposed to run.
- Check that the `rippled` executable is available at the path specified in your `cron` configuration. If necessary, specify the absolute path to the executable, such as `/opt/ripple/bin/rippled`.
- Check your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that [online deletion is being interrupted](online-deletion.html#interrupting-online-deletion) because your server fell out of sync with the network.
## See Also
- **Concepts:**
- [Ledger History](ledger-history.html)
- [Online Deletion](online-deletion.html)
- **Tutorials:**
- [Configure Online Deletion](configure-online-deletion.html)
- [Diagnosing Problems with rippled](diagnosing-problems.html)
- [Understanding Log Messages](understanding-log-messages.html)
- **References:**
- [server_info method][]
- [can_delete method][]
- [logrotate method][]
- [Ledger Data Formats](ledger-data-formats.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

117
content/infrastructure/configuration/data-retention/configure-full-history.md Normal file
View File

@@ -0,0 +1,117 @@
---
html: configure-full-history.html
parent: data-retention.html
blurb: Full history servers provide a record of every transaction ever to occur in the XRP Ledger, although they are expensive to run.
labels:
- Core Server
- Data Retention
---
# Configure Full History
In its default configuration, the `rippled` server automatically deletes outdated history of XRP Ledger state and transactions as new ledger versions become available. This is enough for most servers, which do not need older history to know the current state and process transactions. However, it can be useful for the network if some servers provide as much history of the XRP Ledger as possible.
## Warnings
Storing full history is expensive. As of 2023-07-19, the full history of the XRP Ledger occupies approximately **26 terabytes** of disk space, which must be entirely stored on fast solid state disk drives for proper server performance. Such a large amount of solid state storage is not cheap, and the total amount of history you must store increases by approximately 12 GB per day.
Additionally, storing full history in NuDB requires single files that are larger than the 16 TB limit of ext4 filesystems, which is the default on many Linux distributions. You must use a filesystem with a larger single-file limit, such as XFS (recommended) or ZFS.
Acquiring full history from the peer-to-peer network takes a long time (several months) and requires that your server has enough system and network resources to acquire older history while keeping up with new ledger progress. To get a faster start on acquiring ledger history, you may want to find another server operator who has a large amount of history already downloaded, who can give you a database dump or at least allow your server to explicitly peer with theirs for a long time to acquire history. The server can load ledger history from a file and verify the integrity of the historical ledgers it imports.
You do not need a full history server to participate in the network, validate transactions, or know the current state of the network. Full history is only useful for knowing the outcome of transactions that occurred in the past, or the state of the ledger at a given time in the past. To get such information, you must rely on other servers having the history you need.
If you want to contribute to storing the history of the XRP Ledger network without storing the full history, you can [configure history sharding](configure-history-sharding.html) to store randomly-selected chunks of ledger history instead.
## Configuration Steps
To configure your server to acquire and store full history, complete the following steps:
1. Stop the `rippled` server if it is running.
$ sudo systemctl stop rippled
0. Remove (or comment out) the `online_delete` and `advisory_delete` settings from the `[node_db]` stanza of your server's config file, and change the type to `NuDB` if you haven't already:
[node_db]
type=NuDB
path=/var/lib/rippled/db/nudb
#online_delete=2000
#advisory_delete=0
On a full-history server, you should use NuDB for the ledger store, because RocksDB requires too much RAM when the database is that large. For more information, see [Capacity Planning](capacity-planning.html). You can remove the following performance-related configuration options from the default `[node_db]` stanza, because they only apply to RocksDB: `open_files`, `filter_bits`, `cache_mb`, `file_size_mb`, and `file_size_mult.`
**Caution:** If you have any history already downloaded with RocksDB, you must either delete that data or change the paths to the databases in the config file when you switch to NuDB. You must change both the `path` field of the `[node_db]` stanza **and** the `[database_path]` (SQLite database) setting. Otherwise, the server may [fail to start](server-wont-start.html#state-db-error).
{% include '_snippets/conf-file-location.md' %}<!--_ -->
0. Set the `[ledger_history]` stanza of your server's config file to `full`:
[ledger_history]
full
0. Set the `[ips_fixed]` stanza of your server's config file to explicitly peer with at least one server that has full history available.
[ips_fixed]
169.55.164.20 51235
50.22.123.215 51235
Your server can only download historical data from the peer-to-peer network if one its direct peers has the data available. The easiest way to ensure you can download full history is to peer with a server that already has full history.
**Tip:** Ripple makes a pool of full history servers publicly available. You can resolve the domain `s2.ripple.com` a few times to get the IP addresses of these servers. Ripple offers these servers as a public service, so be aware that their availability to peer with other servers is limited and you may be blocked if you abuse them.
0. If you have a database dump from another full-history server to use as a basis, set the `[import_db]` stanza of your server's config file to point to the data to be imported. (Otherwise, skip this step.)
[import_db]
type=NuDB
path=/tmp/full_history_dump/
0. Remove your server's existing database files, if you have any from previously running `rippled`.
After disabling online deletion, the server ignores any data that was downloaded while online deletion was enabled, so you may as well clear up the disk space. For example:
rm -r /var/lib/rippled/db/*
**Warning:** Be sure that you have not put any files you want to keep in the folder before you delete it. It is generally safe to delete all of a `rippled` server's database files, but you should only do this if the configured database folder is not used for anything other than `rippled`'s databases.
0. Start the `rippled` server, importing the database dump if you have one available:
If you have a database dump to load configured in `[import_db]`, start the server explicitly and include the `--import` [commandline option](commandline-usage.html#daemon-mode-options):
$ /opt/ripple/bin/rippled --conf /etc/opt/ripple/rippled.cfg --import
Importing a large database dump may take several minutes or even hours. During this time, the server is not fully started and synced with the network. Watch the server logs to see the status of the import.
If you are not importing a database dump, start the server normally:
$ sudo systemctl start rippled
0. If you added an `[import_db]` stanza to your server's config file, remove it after the import completes.
Otherwise, your server may try to import the same data again the next time it is restarted.
0. Monitor your server's available history with the [server_info method][].
The range of available ledgers reported in the `complete_ledgers` field should increase over time.
The earliest available ledger version in the production XRP Ledger's history is ledger index **32570**. The first two weeks or so of ledger history was lost due to a bug in the server at the time. [Test nets and other chains](parallel-networks.html) generally have history going back to ledger index **1**.
## See Also
- **Concepts:**
- [Ledger History](ledger-history.html)
- [rippled Server Modes](rippled-server-modes.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html), particularly [Disk Space](capacity-planning.html#disk-space)
- [Configure Online Deletion](configure-online-deletion.html)
- [Diagnosing Problems with rippled](diagnosing-problems.html)
- [Understanding Log Messages](understanding-log-messages.html)
- **References:**
- [server_info method][]
- [can_delete method][]
- [Ledger Data Formats](ledger-data-formats.html)
- [rippled Commandline Usage Reference](commandline-usage.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

91
content/infrastructure/configuration/data-retention/configure-history-sharding.md Normal file
View File

@@ -0,0 +1,91 @@
---
html: configure-history-sharding.html
parent: data-retention.html
blurb: Set up a server to contribute to preserving shards of historical XRP Ledger data.
labels:
- Data Retention
- Core Server
---
# Configure History Sharding
[History Sharding](history-sharding.html) lets servers contribute to preserving historical XRP Ledger data without each server needing to store the full history. By default, `rippled` servers do not store history shards.
**Tip:** While both validator and tracking (or stock) `rippled` servers can be configured to store history shards, Ripple recommends _not_ configuring validator `rippled` servers to store shards, to reduce overhead on those servers. If you run a validator and want to contribute to storing XRP Ledger history, Ripple recommends you run a separate `rippled` server with history sharding enabled.
To configure your `rippled` to store shards of ledger history, complete the following steps:
## 1. Determine how many shards to maintain
Before you configure your `rippled` server to store history shards, you must decide how many history shards you want to keep, which is mostly determined by how much disk space is available for the shard store. This also affects how much history you keep in the default ledger store. You should consider the following when deciding what size to configure your shard store:
- The ledger store (defined by the `[node_db]` stanza) is separate from the history shard store. The ledger store is required for all servers, and always contains a range of recent history, defined by how many ledgers to keep available in the `online_delete` parameter. (The default configuration stores the most recent 2000 ledgers.)
- If you keep at least 2<sup>15</sup> ledgers (32768) in the ledger store, you can efficiently import chunks of recent history from the ledger store into the shard store.
- The history shard store (defined by the `[shard_db]` stanza) is only required for storing history shards. The configuration stanza should be omitted from servers that do not store history shards. The total number of shards stored is defined by the `max_historical_shards` parameter; the server attempts to store no more than this many complete shards. The history shard store _MUST_ be stored on a solid-state disk or similar fast media. Traditional spinning hard disks are insufficient.
- A shard consists of 2<sup>14</sup> ledgers (16384) and occupies approximately 200 MB to 4 GB based on the age of the shard. Older shards are smaller because there was less activity in the XRP Ledger at the time.
- The history shard store and the ledger store _MUST_ be stored at different file paths. You can configure the ledger store and history store to be on different disks or partitions if desired.
- It is possible but redundant to hold full ledger history in both the ledger store and the history shard store.
- The time to acquire a shard, number of file handles needed by the `rippled` server, and memory cache usage is directly affected by the size of the shard.
- You can specify additional paths to store older history shards by providing a `[historical_shard_paths]` stanza. These paths may be on different, slower disks because they hold data that is used less often. The most recent two shards (the ones with the largest ledger indexes) are always stored in the path specified in the `[shard_db]` stanza. [New in: rippled 1.7.0][]
## 2. Edit rippled.cfg
<!-- SPELLING_IGNORE: cfg -->
Edit your `rippled.cfg` file to add a `[shard_db]` stanza and optionally a `[historical_shard_paths]` stanza.
{% include '_snippets/conf-file-location.md' %}<!--_ -->
The following snippet shows an example of a `[shard_db]` stanza:
```
[shard_db]
path=/var/lib/rippled/db/shards/nudb
max_historical_shards=12
# Optional paths for shards other than the newest 2
[historical_shard_paths]
/mnt/disk1
/mnt/disk2
```
The `type` field of `[shard_db]` can be omitted. If present, it _MUST_ be `NuDB`. [New in: rippled 1.3.1][]
**Caution:** If `rippled` detects the wrong type of data in the shard store path, it may [fail to start](server-wont-start.html). You should use a new folder for the shard store. If you previously used a RocksDB shard store (`rippled` 1.2.x and lower), use a different path or delete the RocksDB shard data.
For more information, reference the `[shard_db]` example in the [rippled.cfg configuration example](https://github.com/XRPLF/rippled/blob/master/cfg/rippled-example.cfg).
## 3. Restart the server
```
systemctl restart rippled
```
## 4. Wait for shards to download
After your server syncs to the network, it automatically starts downloading history shards to fill the available space in the shard store. You can see which shards are being downloaded by looking at which folders are created in the folder where you configured your shard store. (This is defined by the `path` field of the `[shard_db]` stanza in the `rippled.cfg` file.)
This folder should contain a numbered folder for each shard your server has. At any given time, up to one folder may contain a `control.txt` file, indicating it is incomplete.
You can instruct your server to download and import a shard from an archive file using the [download_shard method][].
To list the shards your server and its peers have available, you can use the [crawl_shards method][] or the [Peer Crawler](peer-crawler.html).
## See Also
- **Concepts:**
- [Ledger History](ledger-history.html)
- [Online Deletion](online-deletion.html)
- **Tutorials:**
- [Configure Online Deletion](configure-online-deletion.html)
- [Configure the Peer Crawler](configure-the-peer-crawler.html)
- [Capacity Planning](capacity-planning.html)
- **References:**
- [download_shard method][]
- [crawl_shards method][]
- [Ledger Data Formats](ledger-data-formats.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

90
content/infrastructure/configuration/data-retention/configure-online-deletion.md Normal file
View File

@@ -0,0 +1,90 @@
---
html: configure-online-deletion.html
parent: data-retention.html
blurb: Configure how far back your server should store transaction history.
labels:
- Core Server
- Data Retention
---
# Configure Online Deletion
In its default configuration, [the `rippled` server](xrpl-servers.html) [deletes history](online-deletion.html) older than the most recent 2000 [ledger versions](ledgers.html), keeping approximately 15 minutes of [ledger history](ledger-history.html) (based on the current rate between ledgers). This page describes how to configure the amount of history your `rippled` server stores before deleting.
## Prerequisites
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 `rippled` server is already [installed](install-rippled.html) and [online deletion](online-deletion.html) is enabled.
If you followed the installation instructions for a recommended platform, online deletion is enabled by default.
- Your server has [enough disk space](capacity-planning.html#disk-space) to store your chosen amount of history in its ledger store.
## Configuration Steps
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](capacity-planning.html) 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.
0. In your `rippled`'s config file, edit the `online_delete` field of the `[node_db]` stanza.
[node_db]
# Other settings unchanged ...
online_delete=2000
advisory_delete=0
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.
{% include '_snippets/conf-file-location.md' %}<!--_ -->
0. Start (or restart) the `rippled` service.
$ sudo systemctl restart rippled
0. 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"`.
0. 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.
0. Monitor your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that [online deletion is being interrupted](online-deletion.html#interrupting-online-deletion) because your server fell out of sync with the network.
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 `rippled` server for resources. You may want to try any of the following:
- Increase your system specs. See [System Requirements](system-requirements.html) for recommendations.
- Change your configuration to store less history. (Step 2 of this tutorial)
- Change your server's [`node_size` parameter](capacity-planning.html).
- Use [NuDB instead of RocksDB](capacity-planning.html) for the ledger store.
- [Schedule online deletion using Advisory Deletion](configure-advisory-deletion.html).
## See Also
- **Concepts:**
- [Ledger History](ledger-history.html)
- [Online Deletion](online-deletion.html)
- **Tutorials:**
- [Configure Advisory Deletion](configure-advisory-deletion.html)
- [Configure History Sharding](configure-history-sharding.html)
- [Capacity Planning](capacity-planning.html)
- **References:**
- [server_info method][]
- [Ledger Data Formats](ledger-data-formats.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

54
content/infrastructure/configuration/data-retention/history-sharding.md Normal file
View File

@@ -0,0 +1,54 @@
---
html: history-sharding.html
parent: data-retention.html
blurb: History sharding divides the work of keeping historical ledger data among rippled servers.
labels:
- Data Retention
- Core Server
---
# History Sharding
[Introduced in: rippled 0.90.0][]
As XRP Ledger servers run, they naturally produce a database containing data about the ledgers they built or acquired during network runtime. Each server stores that ledger data in its _ledger store_, but [online deletion](online-deletion.html) removes old ledgers' data automatically over time. History sharding provides a separate storage system for older ledger history so that the network can divide up the work of recording the entire (multiple terabyte) history of the XRP Ledger.
Historical sharding distributes the transaction history of the XRP Ledger into segments, called shards, across servers in the XRP Ledger network. A shard is a range of ledgers. A server uses mostly the same format for ledgers in both the ledger store and the shard store, but the two stores are separate.
[![XRP Ledger Network: Ledger Store and Shard Store Diagram](img/xrp-ledger-network-ledger-store-and-shard-store.png)](img/xrp-ledger-network-ledger-store-and-shard-store.png)
<!-- Diagram source: https://docs.google.com/presentation/d/1mg2jZQwgfLCIhOU8Mr5aOiYpIgbIgk3ymBoDb2hh7_s/edit#slide=id.g417450e8da_0_316 -->
## Acquiring and Sharing History Shards
Servers acquire and store history shards only if configured to do so. Acquiring shards begins after synchronizing with the network and backfilling ledger history to the configured number of recent ledgers. During this time of lower network activity, a server set to maintain a shard database randomly chooses a shard to add to its shard store. To increase the probability for an even distribution of the network ledger history, shards are randomly selected for acquisition, and the most recent shard is given no special consideration.
Once a shard is selected, the ledger acquire process begins by fetching the sequence of the last ledger in the shard and working backwards toward the first. The retrieval process begins with the server checking for the data locally. For data that is not available, the server requests data from its peers. Those servers that have the data available for the requested period respond with their history. The requesting server combines those responses to create the shard. The shard is complete when it contains all the ledgers in a specific range.
The server selects and downloads additional shards until it reaches the maximum number of shards it is configured to store. If a server runs out of space before completely acquiring a shard, it stops its retrieval process until it has space available to continue.
## XRP Ledger Network Data Integrity
The history of all ledgers is shared by servers agreeing to keep particular ranges of historical ledgers. This makes it possible for servers to confirm that they have all the data they agreed to maintain, and produce "proof trees" or "ledger deltas" which shows how each ledger in the blockchain's history was the result of applying transactions to the previous state. Since servers that are configured with history sharding randomly select the shards that they store, the entire history of all closed ledgers is stored in a normal distribution curve, increasing the probability that the XRP Ledger Network evenly maintains the history.
History shards are recorded in a deterministic format, so that any two servers assembling the same shard produce the exact same binary data no matter what order they acquired the data and where they got it from. This makes it possible to compare checksums or cryptographic hashes of the shard data to verify the integrity of the data, and it is possible to share and import history shards through other formats. (For example, you could download shard data using Bittorrent or acquire physical media with the shard data pre-loaded on it, and verify that it matches the data that can be downloaded from the network.) [New in: rippled 1.8.1][]
## See Also
- **Concepts:**
- [Ledgers](ledgers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Configure `rippled`](configure-rippled.html)
- [Configure History Sharding](configure-history-sharding.html)
- **References:**
- [crawl_shards method][]
- [download_shard method][]
- [Peer Crawler](peer-crawler.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

9
content/infrastructure/configuration/data-retention/index.md Normal file
View File

@@ -0,0 +1,9 @@
---
html: data-retention.html
parent: configure-rippled.html
template: pagetype-category.html.jinja
blurb: Control how much data your server should keep and when it should remove old data.
---
# Data Retention
Control how much data your server should keep and when it should remove old data, including old versions of the ledger state and past transactions.

141
content/infrastructure/configuration/data-retention/online-deletion.md Normal file
View File

@@ -0,0 +1,141 @@
---
html: online-deletion.html
parent: data-retention.html
blurb: Online deletion purges outdated transaction and state history.
labels:
- Data Retention
- Core Server
---
# Online Deletion
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/misc/SHAMapStoreImp.cpp "Source")
The online deletion feature lets the `rippled` server delete the server's local copy of old ledger versions to keep disk usage from rapidly growing over time. The default config file sets online deletion to run automatically, but online deletion can also be configured to run only when prompted. [New in: rippled 0.27.0][]
The server always keeps the complete _current_ state of the ledger, with all the balances and settings it contains. The deleted data includes older transactions and versions of the ledger state that are older than the stored history.
The default config file sets the `rippled` server to keep the most recent 2000 ledger versions and automatically delete older data.
**Tip:** Even with online deletion, the amount of disk space required to store the same time span's worth of ledger data increases over time, because the size of individual ledger versions tends to grow over time. This growth is very slow in comparison to the accumulation of data that occurs without deleting old ledgers. For more information on disk space needs, see [Capacity Planning](capacity-planning.html).
## Background
The `rippled` server stores [ledger history](ledger-history.html) in its _ledger store_. This data accumulates over time.
Inside the ledger store, ledger data is "de-duplicated". In other words, data that doesn't change from version to version is only stored once. The records themselves in the ledger store do not indicate which ledger version(s) contain them; part of the work of online deletion is identifying which records are only used by outdated ledger versions. This process is time consuming and affects the disk I/O and application cache, so the server cannot delete old data every time it closes a new ledger.
## Online Deletion Behavior
The online deletion settings configure how many ledger versions the `rippled` server should keep available in the ledger store at a time. However, the specified number is a guideline, not a hard rule:
- The server never deletes data more recent than the configured number of ledger versions, but it may have less than that amount available if it has not been running for long enough or if it lost sync with the network at any time. (The server attempts to backfill at least some history; see [fetching history](ledger-history.html#fetching-history) for details.)
- The server may store up to slightly over twice the configured number of ledger versions if online deletion is set to run automatically. (Each time it runs, it reduces the number of stored ledger versions to approximately the configured number.)
If online deletion is delayed because the server is busy, ledger versions can continue to accumulate. When functioning normally, online deletion begins when the server has twice the configured number of ledger versions, but it may not complete until after several more ledger versions have accumulated.
- If advisory deletion is enabled, the server stores all the ledger versions that it has acquired and built until its administrator calls the [can_delete method][].
The amount of data the server stores depends on how often you call [can_delete][can_delete method] and how big an interval of time your `online_delete` setting represents:
- If you call `can_delete` _more often_ than your `online_delete` interval, the server stores **up to twice the `online_delete` number** of ledger versions. (After deletion, this is reduced to approximately the `online_delete` value.)
For example, if you call `can_delete` with a value of `now` once per day and an `online_delete` value of 50,000, the server typically stores up to 100,000 ledger versions before running deletion. After running deletion, the server keeps at least 50,000 ledger versions (about two days' worth). With this configuration, approximately every other `can_delete` call results in no change because the server does not have enough ledger versions to delete.
- If you call `can_delete` _less often_ than your `online_delete` interval, the server stores at most ledger versions spanning an amount of time that is approximately **twice the interval between `can_delete` calls**. (After deletion, this is reduced to approximately one interval's worth of data.)
For example, if you call `can_delete` with a value of `now` once per day and an `online_delete` value of 2000, the server typically stores up to two full days' worth of ledger versions before running deletion. After running deletion, the server keeps approximately one day's worth (about 25,000 ledger versions), but never fewer than 2000 ledger versions.
With online deletion enabled and running automatically (that is, with advisory delete disabled), the total amount of ledger data stored should remain at minimum equal to the number of ledger versions the server is configured to keep, with the maximum being roughly twice that many.
When online deletion runs, it does not reduce the size of SQLite database files on disk; it only makes space within those files available to be reused for new data. Online deletion _does_ reduce the size of RocksDB or NuDB database files containing the ledger store.
The server only counts validated ledger versions when deciding how far back it can delete. In exceptional circumstances where the server is unable to validate new ledger versions (either because of an outage in its local network connection or because the global XRP Ledger network is unable to reach a consensus) `rippled` continues to close ledgers so that it can recover quickly when the network is restored. In this case, the server may accumulate many closed but not validated ledger versions. These unvalidated ledgers do not affect how many _validated_ ledger versions the server keeps before running online deletion.
### Interrupting Online Deletion
Online deletion automatically stops if the [server state](rippled-server-states.html) becomes less than `full`. If this happens, the server writes a log message with the prefix `SHAMapStore::WRN`. The server attempts to start online deletion again after the next validated ledger version after becoming fully synced.
If you stop the server or it crashes while online deletion is running, online deletion resumes after the server is restarted and the server becomes fully synced.
To temporarily disable online deletion, you can use the [can_delete method][] with an argument of `never`. This change persists until you re-enable online deletion by calling [can_delete][can_delete method] again. For more information on controlling when online deletion happens, see [Advisory Deletion](#advisory-deletion).
## Configuration
The following settings relate to online deletion:
- **`online_delete`** - Specify how many validated ledger versions to keep. The server periodically deletes any ledger versions that are older than this number. If not specified, no ledgers are deleted.
The default config file specifies 2000 for this value. This cannot be less than 256, because some events like [Fee Voting](fee-voting.html) and the [Amendment Process](amendments.html#amendment-process) update only every 256 ledgers.
**Caution:** If you run `rippled` with `online_delete` disabled, then later enable `online_delete` and restart the server, the server disregards but does not delete existing ledger history that your server already downloaded while `online_delete` was disabled. To save disk space, delete your existing history before re-starting the server after changing the `online_delete` setting.
- **`[ledger_history]`** - Specify how many validated ledgers to backfill. Must be equal to or less than `online_delete`. If the server does not have at least this many validated ledger versions, it attempts to fetch the data from peers when it can.
The default for this setting is 256 ledgers.
The following diagram shows the relationship between `online_delete` and `ledger_history` settings:
{{ include_svg("img/online_delete-vs-ledger_history.svg", "Ledgers older than `online_delete` are automatically deleted. Ledgers newer than `ledger_history` are backfilled. Ledgers in between are kept if available but not backfilled") }}
- **`advisory_delete`** - If enabled, online deletion is not scheduled automatically. Instead, an administrator must manually trigger online deletion. Use the value `0` for disabled or `1` for enabled.
This setting is disabled by default.
- **`[fetch_depth]`** - Specify how many ledger versions to serve to peers. The server does not accept fetch requests from peers for historical data that is older than the specified number of ledger versions. Specify the value `full` to serve any available data to peers.
The default for `fetch_depth` is `full` (serve all available data).
The `fetch_depth` setting cannot be higher than `online_delete` if both are specified. If `fetch_depth` is set higher, the server treats it as equal to `online_delete` instead.
The following diagram shows how `fetch_depth` works:
{{ include_svg("img/fetch_depth.svg", "Ledger versions older than fetch_depth are not served to peers") }}
For estimates of how much disk space is required to store different amounts of history, see [Capacity Planning](capacity-planning.html#disk-space).
### Advisory Deletion
The default config file schedules online deletion to happen automatically and periodically. If the config file does not specify an `online_delete` interval, online deletion does not occur. If config file enables the `advisory_delete` setting, online deletion only happens when an administrator triggers it using the [can_delete method][].
You can use advisory deletion with a scheduled job to trigger automatic deletion based on clock time instead of the number of ledger versions closed. If your server is heavily used, the extra load from online deletion can cause your server to fall behind and temporarily de-sync from the consensus network. If this is the case, you can use advisory deletion and schedule online deletion to happen only during off-peak times.
You can use advisory deletion for other reasons. For example, you may want to manually confirm that transaction data is backed up to a separate server before deleting it. Alternatively, you may want to manually confirm that a separate task has finished processing transaction data before you delete that data.
The `can_delete` API method can enable or disable automatic deletion, in general or up to a specific ledger version, as long as `advisory_delete` is enabled in the config file. These settings changes persist even if you restart the `rippled` server, unless you disable `advisory_delete` in the config file before restarting.
## How It Works
Online deletion works by creating two databases: at any given time, there is an "old" database, which is read-only, and a "current" database, which is writable. The `rippled` server can read objects from either database, so current ledger versions may contain objects in either one. If an object in a ledger does not change from ledger version to ledger version, only one copy of that object remains in the database, so the server does not store redundant copies of that object. When a new ledger version modifies an object, the server stores the modified object in the "new" database, while the previous version of the object (which is still used by previous ledger versions) remains in the "old" database.
When it comes time for online deletion, the server first walks through the oldest ledger version to keep, and copies all objects in that ledger version from the read-only "old" database into the "current" database. This guarantees that the "current" database now contains all objects used in the chosen ledger version and all newer versions. Then, the server deletes the "old" database, and changes the existing "current" database to become "old" and read-only. The server starts a new "current" database to contain any newer changes after this point.
{{ include_svg('img/online-deletion-process.svg', "Diagram showing how online deletion uses two databases") }}
## See Also
- **Concepts:**
- [Ledgers](ledgers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Configure `rippled`](configure-rippled.html)
- [Configure Online Deletion](configure-online-deletion.html)
- [Configure Advisory Deletion](configure-advisory-deletion.html)
- [Configure History Sharding](configure-history-sharding.html)
- [Configure Full History](configure-full-history.html)
- **References:**
- [ledger method][]
- [server_info method][]
- [ledger_request method][]
- [can_delete method][]
- [ledger_cleaner method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

58
content/infrastructure/configuration/enable-public-signing.md Normal file
View File

@@ -0,0 +1,58 @@
---
html: enable-public-signing.html
parent: configure-rippled.html
blurb: Allow others to use your server to sign transactions. (Not recommended)
labels:
- Core Server
- Security
---
# Enable Public Signing
By default, the signing methods for [`rippled`](xrpl-servers.html) are limited to [administrative connections](admin-api-methods.html). If you want to allow signing methods to be used as public API methods (like with versions of `rippled` before v1.1.0), you can enable it with a configuration change. [New in: rippled 1.1.0][]
This enables the following methods to be used on "public" [JSON-RPC and WebSocket connections](get-started-using-http-websocket-apis.html), if your server accepts them:
- [sign][sign method]
- [sign_for][sign_for method]
- [submit][submit method] (in "sign-and-submit" mode)
You **do not** need to enable public signing to use these methods from an admin connection.
**Caution:** Ripple does not recommend enabling public signing. Like the [wallet_propose method][], the signing commands do not perform any actions that would require administrative-level permissions, but restricting them to admin connections protects users from irresponsibly sending or receiving secret keys over unsecured communications, or to servers they do not control.
To enable public signing, perform the following steps:
1. Edit your `rippled`'s config file.
vim /etc/opt/ripple/rippled.cfg
{% include '_snippets/conf-file-location.md' %}<!--_ -->
2. Add the following stanza to your config file, and save the changes:
[signing_support]
true
3. Restart your `rippled` server:
systemctl restart rippled
## See Also
- **Concepts:**
- [Transactions](transactions.html)
- [Cryptographic Keys](cryptographic-keys.html)
- **Tutorials:**
- [Set Up Secure Signing](secure-signing.html)
- [Get Started Using HTTP / WebSocket APIs](get-started-using-http-websocket-apis.html)
- [Get Started Using JavaScript](get-started-using-javascript.html)
- **References:**
- [sign method][]
- [sign_for method][]
- [submit method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

9
content/infrastructure/configuration/index.md Normal file
View File

@@ -0,0 +1,9 @@
---
html: configure-rippled.html
parent: infrastructure.html
template: pagetype-category.html.jinja
blurb: Customize the configuration of an XRP Ledger server.
---
# Configuration
Customize the configuration of an XRP Ledger server.

104
content/infrastructure/configuration/peering/cluster-rippled-servers.md Normal file
View File

@@ -0,0 +1,104 @@
---
html: cluster-rippled-servers.html
parent: configure-peering.html
blurb: Set up a group of servers that share work for higher efficiency.
labels:
- Core Server
---
# Cluster rippled Servers
If you run multiple [`rippled` servers](xrpl-servers.html) in the same data center, you can configure them in a [cluster](clustering.html) to maximize efficiency. To configure clustering:
1. For each of your servers, note the IP address of the server.
2. For each of your servers, generate a unique seed using the [validation_create method][].
For example, using the commandline interface:
$ 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` and `validation_public_key` parameters from each response somewhere secure.
3. On each server, edit the [config file](https://github.com/XRPLF/rippled/blob/master/cfg/rippled-example.cfg), modifying the following sections:
1. In the `[ips_fixed]` section, list the IP address and port of each _other_ member of the cluster. For each of those servers, the port number should match the `protocol = peer` port (usually 51235) from that server's `rippled.cfg`. For example:
[ips_fixed]
192.168.0.1 51235
192.168.0.2 51235
This defines specific peer servers to which this server should always attempt to maintain a direct peer-to-peer connection.
**Note:** If you omit the port number, the server uses port 2459, the IANA-assigned port for the XRP Ledger protocol.
2. In the `[node_seed]` section, set the server's node seed to one of the `validation_seed` values you generated using the [validation_create method][] in step 2. Each server must use a unique node seed. For example:
[node_seed]
ssZkdwURFMBXenJPbrpE14b6noJSu
This defines the key pair the server uses to sign peer-to-peer communications, excluding validation messages.
3. In the `[cluster_nodes]` section, set the members of the server's cluster, identified by their `validation_public_key` values. Each server should list the public keys of all _other_ members of the cluster here. Optionally, add a custom name for each server. For example:
[cluster_nodes]
n9McNsnzzXQPbg96PEUrrQ6z3wrvgtU4M7c97tncMpSoDzaQvPar keynes
n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa friedman
This defines the key pairs the server uses to recognize members of its cluster.
4. After saving the config file, restart `rippled` on each server.
# systemctl restart rippled
5. To confirm that each server is now a member of the cluster, use the [peers method][]. The `cluster` field should list the public keys and (if configured) the custom names for each server.
For example, using the commandline interface:
$ rippled peers
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
{
"result" : {
"cluster" : {
"n9McNsnzzXQPbg96PEUrrQ6z3wrvgtU4M7c97tncMpSoDzaQvPar": {
"tag": "keynes",
"age": 1
},
"n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa": {
"tag": "friedman",
"age": 1
}
},
"peers" : [
... (omitted) ...
],
"status" : "success"
}
}
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- **Tutorials:**
- [Install rippled](install-rippled.html)
- **References:**
- [validation_create method][]
- [peers method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

100
content/infrastructure/configuration/peering/configure-a-private-server.md Normal file
View File

@@ -0,0 +1,100 @@
---
html: configure-a-private-server.html
parent: configure-peering.html
blurb: Set up a server to connect only to specific, trusted peers.
labels:
- Core Server
- Security
---
# Configure a Private Server
A [private server](peer-protocol.html#private-peers) is a `rippled` server that connects to the network only through specific, trusted peers instead of connecting directly to discovered peers in the open peer-to-peer network. This kind of configuration is an optional precaution most commonly recommended for [validators](run-rippled-as-a-validator.html), but it can be useful for other specific purposes.
## Prerequisites
To use a private server, you must meet the following requirements:
- You must have [`rippled` installed](install-rippled.html) and updated to the latest version, but not running yet.
- You must decide whether to connect through **proxies** you run yourself, or through **public hubs**. For a comparison of these options, see [Pros and Cons of Peering Configurations](peer-protocol.html#pros-and-cons-of-peering-configurations).
- If you are using proxies, you must have additional machines with `rippled` installed and running to use as the proxies. These servers must be able to connect to the outside network and to your private server.
- For either configuration, you must know the IP addresses and ports of the peers you intend to connect to.
## Steps
To set up a specific server as a private peer, complete the following steps:
1. Edit your `rippled`'s config file.
vim /etc/opt/ripple/rippled.cfg
{% include '_snippets/conf-file-location.md' %}<!--_ -->
2. Enable private peering.
Add or uncomment the following stanza in your config file:
[peer_private]
1
3. Add fixed peers.
Add or uncomment an `[ips_fixed]` stanza in your config file. Each line in this stanza should be the hostname or IP address of a peer to connect to, followed by a space and the port where this peer accepts peer protocol connections.
For example, to connect using **public hubs**, you could use the following stanza:
[ips_fixed]
r.ripple.com 51235
zaphod.alloy.ee 51235
If your server connects using **proxies**, the IP addresses and ports should match the configurations of the `rippled` servers you are using as proxies. For each of those servers, the port number should match the `protocol = peer` port in that server's config file (usually 51235). For example, your configuration might look like this:
[ips_fixed]
192.168.0.1 51235
192.168.0.2 51235
**Note:** If you omit the port number, the server uses port 2459, the IANA-assigned port for the XRP Ledger protocol.
4. If using proxies, cluster them with your private peer and each other.
If you are using public hubs, skip this step.
If you are using proxies, [configure the proxies as a cluster](cluster-rippled-servers.html) that includes your private peer. Each member of the cluster should have an `[ips_fixed]` stanza that lists each _other_ member of the cluster. However, **only the private server** should have a `[peer_private]` stanza.
Restart `rippled` on the proxies one-by-one. On each proxy server:
sudo service systemctl restart rippled
5. Start `rippled` on the private server.
sudo service systemctl start rippled
6. Use the [peers method][] to confirm that your private server is connected _only_ to its peers.
The `peers` array in the response should not contain any objects whose `address` is not one of your configured peers. If this is not the case, double-check your config file and restart the private server.
## Next Steps
As an additional precaution, you should configure your firewall to block incoming connections to your private server from servers that are not your specific peers. If you are running proxy servers, [forward peer ports](forward-ports-for-peering.html) through your firewall to the proxies, but **not** to the private peer. The exact details of how to configure this depend on what firewall you use.
Be sure the firewall **does not block** outgoing HTTP connections on port 80. The default configuration uses this port to download the latest recommended validator list from **vl.ripple.com**. Without a validator list, the server does not know which validators to trust and cannot recognize when the network reaches a consensus.
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- [Consensus](consensus.html)
- [Parallel Networks](parallel-networks.html)
- **Tutorials:**
- [Configure the Peer Crawler](configure-the-peer-crawler.html)
- **References:**
- [peers method][]
- [connect method][]
- [fetch_info method][]
- [Peer Crawler](peer-crawler.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

79
content/infrastructure/configuration/peering/configure-the-peer-crawler.md Normal file
View File

@@ -0,0 +1,79 @@
---
html: configure-the-peer-crawler.html
parent: configure-peering.html
blurb: Configure how much information your rippled server reports publicly about its status and peers.
labels:
- Core Server
- Security
---
# Configure the Peer Crawler
By default, [`rippled` servers](xrpl-servers.html) 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](peer-protocol.html). You can configure your server to provide more or less information, or to reject peer crawler requests entirely.
This document contains steps for two options:
- [Change the Information Reported by the Peer Crawler](#change-the-information-reported-by-the-peer-crawler)
- [Disable the Peer Crawler](#disable-the-peer-crawler)
## Change the Information Reported by the Peer Crawler
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 fields in this stanza control which fields the server returns in the [peer crawler response](peer-crawler.html#response-format). The names of the config fields match the fields of the API response. A setting with a value of `1` means to include the field in the response. A value of `0` means to omit that field from the response. This example shows the default values for each setting.
3. After saving the changes to the config file, restart your `rippled` server to apply the updated configuration:
systemctl restart rippled
## Disable 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
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- **Tutorials:**
- [Manage the rippled Server](manage-the-rippled-server.html)
- **References:**
- [server_info method][]
- [peers method][]
- [Peer Crawler](peer-crawler.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

51
content/infrastructure/configuration/peering/enable-link-compression.md Normal file
View File

@@ -0,0 +1,51 @@
---
html: enable-link-compression.html
parent: configure-peering.html
blurb: Save bandwidth by compressing peer-to-peer communications.
labels:
- Core Server
---
# Enable Link Compression
The `rippled` server can save bandwidth by compressing its [peer-to-peer communications](peer-protocol.html), at a cost of greater CPU usage. If you enable link compression, the server automatically compresses communications with peer servers that also have link compression enabled.
## Steps
To enable link compression on your server, complete the following steps:
### 1. Edit your `rippled` server's config file.
```sh
$ vim /etc/opt/ripple/rippled.cfg
```
{% include '_snippets/conf-file-location.md' %}<!--_ -->
### 2. In the config file, add or uncomment the `[compression]` stanza.
To enable compression:
```text
[compression]
true
```
Use `false` to disable compression (the default).
### 3. Restart the `rippled` server
```sh
$ sudo systemctl restart rippled.service
```
After the restart, your server automatically uses link compression with other peers that also have link compression enabled.
## See Also
- [Capacity Planning](capacity-planning.html)
- [Peer Protocol](peer-protocol.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

84
content/infrastructure/configuration/peering/forward-ports-for-peering.md Normal file
View File

@@ -0,0 +1,84 @@
---
html: forward-ports-for-peering.html
parent: configure-peering.html
blurb: Configure your firewall to allow incoming peers to your rippled server.
labels:
- Core Server
---
# Forward Ports for Peering
Servers in the XRP Ledger peer-to-peer network communicate over the [peer protocol](peer-protocol.html). For the best combination of security and connectivity to the rest of the network, you should use a firewall to protect your server from most ports, but open or forward the peer protocol port.
While your `rippled` server is running, you can check to see how many peers you have by running the [server_info method][]. The `peers` field of the `info` object shows how many peers are currently connected to your server. If this number is exactly 10 or 11, that usually means your firewall is blocking incoming connections.
Example of a `server_info` result (trimmed) showing only 10 peers, likely because a firewall is blocking incoming peer connections:
```json
$ ./rippled server_info
Loading: "/etc/opt/ripple/rippled.cfg"
2019-Dec-23 22:15:09.343961928 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
"result" : {
"info" : {
... (trimmed) ...
"load_factor" : 1,
"peer_disconnects" : "0",
"peer_disconnects_resources" : "0",
"peers" : 10,
"pubkey_node" : "n9KUjqxCr5FKThSNXdzb7oqN8rYwScB2dUnNqxQxbEA17JkaWy5x",
"pubkey_validator" : "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
"published_ledger" : "none",
"server_state" : "connected",
... (trimmed) ...
},
"status" : "success"
}
}
```
To allow incoming connections, configure your firewall to allow incoming traffic on the peer protocol port, which is served on **port 51235** in the default config file. The instructions to open a port depend on your firewall. If your server is behind a router that performs Network Address Translation (NAT), you must configure your router to forward the port to your server.
If you use the `firewalld` software firewall on Red Hat Enterprise Linux, you can [use the `firewall-cmd` tool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/sec-using_zones_to_manage_incoming_traffic_depending_on_source) to open **port 51235** to all incoming traffic.
_Assuming `--zone=public` is your public [zone](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/sec-working_with_zones#sec-Listing_Zones)._
```sh
$ sudo firewall-cmd --zone=public --add-port=51235/tcp
```
Then, restart the `rippled` server:
```sh
$ sudo systemctl restart rippled.service
```
To make it permanent:
```sh
$ sudo firewall-cmd --zone=public --permanent --add-port=51235/tcp
```
For other software and hardware firewalls, see the manufacturer's official documentation.
If you are using a hosting service with a virtual firewall (for example, [AWS Security Groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)), you do not need to use `firewalld`, but you still need to allow inbound traffic from the open internet on the peer port. Make sure you apply the relevant rules to your host or virtual machine.
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- [The `rippled` Server](xrpl-servers.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Troubleshoot the `rippled` Server](troubleshoot-the-rippled-server.html)
- **References:**
- [connect method][]
- [peers method][]
- [print method][]
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

14
content/infrastructure/configuration/peering/index.md Normal file
View File

@@ -0,0 +1,14 @@
---
html: configure-peering.html
name: Peering
parent: configure-rippled.html
template: pagetype-category.html.jinja
blurb: Configure how your server connects to the peer-to-peer network.
labels:
- Core Server
---
# Configure Peering
The XRP Ledger's peer-to-peer protocol automatically manages peer connections in most cases. In some cases, you may want to manually adjust which peers your server connects to, to maximize your server's availability and connectivity with the rest of the network.
If you run multiple servers in the same datacenter, you may want [to cluster them](cluster-rippled-servers.html) to improve efficiency. You can use reserved peer slots for servers you don't run but want to stay connected to, such as important hubs in the topology of the peer-to-peer network. For other peers, the server can automatically find peers and manage its connections, although you may occasionally want to intervene to block a peer that's behaving undesirably.

79
content/infrastructure/configuration/peering/manually-connect-to-a-specific-peer.md Normal file
View File

@@ -0,0 +1,79 @@
---
html: manually-connect-to-a-specific-peer.html
parent: configure-peering.html
blurb: Connect your rippled server to a specific peer.
labels:
- Core Server
---
# Manually Connect to a Specific Peer
Use these steps to manually connect your server to a specific [peer](peer-protocol.html) in the XRP Ledger network.
**Tip:** If you want to make sure your server automatically connects to this server on startup and remains connected later, you may want to configure a [peer reservation](use-a-peer-reservation.html) for that peer.
## Prerequisites
- You must know the IP address of the peer you want to connect to.
- You must know what port the peer you want to connect to uses for the XRP Ledger [peer protocol](peer-protocol.html). The default config file uses port 51235.
- You must have a network connection from your server to the peer. For example, the peer server must [forward the appropriate port through its firewall](forward-ports-for-peering.html).
- The peer server must have available peer slots. If the peer is already at its maximum number of peers, you can ask the peer server's operator to add a [peer reservation](use-a-peer-reservation.html) for your server.
## Steps
To connect, use the [connect method][]. For example:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"command": "connect",
"ip": "169.54.2.151",
"port": 51235
}
```
*JSON-RPC*
```
{
"method": "connect",
"params": [
{
"ip": "169.54.2.151",
"port": 51235
}
]
}
```
*Commandline*
```
rippled connect 169.54.2.151 51235
```
<!-- MULTICODE_BLOCK_END -->
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- [The `rippled` Server](xrpl-servers.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Troubleshoot the `rippled` Server](troubleshoot-the-rippled-server.html)
- **References:**
- [connect method][]
- [peers method][]
- [print method][]
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

55
content/infrastructure/configuration/peering/set-max-number-of-peers.md Normal file
View File

@@ -0,0 +1,55 @@
---
html: set-max-number-of-peers.html
parent: configure-peering.html
blurb: Set the maximum number of peers your rippled server connects to.
labels:
- Core Server
---
# Set Maximum Number of Peers
The `rippled` server has a configurable soft maximum number of [peers](peer-protocol.html) to connect to. The default maximum number of peers is **21**.
**Note:** Internally, the server generates approximate quotas of incoming and outgoing peers. You can potentially go over the soft maximum if you are using [fixed peers, peer reservations](peer-protocol.html#fixed-peers-and-peer-reservations), or if you manually connect to additional peers using the [connect method][].
To change the maximum number of peers your server allows, complete the following steps:
1. Edit your `rippled`'s config file.
$ vim /etc/opt/ripple/rippled.cfg
{% include '_snippets/conf-file-location.md' %}<!--_ -->
2. In the config file, uncomment and edit the `[peers_max]` stanza, or add one if you don't have one already:
[peers_max]
30
The only content of the stanza should be an integer indicating the total number of peers to allow. By default, the server attempts to maintain a ratio of about 85% incoming and 15% outgoing peers, but with a minimum of 10 outgoing peers, so any value less than 68 won't increase the number of outgoing peer connections your server makes.
If the `[peers_max]` value is less than 10, the server still allows a hardcoded minimum of 10 outgoing peers so that it can maintain connectivity with the network. To block all outgoing peer connections, [configure the server as a private peer](run-rippled-as-a-validator.html#connect-using-proxies) instead.
**Caution:** The more peer servers you are connected to, the more network bandwidth your `rippled` server uses. You should only configure large numbers of peer servers if your `rippled` server has a good network connection and you can afford the costs you may incur for the bandwidth it uses.
3. Restart the `rippled` server.
$ sudo systemctl restart rippled.service
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- [The `rippled` Server](xrpl-servers.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Troubleshoot the `rippled` Server](troubleshoot-the-rippled-server.html)
- **References:**
- [connect method][]
- [peers method][]
- [print method][]
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

185
content/infrastructure/configuration/peering/use-a-peer-reservation.md Normal file
View File

@@ -0,0 +1,185 @@
---
html: use-a-peer-reservation.html
parent: configure-peering.html
blurb: Set up a more reliable connection to a specific peer using a peer reservation.
labels:
- Core Server
---
# 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](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
To complete these steps, you must meet the following prerequisites:
- 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. (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](#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.)
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 )
2. Edit your `rippled`'s config file.
vim /etc/opt/ripple/rippled.cfg
{% include '_snippets/conf-file-location.md' %}<!--_ -->
3. 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.
4. 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:
```sh
$ 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:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"command": "connect",
"ip": "169.54.2.151",
"port": 51235
}
```
*JSON-RPC*
```
{
"method": "connect",
"params": [
{
"ip": "169.54.2.151",
"port": 51235
}
]
}
```
*Commandline*
```
rippled connect 169.54.2.151 51235
```
<!-- MULTICODE_BLOCK_END -->
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](https://github.com/gnanderson/rbh). <!-- SPELLING_IGNORE: rbh -->
## See Also
- **Concepts:**
- [Peer Protocol](peer-protocol.html)
- [Consensus](consensus.html)
- [Parallel Networks](parallel-networks.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Troubleshooting `rippled`](troubleshoot-the-rippled-server.html)
- **References:**
- [peers method][]
- [peer_reservations_add method][]
- [peer_reservations_del method][]
- [peer_reservations_list method][]
- [connect method][]
- [fetch_info method][]
- [Peer Crawler](peer-crawler.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

9
content/infrastructure/configuration/server-modes/index.md Normal file
View File

@@ -0,0 +1,9 @@
---
html: server-modes.html
parent: configure-rippled.html
template: pagetype-category.html.jinja
blurb: Information on how to run a core server in different modes specialized for different purposes.
---
# Server Modes
The core XRP Ledger server can run in different modes specialized for different purposes.

55
content/infrastructure/configuration/server-modes/run-rippled-as-a-stock-server.md Normal file
View File

@@ -0,0 +1,55 @@
---
html: run-rippled-as-a-stock-server.html
parent: server-modes.html
blurb: A multipurpose configuration for anyone integrating XRP.
labels:
- Core Server
---
# Run rippled as a Stock Server
A stock server is a multipurpose configuration for `rippled`. With a stock server, you can submit transactions to the XRP Ledger, access ledger history, and use the latest [tools](software-ecosystem.html) to integrate with XRP and the XRP Ledger. You can connect client applications to the XRP Ledger using this server.
A stock server does all of the following:
- Connects to a [network of peers](peer-protocol.html)
- Relays cryptographically signed [transactions](transactions.html)
- Maintains a local copy of the complete shared global [ledger](ledgers.html)
To participate in the [consensus process](consensus.html) as a validator, [run rippled as a validator](run-rippled-as-a-validator.html) instead.
## Install and run `rippled`
The default package installation installs a stock server with a small amount of transaction history. For installation steps, see [Install `rippled`](install-rippled.html).
After installation, you can adjust how much history your server stores at a time. For steps on how to do this, see [Configure Online Deletion](configure-online-deletion.html).
## Troubleshooting
For more information, see [Troubleshooting `rippled`](troubleshoot-the-rippled-server.html)
## See Also
- **Concepts:**
- [XRP Ledger Overview](xrp-ledger-overview.html)
- [The `rippled` Server](xrpl-servers.html)
- **Tutorials:**
- [Cluster rippled Servers](cluster-rippled-servers.html)
- [Install `rippled`](install-rippled.html)
- [Capacity Planning](capacity-planning.html)
- **References:**
- [Validator Keys Tool Guide](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md)
- [consensus_info method][]
- [validator_list_sites method][]
- [validators method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

285
content/infrastructure/configuration/server-modes/run-rippled-as-a-validator.md Normal file
View File

@@ -0,0 +1,285 @@
---
html: run-rippled-as-a-validator.html
parent: server-modes.html
blurb: Have your server vote on the consensus ledger.
labels:
- Core Server
- Blockchain
top_nav_grouping: Popular Pages
top_nav_name: Join UNL
---
# Run rippled as a Validator
A [`rippled` server](xrpl-servers.html) running in [validator mode](rippled-server-modes.html) does everything a stock server does:
- Connects to a [network of peers](peer-protocol.html)
- Relays cryptographically signed [transactions](transactions.html)
- Maintains a local copy of the complete shared global [ledger](ledgers.html)
What makes a validator _different_ is that it also issues validation messages, which are sets of candidate transactions for evaluation by the XRP Ledger network during the [consensus process](consensus-principles-and-rules.html#how-consensus-works).
Issuing validation messages does not automatically give your validator a say in the consensus process, so the system is not vulnerable to a [Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack). Other servers ignore your validation messages unless they add your validator to their Unique Node List (UNL). If your validator is included in a UNL, it is a _trusted_ validator and its proposals are considered in the consensus process by the servers that trust it.
Even if your validator isn't a _trusted_ validator, it stills plays an important role in the overall health of the network. These validators help set the standard that trusted validators are measured against. For example, if a trusted validator is disagreeing with a lot of these validators that aren't listed in UNLs, that might indicate a problem.
**Warning:** Validators should not be accessible to the public. Do not allow public WebSocket access to your validator server or any other form of public access.
## 1. Understand the traits of a good validator
Strive to have your validator embody the following properties. Being a good validator helps `rippled` server operators and validator list publishers (such as https://vl.ripple.com and https://vl.xrplf.org) trust your validator before adding it to their UNLs.
- **Available**
A good validator is always running and submitting validation votes for every proposed ledger. Strive for 100% uptime.
- **In agreement**
A good validator's votes match the outcome of the consensus process as often as possible. To do otherwise could indicate that your validator's software is outdated, buggy, or intentionally biased. Always run the [latest `rippled` release](https://github.com/XRPLF/rippled/tree/release) without modifications. [Watch `rippled` releases](https://github.com/XRPLF/rippled/releases) and subscribe to the [Google Group](https://groups.google.com/g/ripple-server) to be notified of new releases.
- **Issuing prompt votes**
A good validator's votes arrive quickly and not after a consensus round has already finished. To keep your votes on time, make sure your validator meets the recommended [system requirements](system-requirements.html), which include a fast internet connection.
It is possible to submit new transactions and query data using a validator, but heavy loads of API queries may make the validator less reliable at keeping up with consensus. If your API needs are light enough, then you can use a server for both purposes. Ideally, a validator should be dedicated to participating in consensus.
- **Identified**
A good validator has a clearly identified owner. Providing [domain verification](#6-provide-domain-verification) is a good start. Ideally, XRP Ledger network UNLs include validators run by different owners in multiple legal jurisdictions and geographic areas. This reduces the chance that any localized events could interfere with the impartial operations of trusted validators. <!-- STYLE_OVERRIDE: clearly -->
It is strongly recommended that operators use the list providers that are present in this [example file](https://github.com/XRPLF/rippled/blob/develop/cfg/validators-example.txt).
## 2. Install a `rippled` server
For more information, see [Install `rippled`](install-rippled.html).
## 3. Enable validation on your `rippled` server
Enabling validation on your `rippled` server means providing a validator token in your server's `rippled.cfg` file. You can use the `validator-keys` tool (included in `rippled` packages) to securely generate and manage your validator keys and tokens.
In a secure location **not** on your validator:
1. Manually build and run the `validator-keys` tool, if you don't already have it installed via a `rippled` RPM.
For information about manually building and running the `validator-keys` tool, see [validator-keys-tool](https://github.com/ripple/validator-keys-tool).
2. Generate a validator key pair using the `create_keys` command.
$ validator-keys create_keys
Sample output on Ubuntu:
Validator keys stored in /home/my-user/.ripple/validator-keys.json
This file should be stored securely and not shared.
Sample output on macOS:
Validator keys stored in /Users/my-user/.ripple/validator-keys.json
This file should be stored securely and not shared.
**Warning:** Store the generated `validator-keys.json` key file in a secure, offline, and recoverable location, such as an encrypted USB flash drive. Do not store keys on the validator where you intend to use the keys. If your `secret_key` is compromised, [revoke the key](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md#key-revocation) immediately. Do not modify the contents of `validator-keys.json`, except to update the backup after generating a new token. If you generate more than one token from the same backup without updating, the network ignores the later tokens because they use the same `token_sequence` number.
For more information about the `validator-keys` tool and the key pairs it generates, see the [Validator Keys Tool Guide](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md).
3. Generate a validator token using the `create_token` command.
$ validator-keys create_token --keyfile /PATH/TO/YOUR/validator-keys.json
Sample output:
Update rippled.cfg file with these values:
# validator public key: nHUtNnLVx7odrz5dnfb2xpIgbEeJPbzJWfdicSkGyVw1eE5GpjQr
[validator_token]
eyJ2YWxpZGF0aW9uX3NlY3J|dF9rZXkiOiI5ZWQ0NWY4NjYyNDFjYzE4YTI3NDdiNT
QzODdjMDYyNTkwNzk3MmY0ZTcxOTAyMzFmYWE5Mzc0NTdmYT|kYWY2IiwibWFuaWZl
c3QiOiJKQUFBQUFGeEllMUZ0d21pbXZHdEgyaUNjTUpxQzlnVkZLaWxHZncxL3ZDeE
hYWExwbGMyR25NaEFrRTFhZ3FYeEJ3RHdEYklENk9NU1l1TTBGREFscEFnTms4U0tG
bjdNTzJmZGtjd1JRSWhBT25ndTlzQUtxWFlvdUorbDJWMFcrc0FPa1ZCK1pSUzZQU2
hsSkFmVXNYZkFpQnNWSkdlc2FhZE9KYy9hQVpva1MxdnltR21WcmxIUEtXWDNZeXd1
NmluOEhBU1FLUHVnQkQ2N2tNYVJGR3ZtcEFUSGxHS0pkdkRGbFdQWXk1QXFEZWRGdj
VUSmEydzBpMjFlcTNNWXl3TFZKWm5GT3I3QzBrdzJBaVR6U0NqSXpkaXRROD0ifQ==
On your validator:
1. Add `[validator_token]` and its value to your validator's `rippled.cfg` file.
If you previously configured your validator without the `validator-keys` tool, delete `[validation_seed]` and its value from your `rippled.cfg` file. This changes your validator public key.
2. Restart `rippled`.
$ sudo systemctl restart rippled.service
3. Use the `server_info` command to get information about your validator to verify that it is running as a validator.
$ rippled server_info
- The `pubkey_validator` value in the response should match the `public_key` in the `validator-keys.json` file that you generated for use with your validator.
- The `server_state` value should be _**proposing**_.
**Security Tip:** Change the permissions on your `rippled.cfg` file to be more restrictive. On Linux it is recommended to be `0600`. You can do this with `chmod 0600 rippled.cfg`
## 4. Connect to the network
This section describes three different configurations you can use to connect your validator to the XRP Ledger network. Use the configuration that best suits your use case.
- [Discovered peers](#connect-using-discovered-peers): Connect to any servers in the peer-to-peer network.
- [Proxies](#connect-using-proxies): Run stock `rippled` servers as proxies between your validator and the rest of the peer-to-peer network.
- [Public hubs](#connect-using-public-hubs): Connect only to specific public servers with a high reputation.
For a comparison of these approaches, see [Pros and Cons of Peering Configurations](peer-protocol.html#pros-and-cons-of-peering-configurations).
### Connect using discovered peers
This configuration connects your validator to the XRP Ledger network using [discovered peers](peer-protocol.html#peer-discovery). This is the default behavior for `rippled` servers.
_**To connect your validator to the XRP Ledger network using discovered peers,**_ omit the `[peer_private]` stanza or set it to `0` in your validator's `rippled.cfg` file. The [example `rippled.cfg` file](https://github.com/XRPLF/rippled/blob/develop/cfg/rippled-example.cfg) is delivered with this configuration.
### Connect using proxies
This configuration connects your validator to the network through stock `rippled` servers that you run yourself. These proxy servers sit between your validator and inbound and outbound network traffic.
_**To connect your validator to the XRP Ledger network using proxies:**_
1. Set up stock `rippled` servers. For more information, see [Install rippled](install-rippled.html).
2. Configure your validator and stock `rippled` servers to run in a [cluster](cluster-rippled-servers.html).
3. In your validator's `rippled.cfg` file, set `[peer_private]` to `1`. This prevents your validator's IP address from being forwarded. For more information, see [Private Peers](peer-protocol.html#private-peers). It also prevents your validator from connecting to servers other than those defined in the `[ips_fixed]` stanza you defined to run your validator in a cluster.
**Warning:** Be sure that you don't publish your validator's IP address in other ways.
4. Configure your validator host machine's firewall to allow the following traffic only:
- Inbound traffic: Only from IP addresses of the stock `rippled` servers in the cluster you configured.
- Outbound traffic: Only to the IP addresses of the stock `rippled` servers in the cluster you configured and to your UNL list providers through port 443.
5. Restart `rippled`.
$ sudo systemctl restart rippled.service
6. Use the [Peer Crawler](peer-crawler.html) endpoint on one of your stock `rippled` servers. The response should not include your validator. This verifies that your validator's `[peer_private]` configuration is working. One of the effects of enabling `[peer_private]` on your validator is that your validator's peers do not include it in their Peer Crawler results.
$ curl --insecure https://STOCK_SERVER_IP_ADDRESS_HERE:51235/crawl | python3 -m json.tool
<!-- { TODO: Future: add a recommended network architecture diagram to represent the proxy, clustering, and firewall setup: https://ripplelabs.atlassian.net/browse/DOC-2046 }-->
### Connect using public hubs
This configuration connects your validator to the network using three [public hubs](rippled-server-modes.html#public-hubs). This configuration is similar to [connecting using proxies you run yourself](#connect-using-proxies), but instead you connect through public hubs.
_**To connect your validator to the network using public hubs:**_
1. In your validator's `rippled.cfg` file, include the following `[ips_fixed]` stanza. The three values, `r.ripple.com 51235`, `zaphod.alloy.ee 51235` and `sahyadri.isrdc.in 51235`, are default public hubs. This stanza tells `rippled` to always attempt to maintain peer connections with these public hubs.
[ips_fixed]
r.ripple.com 51235
zaphod.alloy.ee 51235
sahyadri.isrdc.in 51235
**Caution:** This configuration connects your validator to the network using default public hubs. Because these are the _default_ public hubs, they may sometimes be too busy to provide your validator with a connection to the network. To help avoid this issue, connect to more public hubs and, even better, connect to non-default public hubs.
You can include the IP addresses of other `rippled` servers here, but _**only**_ if you can expect them to:
- Relay messages without censoring.
- Stay online consistently.
- Not DDoS you.
- Not try to crash your server.
- Not publish your IP address to strangers.
2. Also in your validator's `rippled.cfg` file, include the following `[peer_private]` stanza and set it to `1`. This instructs your validator’s peers not to broadcast your validator’s IP address. This setting also instructs your validator to connect to only the peers configured in your `[ips_fixed]` stanza. This ensures that your validator connects to and shares its IP with only peer `rippled` servers you know and trust.
[peer_private]
1
**Warning:** Be sure that you don't publish your validator's IP address in other ways.
With `[peer_private]` enabled, `rippled` ignores any connections suggested by the `[ips]` stanza. If you need to connect to an IP currently in your `[ips]` stanza, put it in the `[ips_fixed]` stanza instead, but _**only**_ if you can expect them to behave responsibly as described in step 1.
3. Restart `rippled`.
$ sudo systemctl restart rippled.service
## 5. Verify your network connection
Here are some methods you can use to verify that your validator has a healthy connection to the XRP Ledger network:
- Use the [`peers`](peers.html) command to return a list of all `rippled` servers currently connected to your validator. If the `peers` array is `null`, you don’t have a healthy connection to the network. If you've set up your validator using the instructions in this document, the `peers` array should include the same number of objects as the number of peers defined in your `[ips_fixed]` stanza.
If you listed a public hub in your `[ips_fixed]` stanza and it is busy, it may reject your validator's connection. In this case, you may end up with fewer connections than configured in your `[ips_fixed]` stanza. Your validator retries the connection if it's initially rejected.
If you are having trouble maintaining a reliable and safe connection to the network and haven't set up connections using public hubs or proxies, see [4. Connect to the network](#4-connect-to-the-network). Using one of the methods described in the section may help your validator remain healthily connected to the network.
- Use the [`server_info`](server_info.html) command to return some basic information about your validator. The `server_state` should be set to `proposing`. It may also be set to `full` or `validating`, but only for a few minutes before moving into `proposing`.
If the `server_state` does not spend the majority of its time set to `proposing`, it may be a sign that your validator is unable to fully participate in the XRP Ledger network. For more information about server states and using the `server_info` endpoint to diagnose issues with your validator, see [`rippled` Server States](rippled-server-states.html) and [Get the `server_info`](diagnosing-problems.html#get-the-server_info).
- Use the [`validators`](validators.html) command to return the current list of published and trusted validators used by the validator. Ensure that the `validator_list_expires` value is either `never` or not expired or about to expire.
## 6. Provide domain verification
To help validation list publishers and other participants in the XRP Ledger network understand who runs your validator, provide domain verification for your validator. At a high level, domain verification is a two-way link:
- Use your domain to claim ownership of a validator key.
- Use your validator key to claim ownership of a domain.
Creating this link establishes strong evidence that you own both the validator key and the domain. Providing this evidence is one aspect of [being a good validator](#1-understand-the-traits-of-a-good-validator).
To provide domain verification:
1. Choose a domain name you own that you want to be publicly associated with your validator. As a precaution against DDoS attempts, your domain name should not resolve to the ip address of your validator.
2. Serve an [`xrp-ledger.toml`](xrp-ledger-toml.html) file at your domain, and complete the [domain verification](xrp-ledger-toml.html#domain-verification) steps. Once you have completed these steps, your validator should be visible to the livenet [explorer](https://livenet.xrpl.org/network/validators) or any other site that monitors the validator network and supports decetralized domain verification.
3. Share your validator's public key with the public, especially other `rippled` operators. For example, you can share your validator's public key on your website, on social media, in the [XRPChat community forum](https://www.xrpchat.com/), or in a press release.
## Revoke validator keys
If your validator's master private key is compromised, you must revoke it immediately and permanently.
For information about how to revoke a master key pair you generated for your validator using the `validator-keys` tool, see [Key Revocation](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md#key-revocation).
## See Also
- **Concepts:**
- [XRP Ledger Overview](xrp-ledger-overview.html)
- [The `rippled` Server](xrpl-servers.html)
- **Tutorials:**
- [Cluster rippled Servers](cluster-rippled-servers.html)
- [Install `rippled`](install-rippled.html)
- [Capacity Planning](capacity-planning.html)
- **References:**
- [Validator Keys Tool Guide](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md)
- [consensus_info method][]
- [validator_list_sites method][]
- [validators method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}