For the best viewing experience, please turn your phone to portrait mode.

Lisk Core Configuration

The general config file for Lisk Core is located in the root directory of the Lisk Core repository. We give you an overview for a greater understanding of the config.json file and a description of each parameter.

For an advanced configurations, please go directly to the sections listed below :

 {
    "wsPort": 8001, // The port Lisk will listen to for WebSocket connections, e.g. P2P broadcasts
    "httpPort": 8000, // The port Lisk will listen to for HTTP connections, e.g. API calls
    "address": "0.0.0.0", // The ip Lisk will listen on (IPv4)
    "version": "1.0.0", // The version of Lisk
    "minVersion": ">=1.0.0", // The minimum version Lisk will communicate with
    "fileLogLevel": "error", // Logging level for Lisk: info, error, debug, none
    "logFileName": "logs/lisk.log", // The path and name of the logfile
    "consoleLogLevel": "error", // The console logging level for app.js: info, error, debug, none
    "trustProxy": false, // If true, client IP addresses are understood as the left-most entry in the X-Forwarded-* header
    "topAccounts": false, // Enables the top accounts endpoint for the explorer when set to True
    "cacheEnabled": false, // If true, enables cache
    "wsWorkers": 1, // Number of Web Workers
    "db": {
        "host": "localhost", // The ip of the database
        "port": 5432, // The port of the database
        "database": "lisk_main", // The name of the instance to use
        "user": "", // The user to use with the database, defaults to the current user
        "password": "password", // The default password to use with the database
        "min": 10, // Specifies the minimum amount of database handles
        "max": 95, // Specifies the maximum amount of database handles
        "poolIdleTimeout": 30000, // This parameter sets how long to hold connection handles open
        "reapIntervalMillis": 1000, // Closes & removes clients which have been idle > 1 second
        "logEvents": [ "error"], // Database logging events: connect, disconnect, query, task, transact, error
        "logFileName": "logs/lisk_db.log" // Relative path of the log file
    },
    "redis": {
              "host": "127.0.0.1", // The ip of the Redis instance
              "port": 6380, // The port Redis will listen on
              "db": 0, // Set the database to use. Default is '0'
              "password": null // If null, Redis is not password protected
    },
    "api": {
        "enabled": true, // Controls the API's availability. If disabled no API access is possible
        "access": {
            "public": false, // Controls the whitelist. When true all incoming connections are allowed
            "whiteList": ["127.0.0.1"] // This parameter allows connections to the API by IP. Defaults to only allow local host
        },
        "options": {
            "limits": {
                "max": 0, // Maximum of API conncections
                "delayMs": 0, // Minimum delay between API calls in ms
                "delayAfter": 0, // Minimum delay after an API call in ms
                "windowMs": 60000 // Minimum delay between API calls from the same window
            },
            "cors": {
               "origin": "*", // Defines the domains, that the resource can be accessed by in a cross-site manner. Defaults to all domains. 
               "methods": ["GET", "POST", "PUT"] // Defines the allowed methods for CORS
              }
        }
    },
    "peers": {
        "enabled": true, // Controls the Peers API's availability. If disabled, no inbound network communications will function
        "list": [ // Specifies a list of seed peers to connect to 
            {
                "ip": "192.168.1.1", // The ip of the peer
                "wsPort": 8000 // The WebSocket Port of the peer
            }
        ],
        "access": {
                    "blackList": [] // Peers to exclude from communicating with
                },
        "options": {
            "timeout": 5000, // How long to wait for peers to respond with data. Defaults to 5 seconds
            "broadhashConsensusCalculationInterval": 5000 // Interval for recalculating the broadhash consensus. Defaults to 5 seconds
        }
    },
    "broadcasts": {
        "active": true, // If true, enables broadcasts
        "broadcastInterval": 5000, // Specifies how often the node will broadcast transaction bundles
        "broadcastLimit": 20, // How many nodes will be used in a single broadcast
        "parallelLimit": 20, // Specifies how many parallel threads will be used to broadcast transactions
        "releaseLimit": 25, // How many transactions can be included in a single bundle
        "relayLimit": 2 // Specifies how many times a transaction broadcast from the node will be relayed
    },
    "transactions": {
        "maxTxsPerQueue": 1000 // Sets the maximum size of each transaction queue. Default: 1000
    },
    "forging": {
        "force": false, // Forces forging to be on, only used on local development networks
        "defaultPassword": [], // Specifies default password for all encrypted passphrases (Intended for testing environments)
        "delegates": [], // Lists delegates, who are authorised to forge on this node.
        "access": {
            "whiteList": [ "127.0.0.1" ]// This parameter allows connections to the Forging API by IP. Defaults to allow only local connections
        }
    },
    "syncing": {
        "active": true // If true, enables syncing (fallback for broadcasts)
    },
    "loading": {
        "loadPerIteration": 5000 // How many blocks to load from a peer or the database during verification
    },
    "ssl": {
        "enabled": false, // Enables SSL for the Lisk process for Lisk UI - Default is false
        "options": {
            "port": 443, // Port to host the Lisk Wallet on, default is 443 but is recommended to use a port above 1024 with iptables
            "address": "0.0.0.0", // Interface to listen on for the Lisk Wallet
            "key": "./ssl/lisk.key", // Required private key to decrypt and verify the SSL Certificate
            "cert": "./ssl/lisk.crt" // SSL certificate to use with the Lisk Wallet
        }
    },
    "nethash": "ed14889723f24ecc54871d058d98ce91ff2f973192075c0155ba2b7b70ad2511" // Network hash of the Genesis block, used to differentiate networks. This should never be manually edited
}

