mirror of https://github.com/waku-org/nwaku.git
docs: add operator guide docs (#963)
This commit is contained in:
Hanno Cornelius
GitHub
parent
984f3179a7
commit
35045d9d97
|
|
@ -0,0 +1,35 @@
|
||||||
|
# The nwaku guide for operators
|
||||||
|
|
||||||
|
*If you're eager to get started, check out our [quickstart guide](./quickstart.md).*
|
||||||
|
|
||||||
|
Nwaku is a client implementation in Nim of the [Waku v2 family of protocols](https://rfc.vac.dev/spec/10/) for peer-to-peer communication.
|
||||||
|
The protocols are designed to be secure, privacy-preserving, censorship-resistant and able to run in resource restricted environments.
|
||||||
|
Moreover, we've taken a modular approach so that node operators can choose which protocols they want to support
|
||||||
|
based on their own motivations and availability of resources.
|
||||||
|
We call this concept ["adaptive nodes"](https://rfc.vac.dev/spec/30/),
|
||||||
|
implying that a Waku v2 network can consist of heterogeneous nodes contributing at different levels to the network.
|
||||||
|
|
||||||
|
Nwaku (formerly `nim-waku`) aims to be a lightweight and robust Waku v2 client.
|
||||||
|
It serves as the reference implementation for researchers,
|
||||||
|
who extend the client in parallel to spec development.
|
||||||
|
As such, it is first in line to support innovative and new Waku v2 protocols,
|
||||||
|
but configurable enough to serve the adaptive needs of a various operators.
|
||||||
|
We are also developing a set of operator-focused tools to monitor and maintain a running nwaku node.
|
||||||
|
|
||||||
|
This guide provides step-by-step tutorials covering how to build and configure your own nwaku node,
|
||||||
|
connect to an existing Waku v2 network
|
||||||
|
and use existing tools for monitoring and maintaining a running node.
|
||||||
|
|
||||||
|
## Helpful resources
|
||||||
|
|
||||||
|
<!-- TODO -->
|
||||||
|
|
||||||
|
## Getting in touch or reporting an issue
|
||||||
|
|
||||||
|
For an inquiry, or if you would like to propose new features, feel free to [open a general issue](https://github.com/status-im/nwaku/issues/new/).
|
||||||
|
|
||||||
|
For bug reports, please [tag your issue with the `bug` label](https://github.com/status-im/nwaku/issues/new/).
|
||||||
|
|
||||||
|
If you believe the reported issue requires critical attention, please [use the `critical` label](https://github.com/status-im/nwaku/issues/new?labels=critical,bug) to assist with triaging.
|
||||||
|
|
||||||
|
To get help, or participate in the conversation, join the [Vac Discord](https://discord.gg/KNj3ctuZvZ) server.
|
||||||
|
|
@ -0,0 +1,59 @@
|
||||||
|
# Build nwaku
|
||||||
|
|
||||||
|
Nwaku can be built on Linux and macOS.
|
||||||
|
Windows support is experimental.
|
||||||
|
|
||||||
|
## Installing dependencies
|
||||||
|
|
||||||
|
Cloning and building nwaku requires the usual developer tools,
|
||||||
|
such as a C compiler, Make, Bash and Git.
|
||||||
|
|
||||||
|
### Linux
|
||||||
|
|
||||||
|
On common Linux distributions the dependencies can be installed with
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Debian and Ubuntu
|
||||||
|
sudo apt-get install build-essential git
|
||||||
|
|
||||||
|
# Fedora
|
||||||
|
dnf install @development-tools
|
||||||
|
|
||||||
|
# Archlinux, using an AUR manager
|
||||||
|
yourAURmanager -S base-devel
|
||||||
|
```
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
|
||||||
|
Assuming you use [Homebrew](https://brew.sh/) to manage packages
|
||||||
|
|
||||||
|
```sh
|
||||||
|
brew install cmake
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building nwaku
|
||||||
|
|
||||||
|
### 1. Clone the nwaku repository
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git clone https://github.com/status-im/nwaku
|
||||||
|
cd nwaku
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Make the `wakunode2` target
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# The first `make` invocation will update all Git submodules.
|
||||||
|
# You'll run `make update` after each `git pull`, in the future, to keep those submodules up to date.
|
||||||
|
make wakunode2
|
||||||
|
```
|
||||||
|
|
||||||
|
This will create a `wakunode2` binary in the `./build/` directory.
|
||||||
|
|
||||||
|
> **Note:** Building `wakunode2` requires 2GB of RAM.
|
||||||
|
The build will fail on systems not fulfilling this requirement.
|
||||||
|
|
||||||
|
> Setting up a `wakunode2` on the smallest [digital ocean](https://docs.digitalocean.com/products/droplets/how-to/) droplet, you can either
|
||||||
|
> * compile on a stronger droplet featuring the same CPU architecture and downgrade after compiling, or
|
||||||
|
> * activate swap on the smallest droplet, or
|
||||||
|
> * use Docker.
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
# Use DNS discovery to connect to existing nodes
|
||||||
|
|
||||||
|
> **Note:** This page describes using DNS to discover other peers
|
||||||
|
and is unrelated to the [domain name configuration](./configure-domain.md) for your nwaku node.
|
||||||
|
|
||||||
|
A node can discover other nodes to connect to using [DNS-based discovery](../../tutorial/dns-disc.md).
|
||||||
|
The following command line options are available:
|
||||||
|
|
||||||
|
```
|
||||||
|
--dns-discovery Enable DNS Discovery
|
||||||
|
--dns-discovery-url URL for DNS node list in format 'enrtree://<key>@<fqdn>'
|
||||||
|
--dns-discovery-name-server DNS name server IPs to query. Argument may be repeated.
|
||||||
|
```
|
||||||
|
|
||||||
|
- `--dns-discovery` is used to enable DNS discovery on the node.
|
||||||
|
Waku DNS discovery is disabled by default.
|
||||||
|
- `--dns-discovery-url` is mandatory if DNS discovery is enabled.
|
||||||
|
It contains the URL for the node list.
|
||||||
|
The URL must be in the format `enrtree://<key>@<fqdn>` where `<fqdn>` is the fully qualified domain name and `<key>` is the base32 encoding of the compressed 32-byte public key that signed the list at that location.
|
||||||
|
- `--dns-discovery-name-server` is optional and contains the IP(s) of the DNS name servers to query.
|
||||||
|
If left unspecified, the Cloudflare servers `1.1.1.1` and `1.0.0.1` will be used by default.
|
||||||
|
|
||||||
|
A node will attempt connection to all discovered nodes.
|
||||||
|
|
||||||
|
This can be used, for example, to connect to one of the existing fleets.
|
||||||
|
Current URLs for the published fleet lists:
|
||||||
|
- production fleet: `enrtree://ANTL4SLG2COUILKAPE7EF2BYNL2SHSHVCHLRD5J7ZJLN5R3PRJD2Y@prod.waku.nodes.status.im`
|
||||||
|
- test fleet: `enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.waku.nodes.status.im`
|
||||||
|
|
||||||
|
See the [separate tutorial](../../tutorial/dns-disc.md) for a complete guide to DNS discovery.
|
||||||
|
|
@ -0,0 +1,16 @@
|
||||||
|
# Configure a domain name
|
||||||
|
|
||||||
|
> **Note:** This page describes configuring a domain name that resolves to your node's IP
|
||||||
|
and is unrelated to [DNS discovery](./configure-dns-disc.md),
|
||||||
|
by which a node may discover the listening addresses of other peers using DNS.
|
||||||
|
|
||||||
|
It is possible to configure an IPv4 DNS domain name that resolves to the node's public IPv4 address.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
wakunode2 --dns4-domain-name=mynode.example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
This allows for the node's publically announced `multiaddrs` to use the `/dns4` scheme.
|
||||||
|
In addition, nodes with domain name and [secure websocket configured](./configure-websocket.md),
|
||||||
|
will generate a discoverable ENR containing the `/wss` multiaddr with `/dns4` domain name.
|
||||||
|
This is necessary to verify domain certificates when connecting to this node over secure websocket.
|
||||||
|
|
@ -0,0 +1,54 @@
|
||||||
|
# Generate and configure a node key
|
||||||
|
|
||||||
|
By default a node will generate a new, random key pair each time it boots,
|
||||||
|
resulting in a different public libp2p `multiaddrs` after each restart.
|
||||||
|
|
||||||
|
To maintain consistent addressing across restarts,
|
||||||
|
it is possible to configure the node with a previously generated private key using the `--nodekey` option.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
wakunode2 --nodekey=<64_char_hex>
|
||||||
|
```
|
||||||
|
|
||||||
|
This option takes a [Secp256k1](https://en.bitcoin.it/wiki/Secp256k1) private key in 64 char hexstring format.
|
||||||
|
|
||||||
|
To generate such a key on Linux systems,
|
||||||
|
use the openssl `rand` command to generate a pseudo-random 32 byte hexstring.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
openssl rand -hex 32
|
||||||
|
```
|
||||||
|
|
||||||
|
Example output:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ openssl rand -hex 32
|
||||||
|
6a29e767c96a2a380bb66b9a6ffcd6eb54049e14d796a1d866307b8beb7aee58
|
||||||
|
```
|
||||||
|
|
||||||
|
where the key `6a29e767c96a2a380bb66b9a6ffcd6eb54049e14d796a1d866307b8beb7aee58` can be used as `nodekey`.
|
||||||
|
|
||||||
|
To create a reusable keyfile on Linux using `openssl`,
|
||||||
|
use the `ecparam` command coupled with some standard utilities
|
||||||
|
whenever you want to extract the 32 byte private key in hex format.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Generate keyfile
|
||||||
|
openssl ecparam -genkey -name secp256k1 -out my_private_key.pem
|
||||||
|
# Extract 32 byte private key
|
||||||
|
openssl ec -in my_private_key.pem -outform DER | tail -c +8 | head -c 32| xxd -p -c 32
|
||||||
|
```
|
||||||
|
|
||||||
|
Example output:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
read EC key
|
||||||
|
writing EC key
|
||||||
|
0c687bb8a7984c770b566eae08520c67f53d302f24b8d4e5e47cc479a1e1ce23
|
||||||
|
```
|
||||||
|
|
||||||
|
where the key `0c687bb8a7984c770b566eae08520c67f53d302f24b8d4e5e47cc479a1e1ce23` can be used as `nodekey`.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
wakunode2 --nodekey=0c687bb8a7984c770b566eae08520c67f53d302f24b8d4e5e47cc479a1e1ce23
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,56 @@
|
||||||
|
# Configure store protocol
|
||||||
|
|
||||||
|
Store protocol is enabled by default on a nwaku node.
|
||||||
|
This is controlled by the `--store` CLI option.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Disable store protocol on startup
|
||||||
|
./build/wakunode2 --store:false
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that this only mounts the `store` protocol,
|
||||||
|
meaning your node will indicate to other peers that it supports `store`.
|
||||||
|
It does not yet allow your node to either retrieve historical messages as a client
|
||||||
|
or store and serve historical messages itself.
|
||||||
|
|
||||||
|
## Configuring a store client
|
||||||
|
|
||||||
|
Ensure that `store` is enabled (this is `true` by default) and provide at least one store service node address with the `--storenode` CLI option.
|
||||||
|
|
||||||
|
See the following example, using the peer at `/dns4/node-01.ac-cn-hongkong-c.wakuv2.test.statusim.net/tcp/30303/p2p/16Uiu2HAkvWiyFsgRhuJEb9JfjYxEkoHLgnUQmr1N5mKWnYjxYRVm` as store service node.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--store:true \
|
||||||
|
--storenode:/dns4/node-01.ac-cn-hongkong-c.wakuv2.test.statusim.net/tcp/30303/p2p/16Uiu2HAkvWiyFsgRhuJEb9JfjYxEkoHLgnUQmr1N5mKWnYjxYRVm
|
||||||
|
```
|
||||||
|
|
||||||
|
Your node can now send queries to retrieve historical messages
|
||||||
|
from the configured store service node.
|
||||||
|
One way to trigger such queries is asking your node for historical messages using the [Waku v2 JSON RPC API](https://rfc.vac.dev/spec/16/).
|
||||||
|
|
||||||
|
## Configuring a store service node
|
||||||
|
|
||||||
|
To store historical messages on your node which can be served to store clients the `--persist-messages` CLI option must be enabled.
|
||||||
|
By default a node would store up to the latest `50 000` messages.
|
||||||
|
This is configurable using the `--store-capacity` option.
|
||||||
|
A node that has a `--db-path` set will backup historical messages to a local database at the DB path
|
||||||
|
and persist these messages even after a restart.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--store:true \
|
||||||
|
--persist-messages:true \
|
||||||
|
--db-path:/mnt/nwaku/data/db1/ \
|
||||||
|
--store-capacity:150000
|
||||||
|
```
|
||||||
|
|
||||||
|
### How much resources should I allocate?
|
||||||
|
|
||||||
|
Currently store service nodes use an in-memory key-value store as primary storage with the disk-based database only used for backups.
|
||||||
|
Most Waku messages average a size of 1KB - 2KB,
|
||||||
|
implying a minimum memory requirement of at least ~250MB
|
||||||
|
for a medium capacity store of 100k messages.
|
||||||
|
Note, however, that the allowable maximum size for Waku messages is up to 1MB.
|
||||||
|
We are working on a disk-only and hybrid store to lower the memory requirement.
|
||||||
|
It will soon also be possible to configure store capacity on maximum store size or number of days' history to keep.
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
# Configure websocket transport
|
||||||
|
|
||||||
|
Websocket is currently the only Waku transport supported by browser nodes using [js-waku](https://github.com/status-im/js-waku).
|
||||||
|
Setting up websocket enables your node to directly serve browser peers.
|
||||||
|
|
||||||
|
A valid certificate is necessary to serve browser nodes,
|
||||||
|
you can use [`letsencrypt`](https://letsencrypt.org/):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo letsencrypt -d <your.domain.name>
|
||||||
|
```
|
||||||
|
|
||||||
|
You will need the `privkey.pem` and `fullchain.pem` files.
|
||||||
|
|
||||||
|
To enable secure websocket, pass the generated files to `wakunode2`:
|
||||||
|
Note, the default port for websocket is 8000.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
wakunode2 --websocket-secure-support=true --websocket-secure-key-path="<letsencrypt cert dir>/privkey.pem" --websocket-secure-cert-path="<letsencrypt cert dir>/fullchain.pem"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Self-signed certificates
|
||||||
|
|
||||||
|
Self-signed certificates are not recommended for production setups because:
|
||||||
|
|
||||||
|
- Browsers do not accept self-signed certificates
|
||||||
|
- Browsers do not display an error when rejecting a certificate for websocket.
|
||||||
|
|
||||||
|
However, they can be used for local testing purposes:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
mkdir -p ./ssl_dir/
|
||||||
|
openssl req -x509 -newkey rsa:4096 -keyout ./ssl_dir/key.pem -out ./ssl_dir/cert.pem -sha256 -nodes
|
||||||
|
wakunode2 --websocket-secure-support=true --websocket-secure-key-path="./ssl_dir/key.pem" --websocket-secure-cert-path="./ssl_dir/cert.pem"
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,11 @@
|
||||||
|
# Configure a nwaku node
|
||||||
|
|
||||||
|
Nwaku can be configured to serve the adaptive needs of different operators.
|
||||||
|
This page serves as an index of tutorials explaining how to configure your nwaku node for different use cases.
|
||||||
|
|
||||||
|
1. [Connect to other peers](./connect.md)
|
||||||
|
1. [Configure a domain name](./configure-domain.md)
|
||||||
|
1. [Use DNS discovery to connect to existing nodes](./configure-dns-disc.md)
|
||||||
|
1. [Configure store protocol](./configure-store.md)
|
||||||
|
1. [Generate and configure a node key](./configure-key.md)
|
||||||
|
1. [Configure websocket transport](./configure-websocket.md)
|
||||||
|
|
@ -0,0 +1,60 @@
|
||||||
|
# Connect to other peers
|
||||||
|
|
||||||
|
*Note that this tutorial describes how to **configure** a node to connect to other peers before runnning the node.
|
||||||
|
For connecting a running node to existing peers,
|
||||||
|
see the [JSON-RPC API](https://rfc.vac.dev/spec/16/).*
|
||||||
|
|
||||||
|
There are currently three options.
|
||||||
|
Note that each of these options can be used in combination with any of the other two.
|
||||||
|
In other words, it is possible to configure a node to connect
|
||||||
|
to a static list of peers and
|
||||||
|
to discover such peer lists using DNS discovery and
|
||||||
|
discover and connect to random peers using discovery v5 with a bootstrap node.
|
||||||
|
|
||||||
|
## Option 1: Configure peers statically
|
||||||
|
|
||||||
|
Static peers can be provided to a nwaku node on startup using the `--staticnode` CLI parameter.
|
||||||
|
The `--staticnode` option can be repeated for each peer you want to connect to on startup.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--staticnode:<libp2p-multiaddr-peer1> \
|
||||||
|
--staticnode:<libp2p-multiaddr-peer2>
|
||||||
|
```
|
||||||
|
|
||||||
|
As an example, consider a nwaku node that connects to two known peers
|
||||||
|
on the same local host (with IP `0.0.0.0`)
|
||||||
|
with TCP ports `60002` and `60003`,
|
||||||
|
and peer IDs `16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H` and `16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ` respectively.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--staticnode:/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \
|
||||||
|
--staticnode:/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ
|
||||||
|
```
|
||||||
|
|
||||||
|
## Option 2: Discover peers using DNS discovery
|
||||||
|
|
||||||
|
A node can discover other nodes to connect to using DNS-based discovery.
|
||||||
|
For a quickstart guide on how to configure DNS discovery,
|
||||||
|
see [this tutorial](./configure-dns-disc.md).
|
||||||
|
There is also a [more comprehensive tutorial](../../tutorial/dns-disc.md) for advanced users.
|
||||||
|
|
||||||
|
## Option 3: Discover peers using Waku Discovery v5
|
||||||
|
|
||||||
|
<!-- TODO: add link to a separate discv5 config tutorial here -->
|
||||||
|
|
||||||
|
Enable Discovery v5 using the `--discv5-discovery` option.
|
||||||
|
|
||||||
|
It is possible to configure bootstrap entries for the Discovery v5 routing table
|
||||||
|
using the `--discv5-bootstrap-node` option repeatedly.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--discv5-discovery:true \
|
||||||
|
--discv5-bootstrap-node:<discv5-enr-bootstrap-entry1> \
|
||||||
|
--discv5-bootstrap-node:<discv5-enr-bootstrap-entry2>
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that if Discovery v5 is enabled and used in conjunction with DNS-based discovery,
|
||||||
|
the nwaku node will attempt to bootstrap the Discovery v5 routing table with ENRs extracted from the peers discovered via DNS.
|
||||||
|
|
@ -0,0 +1,217 @@
|
||||||
|
# Running nwaku
|
||||||
|
|
||||||
|
Nwaku binaries can be [built](./build.md) and run on Linux and macOS.
|
||||||
|
Windows support is experimental.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Run with default configuration
|
||||||
|
./build/wakunode2
|
||||||
|
|
||||||
|
# See available command line options
|
||||||
|
./build/wakunode2 --help
|
||||||
|
```
|
||||||
|
|
||||||
|
## Default configuration
|
||||||
|
|
||||||
|
By default a nwaku node will:
|
||||||
|
- generate a new private key and libp2p identities after every restart.
|
||||||
|
See [this tutorial](./configure-key.md) if you want to generate and configure a persistent private key.
|
||||||
|
- listen for incoming libp2p connections on the default TCP port (`60000`)
|
||||||
|
- enable `relay` protocol
|
||||||
|
- subscribe to the default pubsub topic, namely `/waku/2/default-waku/proto`
|
||||||
|
- enable `store` protocol, but only as a client.
|
||||||
|
This implies that the nwaku node will not persist any historical messages itself,
|
||||||
|
but can query `store` service peers who do so.
|
||||||
|
To configure `store` as a service node,
|
||||||
|
see [this tutorial](./configure-store.md).
|
||||||
|
|
||||||
|
> **Note:** The `filter` and `lightpush` protocols are _not_ enabled by default.
|
||||||
|
Consult the [configuration guide](./configure.md) on how to configure your nwaku node to run these protocols.
|
||||||
|
|
||||||
|
Some typical non-default configurations are explained below.
|
||||||
|
For more advanced configuration, see the [configuration guide](./configure.md).
|
||||||
|
Different ways to connect to other nodes are expanded upon in our [connection guide](./connect.md).
|
||||||
|
|
||||||
|
## Finding your listening address(es)
|
||||||
|
|
||||||
|
Find the log entry beginning with `Listening on`.
|
||||||
|
It should be printed at INFO level when you start your node
|
||||||
|
and contains a list of all publically announced listening addresses for the nwaku node.
|
||||||
|
|
||||||
|
For example
|
||||||
|
|
||||||
|
```
|
||||||
|
INF 2022-05-11 16:42:30.591+02:00 Listening on topics="wakunode" tid=6661 file=wakunode2.nim:941 full=[/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H][/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H]
|
||||||
|
```
|
||||||
|
|
||||||
|
indicates that your node is listening on the TCP transport address
|
||||||
|
|
||||||
|
```
|
||||||
|
/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H
|
||||||
|
```
|
||||||
|
|
||||||
|
and websocket address
|
||||||
|
|
||||||
|
```
|
||||||
|
/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also query a running node for its listening addresses
|
||||||
|
using a [`get_waku_v2_debug_v1_info` JSON-RPC API](https://rfc.vac.dev/spec/16/#get_waku_v2_debug_v1_info) call.
|
||||||
|
|
||||||
|
For example
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -d '{"jsonrpc":"2.0","id":"id","method":"get_waku_v2_debug_v1_info", "params":[]}' --header "Content-Type: application/json" http://localhost:8545
|
||||||
|
```
|
||||||
|
|
||||||
|
returns a response similar to
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"jsonrpc": "2.0",
|
||||||
|
"id": "id",
|
||||||
|
"result": {
|
||||||
|
"listenAddresses": [
|
||||||
|
"/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmLU5Nwng9dWFZwM2DgJ5QGcUuDnefJyHJiXUCVaprhgL4"
|
||||||
|
],
|
||||||
|
"enrUri": "enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Finding your discoverable ENR address(es)
|
||||||
|
|
||||||
|
A nwaku node can encode its addressing information in an [Ethereum Node Record (ENR)](https://eips.ethereum.org/EIPS/eip-778) according to [`31/WAKU2-ENR`](https://rfc.vac.dev/spec/31/).
|
||||||
|
These ENR are most often used for discovery purposes.
|
||||||
|
|
||||||
|
### ENR for DNS discovery
|
||||||
|
|
||||||
|
Find the log entry beginning with `DNS: discoverable ENR`.
|
||||||
|
It should be printed at INFO level when you start your node with [DNS discovery enabled](./configure-dns-disc.md)
|
||||||
|
and contains an ENR that can be added to node lists discoverable via DNS.
|
||||||
|
|
||||||
|
For example
|
||||||
|
|
||||||
|
```
|
||||||
|
INF 2022-05-20 11:52:48.772+02:00 DNS: discoverable ENR topics="wakunode" tid=5182 file=wakunode2.nim:941 enr=enr:-Iu4QBZs5huNuEAjI9WA0HOAjzpmp39vKJAtYRG3HXH86-i3HGcxMgupIkyDBmBq9qJ2wFfgMiW8AUzUxTFMAzfJM5MBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQN0EcrUbHrL_O_kNXDlBvcO1I4yZUdNk7VZI5GsXaWgvYN0Y3CC6mCFd2FrdTID
|
||||||
|
```
|
||||||
|
|
||||||
|
indicates that your node addresses are encoded in the ENR
|
||||||
|
|
||||||
|
```
|
||||||
|
enr=enr:-Iu4QBZs5huNuEAjI9WA0HOAjzpmp39vKJAtYRG3HXH86-i3HGcxMgupIkyDBmBq9qJ2wFfgMiW8AUzUxTFMAzfJM5MBgmlkgnY0gmlwhAAAAACJc2VjcDI1NmsxoQN0EcrUbHrL_O_kNXDlBvcO1I4yZUdNk7VZI5GsXaWgvYN0Y3CC6mCFd2FrdTID
|
||||||
|
```
|
||||||
|
|
||||||
|
### ENR for Discovery v5
|
||||||
|
|
||||||
|
Find the log entry beginning with `Discv5: discoverable ENR`.
|
||||||
|
It should be printed at INFO level when you start your node with [Waku Discovery v5 enabled](https://rfc.vac.dev/spec/33/)
|
||||||
|
and contains the ENR that will be discoverable by other peers.
|
||||||
|
|
||||||
|
For example
|
||||||
|
|
||||||
|
```
|
||||||
|
INF 2022-05-20 11:52:48.775+02:00 Discv5: discoverable ENR topics="wakunode" tid=5182 file=wakunode2.nim:905 enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
|
||||||
|
```
|
||||||
|
|
||||||
|
indicates that your node addresses are encoded in the ENR
|
||||||
|
|
||||||
|
```
|
||||||
|
enr=enr:-IO4QDxToTg86pPCK2KvMeVCXC2ADVZWrxXSvNZeaoa0JhShbM5qed69RQz1s1mWEEqJ3aoklo_7EU9iIBcPMVeKlCQBgmlkgnY0iXNlY3AyNTZrMaEDdBHK1Gx6y_zv5DVw5Qb3DtSOMmVHTZO1WSORrF2loL2DdWRwgiMohXdha3UyAw
|
||||||
|
```
|
||||||
|
|
||||||
|
## Typical configuration (relay node)
|
||||||
|
|
||||||
|
The typical configuration for a nwaku node is to run the `relay` protocol,
|
||||||
|
subscribed to the default pubsub topic `/waku/2/default-waku/proto`,
|
||||||
|
and connecting to one or more existing peers.
|
||||||
|
We assume below that running nodes also participate in Discovery v5
|
||||||
|
to continually discover and connect to random peers for a more robust mesh.
|
||||||
|
|
||||||
|
### Connecting to known peer(s)
|
||||||
|
|
||||||
|
A typical run configuration for a nwaku node is to connect to existing peers with known listening addresses using the `--staticnode` option.
|
||||||
|
The `--staticnode` option can be repeated for each peer you want to connect to on startup.
|
||||||
|
This is also useful if you want to run several nwaku instances locally
|
||||||
|
and therefore know the listening addresses of all peers.
|
||||||
|
|
||||||
|
As an example, consider a nwaku node that connects to two known peers
|
||||||
|
on the same local host (with IP `0.0.0.0`)
|
||||||
|
with TCP ports `60002` and `60003`,
|
||||||
|
and peer IDs `16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H` and `16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ` respectively.
|
||||||
|
The Discovery v5 routing table can similarly be bootstrapped using a static ENR.
|
||||||
|
We include an example below.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--ports-shift:1 \
|
||||||
|
--staticnode:/ip4/0.0.0.0/tcp/60002/p2p/16Uiu2HAkzjwwgEAXfeGNMKFPSpc6vGBRqCdTLG5q3Gmk2v4pQw7H \
|
||||||
|
--staticnode:/ip4/0.0.0.0/tcp/60003/p2p/16Uiu2HAmFBA7LGtwY5WVVikdmXVo3cKLqkmvVtuDu63fe8safeQJ \
|
||||||
|
--discv5-discovery:true \
|
||||||
|
--discv5-bootstrap-node:enr:-JK4QM2ylZVUhVPqXrqhWWi38V46bF2XZXPSHh_D7f2PmUHbIw-4DidCBnBnm-IbxtjXOFbdMMgpHUv4dYVH6TgnkucBgmlkgnY0gmowhCJ6_HaJc2VjcDI1NmsxoQM06FsT6EJ57mzR_wiLu2Bz1dER2nUFSCpaFzCccQtnhYN0Y3CCdl-DdWRwgiMohXdha3UyDw
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Tip:** `--ports-shift` shifts all configured ports forward by the configured amount.
|
||||||
|
This is another useful option when running several nwaku instances on a single machine
|
||||||
|
and would like to avoid port clashes without manually configuring each port.
|
||||||
|
|
||||||
|
### Connecting to the `wakuv2.prod` network
|
||||||
|
|
||||||
|
*See [this explainer](https://github.com/status-im/nwaku/blob/6ebe26ad0587d56a87a879d89b7328f67f048911/docs/contributors/waku-fleets.md) on the different networks and Waku v2 fleets.*
|
||||||
|
|
||||||
|
You can use DNS discovery to bootstrap connection to the existing production network.
|
||||||
|
Discovery v5 will attempt to extract the ENRs of the discovered nodes as bootstrap entries to the routing table.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--ports-shift:1 \
|
||||||
|
--dns-discovery:true \
|
||||||
|
--dns-discovery-url:enrtree://ANTL4SLG2COUILKAPE7EF2BYNL2SHSHVCHLRD5J7ZJLN5R3PRJD2Y@prod.waku.nodes.status.im \
|
||||||
|
--discv5-discovery:true
|
||||||
|
```
|
||||||
|
|
||||||
|
### Connecting to the `wakuv2.test` network
|
||||||
|
|
||||||
|
*See [this explainer](https://github.com/status-im/nwaku/blob/6ebe26ad0587d56a87a879d89b7328f67f048911/docs/contributors/waku-fleets.md) on the different networks and Waku v2 fleets.*
|
||||||
|
|
||||||
|
You can use DNS discovery to bootstrap connection to the existing test network.
|
||||||
|
Discovery v5 will attempt to extract the ENRs of the discovered nodes as bootstrap entries to the routing table.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--ports-shift:1 \
|
||||||
|
--dns-discovery:true \
|
||||||
|
--dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.waku.nodes.status.im \
|
||||||
|
--discv5-discovery:true
|
||||||
|
```
|
||||||
|
|
||||||
|
## Typical configuration (relay and store service node)
|
||||||
|
|
||||||
|
Often nwaku nodes choose to also store historical messages
|
||||||
|
from where it can be queried by other peers who may have been temporarily offline.
|
||||||
|
For example, a typical configuration for such a store service node,
|
||||||
|
[connecting to the `wakuv2.test`](#connecting-to-the-wakuv2test-fleet) fleet on startup,
|
||||||
|
appears below.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./build/wakunode2 \
|
||||||
|
--ports-shift:1 \
|
||||||
|
--store:true \
|
||||||
|
--persist-messages:true \
|
||||||
|
--db-path:/mnt/nwaku/data/db1/ \
|
||||||
|
--store-capacity:150000 \
|
||||||
|
--dns-discovery:true \
|
||||||
|
--dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.waku.nodes.status.im \
|
||||||
|
--discv5-discovery:true
|
||||||
|
```
|
||||||
|
|
||||||
|
See our [store configuration tutorial](./configure-store.md) for more.
|
||||||
|
|
||||||
|
## Interact with a running nwaku node
|
||||||
|
|
||||||
|
A running nwaku node can be interacted with using the [Waku v2 JSON RPC API](https://rfc.vac.dev/spec/16/).
|
||||||
|
|
||||||
|
> **Note:** Private and Admin API functionality are disabled by default.
|
||||||
|
To configure a nwaku node with these enabled,
|
||||||
|
use the `--rpc-admin:true` and `--rpc-private:true` CLI options.
|
||||||
|
|
@ -0,0 +1,28 @@
|
||||||
|
# Quickstart: running a nwaku node
|
||||||
|
|
||||||
|
This guide explains how to build and run a nwaku node
|
||||||
|
for the most common use cases.
|
||||||
|
For a more advanced configuration see our [configuration guides](./how-to/configure.md)
|
||||||
|
|
||||||
|
## 1. Build
|
||||||
|
|
||||||
|
[Build the nwaku node](./how-to/build.md)
|
||||||
|
or download a precompiled binary from our [releases page](https://github.com/status-im/nwaku/releases).
|
||||||
|
Docker images are published to [statusteam/nim-waku](https://hub.docker.com/r/statusteam/nim-waku/tags) on DockerHub.
|
||||||
|
|
||||||
|
<!-- TODO: more advanced explanation on finding and using docker images -->
|
||||||
|
|
||||||
|
## 2. Run
|
||||||
|
|
||||||
|
[Run the nwaku node](./how-to/run.md) using a default or common configuration
|
||||||
|
or [configure](./how-to/configure.md) the node for more advanced use cases.
|
||||||
|
|
||||||
|
[Connect](./how-to/connect.md) the nwaku node to other peers to start communicating.
|
||||||
|
|
||||||
|
## 3. Interact
|
||||||
|
|
||||||
|
A running nwaku node can be interacted with using the [Waku v2 JSON RPC API](https://rfc.vac.dev/spec/16/).
|
||||||
|
|
||||||
|
> **Note:** Private and Admin API functionality are disabled by default.
|
||||||
|
To configure a nwaku node with these enabled,
|
||||||
|
use the `--rpc-admin:true` and `--rpc-private:true` CLI options.
|
||||||
Loading…
Reference in New Issue