From 0b8e73206f1849a29dd16b8244c76ecd5ca17e57 Mon Sep 17 00:00:00 2001 From: Marek Date: Tue, 23 May 2023 15:18:57 +0200 Subject: [PATCH] change(docs): Update User Docs (#6733) * Move releases info to `Building Zebra` * Move Zebra use-cases to `Using Zebra` * Point the links in Zebra use-cases to docs * Move the contents of `Release Candidates` * Refactor the `System Requirements` link * Update the syncing times * Update notes on performance * Move data usage to `System Requirements` * Remove "building Zebra" from lightwalletd docs I think we can assume people will follow the previous parts of the docs for how to build Zebra. * Move lightwalletd details from `README.md` to docs `README.md` already mentions lightwalletd from the `Using Zebra` section, and refers the reader to the docs where the details were moved and refactored. * Mention `lightwalletd` and mining in Running Zebra * Move Troubleshooting to its own file * Move "Improving Performance" to its own file * Move instructions for ARM to "Installing Zebra" * Reword the Testnet sync duration description Co-authored-by: Pili Guerra * Move "Improving Performance" to "Troubleshooting" * Remove the Testnet unreliability caveat --------- Co-authored-by: Pili Guerra --- README.md | 57 +++++++-------------- book/src/SUMMARY.md | 1 + book/src/user/install.md | 6 +++ book/src/user/lightwalletd.md | 45 ++++++++++------- book/src/user/requirements.md | 54 +++++--------------- book/src/user/run.md | 83 +++--------------------------- book/src/user/troubleshooting.md | 87 ++++++++++++++++++++++++++++++++ 7 files changed, 157 insertions(+), 176 deletions(-) create mode 100644 book/src/user/troubleshooting.md diff --git a/README.md b/README.md index 362f19c8a..9090ccb5c 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,6 @@ - [Docker](#docker) - [Building Zebra](#building-zebra) - [Optional Features](#optional-features) - - [Configuring JSON-RPC for lightwalletd](#configuring-json-rpc-for-lightwalletd) - [Network Ports](#network-ports) - [Known Issues](#known-issues) - [Future Work](#future-work) @@ -46,30 +45,26 @@ You would want to run Zebra if you want to contribute to the Zcash network: the more nodes are run, the more reliable the network will be in terms of speed and resistance to denial of service attacks, for example. -Zebra aims to be [faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages) -than other Zcash implementations. - -## Release Candidates - -Every few weeks, we release a [new Zebra version](https://github.com/ZcashFoundation/zebra/releases). - -Zebra's network stack is interoperable with `zcashd`, -and Zebra implements all the features required to reach Zcash network consensus. -Currently, Zebra validates all of the Zcash consensus rules for the NU5 network upgrade. - Zebra validates blocks and transactions, but needs extra software to generate them: -- to generate transactions, [configure `zebrad`'s JSON-RPC port](https://github.com/ZcashFoundation/zebra#configuring-json-rpc-for-lightwalletd), - and use a light wallet with `lightwalletd` and Zebra. -- to generate blocks, [compile `zebrad` with the `getblocktemplate-rpcs` feature](https://doc.zebra.zfnd.org/zebrad/#json-rpc), configure the JSON-RPC port, - and use a mining pool or miner with Zebra's mining JSON-RPCs. - Mining support is currently incomplete, experimental, and off by default. +- To generate transactions, [run Zebra with + `lightwalletd`](https://zebra.zfnd.org/user/lightwalletd.html). +- To generate blocks, [enable mining + support](https://zebra.zfnd.org/user/mining.html), and use a mining pool or + miner with Zebra's mining JSON-RPCs. Mining support is currently incomplete, + experimental, and off by default. + +Zebra's network stack is interoperable with `zcashd`, and Zebra implements all +the features required to reach Zcash network consensus, including the validation +of all the consensus rules for the NU5 network upgrade. +[Here](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages) are some +benefits of Zebra. ## Getting Started You can run Zebra using our Docker image or you can build it manually. Please -see the [requirements section of the Zebra Book](https://zebra.zfnd.org/user/requirements.html) for system -requirements. +see the [System Requirements](https://zebra.zfnd.org/user/requirements.html) +section in the Zebra book for system requirements. ### Docker @@ -91,6 +86,9 @@ Zebra is tested with the latest `stable` Rust version. Earlier versions are not supported or tested. Note that Zebra's code currently uses features introduced in Rust 1.68, or any later stable release. +Every few weeks, we release a [new Zebra +version](https://github.com/ZcashFoundation/zebra/releases). + Below are quick summaries for installing the dependencies on your machine.

General instructions for installing dependencies

 @@ -152,27 +150,6 @@ documentation](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-feature-flags) Some debugging and monitoring features are disabled in release builds to increase performance. -### Configuring JSON-RPC for lightwalletd - -To use `zebrad` as a `lightwalletd` backend, give it this `~/.config/zebrad.toml`: - -```toml -[rpc] -# listen for RPC queries on localhost -listen_addr = '127.0.0.1:8232' - -# automatically use multiple CPU threads -parallel_cpu_threads = 0 -``` - -**WARNING:** This config allows multiple Zebra instances to share the same RPC port. -See the [RPC config documentation](https://doc.zebra.zfnd.org/zebra_rpc/config/struct.Config.html) for details. - -`lightwalletd` also requires a `zcash.conf` file. - -It is recommended to use [adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd) because that is used in testing. -Other `lightwalletd` forks have limited support, see the [detailed `lightwalletd` instructions](https://github.com/ZcashFoundation/zebra/blob/main/book/src/user/lightwalletd.md#sync-lightwalletd). - ### Network Ports Zebra uses the following inbound and outbound TCP ports: diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index a98c39c5e..6840019a2 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -16,6 +16,7 @@ - [Mining](user/mining.md) - [Testnet Mining with s-nomp](user/mining-testnet-s-nomp.md) - [Kibana blockchain explorer](user/elasticsearch.md) + - [Troubleshooting](user/troubleshooting.md) - [Developer Documentation](dev.md) - [Contribution Guide](CONTRIBUTING.md) - [Design Overview](dev/overview.md) diff --git a/book/src/user/install.md b/book/src/user/install.md index fad05d693..6f0394839 100644 --- a/book/src/user/install.md +++ b/book/src/user/install.md @@ -2,6 +2,12 @@ Follow the [Docker or compilation instructions in the README](https://github.com/ZcashFoundation/zebra#getting-started). +#### ARM + +If you're using an ARM machine, [install the Rust compiler for +ARM](https://rust-lang.github.io/rustup/installation/other.html). If you build +using the x86_64 tools, Zebra might run really slowly. + #### Build Troubleshooting If you're having trouble with: diff --git a/book/src/user/lightwalletd.md b/book/src/user/lightwalletd.md index aade5583f..cc9c99100 100644 --- a/book/src/user/lightwalletd.md +++ b/book/src/user/lightwalletd.md @@ -1,12 +1,15 @@ # Running lightwalletd with zebra -Zebra's RPC methods can support a lightwalletd service backed by zebrad. +Zebra's RPC methods can support a lightwalletd service backed by zebrad. We +recommend using +[adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd) because we +use it in testing. Other `lightwalletd` forks have limited support, see the +[Sync lightwalletd](#sync-lightwalletd) section for more info. Contents: -- [Download and build Zebra](#download-and-build-zebra) - [Configure zebra for lightwalletd](#configure-zebra-for-lightwalletd) - - [RPC section](#rpc-section) + - [JSON-RPC](#json-rpc) - [Sync Zebra](#sync-zebra) - [Download and build lightwalletd](#download-and-build-lightwalletd) - [Sync lightwalletd](#sync-lightwalletd) @@ -15,16 +18,8 @@ Contents: - [Download and build the cli-wallet](#download-and-build-the-cli-wallet) - [Run the wallet](#run-the-wallet) -## Download and build Zebra -[#download-and-build-zebra]: #download-and-build-zebra - -```console -cargo install --locked --git https://github.com/ZcashFoundation/zebra zebrad -``` - -Zebra binary will be at ` ~/.cargo/bin/zebrad`. - ## Configure zebra for lightwalletd + [#configure-zebra-for-lightwalletd]: #configure-zebra-for-lightwalletd We need a zebra configuration file. First, we create a file with the default settings: @@ -37,17 +32,33 @@ The above command places the generated `zebrad.toml` config file in the default Tweak the following option in order to prepare for lightwalletd setup. -### RPC section -[#rpc-section]: #rpc-section +### JSON-RPC -This change is required for zebra to behave as an RPC endpoint. The standard port for RPC endpoint is `8232`. +[#rpc-section]: #json-rpc -``` +We need to configure Zebra to behave as an RPC endpoint. The standard RPC port +for Zebra is: + +- `8232` for Mainnet, and +- `18323` for Testnet. + +For example, to use Zebra as a `lightwalletd` backend on Mainnet, give it this +`~/.config/zebrad.toml`: + +```toml [rpc] -listen_addr = "127.0.0.1:8232" +# listen for RPC queries on localhost +listen_addr = '127.0.0.1:8232' + +# automatically use multiple CPU threads +parallel_cpu_threads = 0 ``` +**WARNING:** This config allows multiple Zebra instances to share the same RPC port. +See the [RPC config documentation](https://doc.zebra.zfnd.org/zebra_rpc/config/struct.Config.html) for details. + ## Sync Zebra + [#sync-zebra]: #sync-zebra With the configuration in place you can start synchronizing Zebra with the Zcash blockchain. This may take a while depending on your hardware. diff --git a/book/src/user/requirements.md b/book/src/user/requirements.md index 70ee6b00c..d12b16ce3 100644 --- a/book/src/user/requirements.md +++ b/book/src/user/requirements.md @@ -30,13 +30,20 @@ Zebra uses the following inbound and outbound TCP ports: - 8233 on Mainnet - 18233 on Testnet -Outbound connections are required to sync, inbound connections are optional. -Zebra also needs access to the Zcash DNS seeders, via the OS DNS resolver -(usually port 53). +If you configure Zebra with a specific +[`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr), +it will advertise this address to other nodes for inbound connections. Outbound +connections are required to sync, inbound connections are optional. Zebra also +needs access to the Zcash DNS seeders, via the OS DNS resolver (usually port +53). -The typical Mainnet network usage is: +Zebra makes outbound connections to peers on any port. But `zcashd` prefers +peers on the default ports, so that it can't be used for DDoS attacks on other +networks. -- Initial sync: 300 GB download, as already noted, we expect the initial +### Typical Mainnet Network Usage + +- Initial sync: 300 GB download. As already noted, we expect the initial download to grow. - Ongoing updates: 10 MB - 10 GB upload and download per day, depending on user-created transaction size and peer requests. @@ -51,40 +58,3 @@ ticket.](https://github.com/ZcashFoundation/zebra/issues/new/choose) ## Sentry Production Monitoring Compile Zebra with `--features sentry` to monitor it using Sentry in production. - -# Troubleshooting - -We continuously test that our builds and tests pass on the _latest_ [GitHub -Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) -for: - -- macOS, -- Ubuntu, -- Docker: - - Debian Bullseye. - -## Memory Issues - -- If Zebra's build runs out of RAM, try setting `export CARGO_BUILD_JOBS=2`. -- If Zebra's tests timeout or run out of RAM, try running `cargo test -- --test-threads=2`. Note that `cargo` uses all processor cores on your machine - by default. - -## Network Issues - -- Some of Zebra's tests download Zcash blocks, so they might be unreliable - depending on your network connection. You can set `ZEBRA_SKIP_NETWORK_TESTS=1` - to skip the network tests. -- Zebra may be unreliable on Testnet, and under less-than-perfect network - conditions. See our [future - work](https://github.com/ZcashFoundation/zebra#future-work) for details. - -## Issues with Tests on macOS - -Some of Zebra's tests deliberately cause errors that make Zebra panic. macOS -records these panics as crash reports. If you are seeing "Crash Reporter" -dialogs during Zebra tests, you can disable them using this Terminal.app -command: - -```sh -defaults write com.apple.CrashReporter DialogType none -``` diff --git a/book/src/user/run.md b/book/src/user/run.md index 2ee478996..8d383db60 100644 --- a/book/src/user/run.md +++ b/book/src/user/run.md @@ -9,7 +9,12 @@ The configuration format is the TOML encoding of the internal config structure, and documentation for all of the config options can be found [here](https://doc.zebra.zfnd.org/zebrad/config/struct.ZebradConfig.html). -* `zebrad start` starts a full node. +- `zebrad start` starts a full node. + +You can run Zebra as a: + +- [`lightwalletd` backend](https://zebra.zfnd.org/user/lightwalletd.html), and +- experimental [mining backend](https://zebra.zfnd.org/user/mining.html). ## Supported versions @@ -21,79 +26,3 @@ Always run a supported version of Zebra, and upgrade it regularly, so it doesn't - `1`: Application exited unsuccessfully - `2`: Application crashed - `zebrad` may also return platform-dependent codes. - -## Network Ports and Data Usage - -`zebrad`'s default ports and network usage are -[documented in the README.](https://github.com/ZcashFoundation/zebra#network-ports-and-data-usage) - -If Zebra is configured with a specific [`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr), -it will advertise this address to other nodes for inbound connections. - -Zebra makes outbound connections to peers on any port. -But `zcashd` prefers peers on the default ports, -so that it can't be used for DDoS attacks on other networks. - -The major constraint we've found on `zebrad` performance is the network weather, -especially the ability to make good connections to other Zcash network peers. - -Zebra needs some peers which have a round-trip latency of 2 seconds or less. -If this is a problem for you, please let us know! - -## Improving Performance - -Zebra usually syncs in around a day, depending on your network connection, and the overall Zcash network load. - -If you're having trouble syncing, try the following config changes: - -### Release Build - -Make sure you're using a release build on your native architecture. - -If you're using an ARM machine, -[install the Rust compiler for ARM](https://rust-lang.github.io/rustup/installation/other.html). -If you build using the x86_64 tools, Zebra might run really slowly. - -Run a release build using the -[`cargo install` command from the README.](https://github.com/ZcashFoundation/zebra#build-and-run-instructions) - -### Syncer Lookahead Limit - -If your connection is slow, try -[downloading fewer blocks at a time](https://doc.zebra.zfnd.org/zebrad/config/struct.SyncSection.html#structfield.lookahead_limit): - -```toml -[sync] -lookahead_limit = 1000 -max_concurrent_block_requests = 25 -``` - -### Peer Set Size - -If your connection is slow, try [connecting to fewer peers](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.peerset_initial_target_size): - -```toml -[network] -peerset_initial_target_size = 25 -``` - -### Turn off debug logging - -Zebra logs at info level by default. - -If Zebra is slow, make sure it is logging at info level: - -```toml -[tracing] -filter = 'info' -``` - -Or restrict debug logging to a specific Zebra component: - -```toml -[tracing] -filter = 'info,zebra_network=debug' -``` - -If you keep on seeing multiple info logs per second, please -[open a bug.](https://github.com/ZcashFoundation/zebra/issues/new/choose) diff --git a/book/src/user/troubleshooting.md b/book/src/user/troubleshooting.md new file mode 100644 index 000000000..b1a89d435 --- /dev/null +++ b/book/src/user/troubleshooting.md @@ -0,0 +1,87 @@ +# Troubleshooting + +We continuously test that our builds and tests pass on the _latest_ [GitHub +Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) +for: + +- macOS, +- Ubuntu, +- Docker: + - Debian Bullseye. + +## Memory Issues + +- If Zebra's build runs out of RAM, try setting `export CARGO_BUILD_JOBS=2`. +- If Zebra's tests timeout or run out of RAM, try running `cargo test -- --test-threads=2`. Note that `cargo` uses all processor cores on your machine + by default. + +## Network Issues + +Some of Zebra's tests download Zcash blocks, so they might be unreliable +depending on your network connection. You can set `ZEBRA_SKIP_NETWORK_TESTS=1` +to skip the network tests. + +## Issues with Tests on macOS + +Some of Zebra's tests deliberately cause errors that make Zebra panic. macOS +records these panics as crash reports. If you are seeing "Crash Reporter" +dialogs during Zebra tests, you can disable them using this Terminal.app +command: + +```sh +defaults write com.apple.CrashReporter DialogType none +``` + +## Improving Performance + +Zebra usually syncs in around three days on Mainnet and half a day on +Testnet. The sync speed depends on your network connection and the overall Zcash +network load. The major constraint we've found on `zebrad` performance is the +network weather, especially the ability to make good connections to other Zcash +network peers. If you're having trouble syncing, try the following config +changes. + +### Release Build + +Make sure you're using a release build on your native architecture. + +### Syncer Lookahead Limit + +If your connection is slow, try +[downloading fewer blocks at a time](https://doc.zebra.zfnd.org/zebrad/config/struct.SyncSection.html#structfield.lookahead_limit): + +```toml +[sync] +lookahead_limit = 1000 +max_concurrent_block_requests = 25 +``` + +### Peer Set Size + +If your connection is slow, try [connecting to fewer peers](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.peerset_initial_target_size): + +```toml +[network] +peerset_initial_target_size = 25 +``` + +### Turn off debug logging + +Zebra logs at info level by default. + +If Zebra is slow, make sure it is logging at info level: + +```toml +[tracing] +filter = 'info' +``` + +Or restrict debug logging to a specific Zebra component: + +```toml +[tracing] +filter = 'info,zebra_network=debug' +``` + +If you keep on seeing multiple info logs per second, please +[open a bug.](https://github.com/ZcashFoundation/zebra/issues/new/choose)