Home

Welcome to the IOTA full node installation wiki!

My first tutorial has been written around August 2017. This tutorial is aimed at those who have at least some background working on the Linux command line (and was specifically written for CentOS).

Since then, the IOTA community has grown exponentially and many new members want to join the effort and host their own full node. And, as suggested by many tutorials (and justifiably), Linux is the best way to go.

I realized that it would be very helpful to write a new tutorial, one that aims at those who posses less, or almost no skills with Linux.

In addition, I found that many tutorials lack some overall system configuration. For example, running IRI as an unprivileged user, configuring firewalls and so on.

A copy-paste tutorial is awesome, but as it so often happens, the user misses some basic technical explanation about the setup. While it is impossible to include a crash-course of Linux for the purpose of this tutorial, I will try to explain some basic concepts where I find that many users had troubles with.

For some details I will leave it to you to google (for example, how to SSH access your server). Otherwise the tutorial becomes too lofty.

Overview

This tutorial will help you setup a full node on a Linux system (Ubuntu or CentOS). The git repository I have created includes an automated installation. I hope to be adding other distributions like Debian in the future.

It will install IRI and IOTA peer manager, a web GUI with which you can view your neighbors, add or remove neighbors, view the sync etc.

The Requirements

Virtual Private Server

This is probably the best and most common option for running a full node. I will not get into where or how to purchase a VPS (virtual private server). There are many companies offering a VPS for good prices. The basic recommendation is to have one with at least 4GB RAM, 2 cores and minimum 30GB harddrive (SSD preferably).

Operating System

When you purchase a VPS you are often given the option which operating system (Linux of course) and which distribution to install on it. This tutorial currently supports CentOS (>=7) and Ubuntu (>=16)

Accessing the VPS

Once you have your VPS deployed, most hosting provide a terminal (either GUI application or web-based terminal). With the terminal you can login to your VPS's command line. You probably received a password with which you can login to the server. This can be a 'root' password, or a 'privileged' user (with which you can access 'root' privileges).

The best way to access the server is via a Secure Shell (SSH). If your desktop is Mac or Linux, this is native on the command line. If you use Windows, I recommend installing Putty

There are plenty of tutorials on the web explaining how to use SSH (or SSH via Putty). Basically, you can use a password login or SSH keys (better).

System User

Given you are the owner of the server, you should either have direct access to the 'root' account or to a user which is privileged. It is often recommended to run all commands as the privileges user, prefixing the commands with 'sudo'. In this tutorial I will leave it to the user to decide.

If you accessed the server as a privileged user, and want to become 'root', you can issue a sudo su -. Otherwise, you will have to prefix most commands with sudo, e.g. sudo apt-get install somepackage.

Installation

To prepare for running the automated "playbook" from this repository you require some basic packages. First, it is always a good practice to check for updates on the server.

Update System Packages

For Ubuntu we can type:

apt-get update

and for CentOS:

yum update

This will search for any packages to update on the system and require you to confirm the update.

Reboot Required?

Sometimes it is required to reboot the system after these updates (e.g. kernel updated).

For **Ubuntu **we can check if a reboot is required. Issue the command ls -l /var/run/reboot-required

# ls -l /var/run/reboot-required
-rw-r--r-- 1 root root 32 Dec  8 10:09 /var/run/reboot-required

If the file is found as seen here, you can issue a reboot (shutdown -r now or simply reboot).

For Centos we have a few options how to check if a reboot is required. A simple one I've learned of recently is to install yum-utils:

yum install yum-utils -y

There's a utility that comes with it, we can run needs-restarting -r:

# needs-restarting  -r
Core libraries or services have been updated:
  systemd -> 219-42.el7_4.4
  glibc -> 2.17-196.el7_4.2
  linux-firmware -> 20170606-56.gitc990aae.el7
  gnutls -> 3.3.26-9.el7
  glibc -> 2.17-196.el7_4.2
  kernel -> 3.10.0-693.11.1.el7

