Lisk Core Configuration

If you are using the Docker distribution, Lisk Core is configured in a slightly different manner. Please go to the Docker Administration page to find out more about the docker-specific configuration of the Lisk Core.

Command Line Options

Please note, there are numerous options available that can be deployed to override the configuration on the runtime whilst starting the Lisk Core.

To overwrite config options from the Command Line, execute the following commands below:

  • Pass options as ENV variables

  • Pass options as flags

LISK_NETWORK=[network] LISK_CONFIG_FILE=[config-path] LISK_ADDRESS=[address] LISK_WS_PORT=[port] pm2 start lisk
The flag options are deprecated. Therefore it is recommend to pass the options as ENV variables.
node dist/index.js -p [port] -a [address] -c [config-path] -n [network]

You can pass devnet (default), alphanet, betanet, testnet or mainnet for the [network] option.

All ENV variables are restricted with a operating system constraint of ENV variable maximum length.

Comma-separated lists will replace the original config values. For example, If LISK_PEERS is specified, the original peers.list specific to the network will be replaced completely.

Each of these options listed below can be appended in the command line:

Command line Option ENV Variable Description

--network
-n

LISK_NETWORK

Any of these options can be used devnet, alphanet, betanet, testnet and mainnet. The default value is devnet.

--config
-c

LISK_CONFIG_FILE

Pass the custom configuration file, which will override values of the following: config/default/config.json.

--port
-p

LISK_WS_PORT

TCP port for P2P layer

--http-port
-h

LISK_HTTP_PORT

TCP port for HTTP API

--address
-a

LISK_ADDRESS

Listening host name or IP

--log
-l

LISK_FILE_LOG_LEVEL

Log level for file output

LISK_CONSOLE_LOG_LEVEL

Log level for console output

LISK_CACHE_ENABLED

Enable or disable cache. Must be set to true/false

--database
-d

LISK_DB_NAME

PostgreSQL database name to connect to

LISK_DB_HOST

PostgreSQL database host name

LISK_DB_PORT

PostgreSQL database port

LISK_DB_USER

PostgreSQL database username to connect to

LISK_DB_PASSWORD

PostgreSQL database password to connect to

--redis
-r

LISK_REDIS_HOST

Redis host name

LISK_REDIS_PORT

Redis port

LISK_REDIS_DB_NAME

Redis database name to connect to

LISK_REDIS_DB_PASSWORD

Redis database password to connect to

--peers
-p

LISK_PEERS

Comma separated list of peers to connect to in the following format 192.168.99.100:5000,172.169.99.77:5000

LISK_API_PUBLIC

Enable or disable public access of http API. Must be set to true/false

LISK_API_WHITELIST

Comma separated list of IPs to enable API access. Format 192.168.99.100,172.169.99.77

LISK_FORGING_DELEGATES

Comma separated list of delegates to load in the format publicKey|encryptedPassphrase,publicKey2|encryptedPassphrase2

LISK_FORGING_WHITELIST

Comma separated list of IPs to enable access to forging endpoints. Format 192.168.99.100,172.169.99.77

--rebuild
-b

Rebuilds certain database tables on the basis of the local blockchain data. Must be followed by an integer, that specifies the last delegate round that should be part of the rebuild. If 0 is specified, all rounds are rebuilt.

LISK_CHILD_PROCESS_MODULES

Comma separated list of modules, that shall be loaded in a separate process. To enable inter process communication, set ipc.enabled to true inside the config.json file.

Network-specific config files

The root folder for all configurations is config/. The default network is devnet. To connect to another network, specify the network when starting the Lisk Core, as described in Source Administration. The network specific configurations can be found under config/<network>/config.json, whereby <network> can be any of these values listed below:

  • devnet

  • alphanet

  • betanet

  • testnet

  • mainnet

Do not override any value in the files mentioned above, as the changes will be overwritten everytime the Lisk Core is upgraded. If a custom configuration is required, use the environment variables or alternatively create your own .json file and pass it as command line option.

Custom config file

To use a custom config, firstly create a .json-file. Further information can be found in the Config Structure section.

Only the values required to be updated are needed, as for all other options the pre-defined values will be used as described in the Config Load Order section.

Binary and Commander distributions both provide a config.json, which can be customized as desired.

For Source distributions, the config file needs to be created seperately and needs to be passed as described below:

  • Binary

  • Commander

  • Source

The binary script provides a custom config.json which is stored in the root folder of your Lisk Core installation by default.

For example, Lisk Core for Mainnet is installed under ~/lisk-main, and the config is stored directly in ~/lisk-main/config.json

The config.json will be used automatically when reloading the node with the following command:

bash lisk.sh reload

Lisk Commander provides a custom config.json which is stored in the root folder of your Lisk Core instance by default.

For example, Lisk Core for Mainnet is installed under ~/.lisk/instances/lisk-mainnet, and the config is stored directly in ~/.lisk/instances/lisk-main/config.json

The config.json will be used automatically when reloading the node with the following command:

