romansemko/nelson.cli repository overview

⁠Deviota Nelson

Nelson is a tool meant to be used with IOTA's IRI Node. It automatically manages neighbors of your full node, negotiating connections, finding new neighbors and protecting against bad actors.

⁠Table of contents

• Getting Started⁠
  • Prerequisites⁠
  • Installing⁠
  • Upgrading⁠
  • Running as a service⁠
• Docker⁠
• Building Locally⁠
• Configuration⁠
  • config.ini⁠
  • Command line options⁠
  • Options description⁠
• Automated Scripts⁠
  • Amazon CloudFormation⁠
• Running Nelson⁠
  • Initial nodes⁠
  • Epochs and Cycles⁠
  • Monitor⁠
  • API⁠
  • Webhooks⁠
• FAQ⁠
• Contributing⁠
  • Donations⁠
  • Running your own entry node⁠
• Authors⁠
• License⁠

⁠Getting Started

These instructions will get you a copy of the project up and running on your local machine.

⁠Prerequisites

It is expected that you have already installed Java, downloaded the IRI jar file and know how to start it. The local IRI instance must have api enabled and allowing to add/remove neighbors.

Nelson is running on Node.js You will have to install node (at least version LTS 8.9.4) and npm (node package manager) on your system. Alternatively to npm you can (and should) use yarn package manager.

⁠Port Forwarding

If you are trying to run a Nelson node at home, you may need to open some ports (port forwarding) in your NAT Router:

• UDP 14600
• TCP 15600
• TCP 16600

Please refer to your Router's manual on how to do that.

Furthermore, please be aware that apart of firewall and port-forwarding in router, your Internet provider may also be an issue. Some providers (like Vodafone in Germany) do not have enough IPv4 addresses for homes and thus use something called "IPv4 over DS Lite". In those cases the traffic will not come through over the ports mentioned above. Unfortunately, there is no quick fix for this issue (maybe changing providers). There is some hope with the upcoming PCP-protocol, this will not happen this year (2018) for most providers, though.

⁠WARNING FOR UBUNTU

Ubuntu 16.04 apt comes with an outdated Node version (4.X). You need to install the latest version separately:

https://nodejs.org/en/download/package-manager/⁠

⁠Installing

Globally install Nelson

npm install -g nelson.cli

And run it

nelson --gui --getNeighbors

The --getNeighbors option is used to download an entry set of trusted Nelson peers for new Nelson instances. As your Nelson stays online and gets to know its neighbors, it will rely less and less on the initial entry points.

The --gui option is used to provide a simple GUI interface in the console.

Below is the list of all possible options.

⁠Upgrading

To upgrade your Nelson to version X.X.X, simply run:

npm install -g [email protected]

Please check where npm installs your global packages! It happens very often that the first installed binary is put into /usr/local/bin and the updated into /usr/bin. Run nelson --version after the upgrade to make sure you are using the most recent one. Update your scripts and/or services to point to the right binary!

⁠Running as a service

You can use the node process manager⁠ to run Nelson as a service. Just do the following:

# Install the process manager:
npm install pm2 -g

# Make pm2 start at startup:
pm2 startup

# Start the Nelson as service
# If you created a nelson config somewhere on your system, provide the path to the config:
pm2 start nelson -- --config /path/to/nelson-config.ini

# Otherwise you can just do: pm2 start nelson

# Save current processes runing with pm2 to startup on boot:
pm2 save

# Get Nelson logs:
pm2 monit
# or
pm2 log

⁠Docker

Provided you have docker installed, Nelson can be started as follows:

docker run <docker opts> romansemko/nelson.cli <nelson command line opts>

Hence, running IRI with Nelson can be done with two simple commands:

docker run -d --net host -p 14265:14265 --name iri iotaledger/iri
docker run -d --net host -p 18600:18600 --name nelson romansemko/nelson.cli -r localhost -i 14265 -u 14777 -t 15777 --neighbors "mainnet.deviota.com/16600 mainnet2.deviota.com/16600 mainnet3.deviota.com/16600 iotairi.tt-tec.net/16600"

The options passed to Nelson's docker (-r localhost -i 14265 -u 14600 -t 15600 --neighbors ...) set IRI's hostname and ports (api, TCP, UDP) and the initial neighbors (You could also have used --getNeighbors). Please refer below for more info on options.

To keep Nelson's peer database outside of the container, so that you do not lose your collected neighbor's data, you can mount a volume bound to a host's folder:

docker run -d --net host -p 18600:18600 --name nelson -v /path/to/nelson/data/directory:/data romansemko/nelson.cli 

⁠Building Locally

If you are a developer you may want to build the project locally and play around with the sources. Otherwise, ignore this section. Make sure you have yarn⁠ package manager installed. Checkout the project:

git clone https://github.com/SemkoDev/nelson.cli.git
cd nelson.cli

Install dependencies:

yarn install --pure-lockfile

Run tests and make binaries:

yarn make

Try to run Nelson:

node ./dist/nelson.js --gui --getNeighbors

⁠Configuration

You are free to either use command line options or an .ini file to configure Nelson. If you use a config file, it has precedence and all command line options are ignored.

⁠config.ini

To use a configuration file, run Nelson with --config option:

nelson --config ./config.ini

# Alternatively, set an environment variable:
NELSON_CONFIG= ./config.ini nelson

You can provide one or more of the following options in your ini file. Example:

[nelson]
name = My Nelson Node
cycleInterval = 60
epochInterval = 300
apiPort = 18600
apiHostname = 127.0.0.1
port = 16600
IRIHostname = localhost
IRIProtocol = any
IRIPort = 14265
TCPPort = 15600
UDPPort = 14600
dataPath = data/neighbors.db
; maximal incoming connections. Please do not set below this limit:
incomingMax = 5
; maximal outgoing connections. Only set below this limit, if you have trusted, manual neighbors:
outgoingMax = 4
isMaster = false
silent = false
gui = false
getNeighbors = https://raw.githubusercontent.com/SemkoDev/nelson.cli/master/ENTRYNODES
; add as many initial Nelson neighbors, as you like
neighbors[] = mainnet.deviota.com/16600
neighbors[] = mainnet2.deviota.com/16600
neighbors[] = mainnet3.deviota.com/16600
neighbors[] = iotairi.tt-tec.net/16600

; Protect API with basic auth
[nelson.apiAuth]
username=user
password=pass

⁠WARNING ON NEIGHBORS:

These are NOT IRI neighbor addresses, but the Nelson addresses. If you have used them erroneously as Nelson addresses in the past, chances are that Nelson will think these "static" neighbors are his and will keep removing them from IRI.

To Fix this, just delete data/neighbors.db and start Nelson fresh with just --getNeighbors

⁠Command line options

Command line options are named the same as INI options. Some have additional short versions.

⁠Options description