From 188a7a640d73aa11e029b3b9dcc46a26c10118e5 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 13 Jun 2018 15:19:24 -0700 Subject: [PATCH] Expand CLI usage ref draft --- .../rippled-api/commandline-usage.md | 138 ++++++++++++++---- 1 file changed, 106 insertions(+), 32 deletions(-) diff --git a/content/references/rippled-api/commandline-usage.md b/content/references/rippled-api/commandline-usage.md index 24cf3d1589..9e0ce17a40 100644 --- a/content/references/rippled-api/commandline-usage.md +++ b/content/references/rippled-api/commandline-usage.md @@ -6,54 +6,128 @@ The `rippled` executable usually runs as a daemon that powers the XRP Ledger, al - **Daemon Mode** - The default. Connect to the XRP Ledger to process transactions and build a ledger database. - **Stand-Alone Mode** - Use the `-a` or `--standalone` option. Like daemon mode, except it does not connect to other servers. You can use this mode to test transaction processing or other features. -- **Client Mode** - Connect to another `rippled` server as a JSON-RPC client, then exit. You can use this to look up server status and ledger data if the executable is already running in another process. -- **Version statement** - Use `--version` to have `rippled` print its version number, then exit. -- **Unit Tests** - Use `-u` or `--unittest` to run unit tests, print a summary of results, then exit. Use this to confirm that the process compiled correctly. -- **Help** - Print a usage statement, then exit. +- **Client Mode** - Specify an API method name to connect to another `rippled` server as a JSON-RPC client, then exit. You can use this to look up server status and ledger data if the executable is already running in another process. +- **Other Usage** - Each of the following commands causes the `rippled` executable to print some information, then exit: + - **Help** - Use `-h` or `--help` to print a usage statement. + - **Unit Tests** - Use `-u` or `--unittest` to run unit tests and print a summary of results. This can be helpful to confirm that you have compiled `rippled` successfully. + - **Version statement** - Use `--version` to have `rippled` print its version number, then exit. + +## Generic Options + +These options are apply to most modes: + +| Option | Short Version | Description | +|---|---|---| +| `--conf {FILE}` | | Use `{FILE}` as the configuration file instead of looking for config files in the default locations. ***TODO: list default config file paths in priority order*** | + +### Verbosity Options + +The following generic options affect the amount of information written to standard output and log files: + +| Option | Short Version | Description | +|:------------|:--------------|:-----------------------------------------------| +| `--debug` | | Print debug-level logging. ***TODO: to stdout and/or logs?*** | +| `--quiet` | `-q` | Print fewer messages to standard out. ***TODO: and logs?*** | +| `--silent` | | After logging, print less to standard output. ***TODO: comparison with -q?*** | +| `--verbose` | `-v` | Print more information (***TODO: how much?***) to logs and standard output. | -## Basic Information +## Daemon Mode Options -### Usage Statement +Daemon mode is the default mode of operation for `rippled`. In addition to the [Generic Options](#generic-options) + +| Option | Short Version | Description | +|:--------------------|:--------------|:---------------------------------------| +| `--fg` | | Run the daemon as a single process in the foreground. Otherwise, `rippled` forks a second process for the daemon while the first process runs as a monitor. | +| `--import` | | Before fully starting, import ledger data from another `rippled` server's ledger store. Requires a valid `[import_db]` stanza in the config file. | +| `--nodetoshard` | | Before fully starting, copy any complete [history shards](history-sharding.html) from the ledger store into the shard store, up to the shard store's configured maximum disk space. Uses large amounts of CPU and I/O. Caution: this command copies data (instead of moving it), so you must have enough disk space to store the data in both the shard store and the ledger store. | +| `--quorum {QUORUM}` | | Override the minimum quorum for validation by requiring a agreement of `{QUORUM}` trusted validators. By default, the quorum for validation is automatically set to a safe number of trusted validators based on how many there are. This options is intended for bootstrapping [test networks](parallel-networks.html). If some validators are not online, this option can allow progress with a lower than normal quorum. **Warning:** If you set the quorum manually, it may be too low to prevent your server from diverging from the rest of the network. Only use this option if you have a deep understanding of consensus and have a need to use a non-standard configuration. | +| `---validateShards` | | Validate an existing shard store. For more information see, [History Sharding](history-sharding.html). ***TODO: This means, what, to check it for consistency? Or to consider it valid?*** | + +## Stand-Alone Mode Options + +| Option | Short Version | Description | +|:---------------|:--------------|:--------------------------------------------| +| `--standalone` | `-a` | Run in stand-alone mode. In this mode, `rippled` does not connect to the network or perform consensus. (Otherwise, `rippled` runs in daemon mode.) | +| `--replay` | | Replay a ledger close. ***TODO: Does this belong with the initial ledger options? How does this even work?*** | + +### Initial Ledger Options + +The following options determine which ledger to load first when starting up. These options are intended for replaying historical ledgers or bootstrapping test networks. + +| Option | Short Version | Description | +|:----------------------|:--------------|:-------------------------------------| +| `--ledger {LEDGER}` | | Load the ledger version identified by `{LEDGER}` (either a ledger hash or a ledger index) as the initial ledger. ***TODO: this is more useful in stand-alone but can be used in both, I think? Maybe reconsider the organization of options...*** | +| `--ledgerfile {FILE}` | | Load the ledger version from the specified `{FILE}`. ***TODO: what sort of file should this be? where does it come from?*** | +| `--load` | | Load the initial ledger from the ledger store on disk. ***TODO: isn't this the default behavior anyway?*** | +| `--net` | | Load the initial ledger from the network. ***TODO: In what circumstances is this meaningfully different from `--load`?*** | +| `--start` | | Create a new genesis ledger to use as the initial ledger. | +| `---valid` | | Consider the initial ledger a valid network ledger. ***TODO: clarify how this is different from the default and why you might use it.*** | + +## Client Mode ```bash -rippled --help -rippled -h +rippled [OPTIONS] -- {COMMAND} {COMMAND_PARAMETERS} ``` -Display a usage statement with available options, then exit. +In client mode, the `rippled` executable acts as a client to another `rippled` service. (The service may be the same executable running in a separate process locally, or it could be a `rippled` server on another server.) -### Unit Testing +To run in client mode, provide the [commandline syntax](request-formatting.html#commandline-format) for one of the [`rippled` API](rippled-api.html) methods. + +In addition to the individual command syntax, client mode accepts the [Generic Options](#generic-options) and the following options: + +| Option | Short Version | Description | +|:------------------------|:--------------|:-----------------------------------| +| `--rpc` | | Explicitly specify that the server should run in client mode. Not required. | +| `--rpc_ip {IP_ADDRESS}` | | Connect to the `rippled` server at the specified IP Address. | +| `--rpc_port {PORT}` | | Connect to the `rippled` server on the specified port. | + +**Tip:** Some arguments accept negative numbers as values. To ensure that arguments to API commands are not interpreted as options instead, pass the `--` argument before the command name. + +Example usage (get account transaction history from the earliest available to latest available ledger versions): + +```bash +rippled -- account_tx r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 -1 -1 +``` + + +## Unit Tests ```bash rippled --unittest rippled -u ``` -Takes optional arguments ***TODO: what args why?*** +Unit testing runs tests built into the `rippled` source code to confirm that the executable performs as expected. This includes things like testing built-in data types and transaction processing routines. -## Daemon Mode +If unit testing reports a failure, that generally indicates one of the following: -| Option | Short Version | Description | -|---|---|---| -| `--conf {FILE}` | | Use `{FILE}` as the configuration file instead of looking for config files in the default locations. ***TODO: list default config file paths in priority order*** | -| `--fg` | | Run in the foreground instead of as a background process. ***TODO: does this work? rippled always runs in the foreground for me. --mDuo13*** | -| `--import` | | Import ledger data from another `rippled` server's ledger store. Requires a valid `[import_db]` stanza in the config file. | -| `--ledger {LEDGER}` | | Load the ledger version identified by `{LEDGER}` (either a ledger hash or a ledger index) as the initial ledger. ***TODO: this is more useful in stand-alone but can be used in both, I think? Maybe reconsider the organization of options...*** | -| `--ledgerfile {FILE}` | | Load the ledger version from the specified `{FILE}`. ***TODO: what sort of file should this be? where does it come from?*** | -| `--load` | | Load the initial ledger from the ledger store on disk. ***TODO: isn't this the default behavior anyway?*** | -| `--net` | | Load the initial ledger from the network. ***TODO: In what circumstances is this meaningfully different from `--load`?*** | -| `--nodetoshard` | | Before fully starting, copy any complete [history shards](history-sharding.html) from the ledger store into the shard store, up to the shard store's configured maximum disk space. Uses large amounts of CPU and I/O. Caution: this command copies data (instead of moving it), so you must have enough disk space to store the data in both the shard store and the ledger store. | -| `--quorum {QUORUM}` | (None) | Override the minimum quorum for validation by requiring a agreement of `{QUORUM}` trusted validators. ***TODO: is this even honored anymore?*** | -| `--start` | | Create a new genesis ledger to use as the initial ledger. | -| `---valid` | | Consider the initial ledger a valid network ledger. ***TODO: clarify how this is different from the default and why you might use it.*** | +- A problem occurred when compiling `rippled` and it is not functioning as intended +- The source code for `rippled` contains a bug +- A unit test has a bug or has not been updated to account for new behavior +### Specific Unit Tests -### Logging Options +```bash +rippled --unittest={TEST_OR_PACKAGE_NAME} +``` -| Option | Short Version | Description | -|---|---|---| -| `--debug` | | Print debug-level logging. ***TODO: to stdout and/or logs?*** | -| `--quiet` | `-q` | Print fewer messages to standard out. ***TODO: and logs?*** | -| `--silent` | | After logging, print less to standard output. ***TODO: comparison with -q?*** | -| `--verbose` | `-v` | Print more information (***TODO: how much?***) to logs and standard output. | +By default, `rippled` runs all unit tests except ones that are classified as "manual". You can run an individual test by specifying its name, or run a subset of tests by specifying a package name. + +The `print` unit test is a special case that prints a list of available tests: + +```bash +rippled --unittest=print +``` + +Tests are grouped into a hierarchy of packages separated by `.` characters and ending in the test case name. + +Certain unit tests are classified as "manual" because they take too long to run. These tests are marked with `|M|` in the output of the `print` unit test. Manual tests do not run by default when you run all unit tests or a package of unit tests. You can run manual tests individually by specifying the name of the test. For example: + +```bash +$ ./rippled --unittest=ripple.tx.OversizeMeta +ripple.tx.OversizeMeta +Longest suite times: + 60.9s ripple.tx.OversizeMeta +60.9s, 1 suite, 1 case, 9016 tests total, 0 failures +```