pm2 stop lisk (1)
LISK_CONFIG_FILE=<CONFIG_PATH> pm2 start lisk (2)
1 Stop Lisk Core in the case whereby it is running.
2 Replace <CONFIG_PATH> with the path to your custom config file.

Config load order

Configurations will be loaded in the following order listed below. Each configuration will override the previous one:

  1. Default configuration values of modules and components of the Lisk Framework

  2. Network specific configuration file

  3. A custom configuration file (if specified by the user)

  4. Command line configurations, specified as command-line flags or ENV variables.

For development purposes, use devnet as the network option. Other networks are specific to public Lisk networks.

The config.json file and a description of each configurable parameter.

Structure

A breakdown of the code structure can be seen below:

Unresolved include directive in modules/ROOT/pages/configuration.adoc - include::../../ROOT/partials/configuration.adoc[]

API Access Control

Controlling access to a node plays a vital role in security. The following configurable flags are available to control the access to your node:

{
  "modules": {
    "http_api": { (1)
      "enabled": true, (2)
      "access": { (3)
        "public": false, (4)
        "whiteList": ["127.0.0.1"], (5)
      },
    }
  }
}
1 Contains options for the API module.
2 Controls the API’s availability. If disabled, no API access is possible.
3 Contains API access options.
4 If true, the API endpoints of the node are available to public.
5 This parameter allows connections to the API by IP. Defaults to only allow local host.

The recommended setup is to configure a whitelist for only trusted IP addresses, such as your home connection. Use IPV4 addresses only as the whitelist does not support IPV6.

To set up a public wallet, simply leave the modules.http_api.access.whitelist array empty.

For optimal security, disable all access setting modules.http_api.enabled to false.

This last configuration may prevent monitoring scripts from functioning.

Forging

To enable your node to forge, firstly it is required to insert some encrypted data into the config file under the chain.forging.delegates array. To encrypt your passphrase, it is recommended to use one of the following alternatives listed below:

The first alternative with the Lisk Commander is described in detail below. Please ensure the Lisk Commander is installed in a secure environment. Upon completion, please follow these commands to generate the encrypted passphrase:

$ lisk
lisk passphrase:encrypt --output-public-key
Please enter your secret passphrase: *****
Please re-enter your secret passphrase: *****
Please enter your password: ***
Please re-enter your password: ***
{
        "encryptedPassphrase": "iterations=1000000&cipherText=30a3c8&iv=b0d7322bf24e0dfe08462f4f&salt=aa7e26c9f4317b61b4f45b5c6909f941&tag=a2e0eadaf1f11a10b342965bc3bafc68&version=1",
        "publicKey": "a4465fd76c16fcc458448076372abf1912cc5b150663a64dffefe550f96feadd"
}
  1. Type in your passphrase followed by the password required for encryption.

  2. This will result in the creation of an encryptedPassphrase key-value pair.

  3. Create the JSON object and add it to your config.json under chain.forging.delegates as can be seen below:

{
  "modules": {
    "chain": { (1)
      "forging": { (2)
        "force": false, (3)
        "delegates": [ (4)
            {
                "encryptedPassphrase": "iterations=1&salt=476d4299531718af8c88156aab0bb7d6&cipherText=663dde611776d87029ec188dc616d96d813ecabcef62ed0ad05ffe30528f5462c8d499db943ba2ded55c3b7c506815d8db1c2d4c35121e1d27e740dc41f6c405ce8ab8e3120b23f546d8b35823a30639&iv=1a83940b72adc57ec060a648&tag=b5b1e6c6e225c428a4473735bc8f1fc9&version=1",
                "publicKey": "9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f"
            }
        ],
      },
    },
    "http_api": { (5)
      "forging": {
        "access": {
          "whiteList": ["127.0.0.1", "REPLACE_ME"], (6)
        },
      },
    }
  }
}
1 Contains options for the chain module.
2 Contains forging options for delegates.
3 Forces forging to be 'on'. This is only used on local development networks.
4 The list of delegates who are allowed to forge on this node. To successfully enable forging for a delegate, the public key and the encrypted passphrase need to be deposited here as a JSON object.
5 Contains options for the API module.
6 Replace with the IP which will be used to access your node
  1. Reload your Lisk Core process to make the changes in the config effective. For example, for Binary install, run the following command: bash lisk.sh reload

Check Forging

Use the following curl command to verify the forging status of your delegate as shown below:

curl \
  http://127.0.0.1:7000/api/node/status/forging \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json'

The result should appear as shown below in the following code snippet:

{
  "meta": {},
  "data": [
    {
      "forging": true,
      "publicKey": "9bc945f92141d5e11e97274c275d127dc7656dda5c8fcbf1df7d44827a732664"
    }
  ],
  "links": {}
}

Enable/Disable Forging

Remember that after restarting your Lisk node, it is necessary to re-enable forging again.

The endpoint to perform this action is idempotent.

This means that the results are identical, regardless of how many times the query is executed.

If your Lisk Node is running on a local machine, it is possible to enable forging through the API client, without any further interruption.

Use the following curl command to enable the forging for your delegate as shown below:

