<titledata-rh="true">Node Configuration Options | Waku Documentation</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://docs.waku.org/run-node/config-options"><metadata-rh="true"property="og:locale"content="en_GB"><metadata-rh="true"name="docusaurus_locale"content="en-GB"><metadata-rh="true"name="docsearch:language"content="en-GB"><metadata-rh="true"name="keywords"content="waku, web3"><metadata-rh="true"name="image"content="https://docs.waku.org/_og/42afe7978e5d4dfb6e31685f9b08e26dbfe9a1d4.png"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="Node Configuration Options | Waku Documentation"><metadata-rh="true"name="description"content="Here are the available node configuration options, along with their default values and descriptions:"><metadata-rh="true"property="og:description"content="Here are the available node configuration options, along with their default values and descriptions:"><linkdata-rh="true"rel="icon"href="/theme/image/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://docs.waku.org/run-node/config-options"><linkdata-rh="true"rel="alternate"href="https://docs.waku.org/run-node/config-options"hreflang="en-GB"><linkdata-rh="true"rel="alternate"href="https://docs.waku.org/run-node/config-options"hreflang="x-default"><linkrel="alternate icon"type="image/png"href="/theme/image/favicon.png">
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="application-level-config">Application-level config<ahref="#application-level-config"class="hash-link"aria-label="Direct link to Application-level config"title="Direct link to Application-level config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>config-file</code></td><td></td><td>Loads configuration from a TOML file (cmd-line parameters take precedence)</td></tr><tr><td><code>protected-shard</code></td><td><code>newSeq[ProtectedShard](0)</code></td><td>Shards and its public keys to be used for message validation, shard:pubkey. Argument may be repeated</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="log-config">Log config<ahref="#log-config"class="hash-link"aria-label="Direct link to Log config"title="Direct link to Log config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>log-level</code></td><td><code>logging.LogLevel.INFO</code></td><td>Sets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL</td></tr><tr><td><code>log-format</code></td><td><code>logging.LogFormat.TEXT</code></td><td>Specifies what kind of logs should be written to stdout. Supported formats: TEXT, JSON</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="general-node-config">General node config<ahref="#general-node-config"class="hash-link"aria-label="Direct link to General node config"title="Direct link to General node config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>cluster-id</code></td><td><code>0</code></td><td>Cluster id that the node is running in. Node in a different cluster id is disconnected</td></tr><tr><td><code>agent-string</code></td><td><code>nwaku</code></td><td>Node agent string which is used as identifier in network</td></tr><tr><td><code>nodekey</code></td><td></td><td>P2P node private key as 64-char hex string</td></tr><tr><td><code>listen-address</code></td><td><code>defaultListenAddress()</code></td><td>Listening address for LibP2P (and Discovery v5, if enabled) traffic</td></tr><tr><td><code>tcp-port</code></td><td><code>60000</code></td><td>TCP listening port</td></tr><tr><td><code>ports-shift</code></td><td><code>0</code></td><td>Add a shift to all port numbers</td></tr><tr><td><code>nat</code></td><td>any</td><td>Specify method to use for determining public address. Must be one of: any, none, upnp, pmp, extip:IP</td></tr><tr><td><code>ext-multiaddr</code></td><td></td><td>External multiaddresses to advertise to the network. Argument may be repeated</td></tr><tr><td><code>ext-multiaddr-only</code></td><td><code>false</code></td><td>Only announce external multiaddresses</td></tr><tr><td><code>max-connections</code></td><td><code>50</code></td><td>Maximum allowed number of libp2p connections</td></tr><tr><td><code>relay-service-ratio</code></td><td><code>"60:40"</code></td><td>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.)</td></tr><tr><td><code>peer-store-capacity</code></td><td></td><td>Maximum stored peers in the peerstore</td></tr><tr><td><code>peer-persistence</code></td><td><code>false</code></td><td>Enable peer persistence</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="dns-addrs-config">DNS addrs config<ahref="#dns-addrs-config"class="hash-link"aria-label="Direct link to DNS addrs config"title="Direct link to DNS addrs config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>dns-addrs</code></td><td><code>true</code></td><td>Enable resolution of <code>dnsaddr</code>, <code>dns4</code> or <code>dns6</code> multiaddrs</td></tr><tr><td><code>dns-addrs-name-server</code></td><td><code>["1.1.1.1", "1.0.0.1"]</code></td><td>DNS name server IPs to query for DNS multiaddrs resolution. Argument may be repeated</td></tr><tr><td><code>dns4-domain-name</code></td><td></td><td>The domain name resolving to the node's public IPv4 address</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="relay-config">Relay config<ahref="#relay-config"class="hash-link"aria-label="Direct link to Relay config"title="Direct link to Relay config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>relay</code></td><td><code>true</code></td><td>Enable relay protocol: true|false</td></tr><tr><td><code>relay-peer-exchange</code></td><td><code>false</code></td><td>Enable gossipsub peer exchange in relay protocol: true|false</td></tr><tr><td><code>rln-relay</code></td><td><code>false</code></td><td>Enable spam protection through rln-relay: true|false</td></tr><tr><td><code>rln-relay-cred-path</code></td><td></td><td>The path for persisting rln-relay credential</td></tr><tr><td><code>rln-relay-membership-index</code></td><td></td><td>The index of the onchain commitment to use</td></tr><tr><td><code>rln-relay-dynamic</code></td><td><code>false</code></td><td>Enable waku-rln-relay with on-chain dynamic group management: true|false</td></tr><tr><td><code>rln-relay-id-key</code></td><td></td><td>Rln relay identity secret key as a Hex string</td></tr><tr><td><code>rln-relay-id-commitment-key</code></td><td></td><td>Rln relay identity commitment key as a Hex string</td></tr><tr><td><code>rln-relay-eth-client-address</code></td><td><code>ws://localhost:8540/</code></td><td>WebSocket address of an Ethereum testnet client e.g., <code>ws://localhost:8540/</code></td></tr><tr><td><code>rln-relay-eth-contract-address</code></td><td></td><td>Address of membership contract on an Ethereum testnet</td></tr><tr><td><code>rln-relay-eth-private-key</code></td><td></td><td>Private key for broadcasting transactions</td></tr><tr><td><code>execute</code></td><td><code>false</code></td><td>Runs the registration function on-chain. By default, a dry-run will occur</td></tr><tr><td><code>rln-relay-cred-password</code></td><td></td><td>Password for encrypting RLN credentials</td></tr><tr><td><code>rln-relay-bandwidth-threshold</code></td><td><code>0 # to maintain backwards compatibility</code></td><td>Message rate in bytes/sec after which verification of proofs should happen</td></tr><tr><td><code>staticnode</code></td><td></td><td>Peer multiaddr to directly connect with. Argument may be repeated</td></tr><tr><td><code>keep-alive</code></td><td><code>false</code></td><td>Enable keep-alive for idle connections: true|false</td></tr><tr><td><code>pubsub-topic</code></td><td></td><td>Default pubsub topic to subscribe to. Argument may be repeated. <strong>Deprecated!</strong> Please use <code>shard</code> and/or <code>content-topic</code> instead</td></tr><tr><td><code>shard</code></td><td></td><td>Shard to subscribe to. Argument may be repeated</td></tr><tr><td><code>num-shards-in-network</code></td><td></td><td>Number of shards in the network. Used to map content topics to shards when using autosharding</td></tr><tr><td><code>content-topic</code></td><td></td><td>Default content topic to subscribe to. Argument may be repeated</td></tr><tr><td><code>reliability</code></td><td><code>false</code></td><td>Enable experimental reliability protocol true|false</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="store-and-message-store-config">Store and message store config<ahref="#store-and-message-store-config"class="hash-link"aria-label="Direct link to Store and message store config"title="Direct link to Store and message store config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>store</code></td><td><code>false</code></td><td>Enable/disable waku store protocol</td></tr><tr><td><code>storenode</code></td><td></td><td>Peer multiaddress to query for storage</td></tr><tr><td><code>store-message-retention-policy</code></td><td><code>time:172800</code></td><td>Message store retention policy. Time retention policy: <code>time:<seconds></code>. Capacity retention policy: <code>capacity:<count></code>. Size retention policy: <code>size:<xMB/xGB></code>. Set to <code>none</code> to disable</td></tr><tr><td><code>store-message-db-url</code></td><td><code>sqlite://store.sqlite3</code></td><td>The database connection URL for persistent storage</td></tr><tr><td><code>store-message-db-vacuum</code></td><td><code>false</code></td><td>Enable database vacuuming at start. Only supported by SQLite database engine</td></tr><tr><td><code>store-message-db-migration</code></td><td><code>true</code></td><td>Enable database migration at start</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="store-sync">Store Sync<ahref="#store-sync"class="hash-link"aria-label="Direct link to Store Sync"title="Direct link to Store Sync"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>store-sync</code></td><td><code>false</code></td><td>Enable/disable waku store sync protocol</td></tr><tr><td><code>store-sync-interval</code></td><td><code>300</code> 5 minutes</td><td>Interval between store synchronization attempts</td></tr><tr><td><code>store-sync-range</code></td><td><code>3600</code> 1 hour</td><td>Amount of time to sync</td></tr><tr><td><code>store-sync-relay-jitter</code></td><td><code>20</code> seconds</td><td>Sync range offset to account for relay's message propagation jitter</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="filter-config">Filter config<ahref="#filter-config"class="hash-link"aria-label="Direct link to Filter config"title="Direct link to Filter config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>filter</code></td><td><code>false</code></td><td>Enable filter protocol: true|false</td></tr><tr><td><code>filternode</code></td><td></td><td>Peer multiaddr to request content filtering of messages</td></tr><tr><td><code>filter-subscription-timeout</code></td><td><code>300 # 5 minutes</code></td><td>Timeout for filter subscription without ping or refresh it, in seconds. Only for v2 filter protocol</td></tr><tr><td><code>filter-max-peers-to-serve</code></td><td><code>1000</code></td><td>Maximum number of peers to serve at a time. Only for v2 filter protocol</td></tr><tr><td><code>filter-max-criteria</code></td><td><code>1000</code></td><td>Maximum number of pubsub and content topic combinations per peer at a time. Only for v2 filter protocol</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="light-push-config">Light push config<ahref="#light-push-config"class="hash-link"aria-label="Direct link to Light push config"title="Direct link to Light push config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th><th></th></tr></thead><tbody><tr><td><code>lightpush</code></td><td><code>false</code></td><td>Enable lightpush protocol: true</td><td>false</td></tr><tr><td><code>lightpushnode</code></td><td></td><td>Peer multiaddr to request lightpush of published messages</td><td></td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="rest-http-config">REST HTTP config<ahref="#rest-http-config"class="hash-link"aria-label="Direct link to REST HTTP config"title="Direct link to REST HTTP config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>rest</code></td><td><code>false</code></td><td>Enable Waku REST HTTP server: true|false</td></tr><tr><td><code>rest-address</code></td><td><code>127.0.0.1</code></td><td>Listening address of the REST HTTP server</td></tr><tr><td><code>rest-port</code></td><td><code>8645</code></td><td>Listening port of the REST HTTP server</td></tr><tr><td><code>rest-relay-cache-capacity</code></td><td><code>30</code></td><td>Capacity of the Relay REST API message cache</td></tr><tr><td><code>rest-admin</code></td><td><code>false</code></td><td>Enable access to REST HTTP Admin API: true|false</td></tr><tr><td><code>rest-allow-origin</code></td><td></td><td>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 <code>localhost:*</code>, <code>127.0.0.1:8080</code>, or allow any website with <code>*</code></td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="metrics-config">Metrics config<ahref="#metrics-config"class="hash-link"aria-label="Direct link to Metrics config"title="Direct link to Metrics config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>metrics-server</code></td><td><code>false</code></td><td>Enable the metrics server: true|false</td></tr><tr><td><code>metrics-server-address</code></td><td><code>127.0.0.1</code></td><td>Listening address of the metrics server</td></tr><tr><td><code>metrics-server-port</code></td><td><code>8008</code></td><td>Listening HTTP port of the metrics server</td></tr><tr><td><code>metrics-logging</code></td><td><code>true</code></td><td>Enable metrics logging: true|false</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="dns-discovery-config">DNS discovery config<ahref="#dns-discovery-config"class="hash-link"aria-label="Direct link to DNS discovery config"title="Direct link to DNS discovery config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>dns-discovery</code></td><td><code>false</code></td><td>Enable discovering nodes via DNS</td></tr><tr><td><code>dns-discovery-url</code></td><td></td><td>URL for DNS node list in format <code>'enrtree://<key\>@<fqdn\>'</code></td></tr><tr><td><code>dns-discovery-name-server</code></td><td><code>["1.1.1.1", "1.0.0.1"]</code></td><td>DNS name server IPs to query. Argument may be repeated</td></tr><tr><td><code>rendezvous</code></td><td><code>true</code></td><td>Enable waku rendezvous discovery server</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="discv5-config">Discv5 config<ahref="#discv5-config"class="hash-link"aria-label="Direct link to Discv5 config"title="Direct link to Discv5 config"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>discv5-discovery</code></td><td><code>false</code></td><td>Enable discovering nodes via Node Discovery v5</td></tr><tr><td><code>discv5-udp-port</code></td><td><code>9000</code></td><td>Listening UDP port for Node Discovery v5</td></tr><tr><td><code>discv5-bootstrap-node</code></td><td></td><td>Text-encoded ENR for bootstrap node. Used when connecting to the network. Argument may be repeated</td></tr><tr><td><code>discv5-enr-auto-update</code></td><td><code>false</code></td><td>Discovery can automatically update its ENR with the IP address</td></tr><tr><td><code>discv5-table-ip-limit</code></td><td><code>10</code></td><td>Maximum amount of nodes with the same IP in discv5 routing tables</td></tr><tr><td><code>discv5-bucket-ip-limit</code></td><td><code>2</code></td><td>Maximum amount of nodes with the same IP in discv5 routing table buckets</td></tr><tr><td><code>discv5-bits-per-hop</code></td><td><code>1</code></td><td>Kademlia's b variable, increase for less hops per lookup</td></tr></tbody></table>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="waku-peer-exchange-config">Waku peer exchange config<ahref="#waku-peer-exchange-config"class="hash-link"aria-label="Direct link to Waku peer exchange config"title="Direct link to Waku peer exchange config"></a></h2>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="websocket-config">WebSocket config<ahref="#websocket-config"class="hash-link"aria-label="Direct link to WebSocket config"title="Direct link to WebSocket config"></a></h2>
<h2class="anchor anchorWithHideOnScrollNavbar_WYt5"id="non-relay-request-response-protocol-dos-protection-configuration">Non-relay, request-response protocol DOS protection configuration<ahref="#non-relay-request-response-protocol-dos-protection-configuration"class="hash-link"aria-label="Direct link to Non-relay, request-response protocol DOS protection configuration"title="Direct link to Non-relay, request-response protocol DOS protection configuration"></a></h2>
<table><thead><tr><th>Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>rate-limit</code></td><td></td><td>This is a repeatable option. Each can describe a specific rate limit configuration for a particular protocol.<br>Formatted as:<code><protocol>:volume/period<time-unit></code><br>- if protocol is not given, settings will be taken as default for un-set protocols. Ex: <code>80/2s</code><br>-Supported protocols are: <code>lightpush</code>|<code>filter</code>|<code>px</code>|<code>store</code>|<code>storev2</code>|<code>storev3</code><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 <code>h</code>|<code>m</code>|<code>s</code>|<code>ms</code><br>- <code>storev2</code> and <code>storev3</code> takes precedence over <code>store</code> 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><code>--rate-limit="100/1s"</code> - default for all protocols if not set otherwise.<br><code>--rate-limit="lightpush:0/0s"</code> - lightpush protocol will not be rate-limited.<br><code>--rate-limit="store:130/1500ms"</code> - both store-v3 and store-v2 will apply 130 request per each 1500ms separately.<br><code>--rate-limit="px:10/1h"</code> PeerExchange will serve only 10 requests every hour.<br><code>--rate-limit="filter:8/5m"</code> - will allow 8 subs/unsubs/ping requests for each subscriber within every 5 min.</td></tr></tbody></table>
