config-options.md
1 --- 2 title: Node Configuration Options 3 hide_table_of_contents: true 4 displayed_sidebar: runNode 5 --- 6 7 Here are the available node configuration options, along with their default values and descriptions: 8 9 ## Application-level config 10 11 | Name | Default Value | Description | 12 | ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- | 13 | `config-file` | | Loads configuration from a TOML file (cmd-line parameters take precedence) | 14 | `protected-shard` | `newSeq[ProtectedShard](0)` | Shards and its public keys to be used for message validation, shard:pubkey. Argument may be repeated | 15 16 ## Log config 17 18 | Name | Default Value | Description | 19 | ------------ | ------------------------ | -------------------------------------------------------------------------------------------------- | 20 | `log-level` | `logging.LogLevel.INFO` | Sets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL | 21 | `log-format` | `logging.LogFormat.TEXT` | Specifies what kind of logs should be written to stdout. Supported formats: TEXT, JSON | 22 23 ## General node config 24 25 | Name | Default Value | Description | 26 | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 27 | `cluster-id` | `0` | Cluster id that the node is running in. Node in a different cluster id is disconnected | 28 | `agent-string` | `nwaku` | Node agent string which is used as identifier in network | 29 | `nodekey` | | P2P node private key as 64-char hex string | 30 | `listen-address` | `defaultListenAddress()` | Listening address for LibP2P (and Discovery v5, if enabled) traffic | 31 | `tcp-port` | `60000` | TCP listening port | 32 | `ports-shift` | `0` | Add a shift to all port numbers | 33 | `nat` | any | Specify method to use for determining public address. Must be one of: any, none, upnp, pmp, extip:IP | 34 | `ext-multiaddr` | | External multiaddresses to advertise to the network. Argument may be repeated | 35 | `ext-multiaddr-only` | `false` | Only announce external multiaddresses | 36 | `max-connections` | `50` | Maximum allowed number of libp2p connections | 37 | `relay-service-ratio` | `"60:40"` | This percentage ratio represents the relay peers to service peers. For example, 60:40, tells that 60% of the max-connections will be used for relay protocol and the other 40% of max-connections will be reserved for other service protocols (e.g., filter, lightpush, store, metadata, etc.) | 38 | `peer-store-capacity` | | Maximum stored peers in the peerstore | 39 | `peer-persistence` | `false` | Enable peer persistence | 40 41 ## DNS addrs config 42 43 | Name | Default Value | Description | 44 | ----------------------- | ------------------------ | ------------------------------------------------------------------------------------ | 45 | `dns-addrs` | `true` | Enable resolution of `dnsaddr`, `dns4` or `dns6` multiaddrs | 46 | `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 | 47 | `dns4-domain-name` | | The domain name resolving to the node's public IPv4 address | 48 49 ## Relay config 50 51 | Name | Default Value | Description | 52 | -------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | 53 | `relay` | `true` | Enable relay protocol: true\|false | 54 | `relay-peer-exchange` | `false` | Enable gossipsub peer exchange in relay protocol: true\|false | 55 | `rln-relay` | `false` | Enable spam protection through rln-relay: true\|false | 56 | `rln-relay-cred-path` | | The path for persisting rln-relay credential | 57 | `rln-relay-membership-index` | | The index of the onchain commitment to use | 58 | `rln-relay-dynamic` | `false` | Enable waku-rln-relay with on-chain dynamic group management: true\|false | 59 | `rln-relay-id-key` | | Rln relay identity secret key as a Hex string | 60 | `rln-relay-id-commitment-key` | | Rln relay identity commitment key as a Hex string | 61 | `rln-relay-eth-client-address` | `ws://localhost:8540/` | WebSocket address of an Ethereum testnet client e.g., `ws://localhost:8540/` | 62 | `rln-relay-eth-contract-address` | | Address of membership contract on an Ethereum testnet | 63 | `rln-relay-eth-private-key` | | Private key for broadcasting transactions | 64 | `execute` | `false` | Runs the registration function on-chain. By default, a dry-run will occur | 65 | `rln-relay-cred-password` | | Password for encrypting RLN credentials | 66 | `rln-relay-bandwidth-threshold` | `0 # to maintain backwards compatibility` | Message rate in bytes/sec after which verification of proofs should happen | 67 | `staticnode` | | Peer multiaddr to directly connect with. Argument may be repeated | 68 | `keep-alive` | `false` | Enable keep-alive for idle connections: true\|false | 69 | `pubsub-topic` | | Default pubsub topic to subscribe to. Argument may be repeated. **Deprecated!** Please use `shard` and/or `content-topic` instead | 70 | `shard` | | Shard to subscribe to. Argument may be repeated | 71 | `num-shards-in-network` | | Number of shards in the network. Used to map content topics to shards when using autosharding | 72 | `content-topic` | | Default content topic to subscribe to. Argument may be repeated | 73 | `reliability` | `false` | Enable experimental reliability protocol true\|false | 74 75 ## Store and message store config 76 77 | Name | Default Value | Description | 78 | -------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 79 | `store` | `false` | Enable/disable waku store protocol | 80 | `storenode` | | Peer multiaddress to query for storage | 81 | `store-message-retention-policy` | `time:172800` | Message store retention policy. Time retention policy: `time:<seconds>`. Capacity retention policy: `capacity:<count>`. Size retention policy: `size:<xMB/xGB>`. Set to `none` to disable | 82 | `store-message-db-url` | `sqlite://store.sqlite3` | The database connection URL for persistent storage | 83 | `store-message-db-vacuum` | `false` | Enable database vacuuming at start. Only supported by SQLite database engine | 84 | `store-message-db-migration` | `true` | Enable database migration at start | 85 86 ## Store Sync 87 88 | Name | Default Value | Description | 89 | ------------------------- | --------------- | ------------------------------------------------------------------- | 90 | `store-sync` | `false` | Enable/disable waku store sync protocol | 91 | `store-sync-interval` | `300` 5 minutes | Interval between store synchronization attempts | 92 | `store-sync-range` | `3600` 1 hour | Amount of time to sync | 93 | `store-sync-relay-jitter` | `20` seconds | Sync range offset to account for relay's message propagation jitter | 94 95 ## Filter config 96 97 | Name | Default Value | Description | 98 | ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- | 99 | `filter` | `false` | Enable filter protocol: true\|false | 100 | `filternode` | | Peer multiaddr to request content filtering of messages | 101 | `filter-subscription-timeout` | `300 # 5 minutes` | Timeout for filter subscription without ping or refresh it, in seconds. Only for v2 filter protocol | 102 | `filter-max-peers-to-serve` | `1000` | Maximum number of peers to serve at a time. Only for v2 filter protocol | 103 | `filter-max-criteria` | `1000` | Maximum number of pubsub and content topic combinations per peer at a time. Only for v2 filter protocol | 104 105 ## Light push config 106 107 | Name | Default Value | Description | | 108 | --------------- | ------------- | --------------------------------------------------------- | ----- | 109 | `lightpush` | `false` | Enable lightpush protocol: true | false | 110 | `lightpushnode` | | Peer multiaddr to request lightpush of published messages | | 111 112 ## REST HTTP config 113 114 | Name | Default Value | Description | 115 | --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 116 | `rest` | `false` | Enable Waku REST HTTP server: true\|false | 117 | `rest-address` | `127.0.0.1` | Listening address of the REST HTTP server | 118 | `rest-port` | `8645` | Listening port of the REST HTTP server | 119 | `rest-relay-cache-capacity` | `30` | Capacity of the Relay REST API message cache | 120 | `rest-admin` | `false` | Enable access to REST HTTP Admin API: true\|false | 121 | `rest-allow-origin` | | Allow cross-origin requests from the specified origin. When using the REST API in a browser, specify the origin host to get a valid response from the node REST HTTP server. This option may be repeated and can contain wildcards (?,\*) for defining URLs and ports such as `localhost:*`, `127.0.0.1:8080`, or allow any website with `*` | 122 123 ## Metrics config 124 125 | Name | Default Value | Description | 126 | ------------------------ | ------------- | ----------------------------------------- | 127 | `metrics-server` | `false` | Enable the metrics server: true\|false | 128 | `metrics-server-address` | `127.0.0.1` | Listening address of the metrics server | 129 | `metrics-server-port` | `8008` | Listening HTTP port of the metrics server | 130 | `metrics-logging` | `true` | Enable metrics logging: true\|false | 131 132 ## DNS discovery config 133 134 | Name | Default Value | Description | 135 | --------------------------- | ------------------------ | ------------------------------------------------------------ | 136 | `dns-discovery` | `false` | Enable discovering nodes via DNS | 137 | `dns-discovery-url` | | URL for DNS node list in format `'enrtree://<key\>@<fqdn\>'` | 138 | `dns-discovery-name-server` | `["1.1.1.1", "1.0.0.1"]` | DNS name server IPs to query. Argument may be repeated | 139 | `rendezvous` | `true` | Enable waku rendezvous discovery server | 140 141 ## Discv5 config 142 143 | Name | Default Value | Description | 144 | ------------------------ | ------------- | -------------------------------------------------------------------------------------------------- | 145 | `discv5-discovery` | `false` | Enable discovering nodes via Node Discovery v5 | 146 | `discv5-udp-port` | `9000` | Listening UDP port for Node Discovery v5 | 147 | `discv5-bootstrap-node` | | Text-encoded ENR for bootstrap node. Used when connecting to the network. Argument may be repeated | 148 | `discv5-enr-auto-update` | `false` | Discovery can automatically update its ENR with the IP address | 149 | `discv5-table-ip-limit` | `10` | Maximum amount of nodes with the same IP in discv5 routing tables | 150 | `discv5-bucket-ip-limit` | `2` | Maximum amount of nodes with the same IP in discv5 routing table buckets | 151 | `discv5-bits-per-hop` | `1` | Kademlia's b variable, increase for less hops per lookup | 152 153 ## Waku peer exchange config 154 155 | Name | Default Value | Description | 156 | -------------------- | ------------- | ------------------------------------------------------------------------------------------------- | 157 | `peer-exchange` | `false` | Enable waku peer exchange protocol (responder side): true\|false | 158 | `peer-exchange-node` | | Peer multiaddr to send peer exchange requests to. (enables peer exchange protocol requester side) | 159 160 ## WebSocket config 161 162 | Name | Default Value | Description | 163 | ---------------------------- | ------------- | ------------------------------------------------------ | 164 | `websocket-support` | `false` | Enable websocket: true\|false | 165 | `websocket-port` | `8000` | WebSocket listening port | 166 | `websocket-secure-support` | `false` | Enable secure websocket: true\|false | 167 | `websocket-secure-key-path` | | Secure websocket key path: '/path/to/key.txt' | 168 | `websocket-secure-cert-path` | | Secure websocket Certificate path: '/path/to/cert.txt' | 169 170 ## Non-relay, request-response protocol DOS protection configuration 171 172 | Name | Default Value | Description | 173 | ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 174 | `rate-limit` | | This is a repeatable option. Each can describe a specific rate limit configuration for a particular protocol.<br />Formatted as:`<protocol>:volume/period<time-unit>`<br />- if protocol is not given, settings will be taken as default for un-set protocols. Ex: `80/2s`<br />-Supported protocols are: `lightpush`\|`filter`\|`px`\|`store`\|`storev2`\|`storev3`<br />-volume must be an integer value, representing number of requests over the period of time allowed.<br />-period\<time-unit\> must be an integer with defined unit as one of `h`\|`m`\|`s`\|`ms`<br />- `storev2` and `storev3` takes precedence over `store` which can easy set both store protocols at once.<br />- In case of multiple set of the same protocol limit, last one will take place.<br />- if config is not set, - which is the default - means unlimited requests are allowed.<br />-filter has a bit different approach. It has a default setting applied if not overridden. Rate limit setting for filter will be applied per subscriber-peers, not globally - it must be considered when changing the setting.<br /><br />Examples:<br />`--rate-limit="100/1s"` - default for all protocols if not set otherwise.<br />`--rate-limit="lightpush:0/0s"` - lightpush protocol will not be rate-limited.<br />`--rate-limit="store:130/1500ms"` - both store-v3 and store-v2 will apply 130 request per each 1500ms separately.<br />`--rate-limit="px:10/1h"` PeerExchange will serve only 10 requests every hour.<br />`--rate-limit="filter:8/5m"` - will allow 8 subs/unsubs/ping requests for each subscriber within every 5 min. | 175 176 :::tip 177 To configure your node using the provided configuration options, have a look at the [Node Configuration Methods](/run-node/config-methods) guide. 178 :::