Mise à jour de GitLab prévue ce samedi 23 octobre 2021 à partir de 9h00 CET

Commit 7f346282 authored by Éloïs's avatar Éloïs
Browse files

[doc] user: write detailed doc for duniter-server users

parent f9c10ece
Title: Advanced commands
Order: 9
Date: 2022-10-04
Slug: advanced_commands
Authors: elois
# Advanced commands
Before reading this page, first read the on-board help in Duniter, it meets the most common needs:
duniter help
If you are new to Duniter, or/and you just want to configure your network properly, read this page instead: [Configure Duniter server variant](./configure.md).
This page is intended for advanced users, advanced testers and developers.
Some advanced options are hidden in the embedded help (duniter help) because they are rarely used and/or are mainly intended for advanced testers and developers.
Some commands are not available via the Duniter binary and need to call directly the NodeJs part.
## Hidden options
This part lists the options accessible via the Duniter binary but hidden in the help.
### Hidden `sync` options
These options must be used with the `sync` sub command.
#### `--cautious`
Check all DUPB rules (very long).
#### `--localsync`
Allow to synchronize on nodes with local network IP address.
### Hidden `config` options
These options must be used with the `config` sub command.
#### `--nb-cores`
Number of cores uses for proof-of-work computation
### `---addep`
Add given endpoint to the list of endpoints of this node.
### `---remep`
Remove given endpoint to the list of endpoints of this node.
### WS2P preferred/privileged options
These options are described in a dedicated page: [WS2P: preferred and privileged nodes](./ws2p_preferred_privileged.md)
#### `--ws2p-no-private`
Disable WS2P Private.
#### `--ws2p-private`
Enable WS2P Private.
#### `--ws2p-socks-proxy <host:port>`
Use Socks Proxy for WS2P Private
#### `--rm-proxies`
Remove all proxies options
### WS2P TOR options
To have your Duniter node use Tor for outgoing connections it makes with other nodes, just set up a Tor proxy and choose a policy for normal ws2p access points (the `--reaching-clear-ep` option):
duniter config --tor-proxy localhost:9050 --reaching-clear-ep tor
You will also need to install the *Tor Browser* or *Tor Standalone* on the same machine. By default, Tor listens on localhost on port 9050. If you change your Tor configuration you will obviously need to change the Duniter configuration accordingly.
You can also choose a mixed node, which will contact the regular access points in plain text, so it will only use Tor to contact .onion access points:
duniter config --tor-proxy localhost:9050 --reaching-clear-ep clear
Finally 3rd choice, you can choose to contact only the .onion access points, the clear access points will never be contacted:
duniter config --tor-proxy localhost:9050 --reaching-clear-ep none
/!\ Each time you change one of these two options you must repeat the other one at the same time or it will be reset!
Finally, to remove your Tor configuration and return to a classic node:
duniter --rm-proxies
You can also decide to encapsulate Duniter in a Tor VM as whonix, in which case you will need to inform Duniter that it will be able to contact .onion access points by enabling the `--force-tor' option:
duniter config --force-tor --reaching-clear-ep tor|none
#### Hidden service
Just enter the .onion address of your hidden service in the `--ws2p-remote-host` option.
## Hidden commands and more hidden options
The following commands and options are not accessible via the `duniter` binary. The NodeJs code must be called directly for them.
For this use the embedded NodeJs :
/opt/duniter/node/bin/node duniter_js <hidden-command>
If you compiled Duniter yourself, you don't have any NodeJs embedded, then use the version of NodeJs you used to compile Duniter.
Not all commands and options are listed here, if you don't find what you need:
1. Search in `duniter_js --help`.
2. Search into the Duniter's code itself.
3. Ask for help on the [Duniter forum](https://forum.duniter.org).
### sync `--memory`
Perform synchronization in memory only. Synchronization will not be stored on the hard disk. This option is useful for a quick blockchain integrity check when combined with the --cautious option.
`duniter_js sync g1.duniter.org 443 --cautious --memory`
### Generate a block manually
Generates the next block from the pool data and the current block, performs the working proof for the requested difficulty and then submits the resulting block to a node.
`duniter_js gen-next g1.duniter.org 10901 74`
This command generates the next block, sends it to node `g1.duniter.org:10901` and calculates the working proof with 74 trouble (footprint beginning with 4 zeros).
#### Option `--show`
Displays the calculated block **before** the proof of work and submission to the network. Controls its contents.
`duniter_js gen-next g1.duniter.org 10901 74 --show`
#### Option `--check`
Modifies the behaviour of the command: it no longer produces proof of work nor submits the block to the network. Instead, it generates the block and checks if it is acceptable by a node.
`duniter_js gen-next --show --check`
### Generate genesis block
Generates block #0 automatically, including a maximum number of members:
`duniter_js gen-root duniter.org 10901 74`
Generates block #0 by manually selecting members to include:
duniter_js gen-root-choose duniter.org 10901 74
? Newcomers to add:
◯ john
◯ dude404
◉ sinogeek
❯◉ deviantime
◯ kernel
## Not listed
Not all commands and options are listed on this page, if you don't find what you need:
1. Search in `duniter_js --help`.
2. Search into the Duniter's code itself.
3. Ask for help on the [Duniter forum](https://forum.duniter.org).
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 1.9.x or higher**.
## 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 `1` and `899`.
## Configuring the network
### The APIs
In version `1.9.x` there are two APIs (Application Programming Interface) allowing your node to communicate with other programs.
1. 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.
2. BMA (Basic Merkled Api) : this old API is dedicated to the communication with client software (Cesium, Sakia, Silkaj), 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). BMA is looking forward to developing a new client API to replace it. **BMA is disabled by default** on your duniter node.
### Configuring WS2P
#### 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.
#### WS2P Private
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>
#### WS2P Public
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:
1. 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.
2. You host your node at home but you don't want to use UPnP (For security reasons for example).
3. 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://host:port/path`.
Note that `ws://` will be replaced by `wss://` if you set the remote port to 443.
#### WS2P preferred/privileged nodes
See [WS2P: preferred and privileged nodes](ws2p_preferred_privileged.md)
### Configuring BMA
The only thing you need to configure is an access point. Answer the questions in the following interactive command:
duniter wizard bma
Here is an example with my own configuration at home:
2017-10-01T19:02:09+02:00 - debug: Plugging file system...
2017-10-01T19:02:09+02:00 - debug: Loading conf...
2017-10-01T19:02:10+02:00 - debug: Configuration saved.
? IPv4 interface eth0
? IPv6 interface None
? Port 10901
? Remote IPv4
? Remote port 10901
? Does this server has a DNS name? No
2017-10-01T19:02:33+02:00 - debug: Configuration saved.
I'm wired, otherwise in wifi you have to choose the wlan0 option.
Unfortunately my box does not support IPv6, so no IPv6 interface: None
I don't use UPnP so I manually set a port (here 10901).
Remote IPv4 corresponds to the public ip of my box, you can know it by visiting the site [https://www.myip.com/](https://www.myip.com/)
Here I have not configured a DNS domain pointing to my duniter node.
If like me you don't use UPnP, you have to manually configure a port forwarding on your box.
### 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).
## Synchronize your node
To join the network of a currency you must synchronize with a node already on this network:
For Ğ1, if you don't know any node you can choose the official node `g1.duniter.org:443`.
## Launch
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
The `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_start` and `direct_webstart` commands accept the `--keyprompt` option (see the keypair section).
## Tracking logs
duniter logs
## Go further
See the [advanced commands](./advanced-commands.md).
Title: User documentation for Duniter Server
Order: 9
Date: 2017-09-22
Slug: configurer
Authors: elois
# User documentation for Duniter Server
- [Use Duniter Docker image](./docker.md)
- [Configure Duniter server variant](./configure.md)
- [WS2P: preferred and privileged nodes](./ws2p_preferred_privileged.md)
- [Compile Duniter manually from source code](./manual_compilation.md)
- [Advanced commands](./advanced-commands.md)
Title: Install Duniter Server
Order: 9
Date: 2017-09-22
Slug: configurer
Authors: elois
# Install Duniter Server
## Distribution based on debian (including Ubuntu and some others)
A debian package is provided for the `x86_64` and `armv7l` architectures. If you don't know what it is, you probably need package for `x86_64` architecture.
If your architecture is different, you can try to [compile Duniter yourself](manual_compilation.md) or [install Duniter via Docker](docker.md).
Go to the [release page](https://git.duniter.org/nodes/typescript/duniter/-/releases) to get a link to the last stable release.
Download the debian package and install it:
sudo dpkg -i duniter-*-linux-x64.deb
Then [configure your Duniter node](configure.md).
## Gentoo 64 bits
In order to install Duniter on Gentoo, there is a package in the overlay [sveyret-overlay](https://github.com/sveyret/sveyret-overlay). A README file can be found in this overlay to help you and add it to the Portage tree.
You will then be able to install the package net-p2p/duniter:
`emerge -av net-p2p/duniter`
The following USE flags allow you to decide what will be built:
Flag Description
desktop Build and install the desktop version instead of the server one
gui Add the GUI (mandatory for desktop version, add the web interface for server version)
The server version node for Gentoo can also be automatically started.
## YunoHost
A [YunoHost package](https://github.com/duniter/duniter_ynh) is available.
## Other distributions
You need to [compile Duniter yourself](manual_compilation.md) or [install Duniter via Docker](docker.md).
## Mac
In theory, duniter-server should compile under Mac, but this has never been tested. You can try to [compile it from source](manual_compilation.md) and let us know the result on the [Duniter forum](https://forum.duniter.org).
## Windows
Duniter-server does not support Windows.
Title: WS2P: preferred and privileged nodes
Order: 9
Date: 2020-10-04
Slug: ws2p_preferred_privileged
Authors: elois
# WS2P: preferred and privileged nodes
## Preferred nodes
List of preferred public keys, your node will connect in priority to duniter nodes whose public key is in your preferred public key list.
To add a public key to your list of preferred keys:
duniter config --ws2p-prefered-add <pubkey>
To remove a key from your preferred key list :
duniter config --ws2p-prefered-rm <pubkey>
To consult the list of your preferred keys:
duniter ws2p list-prefered
## Privileged nodes
Just as you can set preferred keys for your outgoing WS2P connections, you can set privileged keys for your incoming WS2P connections. That is, if you receive more connection requests than the maximum number you have configured, connections initiated by nodes whose public key is part of your privileged keys will be given priority.
To add a key to your privileged key list :
duniter config --ws2p-privileged-add <pubkey>
To remove a key from your privileged key list:
duniter config --ws2p-privileged-rm <pubkey>
To consult the list of your privileged keys:
duniter ws2p list-privileged
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment