Table of contents
- Configuring the cryptographic keypair
- Configuring the network
- The APIs
- Configuring WS2P
- What is UPnP
- Note on public WS2P (recommended)
- Configuring GVA
- Synchronize your node
- Tracking logs
- Go further
Title: Configure Duniter server variant Order: 9 Date: 2017-09-22 Slug: configurer Authors: elois
Configure Duniter server variant
Here is a short tutorial to configure your newly installed Duniter server node.
Warning: this tutorial is for server variant users only and in version 2.0.x or higher.
This tutorial shows how to configure duniter on command line. It is also possible to configure duniter via environment variables.
Configuring the cryptographic keypair
All duniter nodes have a cryptographic keypair, which they use to sign the information they transmit over the network. There are two types of duniter nodes:
1. member nodes: If the node's keypair corresponds to a member identity, then the node is a "member" node, and will automatically take part in the calculation of the blocks.
2. Mirror nodes: If the node's keypair does not match a member identity, then the node is "mirror" type, it will not be able to write a block, but will still be useful for network resilience and for responding to client requests.
By default this keypair is random, so the duniter node is a mirror node. You can change the node's keypair with this command:
duniter wizard key
Please note that the keypair filled in with this command will be stored in clear on the disk!
To avoid this you can choose to set the keypair to be inserted only at the start of the node so that your keypair will be stored only in RAM, so add the option
--keyprompt to the node start command.
Having several nodes with the same keypair
It is possible to have several member nodes with your member keypair but in this case you must assign a unique identifier to each of your nodes, this unique identifier is named prefix because its unique role is to prefix the nonce of the blocks you are calculating in order to prevent two of your nodes from calculating the same proof.
On your 1st node: You don't have to do anything, the prefix is
1 by default.
On your second node:
duniter config --prefix 2
On your third node:
duniter config --prefix 3
The prefix must be an integer between
Configuring the network
2.0.x there are two APIs (Application Programming Interface) allowing your node to communicate with other programs.
- WS2P (WebSocketToPeer): this API is dedicated to inter-node communication, i.e. between your duniter node and other nodes of the same currency. WS2P is enabled by default on your duniter node.
- GVA (Graphql Verification Api): this API is dedicated to the communication with client software (Ğecko, Tikka, ğcli, etc), it can also be used by any external program wishing to request the network (a website that would like to check the presence of a blockchain transaction for example). GVA is disabled by default on your duniter node.
Notion of WS2P Public and WS2P Private
WS2P Private = outgoing WS2P connections. WS2P public = incoming WS2P connections.
A WS2P connection between two duniter nodes always has a direction, it is initiated by one of the nodes which is therefore the initiator and the other is the acceptor. Connections that your duniter node initiates with other duniter nodes are outbound, depending on your private WS2P configuration. On the other hand, connections that your duniter node accepts from another node are incoming, depending on your public WS2P configuration.
This mode is enabled by default and configured automatically.
To change the maximum number of simultaneous outgoing WS2P connections:
duniter config --ws2p-max-private <count>
This mode is disabled by default, in order for it to work you must configure a WS2P endpoint that other duniter nodes will be able to use to reach you.
First enable the public WS2P mode:
duniter config --ws2p-public
Configure a WS2P endpoint
For WS2P Public to work you must configure a WS2P endpoint that other duniter nodes will be able to use to reach you. There are three possible cases:
You host your node at home and you want to use UPnP (enabled by default) and then you don't have to do anything, duniter will automatically control your box to configure an endpoint.
You host your node at home but you don't want to use UPnP (For security reasons for example).
You host your node on a dedicated server on a hosting provider, so you don't have UPnP.
If you are in case 2 or 3, you must configure an access point manually:
duniter config --ws2p-noupnp --ws2p-port PORT --ws2p-host HOST --ws2p-remote-port REMOTE_PORT --ws2p-remote-host REMOTE_HOST
The "remote" options correspond, for example, to a box that would do a NAT to your machine, or to a nginx/apache that would do a reverse proxy to your Duniter instance. If your duniter node is connected to the internet through a box, you will need to configure port forwarding on your box by redirecting the port of your choice to the machine running your duniter node. In addition, in order to keep the local IP of this machine unchanged, you must ask your box to assign a permanent DHCP lease to it.
Maximum number of public WS2P connections
To change the maximum number of simultaneous incoming WS2P connections :
duniter config --ws2p-max-public <count>
Check your WS2P configuration
duniter ws2p show-conf
Define a path for your WS2P endpoint
duniter config --ws2p-remote-path <path>
Use only if you want to place your duniter node behind a reverse proxy.
This option allows you to add a path for your public WS2P access point.
Your WS2P access point will then be:
ws:// will be replaced by
wss:// if you set the remote port to 443.
WS2P preferred/privileged nodes
See WS2P: preferred and privileged nodes
What is UPnP
Universal Plug and Play (UPnP) is a protocol that, if enabled on your Internet box, allows the programs you use to configure the network themselves by " controlling " your box.
UPnP has the advantage of being practical, because it avoids you having to configure the network yourself, but in return you have to trust the programs you use because a malicious program can use UPnP to open your network in an unwanted way.
If you are not afraid of the command line and you are demanding on the security of your local network, we recommend you to disable UPnP.
If you install duniter on a VPS or a dedicated server you will have to do without UPnP anyway.
Note on public WS2P (recommended)
Nodes with public WS2P are necessary for the duniter network to work, and the more nodes with public WS2P, the more decentralized the network is.
This mode is optional if only because technically it is sometimes difficult or even impossible to be accessible from the outside (node behind a 4G router for example).
GVA is still disabled by default, to enable it you have 2 choices:
- Use command
duniter gva configure, you will be invited to configure GVA interactively.
- Set environment variable
It is also possible to manually edit
conf.json file :
GVA server listen to
GVA subscriptions websocket server listen to
Each parameter can be redefined by the environment variable of the parameter name in uppercase prefixed by
For example, the
remotePath parameter can be redefined by the
DUNITER_GVA_REMOTE_PATH environment variable.
Synchronize your node
To join the network of a currency you must synchronize with a node already on this network:
duniter sync DUNITER_NODE_HOST:DUNITER_NODE_PORT
For Ğ1, if you don't know any node you can choose the official node
There are four different commands depending on whether or not you want to demonize your Duniter instance and whether or not you want to use the web-ui:
duniter start duniter direct_start duniter webstart duniter direct_webstart
direct_ prefix cancels the demonization, but then you will have to leave your terminal open or use nohup or screen or similar.
In addition, the
direct_webstart commands accept the
--keyprompt option (see the keypair section).
See the advanced commands.