Configuring the Nuts Node
The Nuts node can be configured using a YAML configuration file, environment variables and commandline params.
The parameters follow the following convention:
$ nuts --parameter X is equal to $ NUTS_PARAMETER=X nuts is equal to parameter: X in a yaml file.
Or for this piece of yaml
nested:
parameter: X
is equal to $ nuts --nested.parameter X is equal to $ NUTS_NESTED_PARAMETER=X nuts
Config parameters for engines are prepended by the engine.ConfigKey by default (configurable):
engine:
nested:
parameter: X
is equal to $ nuts --engine.nested.parameter X is equal to $ NUTS_ENGINE_NESTED_PARAMETER=X nuts
While most options are a single value, some are represented as a list (indicated with the square brackets in the table below).
To provide multiple values through flags or environment variables you can separate them with a comma (var1,var2).
If you need to provide an actual value with a comma, you can escape it with a backslash (\,) to avoid it having split into multiple values.
Ordering
Command line parameters have the highest priority, then environment variables, then parameters from the configfile and lastly defaults.
The location of the configfile is determined by the environment variable NUTS_CONFIGFILE or the commandline parameter --configfile. If both are missing the default location ./nuts.yaml is used.
CLI > ENV > Config File > Defaults
Server options
The following options can be configured on the server:
Key |
Default |
Description |
|---|---|---|
configfile |
nuts.yaml |
Nuts config file |
cpuprofile |
When set, a CPU profile is written to the given path. Ignored when strictmode is set. |
|
datadir |
./data |
Directory where the node stores its files. |
internalratelimiter |
true |
When set, expensive internal calls are rate-limited to protect the network. Always enabled in strict mode. |
loggerformat |
text |
Log format (text, json) |
strictmode |
false |
When set, insecure settings are forbidden. |
verbosity |
info |
Log level (trace, debug, info, warn, error) |
tls.certfile |
PEM file containing the certificate for the server (also used as client certificate). |
|
tls.certheader |
Name of the HTTP header that will contain the client certificate when TLS is offloaded. |
|
tls.certkeyfile |
PEM file containing the private key of the server certificate. |
|
tls.offload |
Whether to enable TLS offloading for incoming connections. Enable by setting it to ‘incoming’. If enabled ‘tls.certheader’ must be configured as well. |
|
tls.truststorefile |
truststore.pem |
PEM file containing the trusted CA certificates for authenticating remote servers. |
tls.crl.maxvaliditydays |
0 |
The number of days a CRL can be outdated, after that it will hard-fail. |
Auth |
||
auth.clockskew |
5000 |
Allowed JWT Clock skew in milliseconds |
auth.contractvalidators |
[irma,uzi,dummy] |
sets the different contract validators to use |
auth.publicurl |
public URL which can be reached by a users IRMA client, this should include the scheme and domain: https://example.com. Additional paths should only be added if some sort of url-rewriting is done in a reverse-proxy. |
|
auth.http.timeout |
30 |
HTTP timeout (in seconds) used by the Auth API HTTP client |
auth.irma.autoupdateschemas |
true |
set if you want automatically update the IRMA schemas every 60 minutes. |
auth.irma.schememanager |
pbdf |
IRMA schemeManager to use for attributes. Can be either ‘pbdf’ or ‘irma-demo’. |
Crypto |
||
crypto.storage |
fs |
Storage to use, ‘fs’ for file system, vaultkv for Vault KV store, default: fs. |
crypto.vault.address |
The Vault address. If set it overwrites the VAULT_ADDR env var. |
|
crypto.vault.pathprefix |
kv |
The Vault path prefix. default: kv. |
crypto.vault.timeout |
5s |
Timeout of client calls to Vault, in Golang time.Duration string format (e.g. 5s). |
crypto.vault.token |
The Vault token. If set it overwrites the VAULT_TOKEN env var. |
|
Events |
||
events.nats.hostname |
localhost |
Hostname for the NATS server |
events.nats.port |
4222 |
Port where the NATS server listens on |
events.nats.storagedir |
Directory where file-backed streams are stored in the NATS server |
|
events.nats.timeout |
30 |
Timeout for NATS server operations |
HTTP |
||
http.default.address |
:1323 |
Address and port the server will be listening to |
http.default.log |
metadata |
What to log about HTTP requests. Options are ‘nothing’, ‘metadata’ (log request method, URI, IP and response code), and ‘metadata-and-body’ (log the request and response body, in addition to the metadata). |
http.default.tls |
Whether to enable TLS for the default interface, options are ‘disabled’, ‘server’, ‘server-client’. Leaving it empty is synonymous to ‘disabled’, |
|
http.default.auth.type |
Whether to enable authentication for the default interface, specify ‘token’ for bearer token authentication. |
|
http.default.cors.origin |
[] |
When set, enables CORS from the specified origins on the default HTTP interface. |
JSONLD |
||
jsonld.contexts.localmapping |
This setting allows mapping external URLs to local files for e.g. preventing external dependencies. These mappings have precedence over those in remoteallowlist. |
|
jsonld.contexts.remoteallowlist |
In strict mode, fetching external JSON-LD contexts is not allowed except for context-URLs listed here. |
|
Network |
||
network.bootstrapnodes |
[] |
List of bootstrap nodes (‘<host>:<port>’) which the node initially connect to. |
network.connectiontimeout |
5000 |
Timeout before an outbound connection attempt times out (in milliseconds). |
network.disablenodeauthentication |
false |
Disable node DID authentication using client certificate, causing all node DIDs to be accepted. Unsafe option, only intended for workshops/demo purposes so it’s not allowed in strict-mode. Automatically enabled when TLS is disabled. |
network.enablediscovery |
true |
Whether to enable automatic connecting to other nodes. |
network.enabletls |
true |
Whether to enable TLS for gRPC connections, which can be disabled for demo/development purposes. It is NOT meant for TLS offloading (see ‘tls.offload’). Disabling TLS is not allowed in strict-mode. |
network.grpcaddr |
:5555 |
Local address for gRPC to listen on. If empty the gRPC server won’t be started and other nodes will not be able to connect to this node (outbound connections can still be made). |
network.maxbackoff |
24h0m0s |
Maximum between outbound connections attempts to unresponsive nodes (in Golang duration format, e.g. ‘1h’, ‘30m’). |
network.nodedid |
Specifies the DID of the organization that operates this node, typically a vendor for EPD software. It is used to identify the node on the network. If the DID document does not exist of is deactivated, the node will not start. |
|
network.protocols |
[] |
Specifies the list of network protocols to enable on the server. They are specified by version (1, 2). If not set, all protocols are enabled. |
network.v2.diagnosticsinterval |
5000 |
Interval (in milliseconds) that specifies how often the node should broadcast its diagnostic information to other nodes (specify 0 to disable). |
network.v2.gossipinterval |
5000 |
Interval (in milliseconds) that specifies how often the node should gossip its new hashes to other nodes. |
Storage |
||
storage.bbolt.backup.directory |
Target directory for BBolt database backups. |
|
storage.bbolt.backup.interval |
0s |
Interval, formatted as Golang duration (e.g. 10m, 1h) at which BBolt database backups will be performed. |
storage.redis.address |
Redis database server address. This can be a simple ‘host:port’ or a Redis connection URL with scheme, auth and other options. |
|
storage.redis.database |
Redis database name, which is used as prefix every key. Can be used to have multiple instances use the same Redis instance. |
|
storage.redis.password |
Redis database password. If set, it overrides the username in the connection URL. |
|
storage.redis.username |
Redis database username. If set, it overrides the username in the connection URL. |
|
storage.redis.sentinel.master |
Name of the Redis Sentinel master. Setting this property enables Redis Sentinel. |
|
storage.redis.sentinel.nodes |
[] |
Addresses of the Redis Sentinels to connect to initially. Setting this property enables Redis Sentinel. |
storage.redis.sentinel.password |
Password for authenticating to Redis Sentinels. |
|
storage.redis.sentinel.username |
Username for authenticating to Redis Sentinels. |
|
storage.redis.tls.truststorefile |
PEM file containing the trusted CA certificate(s) for authenticating remote Redis servers. Can only be used when connecting over TLS (use ‘rediss://’ as scheme in address). |
This table is automatically generated using the configuration flags in the core and engines. When they’re changed the options table must be regenerated using the Makefile:
$ make update-docs