There are 2 different network interfaces which are covered by their respective section:
rest: ... p2p: ...
listen: listen address
tls: (optional) enables TLS and disables plain HTTP if provided
cert_file: path to server X.509 certificate chain file, must be PEM-encoded and contain at least 1 item
priv_key_file: path to server private key file, must be PKCS8 with single PEM-encoded, unencrypted key
cors: (optional) CORS configuration, if not provided, CORS is disabled
allowed_origins: (optional) allowed origins, if none provided, echos request origin, note that an origin should include a scheme, for example:
max_age_secs: (optional) maximum CORS caching time in seconds, if none provided, caching is disabled
In order to enable TLS there must be provided certificate and private key files.
jormungandr itself does not have any specific requirements for TLS certificates and you
may give whatever you want including self-signed certificates as long as you do not intend to use
The cryptography standards used by
jcli as well as by all modern browsers and many http clients
place the following requirements on certificates:
- A certificate should adhere to X.509 v3 with appropriate key usage settings and subject alternative name.
- A certificate must not be self-signed.
Given that, your options are to either get a certificate from a well-known CA (Let's Encrypt will
jcli uses Mozilla's CA bundle for verification) or create your own local CA and provide the
root certificate to
jcli via the
EasyRSA is a set of scripts that use OpenSSL and give you an easier experience with setting up your local CA. You can download them here.
Configure your CA. To do that, create the configuration file (
cp vars.example vars); open it with the text editor of your choise (for example,
vim vars); uncomment and edit fields you need to change. Each CA needs to edit these lines (find then in your
varsfile according to their organization structure:
#set_var.EASYRSA_REQ_COUNTRY----"US" #set_var.EASYRSA_REQ_PROVINCE---"California" #set_var.EASYRSA_REQ_CITY---"San.Francisco" #set_var.EASYRSA_REQ_ORG----"Copyleft.Certificate.Co" #set_var.EASYRSA_REQ_EMAIL--"firstname.lastname@example.org" #set_var.EASYRSA_REQ_OU-----"My.Organizational.Unit"
When your configuration is ready, run
./easyrsa build-ca nopass. You will be prompted to set the name of your CA.
./easyrsa gen-req server nopassto create a new private key and a certificate signing request. You will be prompted to enter the host name (
localhostfor local testing).
./easyrsa sign-req server serverto sign the request.
To use the generated certificate, use it and the corresponding key in your
rest: tls: cert_file: <path to server.crt> priv_key_file: <path to server.key>
Use the CA certificate with
trusted_peers: (optional) the list of nodes' multiaddr to connect to in order to bootstrap the p2p topology (and bootstrap our local blockchain). Note that you can use a DNS name in the following format:
dns4if you want the peer to connect with IPv6.
public_address: multiaddr the address to listen from and accept connection from. This is the public address that will be distributed to other peers of the network that may find interest into participating to the blockchain dissemination with the node. Currently only TCP is supported.
public_id: (optional) This is a static identifier, 24 bytes encoded in hexadecimal. They are used to bootstrap the connection to the node if the node introduce itself as a trusted peer. Most of the user don't need to set this value and in fact we are working toward potentially removing the need for this value.
listen_address: (optional) multiaddr specifies the address the node will listen to to receive p2p connection. Can be left empty and the node will listen to whatever value was given to
topics_of_interest: (optional) the different topics we are interested to hear about:
messages: notify other peers this node is interested about Transactions typical setting for a non mining node:
"low". For a stakepool:
blocks: notify other peers this node is interested about new Blocks. typical settings for a non mining node:
"normal". For a stakepool:
max_connections: the maximum number of P2P connections this node should maintain. If not specified, an internal limit is used by default
max_inbound_connections: the maximum number of client P2P connections this node should keep open.
policy: (optional) set the setting for the policy module
quarantine_durationset the time to leave a node in quarantine before allowing it back (or not) into the fold. It is recommended to leave the default value
quarantine_whitelistset a trusted list of peers that will not be quarantined in any circumstance. It should be a list of valid addresses, for example:
["/ip4/127.0.0.1/tcp/3000"]. By default this list is empty,
layers: (optional) set the settings for some of the poldercast custom layers (see below)
max_unreachable_nodes_to_connect_per_event: (optional) set the maximum number of unreachable nodes to contact at a time for every new notification. Every time a new propagation event is triggered, the node will select randomly a certain amount of unreachable nodes to connect to in addition to the one selected by other p2p topology layer
gossip_interval: (optional) interval to start gossiping with new nodes, changing the value will affect the bandwidth. The more often the node will gossip the more bandwidth the node will need. The less often the node gossips the less good the resilience to node churn.
topology_force_reset_interval: (optional) If this value is set, it will trigger a force reset of the topology layers. The default is to not do force the reset. It is recommended to let the protocol handle it.
max_bootstrap_attempts: (optional) number of times to retry bootstrapping from trusted peers. If not set, default behavior, the bootstrap process will keep retrying indefinitely, until completed successfully. If set to 0 (zero), the node will skip bootstrap all together -- even if trusted peers are defined. If the node fails to bootstrap from any of the trusted peers and the number of bootstrap retry attempts is exceeded, then the node will continue to run without completing the bootstrap process. This will allow the node to act as the first node in the p2p network (i.e. genesis node), or immediately begin gossip with the trusted peers if any are defined.
The trusted peers is a concept that is not fully implemented yet. One of the key element for now is that this is the first node any node tries to connect in order to meet new nodes. Right now, as far as we know, only one of them is needed. IOHK provides a few others for redundancy.
Jörmungandr provides multiple additional layers to the
poldercast default ones:
the preferred list or the bottle in the sea.
this is a special list that allows to connect multiple nodes together without relying on the auto peer discovery. All entries in the preferred list are also whitelisted automatically, so they cannot be quarantined.
view_max: this is the number of entries to show in the view each round the layer will randomly select up to
view_maxentries from the whole preferred_list.peers list of entries. [default: 20]
peers: the list of peers to keep in the preferred list [default: EMPTY]
Also, the preferred list will never be quarantined or blacklisted, the node will
attempt to connect to (up to
view_max of) these nodes every time, even if some
are down, unreachable or not operated anymore.
COMPATIBILITY NOTE: in near future the peer list will be only a list of addresses and the ID part will not be necessary.
p2p: layers: preferred_list: view_max: 20 peers: - address: '/ip4/127.0.0.1/tcp/2029' id: 019abc... - ...
This is needed to advertise your node as a trusted peer.
If not set, the node will generate a random ID, which is fine for a regular user.
You can generate a public id with openssl, for example:
openssl rand -hex 24
This is optional an optional value to set. The default is:
messages: low blocks: normal
These value makes sense for most of the users that are not running stake pools or that are not even publicly reachable.
However for a publicly reachable node, the recommended setting would be:
messages: normal blocks: normal
and for a stake pool
messages: high blocks: high