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

Merge commit 'f8d08389620c165deeb799bba8bea7e6482ae31a'

Browse Source
This commit is contained in:
tequ
2023-11-24 16:47:03 +09:00
parent 8c8a5dbaea f8d0838962
commit f2371c8eef
413 changed files with 3388 additions and 1305 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
content/infrastructure/installation/build-on-linux-mac-windows.md Normal file
View File

@@ -0,0 +1,19 @@
---
html: build-on-linux-mac-windows.html
parent: install-rippled.html
blurb: Build rippled on Linux, Mac (macOS), or Windows
labels:
- Core Server
- Blockchain
top_nav_grouping: Popular Pages
---
# Build rippled on Linux, Mac, or Windows
Building `rippled` across various platforms such as Windows, Linux, or macOS requires a C++ development environment. You will need tools like Git, Python, Conan, CMake, and a suitable C++ compiler.
To continue, proceed to [the latest `rippled` build instructions on GitHub](https://github.com/XRPLF/rippled/blob/develop/BUILD.md).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

348
content/infrastructure/installation/build-run-rippled-in-reporting-mode.md Normal file
View File

@@ -0,0 +1,348 @@
---
html: build-run-rippled-in-reporting-mode.html
parent: install-rippled.html
blurb: Build and run a special operating mode of rippled that handles remote procedure calls (RPC) for validated data.
labels:
- Core Server
- Blockchain
top_nav_grouping: Popular Pages
---
# Build and Run `rippled` in Reporting Mode
[Reporting mode](rippled-server-modes.html) is a mode of the XRP Ledger core server specialized for serving [HTTP and WebSocket APIs](http-websocket-apis.html).
In reporting mode, the server does not connect to the peer-to-peer network. Instead, it uses gRPC to get validated data from one or more trusted servers that are connected to the P2P network.
It can then efficiently handle API calls, reducing the load on `rippled` servers running in P2P mode.
{{ include_svg("img/reporting-mode-basic-architecture.svg", "Figure 1: Working of `rippled` in reporting mode") }}
The reporting mode of `rippled` uses two datastores:
* The primary persistent datastore for `rippled` that includes transaction metadata, account states, and ledger headers. You can use NuDB (included with the source) or [Cassandra](https://cassandra.apache.org/) as the primary persistent datastore. If you use Cassandra, multiple reporting mode servers can share access to data in a single Cassandra instance or cluster.
* [PostgreSQL](https://www.postgresql.org/) database to hold relational data, which is used mainly by [tx method][] and [account_tx method][].
When a reporting mode server receives an API request, it loads the data from these data stores if possible. For requests that require data from the P2P network, the reporting mode forwards the request to a P2P server, and then passes the response back to the client.
Multiple reporting mode servers can share access to the same network accessible databases (PostgreSQL and Cassandra); at any given time, only one reporting mode server writes to the databases, while all the others read from the databases.
## How to Run Reporting Mode
### Prerequisites
1. Ensure that your system meets the [system requirements](system-requirements.html).
**Note:** If you choose to use Cassandra as the database, the disk requirements for `rippled` will be lower as the data will not be stored on your local disk.
2. You also need to run at least one `rippled` server in P2P mode.
3. A compatible version of CMake must be installed.
4. Install and configure the datastores required to run `rippled` in reporting mode.
1. Install PostgreSQL.
2. Install and configure the database to be used as the primary persistent datastore. You can choose to use Cassandra or NuDB.
3. On macOS, you need to manually install the Cassandra cpp driver. On all other platforms, the Cassandra driver is built as part of the `rippled` build.
brew install cassandra-cpp-driver
#### Install PostgreSQL
**Install PostgreSQL on Linux**
1. Download and [install PostgreSQL on Linux](https://www.postgresqltutorial.com/install-postgresql-linux/).
2. Connect to the PostgreSQL Database Server using `psql`, and create a user `newuser` and a database `reporting`.
psql postgres
CREATE ROLE newuser WITH LOGIN PASSWORD ‘password’;
ALTER ROLE newuser CREATEDB;
\q
psql postgres -U newuser
postgres=# create database reporting;
**Install PostgreSQL on macOS**
1. Download and install PostgreSQL on macOS.
brew install postgres
brew services start postgres
2. Connect to the PostgreSQL Database Server using `psql` and create a user `newuser` and a database `reporting`.
psql postgres
CREATE ROLE newuser WITH LOGIN PASSWORD ‘password’;
ALTER ROLE newuser CREATEDB;
\q
psql postgres -U newuser
postgres=# create database reporting;
#### Install and Configure the Primary Persistent Datastore
**Cassandra**
Install Cassandra and then create a keyspace for `rippled`, with replication. <!-- SPELLING_IGNORE: keyspace -->
While a replication factor of 3 is recommended, when running locally, replication is not needed and you can set `replication_factor` to 1.
$ cqlsh [host] [port]
> CREATE KEYSPACE `rippled` WITH REPLICATION =
{'class' : 'SimpleStrategy', 'replication_factor' : 1 };
**NuDB**
If you’re running `rippled` in reporting mode for your local network, you can choose to use NuDB instead of Cassandra as your backend database.
NuDB is installed as part of your `rippled` build setup and does not require any additional installation steps.
### Steps
1. Build `rippled` for reporting mode on [Ubuntu or macOS](https://github.com/XRPLF/rippled/blob/release/BUILD.md).
<!-- MULTICODE_BLOCK_START -->
*Linux*
wget https://github.com/Kitware/CMake/releases/download/v3.16.3/cmake-3.16.3-Linux-x86_64.sh
sudo sh cmake-3.16.3-Linux-x86_64.sh --prefix=/usr/local --exclude-subdir
cmake -B build -Dreporting=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel $(nproc)
*macOS*
cmake -B build -G "Unix Makefiles" -Dreporting=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel $(nproc)
<!-- MULTICODE_BLOCK_END -->
2. Create a configuration file to run `rippled` in reporting mode.
Make a copy of the example config file, `rippled-example.cfg`, and save it as `rippled-reporting-mode.cfg` in a location that enables you to run `rippled` as a non-root user. For example:
mkdir -p $HOME/.config/ripple
cp <RIPPLED_SOURCE>/cfg/rippled-example.cfg $HOME/.config/ripple/rippled-reporting-mode.cfg
3. Edit rippled-reporting-mode.cfg to set necessary file paths. The user you plan to run `rippled` as must have write permissions to all of the paths you specify here.
1. Set the `[node_db]` path to the location where you want to store the ledger database.
2. Set the `[database_path]` to the location where you want to store other database data. (This includes an SQLite database with configuration data, and is typically one level above the `[node_db]` path field.)
3. Set the `[debug_logfile]` to a path where `rippled` can write logging information.
Note that these are the only configurations required for `rippled` to start up successfully. All other configurations are optional and can be tweaked after you have a working server.
4. Edit the `rippled-reporting-mode.cfg` file to enable reporting mode:
1. Uncomment the `[reporting]` stanza or add a new one:
[reporting]
etl_source
read_only=0
2. List the `rippled` sources (ETL sources) to extract data from. These `rippled` servers must have gRPC enabled.
NOTE: Only include servers that you trust as reporting mode does not connect to the P2P network and hence cannot verify that the data actually matches the network consensus ledger.
[etl_source]
source_grpc_port=50051
source_ws_port=6006
source_ip=127.0.0.1
5. Configure the databases
1. Specify the Postgres DB for `[ledger_tx_tables]`:
[ledger_tx_tables]
conninfo = postgres://newuser:password@127.0.0.1/reporting
use_tx_tables=1
2. Specify the database for `[node_db]`.
<!-- MULTICODE_BLOCK_START -->
*NuDB*
[node_db]
type=NuDB
path=/home/ubuntu/ripple/
[ledger_history]
1000000
*Cassandra*
[node_db]
type=Cassandra
[ledger_history]
1000000
<!-- MULTICODE_BLOCK_END -->
6. Modify the configuration for `rippled` to open up ports.
1. Open the public websocket port:
[port_ws_admin_local]
port = 6006
ip = 127.0.0.1
admin = 127.0.0.1
protocol = ws
2. Open the gRPC port:
[port_grpc]
port = 60051
ip = 0.0.0.0
3. Add a secured gateway to the IP of your reporting system:
secure_gateway = 127.0.0.1
7. Run `rippled` in reporting mode:
./rippled --conf /home/ubuntu/.config/ripple/rippled-reporting-example.cfg
### What to Expect
Here are the excerpts of what you can expect to see on your terminal.
```text
Loading: "/home/ubuntu/.config/ripple/rippled-reporting-example.cfg"
2021-Dec-09 21:31:52.245577 UTC JobQueue:NFO Using 10 threads
2021-Dec-09 21:31:52.255422 UTC LedgerConsensus:NFO Consensus engine started (cookie: 17859050541656985684)
2021-Dec-09 21:31:52.256542 UTC ReportingETL::ETLSource:NFO Using IP to connect to ETL source: 127.0.0.1:50051
2021-Dec-09 21:31:52.257784 UTC ReportingETL::ETLSource:NFO Made stub for remote = { validated_ledger : , ip : 127.0.0.1 , web socket port : 6006, grpc port : 50051 }
2021-Dec-09 21:31:52.258032 UTC ReportingETL::LoadBalancer:NFO add : added etl source - { validated_ledger : , ip : 127.0.0.1 , web socket port : 6006, grpc port : 50051 }
2021-Dec-09 21:31:52.258327 UTC Application:NFO process starting: rippled-1.8.1+DEBUG
2021-Dec-09 21:31:52.719186 UTC PgPool:DBG max_connections: 18446744073709551615, timeout: 600, connection params: port: 5432, hostaddr: 127.0.0.1, user: newuser, password: *, channel_binding: prefer, dbname: reporting_test_core, host: 127.0.0.1, options: , sslmode: prefer, sslcompression: 0, sslsni: 1, ssl_min_protocol_version: TLSv1.2, gssencmode: prefer, krbsrvname: postgres, target_session_attrs: any
2021-Dec-09 21:31:52.788851 UTC PgPool:NFO server message: NOTICE: relation "version" already exists, skipping
2021-Dec-09 21:31:53.282807 UTC TaggedCache:DBG LedgerCache target size set to 384
2021-Dec-09 21:31:53.282892 UTC TaggedCache:DBG LedgerCache target age set to 240000000000
2021-Dec-09 21:31:53.283741 UTC Amendments:DBG Amendment 98DECF327BF79997AEC178323AD51A830E457BFC6D454DAF3E46E5EC42DC619F (CheckCashMakesTrustLine) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.283836 UTC Amendments:DBG Amendment 157D2D480E006395B76F948E3E07A45A05FE10230D88A7993C71F97AE4B1F2D1 (Checks) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.283917 UTC Amendments:DBG Amendment 1562511F573A19AE9BD103B5D6B9E01B3B46805AEC5D3C4805C902B514399146 (CryptoConditions) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.283975 UTC Amendments:DBG Amendment 86E83A7D2ECE3AD5FA87AB2195AE015C950469ABF0B72EAACED318F74886AE90 (CryptoConditionsSuite) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284016 UTC Amendments:DBG Amendment 30CD365592B8EE40489BA01AE2F7555CAC9C983145871DC82A42A31CF5BAE7D9 (DeletableAccounts) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284062 UTC Amendments:DBG Amendment F64E1EABBE79D55B3BB82020516CEC2C582A98A6BFE20FBE9BB6A0D233418064 (DepositAuth) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284099 UTC Amendments:DBG Amendment 3CBC5C4E630A1B82380295CDA84B32B49DD066602E74E39B85EF64137FA65194 (DepositPreauth) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284126 UTC Amendments:DBG Amendment DC9CA96AEA1DCF83E527D1AFC916EFAF5D27388ECA4060A88817C1238CAEE0BF (EnforceInvariants) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284153 UTC Amendments:DBG Amendment 07D43DCE529B15A10827E5E04943B496762F9A88E3268269D69C44BE49E21104 (Escrow) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284189 UTC Amendments:DBG Amendment 42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE (FeeEscalation) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284216 UTC Amendments:DBG Amendment 740352F2412A9909880C23A559FCECEDA3BE2126FED62FC7660D628A06927F11 (Flow) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284241 UTC Amendments:DBG Amendment 3012E8230864E95A58C60FD61430D7E1B4D3353195F2981DC12B0C7C0950FFAC (FlowCross) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284284 UTC Amendments:DBG Amendment AF8DF7465C338AE64B1E937D6C8DA138C0D63AD5134A68792BBBE1F63356C422 (FlowSortStrands) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284337 UTC Amendments:DBG Amendment 1F4AFA8FA1BC8827AD4C0F682C03A8B671DCDF6B5C4DE36D44243A684103EF88 (HardenedValidations) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284412 UTC Amendments:DBG Amendment 4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 (MultiSign) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284455 UTC Amendments:DBG Amendment 586480873651E106F1D6339B0C4A8945BA705A777F3F4524626FF1FC07EFE41D (MultiSignReserve) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284491 UTC Amendments:DBG Amendment B4E4F5D2D6FB84DF7399960A732309C9FD530EAE5941838160042833625A6076 (NegativeUNL) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284528 UTC Amendments:DBG Amendment 08DE7D96082187F6E6578530258C77FAABABE4C20474BDB82F04B021F1A68647 (PayChan) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284592 UTC Amendments:DBG Amendment 00C1FC4A53E60AB02C864641002B3172F38677E29C26C5406685179B37E1EDAC (RequireFullyCanonicalSig) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284649 UTC Amendments:DBG Amendment CC5ABAE4F3EC92E94A59B1908C2BE82D2228B6485C00AFF8F22DF930D89C194E (SortedDirectories) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284703 UTC Amendments:DBG Amendment 532651B4FD58DF8922A49BA101AB3E996E5BFBF95A913B3E392504863E63B164 (TickSize) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284787 UTC Amendments:DBG Amendment 955DF3FA5891195A9DAEFA1DDC6BB244B545DDE1BAA84CBB25D5F12A8DA68A0C (TicketBatch) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284950 UTC Amendments:DBG Amendment 6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC (TrustSetAuth) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.284997 UTC Amendments:DBG Amendment B4D44CC3111ADD964E846FC57760C8B50FFCD5A82C86A72756F6B058DDDF96AD (fix1201) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285025 UTC Amendments:DBG Amendment E2E6F2866106419B88C50045ACE96368558C345566AC8F2BDF5A5B5587F0E6FA (fix1368) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285067 UTC Amendments:DBG Amendment 42EEA5E28A97824821D4EF97081FE36A54E9593C6E4F20CBAE098C69D2E072DC (fix1373) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285103 UTC Amendments:DBG Amendment 6C92211186613F9647A89DFFBAB8F94C99D4C7E956D495270789128569177DA1 (fix1512) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285129 UTC Amendments:DBG Amendment 67A34F2CF55BFC0F93AACD5B281413176FEE195269FA6D95219A2DF738671172 (fix1513) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285153 UTC Amendments:DBG Amendment 5D08145F0A4983F23AFFFF514E83FAD355C5ABFBB6CAB76FB5BC8519FF5F33BE (fix1515) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285176 UTC Amendments:DBG Amendment B9E739B8296B4A1BB29BE990B17D66E21B62A300A909F25AC55C22D6C72E1F9D (fix1523) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285202 UTC Amendments:DBG Amendment 1D3463A5891F9E589C5AE839FFAC4A917CE96197098A1EF22304E1BC5B98A454 (fix1528) is supported and will be down voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285256 UTC Amendments:DBG Amendment CA7C02118BA27599528543DFE77BA6838D1B0F43B447D4D7F53523CE6A0E9AC2 (fix1543) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285290 UTC Amendments:DBG Amendment 7117E2EC2DBF119CA55181D69819F1999ECEE1A0225A7FD2B9ED47940968479C (fix1571) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285343 UTC Amendments:DBG Amendment FBD513F1B893AC765B78F250E6FFA6A11B573209D1842ADC787C850696741288 (fix1578) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285381 UTC Amendments:DBG Amendment 58BE9B5968C4DA7C59BA900961828B113E5490699B21877DEF9A31E9D0FE5D5F (fix1623) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285424 UTC Amendments:DBG Amendment 25BA44241B3BD880770BFA4DA21C7180576831855368CBEC6A3154FDE4A7676E (fix1781) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285464 UTC Amendments:DBG Amendment 4F46DF03559967AC60F2EB272FEFE3928A7594A45FF774B87A7E540DB0F8F068 (fixAmendmentMajorityCalc) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285500 UTC Amendments:DBG Amendment 8F81B066ED20DAECA20DF57187767685EEF3980B228E0667A650BAF24426D3B4 (fixCheckThreading) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285527 UTC Amendments:DBG Amendment C4483A1896170C66C098DEA5B0E024309C60DC960DE5F01CD7AF986AA3D9AD37 (fixMasterKeyAsRegularKey) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285550 UTC Amendments:DBG Amendment 621A0B264970359869E3C0363A899909AAB7A887C8B73519E4ECF952D33258A8 (fixPayChanRecipientOwnerDir) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285575 UTC Amendments:DBG Amendment 89308AF3B8B10B7192C4E613E1D2E4D9BA64B2EE2D5232402AE82A6A7220D953 (fixQualityUpperBound) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285614 UTC Amendments:DBG Amendment B6B3EEDC0267AB50491FDC450A398AF30DBCD977CECED8BEF2499CAB5DAC19E2 (fixRmSmallIncreasedQOffers) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285651 UTC Amendments:DBG Amendment 452F5906C46D46F407883344BFDD90E672B672C5E9943DB4891E3A34FEEEB9DB (fixSTAmountCanonicalize) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.285725 UTC Amendments:DBG Amendment 2CD5286D8D687E98B41102BDD797198E81EA41DF7BD104E6561FEB104EFF2561 (fixTakerDryOfferRemoval) is supported and will be up voted if not enabled on the ledger.
2021-Dec-09 21:31:53.290446 UTC Server:NFO Opened 'port_rpc_admin_local' (ip=127.0.0.1:7005, admin IPs:127.0.0.1, http)
2021-Dec-09 21:31:53.290834 UTC Server:NFO Opened 'port_ws_admin_local' (ip=127.0.0.1:7006, admin IPs:127.0.0.1, ws)
2021-Dec-09 21:31:53.290984 UTC Application:WRN Running in standalone mode
2021-Dec-09 21:31:53.291048 UTC NetworkOPs:NFO STATE->full
2021-Dec-09 21:31:53.291192 UTC Application:FTL Startup RPC:
{
"command" : "log_level",
"severity" : "debug"
}
2021-Dec-09 21:31:53.291347 UTC RPCHandler:DBG RPC call log_level completed in 2.2e-08seconds
2021-Dec-09 21:31:53.291440 UTC Application:FTL Result:
{
"warnings" :
[
{
"id" : 1004,
"message" : "This is a reporting server. The default behavior of a reporting server is to only return validated data. If you are looking for not yet validated data, include \"ledger_index : current\" in your request, which will cause this server to forward the request to a p2p node. If the forward is successful the response will include \"forwarded\" : \"true\""
}
]
}
2021-Dec-09 21:31:53.291502 UTC ReportingETL:NFO Starting reporting etl
2021-Dec-09 21:31:53.291605 UTC Application:NFO Application starting. Version is 1.8.1+DEBUG
2021-Dec-09 21:31:53.291747 UTC LoadManager:DBG Starting
2021-Dec-09 21:31:53.291846 UTC gRPC Server:NFO Starting gRPC server at 0.0.0.0:60051
2021-Dec-09 21:31:53.293246 UTC LedgerCleaner:DBG Started
2021-Dec-09 21:31:53.295543 UTC ReportingETL::ETLSource:DBG handleMessage : Received a message on ledger subscription stream. Message : {
"result" : {},
"status" : "success",
"type" : "response"
}
- { validated_ledger : , ip : 127.0.0.1 , web socket port : 6006, grpc port : 50051 }
2021-Dec-09 21:31:53.368075 UTC ReportingETL:NFO monitor : Database is empty. Will download a ledger from the network.
2021-Dec-09 21:31:53.368183 UTC ReportingETL:NFO monitor : Waiting for next ledger to be validated by network...
```
## Frequently Asked Questions
<!-- STYLE_OVERRIDE: frequently -->
**Do I need to run more than one instance of `rippled` to use reporting mode?**
Yes. A `rippled` server running in reporting mode does not connect to the peer-to-peer network, but instead extracts validated data from one or more `rippled` servers that are connected to the network, so you need to run at least one P2P mode server.
**I’ve already installed `rippled`. Can I update the configuration file to enable reporting mode and restart `rippled`?**
No. Currently, you need to download the source and build `rippled` for reporting mode. There are initiatives in progress to provide packages for reporting mode.
**To run `rippled` in reporting mode, I need at least one `rippled` server running in P2P mode too. Does this mean I need double the disk space?**
The answer depends on the location of your primary data store. If you use Cassandra as the primary data store, the reporting mode server stores much less data on its local disk. The PostgreSQL server can be remote as well. You can have multiple reporting mode servers share the same data this way.
Lastly, the P2P mode server only needs to keep very recent history, while the reporting mode server keeps long term history.
For more information on system requirements to run `rippled`, see the [`rippled` system requirements](system-requirements.html).
**How can I confirm the validity of the data that comes from the PostgreSQL or Cassandra database?**
When `rippled` runs in reporting mode, it only serves validated data from the ETL source specified in the config file. If you are using someone else's `rippled` server in P2P mode as the ETL source, you are implicitly trusting that server. If not, you need to run your own `rippled` node in P2P mode.
**Is it possible to make traditional SQL queries to the relational database rather than using the API?**
Technically, you *can* directly access the database if you want. However, the data is stored as binary blobs and you have to decode the blobs to access the data in them. This makes traditional SQL queries much less useful since they cannot find and filter the individual fields of the data.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

213
content/infrastructure/installation/capacity-planning.md Normal file
View File

@@ -0,0 +1,213 @@
---
html: capacity-planning.html
parent: install-rippled.html
blurb: Plan system specs and tune configuration for rippled in production environments.
labels:
- Core Server
- Data Retention
---
# Capacity Planning
This document describes configuration, network, and hardware recommendations that you can use to tune and optimize the performance of an XRP Ledger server.
The load on an XRP Ledger server varies based on multiple factors. One is the activity in the network. The total size of data in the shared ledger and the total volume of transactions being sent vary based on organic factors throughout the global XRP Ledger community. Another factor is API usage; different types of [API calls](http-websocket-apis.html) put different load on the server. The performance characteristics can be very different between servers that provide a public API, provide a private API to specific integration software, or provide no API at all.
You should consider these factors to ensure that your server has the capacity to handle XRP Ledger network activity today and in the future.
## Configuration Settings
The default configuration file contains settings for a broad range of common use cases. You can get better performance by customizing the settings for your specific hardware and intended usage pattern.
The settings in this section are parameters in the `rippled.cfg` file. You can access an example config file, `rippled-example.cfg`, in the [`cfg` directory](https://github.com/XRPLF/rippled/blob/develop/cfg/rippled-example.cfg) in the `rippled` GitHub repo. The settings in the example config file match the default config installed alongside the server.
### Node Size
The `[node_size]` parameter should match the overall hardware capacity of your server. You can omit this parameter to have the server automatically choose an appropriate setting based on the system's total RAM and number of CPU threads. You can set this value explicitly if the automatic setting is wrong for your system, for example if some of the system's RAM or threads need to be set aside for other software, or the amounts reported by the operating system are inaccurate. (This can occur in some containers.) [Updated in: rippled 1.8.1][]
As a general rule, you should always use the largest node size your available RAM can support. See the following table for recommended settings.
#### Recommendation
Each `[node_size]` has a corresponding requirement for available RAM. For example, if you set `[node_size]` to `huge`, you should have at least 32 GB of available RAM to help ensure that `rippled` can run smoothly.
To tune your server, it may be useful to start with `tiny` and increase the size to `small`, `medium`, and so on as you refine the requirements for your use case.
| RAM available | `node_size` value | Notes |
|:--------------|:------------------|:-----------------------------------------|
| < 8 GB | `tiny` | **Not recommended.** A server with this setting may not sync to a busy network. |
| 8 GB | `small` | Recommended for test servers that only need to run occasionally. |
| 16 GB | `medium` | The `rippled-example.cfg` file uses this value. |
| 32 GB | `large` | **Not recommended.** In practice, this setting performs worse than `huge` in most circumstances. Always use `huge` if you want stability. |
| 64 GB | `huge` | Recommended for production servers. |
If you set the `[node_size]` parameter to an invalid value, the [server fails to start](server-wont-start.html#bad-node_size-value).
### Node DB Type
The `type` field in the `[node_db]` stanza of the `rippled.cfg` file sets the type of key-value store that `rippled` uses to hold the ledger store.
For almost all purposes, use `NuDB`. A fast SSD is required. [Learn more](#more-about-using-nudb)
The `RocksDB` setting is available for legacy purposes, but is generally not recommended. [Learn more](#more-about-using-rocksdb)
The example `rippled-example.cfg` file has the `type` field in the `[node_db]` stanza set to `NuDB`.
#### More About Using RocksDB
[RocksDB](https://rocksdb.org/docs/getting-started.html) is a persistent key-value store built into `rippled`. **Support for RocksDB is considered legacy.** Servers using RocksDB usually struggle to maintain sync with the Mainnet due to the memory requirements of maintaining a large database. Generally, you should use NuDB instead.
Cases where you might use RocksDB include if you need to load historical data saved in RocksDB format, or if you are storing data on slow SSDs or rotational disks. While rotational disks won't be able to keep up with Mainnet, you can probably run offline tests or small private networks on them.
RocksDB has performance-related configuration options that you can tweak for more transaction processing throughput. Here is an example `[node_db]` configuration for RocksDB:
```
[node_db]
type=RocksDB
path=/var/lib/rippled/db/rocksdb
open_files=512
filter_bits=12
cache_mb=512
file_size_mb=64
file_size_mult=2
online_delete=2000
advisory_delete=0
```
(Adjust the `path` to the directory where you want to keep the ledger store on disk. Adjust the `online_delete` and `advisory_delete` settings as desired for your configuration.)
#### More About Using NuDB
[NuDB](https://github.com/vinniefalco/nudb#introduction) is an append-only key-value store that is optimized for SSD drives.
NuDB has nearly constant performance and memory footprints regardless of the [amount of data being stored](#disk-space). NuDB _requires_ a solid-state drive. Scalability testing has shown that NuDB has equivalent or better performance than RocksDB in production and comparable configurations.
Production servers should be configured to use NuDB and to store the amount of historical data required for your use case.
NuDB does not have performance-related configuration options available in `rippled.cfg`. Here is the recommended `[node_db]` configuration for a `rippled` server using NuDB:
```
[node_db]
type=NuDB
path=/var/lib/rippled/db/nudb
online_delete=2000
advisory_delete=0
```
Adjust the `path` to the directory where you want to keep the ledger store on disk. Adjust the `online_delete` and `advisory_delete` settings as desired for your configuration. For more details about these settings, see [Configure Online Deletion](configure-online-deletion.html) and [Configure Advisory Deletion](configure-advisory-deletion.html).
### Log Level
The example `rippled-example.cfg` file sets the logging verbosity to `warning` in the `[rpc_startup]` stanza. This setting greatly reduces disk space and I/O requirements over more verbose logging. However, more verbose logging provides increased visibility for troubleshooting.
**Caution:** If you omit the `log_level` command from the `[rpc_startup]` stanza, the server writes logs to disk at the `debug` level and outputs `warning` level logs to the console. Logging at the `debug` level requires several more GB of disk space per day than `warning` level, depending on transaction volumes and client activity.
## Network and Hardware
Each server in the XRP Ledger network performs all of the transaction processing work of the network. Total activity on the network varies but has mostly increased over time, so you should choose hardware with greater capacity than you need for the current network activity.
### Recommendation
See [System Requirements](system-requirements.html) for a summary of the recommended hardware specs.
#### CPU Utilization and Virtualization
<!-- STYLE_OVERRIDE: utilization -->
You'll get the best performance on bare metal, but virtual machines can perform nearly as well as long as the host hardware has high enough specs.
#### Disk Speed
The speed of storage is one of the most important factors in a server's capacity. Use a high-grade solid state disk drive (SSD) with low-latency random reads and high throughput. Ripple engineers have observed the following maximum reads and writes per second:
- Over 10,000 reads per second (in heavily-used public server clusters)
- Over 7,000 writes per second (in dedicated performance testing)
<!--{# TODO 2021-11: have bigger numbers been seen lately? These might need an update #}-->
#### Disk Space
The `[node_db]` stanza controls the server's _ledger store_, which holds [ledger history](ledger-history.html). The amount of disk space you need depends on how much history you plan to keep available locally. An XRP Ledger server does not need to store more than the most recent 256 ledger versions to follow the consensus process and report the complete state of the ledger, but you can only query your server for transactions that executed in ledger versions it has stored locally. Configure the `path` of the `[node_db]` to point to your chosen storage location for the ledger store.
You can control how much data you keep with [online deletion](online-deletion.html); the default config file has the server keep the latest 2000 ledger versions. Without online deletion, the server's disk requirements grow without bounds.
The following table approximates the requirements for different amounts of history, at the time of writing (2023-07-19):
| Real Time Amount | Number of Ledger Versions | Disk Space Required (NuDB) |
|:-----------------|:--------------------------|:---------------------------|
| 2 hours | 2,000 | 450 MB |
| 1 day | 25,000 | 12 GB |
| 14 days | 350,000 | 168 GB |
| 30 days | 750,000 | 360 GB |
| 90 days | 2,250,000 | 1 TB |
| 1 year | 10,000,000 | 4.5 TB |
| 2 years | 20,000,000 | 9 TB |
| Full history | 81,000,000+ | ~26 TB |
These numbers are estimates. They depend on several factors, most importantly the volume of transactions in the network. As transaction volume increases, each ledger version stores more unique data. You should provision extra storage capacity to prepare for future growth.
The `online_delete` setting tells the server how many ledger versions to keep after deleting old history. You should plan for enough disk space to store twice that many ledger versions at maximum (right before online deletion runs).
For instructions on how to change the amount of history you keep, see [Configure Online Deletion](configure-online-deletion.html).
The `[database_path]` configures separate bookkeeping databases: these include transaction data as well as some runtime configurations.
As a general rule, you can safely delete the database files (both the ledger store and the bookkeeping databases) for a `rippled` server when it isn't running; this clears any stored ledger history the server has, but it can re-acquire that data from the network. However, if you delete the `wallet.db` file in the `[database_path]`, you must manually reapply runtime configuration changes such as [amendment votes](configure-amendment-voting.html) and [peer reservations](use-a-peer-reservation.html).
If you want to contribute to storing ledger history but you do not have enough disk space to store full history, you can use the [History Sharding](history-sharding.html) feature to store a randomized range of ledgers in a separate shard store. History sharding is configured in the `[shard_db]` stanza.
##### Amazon Web Services
Amazon Web Services (AWS) is a popular virtualized hosting environment. You can run `rippled` in AWS, but do not use Elastic Block Storage (EBS). See [System Requirements](system-requirements.html). <!-- SPELLING_IGNORE: ebs, aws -->
AWS instance stores (`ephemeral` storage) provide suitable performance, but you may lose data in some circumstances, including when you start/stop an instance. This may be acceptable, since an individual XRP Ledger server can usually re-acquire lost ledger history from its peers. Configuration settings should be stored on more permanent storage.
Make sure the `path` of your `[node_db]` stanza and your `[database_path]` both point to the appropriate storage.
#### RAM/Memory
Memory requirements are mainly a function of the `node_size` configuration setting and the amount of client traffic retrieving historical data. For more information about memory requirements, see [Node Size](#node-size).
#### Network
Any enterprise or carrier-class data center should have enough network bandwidth to support running XRP Ledger servers. The actual bandwidth necessary varies significantly based on the current transaction volume in the network. Server behavior (such as backfilling [ledger history](ledger-history.html)) also affects network use. Consumer-grade home internet is generally not enough to run a reliable server.
During exceptionally high periods of transaction volume, some operators have reported that their servers have completely saturated a 100 megabit/s network link, so a gigabit network interface is required for reliable performance.
Here are examples of observed uncompressed network bandwidth use for common tasks:
| Task | Send/Receive |
|:------------------------------------------------|:-----------------------|
| Process average transaction volumes | 2 Mbps up, 2 Mbps down |
| Process peak transaction volumes | >100 Mbps up |
| Serve historical ledger and transaction reports | 100 Mbps up |
| Start up `rippled` | 20 Mbps down |
You can save bandwidth by [enabling compression on peer-to-peer communications](enable-link-compression.html), at a cost of higher CPU. Many hardware configurations have spare CPU capacity during normal use, so this can be an economical option if your network bandwidth is limited.
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Configure rippled](configure-rippled.html)
- [Configure Online Deletion](configure-online-deletion.html) - Adjust how many historical ledger versions your server should keep at a time.
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [logrotate method][] - Closes and reopens the server's debug log so you can rotate it with standard tools.
- [server_info method][] - General information about the server including sync status and how many historical ledger versions it has available on disk.
- [get_counts method][] - Additional health information, especially how many objects of various types it holds in RAM.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

10
content/infrastructure/installation/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
html: install-rippled.html
parent: infrastructure.html
top_nav_name: Install & Configure
template: pagetype-category.html.jinja
blurb: Install and update XRP Ledger servers including the core server, rippled, and API server, Clio.
---
# Installation
Install and update XRP Ledger servers including the core server, rippled, and API server, Clio.

154
content/infrastructure/installation/install-clio-on-ubuntu.md Normal file
View File

@@ -0,0 +1,154 @@
---
html: install-clio-on-ubuntu.html
parent: install-rippled.html
blurb: Install a precompiled Clio binary on Ubuntu Linux.
labels:
- Clio Server
---
# Install Clio on Ubuntu Linux
This page describes the recommended instructions for installing the latest stable version of Clio on **Ubuntu Linux 20.04 or higher** using the [`apt`](https://ubuntu.com/server/docs) utility.
These instructions install a binary that has been compiled by Ripple. For instructions on how to build Clio from source, see the [Clio source code repository](https://github.com/XRPLF/clio).
## Prerequisites
Before you install Clio, you must meet the following requirements.
- Ensure that your system meets the [system requirements](system-requirements.html).
**Note:** Clio has the same system requirements as the `rippled` server, except Clio needs less disk space to store the same amount of ledger history.
- You need compatible versions of CMake and Boost. Clio requires C++20 and Boost 1.75.0 or higher.
- Access to a Cassandra cluster that is running locally or remote. You can choose to install and configure a Cassandra cluster manually by following the [Cassandra installation instructions](https://cassandra.apache.org/doc/latest/cassandra/getting_started/installing.html), or run Cassandra on a Docker container using one of the following commands.
- If you choose to persist Clio data, run Cassandra in a Docker container and specify an empty directory to store Clio data:
docker run --rm -it --network=host --name cassandra -v $PWD/cassandra_data:/var/lib/
cassandra cassandra:4.0.4
- If you do not wish to persist Clio data, run the following command:
docker run --rm -it --network=host --name cassandra cassandra:4.0.4
- You need gRPC access to one or more `rippled` servers in P2P mode. The `rippled` servers can either be local or remote, but you must trust them. The most reliable way to do this is to [install `rippled` yourself](install-rippled.html).
## Installation Steps
1. Update repositories:
sudo apt -y update
**Tip:** If you have already installed an up-to-date version of `rippled` on the same machine, you can skip the following steps for adding Ripple's package repository and signing key, which are the same as in the `rippled` install process. Resume from step 5, "Fetch the Ripple repository."
2. Install utilities:
sudo apt -y install apt-transport-https ca-certificates wget gnupg
3. Add Ripple's package-signing GPG key to your list of trusted keys:
sudo mkdir /usr/local/share/keyrings/
wget -q -O - "https://repos.ripple.com/repos/api/gpg/key/public" | gpg --dearmor > ripple-key.gpg
sudo mv ripple-key.gpg /usr/local/share/keyrings
4. Check the fingerprint of the newly-added key:
gpg /usr/local/share/keyrings/ripple-key.gpg
The output should include an entry for Ripple such as the following:
gpg: WARNING: no command supplied. Trying to guess what you mean ...
pub rsa3072 2019-02-14 [SC] [expires: 2026-02-17]
C0010EC205B35A3310DC90DE395F97FFCCAFD9A2
uid TechOps Team at Ripple <techops+rippled@ripple.com>
sub rsa3072 2019-02-14 [E] [expires: 2026-02-17]
In particular, make sure that the fingerprint matches. (In the above example, the fingerprint is on the third line, starting with `C001`.)
4. Add the appropriate Ripple repository for your operating system version:
echo "deb [signed-by=/usr/local/share/keyrings/ripple-key.gpg] https://repos.ripple.com/repos/rippled-deb focal stable" | \
sudo tee -a /etc/apt/sources.list.d/ripple.list
The above example is appropriate for **Ubuntu 20.04 Focal Fossa**.
5. Fetch the Ripple repository.
sudo apt -y update
6. Install the Clio software package. There are two options:
- To run `rippled` on the same machine, install the `clio` package, which sets up both servers:
sudo apt -y install clio
- To run Clio on a separate machine from `rippled`, install the `clio-server` package, which sets up Clio only:
sudo apt -y install clio-server
7. If you are running `rippled` on a separate machine, modify your Clio config file to point to it. You can skip this step if you used the `clio` package to install both on the same machine.
1. Edit the Clio server's config file to modify the connection information for the `rippled` server. The package installs this file at `/opt/clio/etc/config.json`.
"etl_sources":
[
{
"ip":"127.0.0.1",
"ws_port":"6006",
"grpc_port":"50051"
}
]
This includes:
- The IP of `rippled` server.
- The port where `rippled` accepts unencrypted WebSocket connections.
- The port where `rippled` accepts gRPC requests.
**Note** You can use multiple `rippled` servers as a data source by add more entries to the `etl_sources` section. If you do, Clio load balances requests across all the servers in the list, and can keep up with the network as long as at least one of the `rippled` servers is synced.
The [example config file](https://github.com/XRPLF/clio/blob/develop/example-config.json) accesses the `rippled` server running on the local loopback network (127.0.0.1), with the WebSocket (WS) on port 6006 and gRPC on port 50051.
2. Update the `rippled` server's config file to allow the Clio server to connect to it. The package installs this file at `/etc/opt/ripple/rippled.cfg`.
* Open a port to accept unencrypted WebSocket connections.
[port_ws_public]
port = 6005
ip = 0.0.0.0
protocol = ws
* Open a port to handle gRPC requests and specify the IP(s) of Clio server(s) in the `secure_gateway` entry.
[port_grpc]
port = 50051
ip = 0.0.0.0
secure_gateway = 127.0.0.1
**Tip:** If you are not running Clio on the same machine as `rippled`, change the `secure_gateway` in the example stanza to use the IP address of the Clio server.
8. Enable and start the Clio systemd service.
sudo systemctl enable clio
9. Start the `rippled` and Clio servers.
sudo systemctl start rippled
sudo systemctl start clio
If you are starting with a fresh database, Clio needs to download the full ledger. This can take some time. If you are starting both servers for the first time, it can take even longer because Clio waits for `rippled` to sync before extracting ledgers.
## See Also
- **Concepts:**
- [The Clio Server](the-clio-server.html)

114
content/infrastructure/installation/install-rippled-on-centos-rhel-with-yum.md Normal file
View File

@@ -0,0 +1,114 @@
---
html: install-rippled-on-centos-rhel-with-yum.html
parent: install-rippled.html
blurb: Install a precompiled rippled binary on CentOS or Red Hat Enterprise Linux.
labels:
- Core Server
---
# Install on CentOS/Red Hat with yum
This page describes the recommended instructions for installing the latest stable version of `rippled` on **CentOS 7** or **Red Hat Enterprise Linux 7**, using Ripple's [yum](https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified) repository.
These instructions install a binary that has been compiled by Ripple.
## Prerequisites
Before you install `rippled`, you must meet the [System Requirements](system-requirements.html).
## Installation Steps
1. Install the Ripple RPM repository:
Choose the appropriate RPM repository for the stability of releases you want:
- `stable` for the latest production release (`master` branch)
- `unstable` for pre-release builds (`release` branch)
- `nightly` for experimental/development builds (`develop` branch)
<!-- MULTICODE_BLOCK_START -->
*Stable*
cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo
[ripple-stable]
name=XRP Ledger Packages
enabled=1
gpgcheck=0
repo_gpgcheck=1
baseurl=https://repos.ripple.com/repos/rippled-rpm/stable/
gpgkey=https://repos.ripple.com/repos/rippled-rpm/stable/repodata/repomd.xml.key
REPOFILE
*Pre-release*
cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo
[ripple-unstable]
name=XRP Ledger Packages
enabled=1
gpgcheck=0
repo_gpgcheck=1
baseurl=https://repos.ripple.com/repos/rippled-rpm/unstable/
gpgkey=https://repos.ripple.com/repos/rippled-rpm/unstable/repodata/repomd.xml.key
REPOFILE
*Development*
cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo
[ripple-nightly]
name=XRP Ledger Packages
enabled=1
gpgcheck=0
repo_gpgcheck=1
baseurl=https://repos.ripple.com/repos/rippled-rpm/nightly/
gpgkey=https://repos.ripple.com/repos/rippled-rpm/nightly/repodata/repomd.xml.key
REPOFILE
<!-- MULTICODE_BLOCK_START -->
2. Fetch the latest repo updates:
sudo yum -y update
3. Install the new `rippled` package:
sudo yum install rippled
4. Reload systemd unit files:
sudo systemctl daemon-reload
5. Configure the `rippled` service to start on boot:
sudo systemctl enable rippled.service
6. Start the `rippled` service:
sudo systemctl start rippled.service
## Next Steps
{% include '_snippets/post-rippled-install.md' %}<!--_ -->
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Configure rippled](configure-rippled.html)
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- [Get Started with the rippled API](get-started-using-http-websocket-apis.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

118
content/infrastructure/installation/install-rippled-on-ubuntu.md Normal file
View File

@@ -0,0 +1,118 @@
---
html: install-rippled-on-ubuntu.html
parent: install-rippled.html
blurb: Install a precompiled rippled binary on Ubuntu Linux.
labels:
- Core Server
---
# Install on Ubuntu or Debian Linux
This page describes the recommended instructions for installing the latest stable version of `rippled` on **Ubuntu Linux 18.04 or higher** or **Debian 10 or higher**, using the [`apt`](https://ubuntu.com/server/docs) utility.
These instructions install a binary that has been compiled by Ripple.
## Prerequisites
Before you install `rippled`, you must meet the [System Requirements](system-requirements.html).
## Installation Steps
1. Update repositories:
sudo apt -y update
2. Install utilities:
sudo apt -y install apt-transport-https ca-certificates wget gnupg
3. Add Ripple's package-signing GPG key to your list of trusted keys:
sudo mkdir /usr/local/share/keyrings/
wget -q -O - "https://repos.ripple.com/repos/api/gpg/key/public" | gpg --dearmor > ripple-key.gpg
sudo mv ripple-key.gpg /usr/local/share/keyrings/
4. Check the fingerprint of the newly-added key:
gpg --import --import-options show-only /usr/local/share/keyrings/ripple-key.gpg
The output should include an entry for Ripple such as the following:
pub rsa3072 2019-02-14 [SC] [expires: 2026-02-17]
C0010EC205B35A3310DC90DE395F97FFCCAFD9A2
uid TechOps Team at Ripple <techops+rippled@ripple.com>
sub rsa3072 2019-02-14 [E] [expires: 2026-02-17]
In particular, make sure that the fingerprint matches. (In the above example, the fingerprint is on the second line, starting with `C001`.)
5. Add the appropriate Ripple repository for your operating system version:
echo "deb [signed-by=/usr/local/share/keyrings/ripple-key.gpg] https://repos.ripple.com/repos/rippled-deb focal stable" | \
sudo tee -a /etc/apt/sources.list.d/ripple.list
The above example is appropriate for **Ubuntu 20.04 Focal Fossa**. For other operating systems, replace the word `focal` with one of the following:
- `bionic` for **Ubuntu 18.04 Bionic Beaver**
- `buster` for **Debian 10 Buster**
- `bullseye` for **Debian 11 Bullseye**
- `jammy` for **Ubuntu 22.04 Jammy Jellyfish**
If you want access to development or pre-release versions of `rippled`, use one of the following instead of `stable`:
- `unstable` - Pre-release builds ([`release` branch](https://github.com/XRPLF/rippled/tree/release))
- `nightly` - Experimental/development builds ([`develop` branch](https://github.com/XRPLF/rippled/tree/develop))
**Warning:** Unstable and nightly builds may be broken at any time. Do not use these builds for production servers.
6. Fetch the Ripple repository.
sudo apt -y update
7. Install the `rippled` software package:
sudo apt -y install rippled
8. Check the status of the `rippled` service:
systemctl status rippled.service
The `rippled` service should start automatically. If not, you can start it manually:
sudo systemctl start rippled.service
9. Optional: allow `rippled` to bind to privileged ports.
This allows you to serve incoming API requests on port 80 or 443. (If you want to do so, you must also update the config file's port settings.)
sudo setcap 'cap_net_bind_service=+ep' /opt/ripple/bin/rippled
## Next Steps
{% include '_snippets/post-rippled-install.md' %}
<!--_ -->
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Configure rippled](configure-rippled.html)
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- [Get Started with the rippled API](get-started-using-http-websocket-apis.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

112
content/infrastructure/installation/rippled-1-3-migration-instructions.md Normal file
View File

@@ -0,0 +1,112 @@
---
html: rippled-1-3-migration-instructions.html
parent: install-rippled.html
blurb: Use these instructions to upgrade rippled packages from 1.2.x or below to 1.3.x or higher.
status: removed
---
# rippled v1.3.x Migration Instructions
This document describes the migration process for upgrading from `rippled` 1.2.4 or earlier to `rippled` v1.3 or later. This migration process is necessary because the `rippled` install process has changed as of version 1.3.
This document provides migration steps for upgrading on supported platforms:
- [CentOS or Red Hat Enterprise Linux (RHEL)](#migration-on-centos-or-red-hat-enterprise-linux-rhel)
- [Ubuntu Linux](#migration-on-ubuntu-linux)
For other platforms, see the updated instructions for compiling from source. ([Ubuntu](build-run-rippled-ubuntu.html), [macOS](build-run-rippled-macos.html), or [Windows](https://github.com/XRPLF/rippled/tree/develop/Builds/VisualStudio2017))
## Migration on CentOS or Red Hat Enterprise Linux (RHEL)
Ripple's official RPM repository and instructions for using it have changed. If you have [automatic updates](update-rippled-automatically-on-linux.html) enabled, your system should perform the migration automatically. To migrate manually from the old repository to the new one, complete the following steps:
1. Stop the `rippled` server.
$ sudo systemctl stop rippled.service
2. Remove the old Ripple repository package.
$ sudo rpm -e ripple-repo
The `rippled-repo` package is now **DEPRECATED**. The package has been updated one last time for version 1.3.1. In the future, any changes to the repositories will require manual changes to the `ripple.repo` file. <!-- STYLE_OVERRIDE: will -->
3. Add Ripple's new yum repository:
$ cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo
[ripple-stable]
name=XRP Ledger Packages
baseurl=https://repos.ripple.com/repos/rippled-rpm/stable/
enabled=1
gpgcheck=0
gpgkey=https://repos.ripple.com/repos/rippled-rpm/stable/repodata/repomd.xml.key
repo_gpgcheck=1
REPOFILE
4. Install the new `rippled` package:
$ sudo yum install rippled
Version 1.3.1 does not require any changes to your config files (`rippled.cfg` and `validators.txt`). This update procedure leaves your existing config files in place.
5. Reload systemd unit files:
$ sudo systemctl daemon-reload
6. Start the `rippled` service:
$ sudo systemctl start rippled.service
**Warning:** If you use [automatic updates](update-rippled-automatically-on-linux.html), they should continue working after performing this migration process. However, **the `ripple-repo` package is now deprecated**. As a consequence, in the future, any changes to Ripple's repositories may require you to manually update your repos file.
## Migration on Ubuntu Linux
Prior to version 1.3, the supported way to install `rippled` on Ubuntu Linux was using Alien to install the RPM package. Starting with `rippled` v1.3.1, Ripple provides a native package for Ubuntu and Debian Linux, which is the recommended way of installing it. If you already have the RPM package installed, complete the [installation steps](install-rippled-on-ubuntu.html) to upgrade the package and switch over to the native APT (`.deb`) package.
If you have made any changes to your config files (`/opt/ripple/etc/rippled.cfg` and `/opt/ripple/etc/validators.txt`), `apt` may prompt you during installation asking if you want to overwrite your config files with the newest versions from the packages. Version 1.3 does not require any changes to the config file, so you can safely keep your existing config files unchanged.
After installing the native APT package for 1.3, you need to reload/restart the service:
1. Reload systemd unit files:
$ sudo systemctl daemon-reload
2. Restart the `rippled` service:
$ sudo systemctl restart rippled.service
If you no longer need Alien for any other packages, you may optionally uninstall it and its dependencies using the following steps:
1. Uninstall Alien:
$ sudo apt -y remove alien
2. Uninstall unused dependencies:
$ sudo apt -y autoremove
### Automatic Updates
The `rippled` v1.3 package includes an updated auto-update script that works on Ubuntu and Debian Linux. For more information, see [Update `rippled` Automatically on Linux](update-rippled-automatically-on-linux.html).
## See Also
- **[`rippled` v1.3.1 Release Notes](https://github.com/XRPLF/rippled/releases/1.3.1)**
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Update Automatically on Linux](update-rippled-automatically-on-linux.html)
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- [Get Started with the rippled API](get-started-using-http-websocket-apis.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

61
content/infrastructure/installation/system-requirements.md Normal file
View File

@@ -0,0 +1,61 @@
---
html: system-requirements.html
parent: install-rippled.html
blurb: Hardware and software requirements for running rippled.
labels:
- Core Server
---
# System Requirements
## Recommended Specifications
For reliable performance in production environments, it is recommended to run an XRP Ledger (`rippled`) server on bare metal with the following characteristics or better:
- Operating System: Ubuntu (LTS), Red Hat Enterprise Linux (latest release), or a compatible Linux distribution.
- CPU: Intel Xeon 3+ GHz processor with 8+ cores and hyperthreading enabled.
- Disk: SSD / NVMe (10,000 IOPS sustained - not burst or peak - or better). Minimum 50 GB for the database partition. Do not use Amazon Elastic Block Store (AWS EBS) because its latency is too high to sync reliably.
- RAM: 64 GB.
- Network: Enterprise data center network with a gigabit network interface on the host.
For a validator in AWS, consider `z1d.2xlarge` with an extra 1 TB disk for logging and core dump storage.
## Minimum Specifications
**Caution:** These specifications are not enough to reliably [stay synced with Mainnet](server-doesnt-sync.html). For production use, follow the recommended specifications above.
For testing purposes, you can run an XRP Ledger server on commodity hardware with the following minimum requirements:
- Operating System: macOS, Windows (64-bit), or most Linux distributions (Red Hat, Ubuntu, and Debian supported).
- CPU: 64-bit x86_64, 4+ cores.
- Disk: SSD / NVMe (10,000 IOPS sustained - not burst or peak - or better). Minimum 50 GB for the database partition. Do not use Amazon Elastic Block Store (AWS EBS) because its latency is too high to sync reliably.
- RAM: 16 GB+.
<!-- SPELLING_IGNORE: iops, ntp, x86_64, ec2, nvme -->
Amazon EC2's `i3.2xlarge` VM size may be appropriate depending on your workload. A fast network connection is preferable. Any increase in a server's client-handling load increases resources needs.
## System Time
A `rippled` server relies on maintaining the correct time. It is recommended that the system synchronize time using the Network Time Protocol (NTP) with daemons such as `ntpd` or `chrony`.
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html) - More information on the recommended specifications and planning for production needs
- [Install `rippled`](install-rippled.html)
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

49
content/infrastructure/installation/update-rippled-automatically-on-linux.md Normal file
View File

@@ -0,0 +1,49 @@
---
html: update-rippled-automatically-on-linux.html
parent: install-rippled.html
blurb: Set up automatic updates for rippled on Linux.
labels:
- Core Server
- Security
---
# Update Automatically on Linux
On Linux, you can set up `rippled` to automatically upgrade to the latest version with a one-time `cron` configuration. Ripple recommends enabling automatic updates if possible.
These instructions assume you have already installed `rippled` [from the `yum` repository (CentOS/RedHat)](install-rippled-on-centos-rhel-with-yum.html) or [using `apt` (Ubuntu/Debian)](install-rippled-on-ubuntu.html).
To set up automatic updates, complete the following steps:
1. Check that `/opt/ripple/etc/update-rippled-cron` exists. If it does not, update manually ([CentOS/Red Hat](update-rippled-manually-on-centos-rhel.html) or [Ubuntu/Debian](update-rippled-manually-on-ubuntu.html)).
2. Create a symlink in your `cron.d` folder to the `/opt/ripple/etc/update-rippled-cron` config file:
sudo ln -s /opt/ripple/etc/update-rippled-cron /etc/cron.d/
This configuration runs a script to update the installed `rippled` package within an hour of each new release. To avoid network instability from too many servers updating at the same time, this script does not automatically restart the server, so it continues to run the old version until it restarts. [Updated in: rippled 1.8.1][]
3. **Whenever a new release comes out,** you must manually restart the `rippled` service to switch to the updated software.
sudo systemctl restart rippled.service
**Caution:** In the future, it is possible that changes to Ripple's repositories may require manual intervention to update the URLs where your script searches for updates. Stay tuned to the [XRP Ledger Blog](/blog/) or the [ripple-server mailing list](https://groups.google.com/forum/#!forum/ripple-server) for announcements on any required changes.
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [Capacity Planning](capacity-planning.html)
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

63
content/infrastructure/installation/update-rippled-manually-on-centos-rhel.md Normal file
View File

@@ -0,0 +1,63 @@
---
html: update-rippled-manually-on-centos-rhel.html
parent: install-rippled.html
blurb: Manually update rippled on CentOS or Red Hat Enterprise Linux.
labels:
- Core Server
- Security
---
# Update Manually on CentOS/Red Hat
This page describes how to update manually to the latest release of `rippled` on CentOS or Red Hat Enterprise Linux. Ripple recommends setting up [automatic updates](update-rippled-automatically-on-linux.html) instead, where possible.
These instructions assume you have already [installed `rippled` from the `yum` repository](install-rippled-on-centos-rhel-with-yum.html).
**Tip:** To perform these steps all at once, you can run the `/opt/ripple/bin/update-rippled.sh` script, which is included with the `rippled` package. This script should be run as a `sudo` user.
To update manually, complete the following steps:
1. If you are upgrading to `rippled` 1.7.0 from an earlier version, re-add the repository to get Ripple's updated GPG key. Otherwise, skip this step:
$ cat << REPOFILE | sudo tee /etc/yum.repos.d/ripple.repo
[ripple-stable]
name=XRP Ledger Packages
enabled=1
gpgcheck=0
repo_gpgcheck=1
baseurl=https://repos.ripple.com/repos/rippled-rpm/stable
gpgkey=https://repos.ripple.com/repos/rippled-rpm/stable/repodata/repomd.xml.key
REPOFILE
1. Download and install the latest `rippled` package:
$ sudo yum update rippled
This update procedure leaves your existing config files in place.
2. Reload the `systemd` unit files:
$ sudo systemctl daemon-reload
3. Restart the `rippled` service:
$ sudo service rippled restart
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [`rippled` v1.3.x Migration Instructions](rippled-1-3-migration-instructions.html) <!-- Note: remove when versions older than v1.3 are basically extinct -->
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

58
content/infrastructure/installation/update-rippled-manually-on-ubuntu.md Normal file
View File

@@ -0,0 +1,58 @@
---
html: update-rippled-manually-on-ubuntu.html
parent: install-rippled.html
blurb: Manually update rippled on Ubuntu Linux.
labels:
- Core Server
- Security
---
# Update Manually on Ubuntu or Debian
This page describes how to update manually to the latest release of `rippled` on Ubuntu Linux. These instructions assume you have already [installed `rippled` using the native package](install-rippled-on-ubuntu.html). Ripple recommends setting up [automatic updates](update-rippled-automatically-on-linux.html) instead, where possible.
> **Caution:** Ripple renewed the GPG key used to sign binary packages shortly before the release of v1.7.0. If you are upgrading from a version earlier than 1.7.0, you must first download and manually trust the updated public key as follows:
>
> wget -q -O - "https://repos.ripple.com/repos/api/gpg/key/public" | \
> sudo apt-key add -
>
> For more information, see the [`rippled` 1.7.0 release notes](https://xrpl.org/blog/2021/rippled-1.7.0.html#upgrading-special-action-required).
**Tip:** To perform these steps all at once, you can run the `/opt/ripple/bin/update-rippled.sh` script, which is included with the `rippled` package and is compatible with Ubuntu and Debian. This script should be run as a `sudo` user.
To update manually, complete the following steps:
1. Update repositories:
$ sudo apt -y update
2. Upgrade the `rippled` package:
$ sudo apt -y upgrade rippled
3. Reload the `systemd` unit files:
$ sudo systemctl daemon-reload
4. Restart the `rippled` service:
$ sudo service rippled restart
## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [Consensus](consensus.html)
- **Tutorials:**
- [`rippled` v1.3.x Migration Instructions](rippled-1-3-migration-instructions.html) <!-- Note: remove when versions older than v1.3 are basically extinct -->
- [Troubleshoot rippled](troubleshoot-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [`rippled` Commandline Usage](commandline-usage.html)
- [server_info method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}