curl -X PUT \
  http://127.0.0.1:7000/api/node/status/forging \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
          "publicKey": "YYYYYYYYY",
          "password": "XXX",
          "forging": true
      }'

Use the following curl command to disable the forging for your delegate as shown below:

curl -X PUT \
  http://127.0.0.1:7000/api/node/status/forging \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
          "publicKey": "YYYYYYYYY",
          "password": "XXX",
          "forging": false
      }'
  • publicKey is the key for the delegate which is required to be enabled/disabled.

  • password is the password used to encrypt your passphrase in config.json

  • forging is the boolean value to enable or disable the forging.

  • The HTTP Port can be different based on your configuration, therefore it is recommended to check the httpPort in your config.json

SSL

It is recommended to use a webserver such as NGINX or Apache to set up the SSL for the Lisk Core. If that opportunity is not available then it is also possible to configure the Lisk Core to handle SSL connections as described below:

This step requires a signed certificate, (from a CA, such as Let’s Encrypt) or a self-signed certificate. Both the private and public keys will be needed in a location that is accessible to Lisk Core.

The following code snippet listed below displays the essential parameters required to enable SSL security on your node’s connections:

SSL Configuration

{
  "modules": {
      "http_api": {
          "ssl": {
              "enabled": false,           (1)
              "options": {
                  "port": 443,            (2)
                  "address": "0.0.0.0",   (3)
                  "key": "path_to_key",   (4)
                  "cert": "path_to_cert"  (5)
              }
          }
      }
  }
}
1 Change from false to true.
2 Default SSL Port.
3 Change only if it is required to block web access to the node.
4 Replace path_to_key with the actual path to the key file.
5 Replace path_to_cert with the actual path to the certificate file.
If the SSL Port configured above in http_api.ssl.options.port is a privileged port, (below 1024), then either the node must be allowed to use the specified port with setcap, or the configuration must be changed in order to to use a port outside of that range.

Setcap: This is only required to grant Lisk access to port 443.

 sudo setcap cap_net_bind_service=+ep bin/node

To verify your node has been configured correctly, open the web client using this url: https://MY_IP_OR_HOST. A secure SSL connection should now be visible.

Logging

For monitoring or debugging your node, Lisk Core tracks all activities that occur within the node by creating applicable log messages.

These log messages are grouped in different log levels. Hence, this makes it easy to define the level of the log details.

Bunyan is used for the logging library, as this allows simple and fast JSON logging for Node.js services.

Log Levels

Log Level Description

None

No events are logged.

Fatal(60)

The node is going to stop or become unusable. This requires the operator to investigate the problem.

Error(50)

Fatal for a particular request, however the node continues servicing other requests. This also requires the operator to investigate the problem, although it does not necessarily require immediate attention.

Warn(40)

A warning indication that should be investigated eventually.

Info(30)

Detail on a regular operation.

Debug(20)

Anything else, i.e. too verbose to be included in ``info'' level.

Trace(10)

Logging from external libraries used by your node, or else very detailed application logging.

Logging destinations

There are two possible output sources for the logs: The file log stream and the console log stream. Each output source can be configured independently inside of config.json under the options for the logger component.

Console log stream

The console log level displays the logs directly to the console from where the Lisk Core process is started. It is useful for quick debugging or verifying that Lisk Core starts correctly. Default log level for the console log stream is none.

An example command displaying the console log stream can be seen below:

node dist/index.js | npx bunyan  (1)
1 Pretty-prints console logs with log level equal or higher to the console log level.

For more information regarding the Bunyan CLI tool, please refer to the official Bunyan Documentation.

File log stream

All logs that have equal or higher log levels than the in config.json specified file log level are saved in a .log-file for further analysis. By default, the generated log files are saved inside of the logs folder of Lisk Core. Default log level for the file log stream is info.

The file log stream can be used to monitor the node via logs.

Logrotation

It is recommended to set up some form of log rotation for the log files of Lisk Core. If log rotation is not initiated, then the log files may grow very large over time, (depending on the specified file log level), and hence will eventually exceed the server’s disk space limits.

For example, Ubuntu systems provide a service called logrotate specifically for this purpose. Please ensure Logrotate is installed on your system as shown below:

logrotate --version

Now go to the logrotate config directory and create a new logrotate file for Lisk Core as shown below:

cd /etc/logrotate.d
touch lisk

Inside this file, define the parameters for the log rotation.

Example values can be seen below:

/path/to/lisk/logs/mainnet/*.log {
        daily                   (1)
        rotate 5                (2)
        maxage 14               (3)
        compress                (4)
        delaycompress           (5)
        missingok               (6)
        notifempty              (7)
}
1 Daily rotation.
2 Keeps the last 5 most recent logs.
3 Removes logs that are older than 14 days.
4 Compresses old log files.
5 Compresses the data after it has been moved.
6 If no log file is present, then it is ignored.
7 Does not rotate empty log files.

After customizing and saving the config to fit your requirements, it is recommended to test it by doing a dry run using the following command listed below:

sudo logrotate /etc/logrotate.conf --debug