ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-06 17:27:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Start moving files into their final places

Browse Source
This commit is contained in:
mDuo13
2018-05-02 17:29:50 -07:00
parent 795bd8346b
commit 2e02611855
300 changed files with 709 additions and 719 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
content/tutorials/manage-the-rippled-server/tutorial-build-run-rippled-ubuntu.md Normal file
View File

@@ -0,0 +1,191 @@
# Build and Run `rippled` on Ubuntu
`rippled` is the core peer-to-peer server that manages the XRP Ledger. A `rippled` server can connect to a network of peers, relay cryptographically signed transactions, and maintain a local copy of the complete shared global ledger.
For an overview of `rippled`, see [Operating rippled Servers](tutorial-rippled-setup.html).
Use these instructions to build a `rippled` executable from source version 0.90.0 or higher on Ubuntu Linux 16.04 or higher. These instructions were tested on Ubuntu 16.04 LTS.
For information about building `rippled` for other platforms, see [Builds](https://github.com/ripple/rippled/tree/develop/Builds) in the `rippled` GitHub repository.
## System Requirements
**_To build `rippled`:_**
You need a **minimum** of 8GB of RAM.
**_To run `rippled`:_**
Meet these [system requirements](tutorial-rippled-setup.html#minimum-system-requirements).
## 1. Build `rippled`
These instructions use Ubuntu's APT (Advanced Packaging Tool) to install the software prerequisites you need to build and run `rippled`.
1. Update the list of packages that are available for `apt-get` to install or upgrade.
sudo apt-get update
2. Upgrade currently installed packages.
sudo apt-get -y upgrade
3. Install Git.
sudo apt-get -y install git
4. Install SCons.
sudo apt-get -y install scons
5. Install `pkg-config`.
sudo apt-get -y install pkg-config
6. Install Protocol Buffers.
sudo apt-get -y install protobuf-compiler
sudo apt-get -y install libprotobuf-dev
7. Install Secure Socket Layer (SSL) toolkit development files.
sudo apt-get -y install libssl-dev
8. Install `wget` to be able to download Boost in the next step.
sudo apt-get -y install wget
9. Compile Boost.
Starting in `rippled` 0.90.0, the recommended Boost version is 1.64.0. Because Boost version 1.64.0 isn't available in the Ubuntu 16.04 repos, you must compile it yourself.
a. Download Boost 1.64.0.
wget https://dl.bintray.com/boostorg/release/1.64.0/source/boost_1_64_0.tar.gz
b. Untar `boost_1_64_0.tar.gz`.
tar xvzf boost_1_64_0.tar.gz
c. Access the new `boost_1_64_0` directory:
cd boost_1_64_0
d. To prepare the Boost.Build system for use, run:
./bootstrap.sh
e. To invoke Boost.Build to build the separately-compiled Boost libraries, run the following command. Replace `<number of jobs>` with the number of job, or commands, to run in parallel. This may take about 15 minutes, depending on your hardware specs.
./b2 -j <number of jobs>
f. Set the environment variable `BOOST_ROOT` to point to the new `boost_1_64_0` directory. It's best to put this environment variable in your `.profile`, or equivalent, file for your shell so it's automatically set when you log in. Add the following line to the file:
export BOOST_ROOT=/home/ubuntu/boost_1_64_0
g. Source your updated `.profile` file. For example:
source ~/.profile
10. Get `rippled` source code.
git clone https://github.com/ripple/rippled.git
cd rippled
git checkout master
11. If you previously built, or (more importantly) tried and failed to build `rippled`, you should delete the `build/` directory to start clean before moving on to the next step. Otherwise, you may get unexpected behavior, like a `rippled` executable that crashes due to a segmentation fault (segfault).
If this is your first time building `rippled,` you won't have a `build/` directory and can move on to the next step.
12. Build a `rippled` binary executable from source code. This may take about 20 minutes, depending on your hardware specs.
scons
SCons saves the built executable in `rippled/build`.
13. _(Optional)_ Run `rippled` unit tests. If there are no test failures, you can be fairly certain that your `rippled` executable compiled correctly.
./rippled -u
## 2. Configure `rippled`
Complete the following configurations that are required for `rippled` to start up successfully. All other configuration is optional and can be tweaked after you have a working server.
1. Create a copy of the example config file (assumes you're in the `rippled` folder already). Saving the config file to this location enables you to run `rippled` as a non-root user (recommended).
mkdir -p ~/.config/ripple
cp doc/rippled-example.cfg ~/.config/ripple/rippled.cfg
2. Edit the config file 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]`'s 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.
3. Copy the example `validators.txt` file to the same folder as `rippled.cfg`:
cp doc/validators-example.txt ~/.config/ripple/validators.txt
**Warning:** Ripple has designed a [decentralization plan](https://ripple.com/dev-blog/decentralization-strategy-update/) with maximum safety in mind. During the transition, you *should not* modify the `validators.txt` file except as recommended by Ripple. Even minor modifications to your validator settings could cause your server to diverge from the rest of the network and report out of date, incomplete, or inaccurate data. Acting on such data can cause you to lose money.
## 3. Run `rippled`
To run your stock `rippled` server from the executable you built, using the configurations you defined:
```
cd build
./rippled
```
### What to Expect
Once you've run `rippled`, here are excerpts of what you can expect to see in your terminal.
```
Loading: "/home/ubuntu/.config/ripple/rippled.cfg"
Watchdog: Launching child 1
2018-Jan-31 20:19:40 JobQueue:NFO Auto-tuning to 4 validation/transaction/proposal threads.
2018-Jan-31 20:19:40 Amendments:DBG Amendment 4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 is supported.
2018-Jan-31 20:19:40 Amendments:DBG Amendment 6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC is supported.
...
2018-Jan-31 20:19:40 OrderBookDB:DBG Advancing from 0 to 3
2018-Jan-31 20:19:40 OrderBookDB:DBG OrderBookDB::update>
2018-Jan-31 20:19:40 OrderBookDB:DBG OrderBookDB::update< 0 books found
2018-Jan-31 20:19:40 ValidatorList:DBG Loading configured trusted validator list publisher keys
2018-Jan-31 20:19:40 ValidatorList:DBG Loaded 1 keys
2018-Jan-31 20:19:40 ValidatorList:DBG Loading configured validator keys
...
2018-Jan-31 20:19:40 LedgerConsensus:NFO Entering consensus process, watching, synced=no
2018-Jan-31 20:19:40 LedgerConsensus:NFO Consensus mode change before=observing, after=observing
...
2018-Jan-31 20:19:40 Application:FTL Startup RPC:
{
"command" : "log_level",
"severity" : "warning"
}
...
2018-Jan-31 20:20:32 NetworkOPs:WRN We are not running on the consensus ledger
2018-Jan-31 20:20:32 LedgerConsensus:WRN Need consensus ledger 17F251A5AD7120BD0D3ED9EB1B45598AACA1D76EA67C7FFC3384E629C25E198B
2018-Jan-31 20:20:35 NetworkOPs:WRN We are not running on the consensus ledger
2018-Jan-31 20:20:35 LedgerConsensus:WRN Need consensus ledger 0EAEFBC6C63DE7CEA32415336C7524D50E2531781704CE86895EAF84A63477D7
...
2018-Jan-31 20:20:53 LedgerConsensus:WRN View of consensus changed during establish status=establish, mode=wrongLedger
2018-Jan-31 20:20:53 LedgerConsensus:WRN E5C6EF6AB5C1DB0EA5EF1C43C2EDC1179459FBAC5ABDF6523F488DEE276FA9E6 to 7F0E5EE15F8FC41776BA230094C364DE045C35A15073C9E057407506A9E53892
2018-Jan-31 20:20:53 LedgerConsensus:WRN {"accepted":true,"account_hash":"8EE80E7E8ADCE2AB550611752BC4EC748D9DFEBB4B4B98F05BD5F6147CF61ED5","close_flags":0,"close_time":570745240,"close_time_human":"2018-Jan-31 20:20:40","close_time_resolution":20,"closed":true,"hash":"9FA1BAF2A4F6A908B10303E6624E175CCD53D1E87E6B44D09FC28E8FCC63D3C3","ledger_hash":"9FA1BAF2A4F6A908B10303E6624E175CCD53D1E87E6B44D09FC28E8FCC63D3C3","ledger_index":"8","parent_close_time":570745234,"parent_hash":"9AF26062D241A16EDD8436EB1A9B533281D43949A7DA2E4F35A50110537BD596","seqNum":"8","totalCoins":"100000000000000000","total_coins":"100000000000000000","transaction_hash":"0000000000000000000000000000000000000000000000000000000000000000"}
```
## Explore Next Steps
* Now that you have a stock `rippled` server running, you may want to consider running it as a validating server. For information about validating servers and why you might want to run one, see the [rippled Setup Tutorial](tutorial-rippled-setup.html).
* For information about communicating with your `rippled` server using the `rippled` API, see the [`rippled` API reference](reference-rippled.html).
* As a development best practice, you may want to build a `rippled` `.deb` file. For more information, see _Ubuntu Packaging Guide_: [Packaging New Software](http://packaging.ubuntu.com/html/packaging-new-software.html).
* You may also want to install a `systemd` unit. For more information, see [systemd for Upstart Users](https://wiki.ubuntu.com/SystemdForUpstartUsers). You can use the [official `rippled` system unit file](https://github.com/ripple/rippled-package-builder/blob/staging/rpm-builder/rippled.service) or modify it to suit your needs.

37
content/tutorials/manage-the-rippled-server/tutorial-rippled-landing.md Normal file
View File

@@ -0,0 +1,37 @@
# Manage the `rippled` Server
<!--{# There may be a better way to present the info on this page - especially once we have more tutorials per platform. Also, how about the sequence -- which tasks are required/commonly performed/highest priority? Which tasks are advanced/optional/lower priority? #}-->
The tutorials in this section walk you through the ins-and-outs of maintaining a `rippled` server.
* **[Install `rippled`](x)**
Install `rippled` from a binary executable on CentOS/RedHat and Ubuntu.
* **[Build and Run `rippled` on Ubuntu](x)**
Build `rippled` from source and run it on Ubuntu.
* **[Configure and Scale `rippled`](x)**
Configure and scale your `rippled` to meet the needs of your use case, whether you need a test server or a robust production-grade server.
* **[Run `rippled` in Validator Mode](x)**
Configure `rippled` to run in validator mode. In this mode, your `rippled` server participates in the XRP Ledger consensus process.
* **[Run `rippled` in Stand-Alone Mode](x)**
Configure `rippled` to run in stand-alone mode. In this mode, your `rippled` server is not connected to the live XRP Ledger network, which is a great mode to use for testing and development.
* **[Run `rippled` in a Cluster](x)**
Run `rippled` in a cluster to maximize efficiency.
* **[Troubleshoot `rippled`](x)**
Troubleshoot your `rippled`, whether you are just trying to get it running, or if it's been up and running for a while.
* **[Configure the Peer Protocol](x)**
Configure your `rippled` to use the peer protocol to send and receive connections on the peer port.
<!--{# TODO: Not sure about this phrasing -- wondering if this should just be a part of the "Configure and Scale" rippled.cfg tutorial? #}-->

271
content/tutorials/manage-the-rippled-server/tutorial-rippled-setup.md Normal file
View File

@@ -0,0 +1,271 @@
# Operating rippled Servers
The core server of the XRP Ledger peer-to-peer network is [`rippled`](reference-rippled.html). Anyone can run their own `rippled` server that follows the network and keeps a complete copy of the XRP Ledger. You can even have your server take part in the consensus process.
This page contains instructions for:
* [Capacity Planning for `rippled`](#capacity-planning)
* [Installing `rippled`](#installing-rippled)
* [Participating in the Consensus Process](#running-a-validator)
{% include '_snippets/capacity-planning.md' %}
# Installing rippled
For development, you can [compile `rippled` from source](https://wiki.ripple.com/Rippled_build_instructions).
Production `rippled` instances can [use Ripple's binary executable](#installation-on-centosred-hat-with-yum), available from the Ripple [yum](https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified) repository.
## Minimum System Requirements
A `rippled` server should run comfortably on commodity hardware, to make it inexpensive to participate in the network. At present, we recommend the following mimimum requirements:
- Operating System:
- Production: CentOS or RedHat Enterprise Linux (latest release) or Ubuntu (16.04+) supported
- Development: Mac OS X, Windows (64-bit), or most Linux distributions
- CPU: 64-bit x86_64, 2+ cores
- Disk: Minimum 50GB SSD recommended (1000 IOPS, more is better) for the database partition
- RAM:
- Testing: 8GB+
- Production: 32 GB
Amazon EC2's `m3.large` 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.
**Tip:** For recommendations beyond the minimum requirements, see [Capacity Planning](#capacity-planning).
## Installation on CentOS/Red Hat with yum
This section assumes that you are using CentOS 7 or Red Hat Enterprise Linux 7.
1. Install the Ripple RPM repository:
$ sudo rpm -Uvh https://mirrors.ripple.com/ripple-repo-el7.rpm
2. Install the `rippled` software package:
$ sudo yum install --enablerepo=ripple-stable rippled
3. Configure the `rippled` service to start on system boot:
$ sudo systemctl enable rippled.service
4. Start the `rippled` service
$ sudo systemctl start rippled.service
## Installation on Ubuntu with alien
This section assumes that you are using Ubuntu 15.04 or later.
1. Install yum-utils and alien:
$ sudo apt-get update
$ sudo apt-get install yum-utils alien
2. Install the Ripple RPM repository:
$ sudo rpm -Uvh https://mirrors.ripple.com/ripple-repo-el7.rpm
3. Download the `rippled` software package:
$ yumdownloader --enablerepo=ripple-stable --releasever=el7 rippled
4. Verify the signature on the `rippled` software package:
$ sudo rpm --import https://mirrors.ripple.com/rpm/RPM-GPG-KEY-ripple-release && rpm -K rippled*.rpm
5. Install the `rippled` software package:
$ sudo alien -i --scripts rippled*.rpm && rm rippled*.rpm
6. Configure the `rippled` service to start on system boot:
$ sudo systemctl enable rippled.service
7. Start the `rippled` service
$ sudo systemctl start rippled.service
## Postinstall
It can take several minutes for `rippled` to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock `rippled` server that you can use for local signing and API access to the XRP Ledger.
[rippled commands](reference-rippled.html#list-of-public-commands) can be run with:
$ /opt/ripple/bin/rippled <command>
## Updating rippled
You can subscribe to the [rippled Google Group](https://groups.google.com/forum/#!forum/ripple-server) to receive notifications of new `rippled` releases.
### Automatic Update on CentOS/Red Hat
Automatic rippled updates can be enabled with a one-time Cron configuration:
1. Check that `/opt/ripple/bin/update-rippled.sh` exists. If it does not, [update manually](#manual-update-on-centosred-hat).
2. Install `crond`:
$ sudo yum install cronie
3. Open the crontab file for editing
$ sudo crontab -e
4. Add the following to the crontab file. Be sure to add a blank line at the end of the file.
RANDOM_DELAY=59
0 * * * * /opt/ripple/bin/update-rippled.sh
The script updates the installed `rippled` package within an hour of each new release.
### Manual Update on CentOS/Red Hat
Run the following commands to update to the latest release of `rippled`:
$ sudo rpm -Uvh --replacepkgs https://mirrors.ripple.com/ripple-repo-el7.rpm
$ sudo yum update --enablerepo=ripple-stable rippled
$ sudo systemctl daemon-reload
$ sudo service rippled restart
### Manual Update on Ubuntu
Run the following commands to update to the latest release of `rippled`:
$ sudo rpm -Uvh --replacepkgs https://mirrors.ripple.com/ripple-repo-el7.rpm
$ yumdownloader --enablerepo=ripple-stable --releasever=el7 rippled
$ rpm -K rippled*.rpm
$ sudo alien -i --scripts rippled*.rpm
$ sudo systemctl daemon-reload
$ sudo service rippled restart
# Running a Validator
Running a `rippled` validator that participates in the Consensus process is simple:
1. [Enable validation](#validator-setup) on your `rippled` server.
* At first, your server is an _untrusted validator_. Others can see the validations your server issues, but they disregard them in the consensus process.
2. Share the public key with the public, especially other `rippled` operators.
3. When other `rippled` operators add your public key to their list of trusted servers, you have become a _trusted validator_.
* Also see [Properties of a Good Validator](#properties-of-a-good-validator) for best practices.
## Validator Setup
The `validator-keys` tool (included in the `rippled` RPM) is the recommended means to securely generate and manage your validator keys.
1. [Install a `rippled` server.](#installing-rippled)
2. Generate a validator key pair:
$ /opt/ripple/bin/validator-keys create_keys
**Warning:** Store the generated `validator-keys.json` key file in a secure but recoverable location, such as an encrypted USB flash drive. Do not modify its contents.
3. Generate a validator token and edit your `rippled.cfg` file to add the `[validator_token]` value.
$ /opt/ripple/bin/validator-keys create_token --keyfile /path/to/your/validator-keys.json
If you had previously configured your validator without using the `validator-keys` tool, you must also delete the `[validation_seed]` from your `rippled.cfg` file. This changes your validator public key.
4. Start `rippled`:
$ sudo service rippled restart
See [the `validator-keys-tool` GitHub repository](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md) for more information about managing validator keys.
## Public-Facing Server
To protect a production validator from [DDoS](https://en.wikipedia.org/wiki/Denial-of-service_attack) attacks, you can use a stock `rippled` server as a proxy between the validator and the outside network.
1. [Set up the `rippled` validator.](#validator-setup)
2. [Set up one or more stock `rippled` servers.](#installing-rippled)
3. Configure the validator and stock `rippled` servers to be [clustered](#clustering) with each other.
4. Make the following configuration changes to your validator:
* Copy the `[ips_fixed]` list and paste it under `[ips]`. These fields should contain only the IP addresses and ports of the public-facing rippled(s). The validator connects to only these peers.
* Change `[peer_private]` to `1` to prevent its IP address from being forwarded.
5. Configure the validator host machine's firewall to only accept inbound connections from its public-facing rippled(s).
Remember to restart `rippled` for config changes to take effect.
Take care not to publish the IP address of your validator.
## Domain Verification
Network participants are unlikely to trust validators without knowing who is operating them. To address this concern, validator operators can associate their validator with a web domain that they control.
1. Find your validator public key by running the following on the validator server:
$ /opt/ripple/bin/rippled server_info -q | grep pubkey_validator
2. Sign the validator public key (from step 1) using the SSL private key used for your domain. The SSL private key file does not need to be stored on the validator server.
$ openssl dgst -sha256 -hex -sign /path/to/your/ssl.key <(echo <your-validator-public-key>)
3. Using `validator-keys` tool (included in the `rippled` RPM), sign the domain name:
$ /opt/ripple/bin/validator-keys --keyfile /path/to/your/validator-keys.json sign <your-domain-name>
4. To have the verified validator domain included on [XRP Charts](https://xrpcharts.ripple.com/#/validators), submit this [Google Form](https://docs.google.com/forms/d/e/1FAIpQLScszfq7rRLAfArSZtvitCyl-VFA9cNcdnXLFjURsdCQ3gHW7w/viewform) with your validator's information.
# Additional Configuration
`rippled` should connect to the XRP Ledger with the default configuration. However, you can change your settings by editing the `rippled.cfg` file (located at `/opt/ripple/etc/rippled.cfg` when installing `rippled` with yum). For recommendations about configuration settings, see [Capacity Planning](#capacity-planning).
See [the `rippled` GitHub repository](https://github.com/ripple/rippled/blob/release/doc/rippled-example.cfg) for a description of all configuration options.
Changes to the `[debug_logfile]` or `[database_path]` sections may require you to give the `rippled` user and group ownership to your new configured path:
$ chown -R rippled:rippled <configured path>
Restart `rippled` for any configuration changes to take effect:
$ sudo service rippled restart
## Parallel Networks
Most of the time, we describe the XRP Ledger as one collective, singular entity -- and that's mostly true. There is one production XRP Ledger peer-to-peer network, and all business that takes place on the XRP Ledger occurs within the production network.
However, sometimes you may want to do tests and experiments without interacting with the core network. That's why Ripple started the [Ripple Test Net](https://ripple.com/build/ripple-test-net/), an "alternate universe" network, which can act as a testing ground for applications and the `rippled` server itself, without impacting the business operations of everyday XRP Ledger users. The Ripple Test Net (also known as the AltNet) has a separate supply of TestNet-only XRP, which Ripple [gives away for free](https://ripple.com/build/ripple-test-net/) to parties interested in developing applications on the Test Net.
**Caution:** Ripple makes no guarantees about the stability of the test network. It has been and continues to be used to test various properties of server configuration, network topology, and network performance.
Over time, there may also be smaller, temporary test networks for specific purposes.
### Parallel Networks and Consensus
There is no `rippled` setting that defines which network it uses. Instead, it uses the consensus of validators it trusts to know which ledger to accept as the truth. When different consensus groups of `rippled` instances only trust other members of the same group, each group continues as a parallel network. Even if malicious or misbehaving computers connect to both networks, the consensus process overrides the confusion as long as the members of each network are not configured to trust members of another network in excess of their quorum settings.
## Clustering
If you are running multiple `rippled` servers in a single datacenter, you can configure those servers into a cluster to maximize efficiency. Running your `rippled` servers in a cluster provides the following benefits:
* Clustered `rippled` servers share the work of cryptography. If one server has verified the authenticity of a message, the other servers in the cluster trust it and do not re-verify.
* Clustered servers share information about peers and API clients that are misbehaving or abusing the network. This makes it harder to attack all servers of the cluster at once.
* Clustered servers always propagate transactions throughout the cluster, even if the transaction does not meet the current load-based transaction fee on some of them.
To enable clustering, change the following sections of your [config file](https://github.com/ripple/rippled/blob/d7def5509d8338b1e46c0adf309b5912e5168af0/doc/rippled-example.cfg#L297-L346) for each server:
* List the IP address and port of each other server under the `[ips_fixed]` section. The port should be the one from the other servers' `protocol = peer` setting in their `rippled.cfg`. Example:
[ips_fixed]
192.168.0.1 51235
192.168.0.2 51235
* Generate a unique seed (using the [`validation_create` command](reference-rippled.html#validation-seed)) for each of your servers, and configure it under the `[node_seed]` section. The `rippled` server uses this key to sign its messages to other servers in the peer-to-peer network.
* Add the public keys (for peer communication) of each of your other servers under the `[cluster_nodes]` section.