Server modes: rewrite to add reporting mode

content/concepts/the-rippled-server/peer-protocol.md

@@ -60,7 +60,7 @@ Normally, a `rippled` server attempts to maintain a healthy number of peers, and
 In the following cases, a `rippled` server does not connect to untrusted peers:
 
 - If the server is configured as a [private peer](#private-peers), it connects _only_ to its fixed peers.
-- If the server is running in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode) it does not connect to _any_ peers.
+- If the server is running in [stand-alone mode][] it does not connect to _any_ peers.
 
 
 ## Private Peers

content/concepts/the-rippled-server/rippled-server-modes.md

@@ -2,32 +2,43 @@
 
 The `rippled` server software can run in several modes depending on its configuration, including:
 
-* Stock server - follows the network with a local copy of the ledger.
-* Validating server, or _validator_ for short - participates in consensus (and does everything a stock server does, too).
-* `rippled` server in stand-alone mode - for testing. Does not communicate to other `rippled` servers.
+- [**Network Mode**](#network-mode) - This is the main mode of the server: it follows the peer-to-peer network, processes transactions, and maintains some amount of [ledger history](ledger-history.html). This mode can be configured to do any or all of the following roles:
+    - [**Validator**](#validators) - Helps secure the network by participating in consensus
+    - [**API Server**](#api-servers) - Provides [API access](get-started-with-the-rippled-api.html) to read data from the shared ledger, submit transactions, and watch activity in the ledger. Optionally, this can be a [**Full History Server**](#full-history-servers), which keeps a complete record of transaction and ledger history.
+    - [**Hub Server**](#public-hubs) - Relays messages between many other members of the peer-to-peer network.
+- [**Reporting mode**](#reporting-mode) - A specialized mode for serving API requests from a relational database. Since it does not participate in the peer-to-peer network, it requires a connection to a Network Mode server. [New in: rippled 1.7.0][]
+- [**Stand-alone mode**](#stand-alone-mode) - An offline mode for testing. Does not connect to the peer-to-peer network or use consensus.
 
 You can also run the `rippled` executable as a client application for accessing [`rippled` APIs](rippled-api.html) locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)
 
-For information on the commands to run rippled in each of these modes, see the [Commandline Reference](commandline-usage.html).
+For information on the commands to run `rippled` in each of these modes, see the [Commandline Reference](commandline-usage.html).
 
 
-## Reasons to Run a Stock Server
+## Network Mode
 
-There are lots of reasons you might want to run your own `rippled` server, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. Of course, you must practice good network security to protect your server from malicious hackers.
+Network mode is the main and default mode of the `rippled` server, and it can handle almost anything you might want your server to do. These servers form a peer-to-peer network that processes transactions and maintains the shared state of the XRP Ledger. If you want to submit transactions, read ledger data, or otherwise participate in the network, your requests must go through a network mode server at some point.
 
-You need to trust the `rippled` you use. If you connect to a malicious server, there are many ways that it can take advantage of you or cause you to lose money. For example:
+Network mode servers can be further configured to provide additional functionality. A server running in network mode with a minimally-modified config file is also called a _stock server_. Other configurations include:
 
-* A malicious server could report that you were paid when no such payment was made.
-* It could selectively show or hide payment paths and currency exchange offers to guarantee its own profit while not providing you the best deal.
-* If you sent it your address's secret key, it could make arbitrary transactions on your behalf, and even transfer or destroy all the money your address holds.
+- [Validator](#validators)
+- [API Server](#api-servers)
+- [Public Hubs](#public-hubs)
 
-Additionally, running your own server gives you admin control over it, which allows you to run important admin-only and load-intensive commands. If you use a shared server, you have to worry about other users of the same server competing with you for the server's computing power. Many of the commands in the WebSocket API can put a lot of strain on the server, so `rippled` has the option to scale back its responses when it needs to. If you share a server with others, you may not always get the best results possible.
+Network mode servers connect to [Mainnet](parallel-networks.html) by default.
+
+
+### API Servers
+
+All network mode servers provide [APIs](rippled-api.html) for purposes like submitting transactions, checking balances and settings, and administering the server. If you query the XRP Ledger for data or submit transactions for business use, it can be useful to [run your own server](the-rippled-server.html#reasons-to-run-your-own-server).
+
+#### Full History Servers
+
+Unlike some other blockchains, the XRP Ledger does not require servers to have a complete transaction history to know the current state and process new transactions. As a server operator, you decide how much [ledger history](ledger-history.html) to store at a time. However, a network mode server can only answer API requests using the ledger history it has locally available. For example, if you keep six months of history, your server can't describe the outcome of a transaction from a year ago. API servers with [full history](ledger-history.html#full-history) can report all transactions and balances since the inception of the XRP Ledger.
 
-Finally, if you run a validating server, you can use a stock server as a proxy to the public network while keeping your validating server on a private network only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server.
 
 ### Public Hubs
 
-A public hub is a stock server with lots of [peer protocol connections](peer-protocol.html) to other servers. You can help the XRP Ledger network maintain efficient connectivity by running a stock server as a public hub. Successful public hubs embody the following traits:
+A hub server is a network mode server with lots of [peer protocol connections](peer-protocol.html) to other servers. Hub servers, especially _public hubs_ that allow connections from the open internet, help the XRP Ledger network maintain efficient connectivity. Successful public hubs embody the following traits:
 
 - Good bandwidth.
 
@@ -35,28 +46,39 @@ A public hub is a stock server with lots of [peer protocol connections](peer-pro
 
 - Ability to relay messages reliably.
 
+To configure your server as a hub, increase the maximum number of peers allowed and make sure you've [forwarded the appropriate ports](forward-ports-for-peering.html) through your firewall and NAT (network address translation) router as appropriate.
 
 
-## Reasons to Run a Validator
+### Validators
 
-The robustness of the XRP Ledger depends on an interconnected web of validators who each trust a few other validators _not to collude_. The more operators with different interests there are who run validators, the more certain each member of the network can be that it continues to run impartially. If you or your organization relies on the XRP Ledger, it is in your interest to contribute to the consensus process.
+The robustness of the XRP Ledger depends on an interconnected web of _validators_ who each trust some other validators _not to collude_. In addition to processing each transaction and calculating ledger state just like other network mode servers, validators participate actively in the [consensus protocol](consensus.html). If you or your organization relies on the XRP Ledger, it is in your interest to contribute to the consensus process by running _one_ server as a validator.
 
-Not all `rippled` servers need to be validators: trusting more servers from the same operator does not offer better protection against collusion. An organization might run validators in multiple regions for redundancy in case of natural disasters and other emergencies.
+Validation uses only a small amount of computing resources, but there is not much benefit to a single entity or organization running multiple validators because doing so does not provide more protections against collusion. Each validator identifies itself with a unique cryptographic key pair that must be carefully managed; multiple validators must not share a key pair. For these reasons, validation is disabled by default.
 
-If your organization runs a validating server, you may also run one or more stock servers, to balance the computing load of API access, or as a proxy between your validation server and the outside network.
+You can safely enable validation on a server that is also used for other purposes; this type of configuration is called an _all-purpose server_. Alternatively, you can run a _dedicated validator_ that does not perform other tasks, possibly in a [cluster](clustering.html) with other network mode `rippled` servers.
 
 For more information about running a validator, see [Run `rippled` as a Validator](run-rippled-as-a-validator.html).
 
 
+## Reporting Mode
+[New in: rippled 1.7.0][]
 
-## Reasons to Run a `rippled` Server in Stand-Alone Mode
+Reporting mode is specialized mode for serving API requests more efficiently. In this mode, the server connects to a separate Network Mode `rippled` server to get the latest validated ledger data, then loads that data into a relational database ([PostgreSQL](https://www.postgresql.org/)). The reporting mode server does not directly participate in the peer-to-peer network, though it can forward requests such as transaction submission to the network mode server it uses.
 
-You can run `rippled` in stand-alone mode without a consensus of trusted servers. In stand-alone mode, `rippled` does not communicate with any other servers in the XRP Ledger peer-to-peer network, but you can do most of the same actions on your local server only. Stand-alone provides a method for testing `rippled` behavior without being tied to the live network. For example, you can [test the effects of Amendments](amendments.html#testing-amendments) before those Amendments have gone into effect across the decentralized network.
+Multiple reporting mode servers can share access to a PostgreSQL database and [Apache Cassandra](https://cassandra.apache.org/) cluster to serve a large amount of history without each server needing a redundant copy of all the data. Reporting mode servers provide this data through the same [`rippled` APIs](rippled-api.html) with some slight changes to accommodate for the differences in how they store the underlying data.
 
-When you run `rippled` in stand-alone mode, you have to tell it what ledger version to start from:
+Most notably, reporting mode servers do not report pending, non-validated ledger data or transactions. This limitation is relevant to certain use cases that rely on rapid access to in-flux data, such as performing arbitrage in the [decentralized exchange](decentralized-exchange.html).
 
-* Create a [new genesis ledger](start-a-new-genesis-ledger-in-stand-alone-mode.html) from scratch.
-* [Load an existing ledger version](load-a-saved-ledger-in-stand-alone-mode.html) from disk.
+<!-- TODO: link setup steps for Reporting Mode when those are ready -->
+
+
+## Stand-Alone Mode
+
+In stand-alone mode, the server operates without attempting to connect to the peer-to-peer network or follow the consensus process. The server still provides API access as normal and uses the same transaction processing engine, so you can test `rippled` behavior without being tied to the live network. For example, you can:
+
+- [Test the effects of Amendments](amendments.html#testing-amendments) before those Amendments have gone into effect across the decentralized network.
+- [Create a new genesis ledger](start-a-new-genesis-ledger-in-stand-alone-mode.html) from scratch.
+- [Load an existing ledger version](load-a-saved-ledger-in-stand-alone-mode.html) from disk, then replay specific transactions to re-create their outcomes or test other possibilities.
 
 **Caution:** In stand-alone mode, you must [manually advance the ledger](advance-the-ledger-in-stand-alone-mode.html).
 

content/concepts/the-rippled-server/the-rippled-server.md

@@ -0,0 +1,31 @@
+---
+html: the-rippled-server.html
+funnel: Build
+doc_type: Concepts
+category: The rippled Server
+template: template-landing-children.html
+blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server.
+---
+# The `rippled` Server
+
+`rippled` is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the `rippled` server.
+
+## Reasons to Run Your Own Server
+
+For lighter use cases and individual servers, you can often rely on free [public servers](https://xrpl.org/get-started-with-the-rippled-api.html#public-servers). However, the more serious your use of the XRP Ledger becomes, the more important it becomes to have your own infrastructure.
+
+There are lots of reasons you might want to run your own `rippled` server, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. Of course, you must practice good network security to protect your server from malicious hackers.
+
+You need to trust the `rippled` you use. If you connect to a malicious server, there are many ways that it can take advantage of you or cause you to lose money. For example:
+
+* A malicious server could report that you were paid when no such payment was made.
+* It could selectively show or hide payment paths and currency exchange offers to guarantee its own profit while not providing you the best deal.
+* If you sent it your address's secret key, it could make arbitrary transactions on your behalf, and even transfer or destroy all the money your address holds.
+
+Additionally, running your own server gives you admin control over it, which allows you to run important admin-only and load-intensive commands. If you use a shared server, you have to worry about other users of the same server competing with you for the server's computing power. Many of the commands in the WebSocket API can put a lot of strain on the server, so `rippled` has the option to scale back its responses when it needs to. If you share a server with others, you may not always get the best results possible.
+
+Finally, if you run a validating server, you can use a stock server as a proxy to the public network while keeping your validating server on a private network only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server.
+
+## rippled Server Features
+
+<!-- provided by the auto-generated table of children -->