Reboot is required to ensure that your system benefits from these updates.

More information:
https://access.redhat.com/solutions/27943

As you can see, a reboot is required (do so by issuing a reboot or shutdown -r now)

Installing Ansible

Ansible is an awesome software used to automate configuration and/or deployment of services. This repository contains what Ansible refers to as a "Playbook" which is a set of instructions on how to configure the system.

This playbook installs required dependencies, the IOTA IRI package and IOTA Peer Manager. In addition, it configures firewalls and places some handy files for us to control these services.

To install Ansible on Ubuntu I refer to the official documentation:

apt-get install software-properties-common
apt-add-repository ppa:ansible/ansible
apt-get install ansible git

For CentOS, simply run:

yum install ansible git nano -y

You will notice I've added 'git' which is required (at least on CentOS it doesn't have it pre-installed as in Ubuntu). In addition, I've added 'nano' which is helpful for beginners to edit files with (use vi or vim if you are adventurous).

Cloning the Repository

Issue a git clone https://github.com/nuriel77/iri-playbook.git && cd iri-playbook This will pull the repository to the directory in which you are and move you into the repository's directory.

Configuring Values

There are some values you can tweak before the installation runs. There are two files you can edit:

nano group_vars/all/iri.yml

and

nano group_vars/all/iotapm.yml

These files have comments above each option to help you figure out if anything needs to be modified. In particular, look at the iri_java_mem and iri_init_java_mem. Depending on how much RAM your server has, you should set these accordingly.

For example, if your server has 4096MB (4GB memory), a good setting would be:

iri_java_mem: 3072
iri_init_java_mem: 256

Just leave some room for the operating system and other processes. You will also be able to tweak this after the installation, so don't worry about it too much.

Running the Playbook

By default, the playbook will run locally on the server where you've cloned it to. You can run it:

ansible-playbook -i inventory site.yml

Or, for more verbose output add the -v flag:

ansible-playbook -i inventory -v site.yml

This can take a while as it has to install packages, download IRI and compile it. Hopefully this succeeds without any errors (create a git Issue if it does, I will try to help).

Post Installation

We can run a few checks to verify everything is running as expected. First, let's use the 'systemctl' utility to check status of iri (this is the main full node application)

Using the systemctl status iri we can see if the process is Active: active (running).

See examples below.

Controlling IRI

Check status:

systemctl status iri

Stop:

systemctl stop iri

Start:

systemctl start iri

Restart:

systemctl restart iri

Controlling iota-pm (IOTA Peer Manager)

Check status:

systemctl status iota-pm

Stop:

systemctl stop iota-pm

Start:

systemctl start iota-pm

Restart:

systemctl restart iota-pm

Checking Ports

IRI uses 3 ports by default:

UDP neighbor peering port
TCP neighbor peering port
TCP API port (this is where a light wallet would connect to or iota peer manageR)

You can check if IRI and iota-pm are "listening" on the ports, see the output you should expect:

lsof -Pni|egrep "iri|iotapm"
java     2297    iri   19u  IPv6  20331      0t0  UDP *:14600
java     2297    iri   21u  IPv6  20334      0t0  TCP *:14600 (LISTEN)
java     2297    iri   32u  IPv6  20345      0t0  TCP 127.0.0.1:14265 (LISTEN)
node     2359 iotapm   12u  IPv4  21189      0t0  TCP 127.0.0.1:8011 (LISTEN)

What does this tell us?

- means all interfaces - from the example above we see that IRI is listening on ports TCP and UDP no. 14600
IRI is listening for API (or wallet connections) on a local interface (not accessible from "outside") no. 14265
Iota-PM is listening on local interface port no. 8011

This is great. We can now tell new neighbors to connect to our IP (what is your IP? If you have a static IP - which a VPS most probably has - you can view it by issuing a ip a).

For example:

