diff --git a/.cspell.json b/.cspell.json index 7bbc2ab..92699f3 100644 --- a/.cspell.json +++ b/.cspell.json @@ -53,7 +53,8 @@ "package-lock.json", "yarn.lock", "tsconfig.json", - "node_modules/**" + "node_modules/**", + "docs/guides/reference/node-config-options.md" ], "patterns": [ { diff --git a/docs/guides/nwaku/build-source.md b/docs/guides/nwaku/build-source.md index 0d8f9ef..31f59db 100644 --- a/docs/guides/nwaku/build-source.md +++ b/docs/guides/nwaku/build-source.md @@ -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 diff --git a/docs/guides/nwaku/run-docker-compose.md b/docs/guides/nwaku/run-docker-compose.md index 70f3d9d..aa72fc4 100644 --- a/docs/guides/nwaku/run-docker-compose.md +++ b/docs/guides/nwaku/run-docker-compose.md @@ -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 diff --git a/docs/guides/nwaku/run-docker.md b/docs/guides/nwaku/run-docker.md index 452d82d..e447df6 100644 --- a/docs/guides/nwaku/run-docker.md +++ b/docs/guides/nwaku/run-docker.md @@ -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: diff --git a/docs/guides/nwaku/configuration.md b/docs/guides/reference/node-config-methods.md similarity index 75% rename from docs/guides/nwaku/configuration.md rename to docs/guides/reference/node-config-methods.md index 740bca0..b81178d 100644 --- a/docs/guides/nwaku/configuration.md +++ b/docs/guides/reference/node-config-methods.md @@ -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]. <...> diff --git a/docs/guides/reference/node-config-options.md b/docs/guides/reference/node-config-options.md new file mode 100644 index 0000000..cbf9478 --- /dev/null +++ b/docs/guides/reference/node-config-options.md @@ -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: | +| `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:'. Capacity retention policy: 'capacity:'. 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://@' | +| `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' | \ No newline at end of file diff --git a/docs/guides/run-nwaku-node.md b/docs/guides/run-nwaku-node.md index 53eb8f1..bb6561c 100644 --- a/docs/guides/run-nwaku-node.md +++ b/docs/guides/run-nwaku-node.md @@ -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 ``` diff --git a/scripts/config-table-generator.py b/scripts/config-table-generator.py new file mode 100644 index 0000000..9ffc63a --- /dev/null +++ b/scripts/config-table-generator.py @@ -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:" + 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) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index ca3f415..f436caf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -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", ] }, ],