API Access Control

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

     "api": {
        "enabled": true, // Controls the API's availability. If disabled no API access is possible
        "access": {
            "public": false, // Controls the whitelist. When true all incoming connections are allowed
            "whiteList": ["127.0.0.1"] // 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 setup a public wallet, simply leave theapi.access.whitelist array empty.

For best security, disable all access setting api.enabled to false.

Warning

This last configuration may prevent monitoring scripts from functioning.

Forging

If you are running your Lisk Node from a local machine, you can enable forging through the API client, without further interruption.

Important

After restarting you Lisk node, you will need to re-enable forging again.

In order to enable your node as a forger, first you need to insert some encrypted data onto the config file under forging.delegates array, as follows:

Forging
     "forging": {
        "force": false,
        "delegates": [
                {
                "encryptedPassphrase":
                    "iterations=1&salt=476d4299531718af8c88156aab0bb7d6&cipherText=663dde611776d87029ec188dc616d96d813ecabcef62ed0ad05ffe30528f5462c8d499db943ba2ded55c3b7c506815d8db1c2d4c35121e1d27e740dc41f6c405ce8ab8e3120b23f546d8b35823a30639&iv=1a83940b72adc57ec060a648&tag=b5b1e6c6e225c428a4473735bc8f1fc9&version=1",
                "publicKey":
                    "9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f"
           }              
         ],
        "access": {
            "whiteList": [
                "127.0.0.1"
            ]
        }
    },

The lastest snippet's section called access.whitelist makes easy to enable only your IP address to forge through the API client:.

Forging Access

 "access": {
  "whiteList": ["127.0.0.1","REPLACE_ME"] // Replace with the IP which you will use to access your node
}

Enable/Disable Forging

Use following curl command to enable the forging for your delegate.

curl 
   -H 'Content-Type: application/json' 
   -X PUT 
   -d '{
            publicKey: 'XXXX',
            password: 'YYYY',
            forging: true
    }' 
   http://127.0.0.1:4000/api/node/status/forging

Use following curl command to disable the forging for your delegate.

curl 
    -H 'Content-Type: application/json' 
    -X PUT 
    -d '{
            publicKey: 'XXXX',
            password: 'YYYY',
            forging: false
     }' 
    http://127.0.0.1:4000/api/node/status/forging
  • Where publicKey is the key for the delegate you want to enable/disbale
  • password is the password used to encrypt the passphrase in the config.json
  • forging is the boolean value to enable or disable the forging
  • HTTP Port can be different based on your configuration, so check httpPort in your config.json

SSL

Note

To complete this step require a signed certificate (from a CA), or a locally signed certificate using LetsEncrypt. You will need both the private and public keys in a location that is accessible to Lisk.

Next snippet highlights the essential parameters to enable SSL security on your node's connections:

SSL Configuration

 "ssl": {
  "enabled": false,         // Change FROM false TO true
  "options": {
    "port": 443,            // Default SSL Port
    "address": "0.0.0.0",   // Change only if you wish to block web access to the node
    "key": "path_to_key",   // Replace FROM path_to_key TO actual path to key file
    "cert": "path_to_cert"  // Replace FROM path_to_cert TO actual path to certificate file
  }
}
Important

If SSL Port configured above ssl.options.port is within well known ports range (below 1024), you must alter the port specified with setcap or change it to be outside of that range.

Setcap: Only required to grant Lisk access to port 443

 sudo setcap cap_net_bind_service=+ep bin/node

To verify all you have properly configured your node, open the web client using https://MY_IP_OR_HOST. You should now see a secure SSL connection.