# ip a
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 8950 qdisc pfifo_fast state UP qlen 1000
    link/ether fa:16:3e:d6:6e:15 brd ff:ff:ff:ff:ff:ff
    inet 10.50.0.24/24 brd 10.50.0.255 scope global dynamic eth0
       valid_lft 83852sec preferred_lft 83852sec
    inet6 fe80::c5f4:d95b:ba52:865c/64 scope link
       valid_lft forever preferred_lft forever

See the IP address on eth0? (10.50.0.24) this is the IP address of the server.

**Yes **- for those of you who've noticed, this example is a private address. But if you have a VPS you should have a public IP.

I could tell neighbors to connect to my UDP port: udp://10.50.0.14:14600 or to my TCP port: tcp://10.50.0.14:14600.

Note that the playbook installation automatically configured the firewall to allow connections to these ports. If you happen to change those, you will have to allow the new ports in the firewall (if you choose to do so, check google for iptables or firewalld commands).

Checking IRI Full Node Status

The tool curl can issue commands to the IRI API. For example, we can run:

curl -s http://localhost:14265 -X POST -H 'X-IOTA-API-Version: someval' -H 'Content-Type: application/json' -d '{"command": "getNodeInfo"}' | jq

The output you will see is JSON format. Using jq we can, for example, extract the fields of interest:

curl -s http://localhost:14265 -X POST -H 'X-IOTA-API-Version: someval' -H 'Content-Type: application/json' -d '{"command": "getNodeInfo"}' | jq '.latestSolidSubtangleMilestoneIndex, .latestMilestoneIndex'

Something worth mentioning is: if you've just started up your IRI node (or restarted) you will see a matching low number for both latestSolidSubtangleMilestoneIndex and latestMilestoneIndex. This is expected, and after a while (10-15 minutes) your node should start syncing (given that you have neighbors).

Connecting to IOTA Peer Manager

As you've seen above, iota-pm listens on the local interface by default. We can change this, and let it listen on the external IP so that we can connect our browser to it.

Get your external IP address (see above: ip a) On CentOS, edit the file /etc/sysconfig/iota-pm (using nano or vi). On Ubuntu the file is here: /etc/default/iota-pm Change the line:

BIND="127.0.0.1:8011"

to:

BIND="<your external IP address>:8011"

and restart iota-pm:

systemctl restart iota-pm

Now, if you issue a lsof -Pni|grep iotapm, you should see it is listening on the external IP.

You should be able to point your browser to this address, e.g. http://<your-IP>:8011.

NOTE Do not leave iota-pm listening on this port, as this installation does not configure any security or authentication. Anyone can gain access to your iota-pm and mess up with your node. You can run iota-pm behind a proxy (nginx?) and add basic authentication to it.

Adding or Removing Neighbors

In order to add neighbors you can use the iota Peer Manager. It adds the neighbor "on the fly", but you will also have to add the neighbor to the configuration file of IRI. The reason is that after a restart of IRI, any neighbors added with the peer manager will be gone.

In CentOS you can add neighbors to the file:

/etc/sysconfig/iri

In Ubuntu:

/etc/default/iri

Edit the IRI_NEIGHBORS="" value as shown in the comment above.

IRI Remote

IRI has a command-line argument ("option") --remote. What does it do? By default, IRI's API port will listen on the local interface (127.0.0.1). This doesn't allow to connect to it externally. By using the --remote option, you cause IRI to listen on the external IP. For example on CentOS edit /etc/sysconfig/iri, in Ubuntu /etc/default/iri. Find the line:

OPTIONS=""

and add --remote to it:

OPTIONS="--remote"

Then restart iri: systemctl restart iri After IRI initializes, you will see (by issuing lsof -Pni|grep java) that the API port is listening on your external IP.

The playbook, by default is set to not allow external communication to this port for security reasons. Should you want to allow this, you need to allow the port in the firewall. In CentOS:

firewall-cmd --add-port=14265/tcp --zone=public --permanent && firewall-cmd --reload