acid-info
/
waku.guide
mirror of https://github.com/acid-info/waku.guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add config options reference

This commit is contained in:
LordGhostX 2023-06-15 21:42:35 +01:00
parent debad68a88
commit 79ae291ed1
No known key found for this signature in database
GPG Key ID: 520CC5DC4F94FCC7
9 changed files with 276 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.cspell.json
View File

@ -53,7 +53,8 @@
"package-lock.json",
"yarn.lock",
"tsconfig.json",
"node_modules/**"
"node_modules/**",
"docs/guides/reference/node-config-options.md"
],
"patterns": [
{

1
docs/guides/nwaku/build-source.md
View File

@ -98,6 +98,7 @@ To learn more about running nwaku, please refer to:
- [Run a Nwaku Node](/guides/run-nwaku-node#run-the-node)
- [Run Nwaku in Docker Container](/guides/nwaku/run-docker)
- [Run Nwaku with Docker Compose](/guides/nwaku/run-docker-compose)
- [Node Configuration Methods](/guides/reference/node-config-methods)
## Run Test Suite

2
docs/guides/nwaku/run-docker-compose.md
View File

@ -21,7 +21,7 @@ cd nwaku-compose
## Configure the Setup
Modify the `docker-compose.yml` file to customize your node's configuration, including the Docker image and [nwaku arguments](https://github.com/waku-org/nwaku/blob/master/docs/operators/how-to/configure.md). Please visit [statusteam/nim-waku/tags](https://hub.docker.com/r/statusteam/nim-waku/tags) for images of specific `nwaku` releases.
Modify the `docker-compose.yml` file to customize your node's configuration, including the Docker image and [nwaku arguments](/guides/reference/node-config-options). Please visit [statusteam/nim-waku/tags](https://hub.docker.com/r/statusteam/nim-waku/tags) for images of specific `nwaku` releases.
## Run Docker Compose

2
docs/guides/nwaku/run-docker.md
View File

@ -47,7 +47,7 @@ docker run [OPTIONS] [IMAGE] [ARG...]
- `OPTIONS` are your selected [Docker options](https://docs.docker.com/engine/reference/commandline/run/#options)
- `IMAGE` is the image and tag you pulled from the registry or built locally
- `ARG...` is the list of `nwaku` arguments for your [chosen node configuration](/guides/nwaku/configuration)
- `ARG...` is the list of arguments for your [node configuration options](/guides/reference/node-config-options)
Run `nwaku` using the most typical configuration:

14
docs/guides/nwaku/configuration.md → docs/guides/reference/node-config-methods.md
View File

@ -1,5 +1,5 @@
---
title: Node Configuration
title: Node Configuration Methods
---
Waku nodes can be configured using a combination of the following methods:
@ -15,7 +15,7 @@ Note the precedence order: Each configuration method overrides the one below it
## Command Line Options
Node configuration is primarily done using command line options, which override other methods. Specify configuration options by providing them in this format after the binary name:
Node configuration is primarily done using command line options, which override other methods. Specify [configuration options](/guides/reference/node-config-options) by providing them in this format after the binary name:
```bash
wakunode2 --tcp-port=65000
@ -29,9 +29,9 @@ docker run statusteam/nim-waku --tcp-port=65000
## Environment Variables
Nodes can be configured using environment variables by prefixing the variable name with `WAKUNODE2_` and using the command line option in [SCREAMING_SNAKE_CASE](https://en.wiktionary.org/wiki/screaming_snake_case) format.
Nodes can be configured using environment variables by prefixing the variable name with `WAKUNODE2_` and using the configuration option in [SCREAMING_SNAKE_CASE](https://en.wiktionary.org/wiki/screaming_snake_case) format.
To set the `--tcp-port` configuration, the `wakunode2` binary should be called in this format:
To set the `tcp-port` configuration, the `wakunode2` binary should be called in this format:
```bash
WAKUNODE2_TCP_PORT=65000 wakunode2
@ -56,7 +56,7 @@ log-level = "DEBUG"
tcp-port = 65000
```
The `--config-file` command line option lets you specify the configuration file path:
The `config-file` [configuration option](/guides/reference/node-config-options) lets you specify the configuration file path:
```bash
wakunode2 --config-file=[TOML CONFIGURATION FILE]
@ -78,7 +78,7 @@ This is the third configuration method in order of precedence. [Command line opt
## Configuration Default Values
The default configuration is used if no other options are specified. To see the default values of all configuration options, run `wakunode2 --help`:
The default configuration is used if no other options are specified. To see the default values of all [configuration options](/guides/reference/node-config-options), run `wakunode2 --help`:
```bash
$ wakunode2 --help
@ -89,8 +89,6 @@ wakunode2 [OPTIONS]...
The following options are available:
--config-file Loads configuration from a TOML file (cmd-line parameters take precedence).
--log-level Sets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE,
WARN, ERROR or FATAL [=logging.LogLevel.INFO].
--tcp-port TCP listening port. [=60000].
<...>

161
docs/guides/reference/node-config-options.md Normal file
View File

@ -0,0 +1,161 @@
---
title: Node Configuration Options
---
Here are the node configuration options and their descriptions:
## Application-Level Config
| Name | Default Value | Description |
| - | - | - |
| `config-file` | | Loads configuration from a TOML file (cmd-line parameters take precedence) |
| `protected-topic` | `newSeq[ProtectedTopic](0)` | Topics and its public key to be used for message validation, topic:pubkey. Argument may be repeated |
## Log Config
| Name | Default Value | Description |
| - | - | - |
| `log-level` | `logging.LogLevel.INFO` | Sets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL |
| `log-format` | `logging.LogFormat.TEXT` | Specifies what kind of logs should be written to stdout. Suported formats: TEXT, JSON |
## General Node Config
| Name | Default Value | Description |
| - | - | - |
| `agent-string` | `nwaku` | Node agent string which is used as identifier in network |
| `nodekey` | | P2P node private key as 64 char hex string |
| `listen-address` | `defaultListenAddress()` | Listening address for LibP2P (and Discovery v5, if enabled) traffic |
| `tcp-port` | `60000` | TCP listening port |
| `ports-shift` | `0` | Add a shift to all port numbers |
| `nat` | any | Specify method to use for determining public address. Must be one of: any, none, upnp, pmp, extip:<IP\> |
| `ext-multiaddr` | | External multiaddresses to advertise to the network. Argument may be repeated |
| `max-connections` | `50` | Maximum allowed number of libp2p connections |
| `peer-store-capacity` | | Maximum stored peers in the peerstore |
| `peer-persistence` | `false` | Enable peer persistence |
## DNS Addrs Config
| Name | Default Value | Description |
| - | - | - |
| `dns-addrs` | `true` | Enable resolution of `dnsaddr`, `dns4` or `dns6` multiaddrs |
| `dns-addrs-name-server` | `@[1.1.1.1, 1.0.0.1]` | DNS name server IPs to query for DNS multiaddrs resolution. Argument may be repeated |
| `dns4-domain-name` | | The domain name resolving to the node's public IPv4 address |
## Relay Config
| Name | Default Value | Description |
| - | - | - |
| `relay` | `true` | Enable relay protocol: true\|false |
| `relay-peer-exchange` | `false` | Enable gossipsub peer exchange in relay protocol: true\|false |
| `rln-relay` | `false` | Enable spam protection through rln-relay: true\|false |
| `rln-relay-cred-path` | | The path for peristing rln-relay credential |
| `rln-relay-membership-index` | `0` | The index of credentials to use |
| `rln-relay-membership-group-index` | `0` | The index of credentials to use, within a specific rln membership set |
| `rln-relay-pubsub-topic` | `/waku/2/default-waku/proto` | The pubsub topic for which rln-relay gets enabled |
| `rln-relay-content-topic` | `/toy-chat/3/mingde/proto` | The content topic for which rln-relay gets enabled |
| `rln-relay-dynamic` | `false` | Enable waku-rln-relay with on-chain dynamic group management: true\|false |
| `rln-relay-id-key` | | Rln relay identity secret key as a Hex string |
| `rln-relay-id-commitment-key` | | Rln relay identity commitment key as a Hex string |
| `rln-relay-eth-account-address` | | Account address for the Ethereum testnet Sepolia |
| `rln-relay-eth-account-private-key` | | Account private key for the Ethereum testnet Sepolia |
| `rln-relay-eth-client-address` | `ws://localhost:8540/` | WebSocket address of an Ethereum testnet client e.g., ws://localhost:8540/ |
| `rln-relay-eth-contract-address` | | Address of membership contract on an Ethereum testnet |
| `rln-relay-cred-password` | | Password for encrypting RLN credentials |
| `rln-relay-tree-path` | | Path to the RLN merkle tree sled db (https://github.com/spacejam/sled) |
| `staticnode` | | Peer multiaddr to directly connect with. Argument may be repeated |
| `keep-alive` | `false` | Enable keep-alive for idle connections: true\|false |
| `topic` | `@[/waku/2/default-waku/proto]` | Default topic to subscribe to. Argument may be repeated |
## Store and Message Store Config
| Name | Default Value | Description |
| - | - | - |
| `store` | `false` | Enable/disable waku store protocol |
| `storenode` | | Peer multiaddress to query for storage |
| `store-message-retention-policy` | time:172800 | Message store retention policy. Time retention policy: 'time:<seconds\>'. Capacity retention policy: 'capacity:<count\>'. Set to 'none' to disable |
| `store-message-db-url` | `sqlite://store.sqlite3` | The database connection URL for peristent storage |
| `store-message-db-vacuum` | `false` | Enable database vacuuming at start. Only supported by SQLite database engine |
| `store-message-db-migration` | `true` | Enable database migration at start |
| `store-resume-peer` | | Peer multiaddress to resume the message store at boot |
## Filter Config
| Name | Default Value | Description |
| - | - | - |
| `filter` | `false` | Enable filter protocol: true\|false |
| `filternode` | | Peer multiaddr to request content filtering of messages |
| `filter-timeout` | `14400 # 4 hours` | Timeout for filter node in seconds |
## Light Push Config
| Name | Default Value | Description |
| - | - | - |
| `lightpush` | `false` | Enable lightpush protocol: true\|false |
| `lightpushnode` | | Peer multiaddr to request lightpush of published messages |
## JSON-RPC Config
| Name | Default Value | Description |
| - | - | - |
| `rpc` | `true` | Enable Waku JSON-RPC server: true\|false |
| `rpc-address` | `127.0.0.1` | Listening address of the JSON-RPC server |
| `rpc-port` | `8545` | Listening port of the JSON-RPC server |
| `rpc-admin` | `false` | Enable access to JSON-RPC Admin API: true\|false |
| `rpc-private` | `false` | Enable access to JSON-RPC Private API: true\|false |
## REST HTTP Config
| Name | Default Value | Description |
| - | - | - |
| `rest` | `false` | Enable Waku REST HTTP server: true\|false |
| `rest-address` | `127.0.0.1` | Listening address of the REST HTTP server |
| `rest-port` | `8645` | Listening port of the REST HTTP server |
| `rest-relay-cache-capacity` | `30` | Capacity of the Relay REST API message cache |
| `rest-admin` | `false` | Enable access to REST HTTP Admin API: true\|false |
| `rest-private` | `false` | Enable access to REST HTTP Private API: true\|false |
## Metrics Config
| Name | Default Value | Description |
| - | - | - |
| `metrics-server` | `false` | Enable the metrics server: true\|false |
| `metrics-server-address` | `127.0.0.1` | Listening address of the metrics server |
| `metrics-server-port` | `8008` | Listening HTTP port of the metrics server |
| `metrics-logging` | `true` | Enable metrics logging: true\|false |
## DNS Discovery Config
| Name | Default Value | Description |
| - | - | - |
| `dns-discovery` | `false` | Enable discovering nodes via DNS |
| `dns-discovery-url` | | URL for DNS node list in format 'enrtree://<key\>@<fqdn\>' |
| `dns-discovery-name-server` | `@[1.1.1.1, 1.0.0.1]` | DNS name server IPs to query. Argument may be repeated |
## Discovery v5 Config
| Name | Default Value | Description |
| - | - | - |
| `discv5-discovery` | `false` | Enable discovering nodes via Node Discovery v5 |
| `discv5-udp-port` | `9000` | Listening UDP port for Node Discovery v5 |
| `discv5-bootstrap-node` | | Text-encoded ENR for bootstrap node. Used when connecting to the network. Argument may be repeated |
| `discv5-enr-auto-update` | `false` | Discovery can automatically update its ENR with the IP address |
| `discv5-table-ip-limit` | `10` | Maximum amount of nodes with the same IP in discv5 routing tables |
| `discv5-bucket-ip-limit` | `2` | Maximum amount of nodes with the same IP in discv5 routing table buckets |
| `discv5-bits-per-hop` | `1` | Kademlia's b variable, increase for less hops per lookup |
## Waku Peer Exchange Config
| Name | Default Value | Description |
| - | - | - |
| `peer-exchange` | `false` | Enable waku peer exchange protocol (responder side): true\|false |
| `peer-exchange-node` | | Peer multiaddr to send peer exchange requests to. (enables peer exchange protocol requester side) |
## WebSocket Config
| Name | Default Value | Description |
| - | - | - |
| `websocket-support` | `false` | Enable websocket: true\|false |
| `websocket-port` | `8000` | WebSocket listening port |
| `websocket-secure-support` | `false` | Enable secure websocket: true\|false |
| `websocket-secure-key-path` | | Secure websocket key path: '/path/to/key.txt' |
| `websocket-secure-cert-path` | | Secure websocket Certificate path: '/path/to/cert.txt' |

4
docs/guides/run-nwaku-node.md
View File

@ -48,7 +48,7 @@ By default, a `nwaku` node is configured to do the following:
- Enable the `Store` protocol as a client, allowing it to query peers for historical messages but not store any message itself.
:::tip
For more advanced configurations like enabling other protocols or maintaining a consistent `PeerID`, please refer to the [Node Configuration](/guides/nwaku/configuration) guide.
For more advanced configurations like enabling other protocols or maintaining a consistent `PeerID`, please refer to the [Node Configuration Methods](/guides/reference/node-config-methods) guide.
:::
## Connect the Node
@ -131,7 +131,7 @@ INF 2023-06-15 16:09:54.448+01:00 Listening on top
# Listening TCP transport address
/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
# Listening websocket address
# Listening WebSocket address
/ip4/0.0.0.0/tcp/8000/ws/p2p/16Uiu2HAmQCsH9V81xoqTwGuT3qwkZWbwY1TtTQwpr3DjHU2TSwMn
```

94
scripts/config-table-generator.py Normal file
View File

@ -0,0 +1,94 @@
import requests
def extract_config_param(line, param):
return line.split(f"{param}: ")[1].strip()[1:].split('"')[0].strip()
def remove_extra_char(string, char):
if string[-1] == char:
string = string[:-1]
return string
def parse_table_heading(line):
table_heading = line.split("##")[1].strip()
# ensure only config blocks are captured
if "config" not in table_heading or "Application-level" in table_heading:
return None, False
else:
table_heading = table_heading.title()
# ensuring heading consistency
words = [
("Configuration", "Config"),
("And", "and"),
("Lightpush", "Light Push"),
("Json-Rpc", "JSON-RPC"),
("Rest Http", "REST HTTP"),
("Dns", "DNS"),
("V5", "v5"),
("Websocket", "WebSocket")
]
for word in words:
table_heading = table_heading.replace(word[0], word[1])
return "## " + table_heading, True
def extract_config(config_path):
# fetch the config file
config_data = requests.get(config_path)
if config_data.status_code == 200:
config_data = config_data.text.split("\n")
else:
exit("An error occurred while fetching the config file")
config_table = "## Application-Level Config\n\n| Name | Default Value | Description |\n| - | - | - |\n"
row = {"name": None, "default": "", "description": None}
for line in config_data:
line = line.strip()
# we've left a config block
if line == "":
# check if there's a config
if row["description"] is not None and row["name"] != "topics":
# patch since this config executes Nim
if row["name"] == "store-message-retention-policy":
row["default"] = "time:172800"
# patch as nat config name is missing
if row["name"] is None:
row["name"], row["default"] = "nat", "any"
row["description"] += ". Must be one of: any, none, upnp, pmp, extip:<IP>"
config_table += f"| `{row['name']}` | {row['default']} | {row['description']} |\n"
row = {"name": None, "default": "", "description": None}
# create a new config config_table
if line.startswith("## "):
table_heading, is_valid_heading = parse_table_heading(line)
if is_valid_heading:
config_table += f"\n{table_heading}\n\n| Name | Default Value | Description |\n| - | - | - |\n"
# extract the config name
if line.startswith("name:"):
row["name"] = extract_config_param(line, "name")
# extract the config default value
if line.startswith("defaultValue:"):
default_value = line.split("defaultValue: ")[1].strip()
if '""' not in default_value:
default_value = f"`{remove_extra_char(default_value, ',')}`".replace('"', "")
if "ValidIpAddress.init" in default_value:
default_value = default_value.replace("ValidIpAddress.init(", "").replace(")", "")
row["default"] = default_value
# extract the config description
if line.startswith("desc:"):
description = remove_extra_char(extract_config_param(line, "desc"), ".").replace("|", "\|")
row["description"] = description[0].upper() + description[1:]
return config_table.replace(">", "\>")
if __name__ == "__main__":
config_path = "https://raw.githubusercontent.com/waku-org/nwaku/master/apps/wakunode2/config.nim"
table_data = extract_config(config_path)
print(table_data)

9
sidebars.js
View File

@ -64,7 +64,14 @@ const sidebars = {
"guides/nwaku/build-source",
"guides/nwaku/run-docker",
"guides/nwaku/run-docker-compose",
"guides/nwaku/configuration",
]
},
{
type: "category",
label: "Reference",
items: [
"guides/reference/node-config-methods",
"guides/reference/node-config-options",
]
},
],