The ultimate IOTA-Ict tutorial : General edition

Lambtho

IOTA Ict project is advancing fast. New changes are introduced almost every week and user experience has been greatly enhanced over the last couple of weeks. The last release of Ict (Ict 0.5.x) introduced a wonderful web interface to configure, edit and run everything super easily. No more terminal (almost)!

Home page of Ict web interface.

This guide replaces the previous ones and focus on the GUI configuration. It can be employed either for a fresh install or to upgrade an old one to the last version of Ict. The install process is based on an all-in-one install script created by discord user Phil Schaeff and requires no prior technical knowledge.

If you simply want to update from an older version, go directly in section 5 for the update commands and then come back to sections 2.d and 3 for the configuration through the webGUI.

If you plan to do a fresh install of Ict on a raspberry, Microhash has compiled a custom OS (based on dietpi) to flash on your SD card. This “PIct” comes with Ict pre-installed so only the configuration is required. This way of installing Ict is the subject of its own tutorial (link very soon).

You will need…

As of today, Ict can run on any device connected to internet and capable of running java. It can be a Raspberry Pi (a zero or an old version is enough), a Rock64, a regular computer, a VPS, any Virtual Machine or even an Android Phone.

The present tutorial only covers the Ict installation and configuration. Some very nice guides already exist to explain how to initiate the most common devices easily and make them ready for Ict installation.
- Setting up a Raspberry Pi
- Setting up a free google VPS
- Setting up an android phone

This tutorial will mainly focus on the installation for a Raspberry running Raspbian, but the general idea is the same for every other device.

Topics covered

  1. Setup of the device for external access
  2. Setup of Ict
    a. Overview of the install script
    b. Installation of Ict
    c. Finding neighbors
    d. Ict configuration
  3. Install and configure IXIs
    a. Chat.ixi
    b. Report.ixi
  4. Control Ict, interpret the logs,…
  5. Keeping everything up-to-date

1. Preparation of the device

This section assumes you already have a device running and connected to the internet. If you need guidance for it, refer to the tree setup tutorials linked here-above.

Obtaining a static IP

This step is only required if you do not have already a static IP, VPS users for instance are not expected to go through this.

Ict requires you to use a static IP to connect with your neighbors. Unfortunately, Internet Service Providers often provide dynamics IPs. Therefore, you will need to use a dynamic DNS service to have a static way of accessing your dynamic IP. With that service, your device will simply report the actual public IP to the dynDNS server every few minutes, so it can trace back to you.

Start by going on noip.com, or any other dyndns provider of your choice. Create an account and chose a domain name for easier access (this domain name is the one you will be giving to your neighbors).
Now you need to install some scripts on the raspberry that will send your IP to your dyndns provider.

The following commands are for noip install on a raspberry pi. For other systems, you should only change the path of the install /home/usr/noip.

You have to type the lines one at a time and pressing Enter after each one. You can see in depth what each command does on their documentation website.

mkdir /home/pi/noip
cd /home/pi/noip
wget http://www.no-ip.com/client/linux/noip-duc-linux.tar.gz
tar vzxf noip-duc-linux.tar.gz
cd noip-2.1.9–1
sudo make
sudo make install

After that last line, you have to enter your login and password (the ones that you used for noip.com).
The terminal will then ask you for the time interval between each update. Chose something strictly above 5, otherwise it will raise an error. Finally, enter N to the next question.

You can now run noip using

sudo /usr/local/bin/noip2

Finally, we need to make sure it will restart automatically after a reboot of the system. To do so, type sudo crontab -e , and type this at the bottom of the file

@reboot sudo /usr/local/bin/noip2

Save and quit by successively pressing Ctrl + O and then Ctrl + C .

Now simply type cd to return to the home directory before continuing the installation.

Note : Noip free domain names have an expiration date. Every month you will receive an email asking you to confirm that you are still using the domain. Do not forget to confirm it, otherwise your Ict will be disconnected to its neighbor.

Opening a port for Ict in your home router firewall

ICT requires a port to be open in your router (by default it is 1337 for Omega-Ict, but you can use an other one if you wish). Head to the router configuration interface (usually details are printed on a label attached to it). Locate the port forwarding or portmapping tab and link port 1337 to your device local IP and its 1337 port as well. Make sure that you use UDP, otherwise it will not work properly. If you use a VPS, locate the firewall option and allow traffic to the port you want to used for Ict.

While you are at it, you can open port 1338 as well, it will be used for the Report.ixi (we will cover that in a bit). You can also open ports 2187 and 2019 in both UDP and TPC if you are planning to access the web interface of ict and chat.ixi from outside of your network (if you installed ict already outside of your network, like in a VPS, you must do it).

Example config in my home router. External start and end are the one you give to your neighbor; Lan port is the one you will specify in Ict parameters.

2. Setup of Ict

As mentioned in the introduction, discord user schaeff (Phil#1641) created a simple script to automate the installation of Ict. The script was tested on various Linux based systems (debian, Raspbian, gentoo, Red hat,…).
It allows you to either build the executable from the sources or simply download the latest pre-compiled release of Ict. If your plan is to simply run Ict, you probably do not need to download and build the sources. Therefore using the pre-compiled release should suffice (and this will make the install much faster).

a. Script overview

As explained on the github page, the script does the following:

  • Install all required dependencies;
  • Add an user “ict” (security measure);
  • Download and compile the source code or simply download the latest pre-compiled release depending on user choice;
  • It will also download Chat.ixi and Report.ixi
  • Import the old settings from ict.properties if available;
  • Generate a systemd service for easier control of Ict;
  • Start Ict and show the logs.

More explanations on this script can be found on schaeff github repo.

b. Ict first installation

To avoid running into issues during the install process, copy/paste each line one at a time, do not paste multiple lines at once in the terminal.

First you need to install gitand download the install script:

sudo apt-get install git
sudo git clone https://www.github.com/phschaeff/ict-install

If you already have ict installed before and just want to update, please read part 4 of this tutorial “Keeping everything up to date”.

Now, simply run the script you just downloaded with the option to either build from sources (BUILD) or to download the pre-compiled release (RELEASE). Note that the node name should not have any spaces in it.

cd ict-install
sudo bash install-ict.sh <BUILD/RELEASE>

For example:

sudo bash install-ict.sh RELEASE

Everything is now being installed, this procedure can take up to 5 min. Once the install is complete, it will automatically launch everything and display the logs. It is perfectly normal to have errors at the first start, as nothing is configured yet. Quit the logs by pressing Ctrl+ C.

c. Finding neighbors

Ict requires at least one neighbor to operate properly. You can add up to three of them. Go in the #ict-help channel of IOTA’s Discord server and ask for neighbors. A bot was created to handle neighboring request. Simply call it by typing!ictnodes in the channel. A chat will open with the bot, just follow the instructions. If you need extra help type !help in this chat or simply ask in the #ict-help channel.

Since you are already on discord, take a few moments to rank-yourself in the ict-testing group. That will allow the devs and mods to ping you easily in order to inform you of the most important developments (new updates for instance). Go in #rank-yourself channel and type !rank ict-testing .

d. Ict configuration

The last step consists in configuring Ict to connect to your neighbors and tweak some other parameters. This is where the magic happens.

Open your typical web-browser and go to your node address using port 2187. If it is on the same local network as your computer, you can use directly its local IP. If it is not, use the static IP from the server or its domain name. Example :

192.168.1.25:2187
OR
mysuper.ict.com:2187

The webpage will ask you for a password. By default, you should use change_me_now .

The very first thing to do is to change that password for obvious security reason. Do not skip this step! If you do not do it, anyone with your node address (a neighbor for instance) could access the GUI and change parameters.
Simply go to the configuration tab and change the password field (bottom right corner). Then save your configuration using the save button (upper right). All other parameters can be kept at their default values. It is not advised to change them if you do not know what you are doing.

Finally, you need to add your neighbors. Simply go to the neighbor tab and click the add new button to add a neighbor. Then input its address and save. Note that the address should have the form <domain/IP>:<port> .
Example :

12.45.56.88:1337
OR
mysuper.neighbor.com:1337

After a few moments (can take up to a minute), the stats of that neighbor will be plotted on a graph. If it does not update automatically, try refreshing the page.

3. Install and configure IXIs

IXIs are modules that extend the capabilities of Ict. The two major ones available currently are chat.ixi, a decentralised chat, and report.ixi a module that reports your Ict stats to a central server to better mesh and analyze the network. Note that the current version of the all-in-one installer installs those two IXIs by default, so they should already be present on your device.

Start by going to the MANAGE MODULES part. If there is nothing under the installed modules, then we will have to explicitly install them. If they are already installed, then only the configuration is required.

a. Chat.ixi

This IXI is a Proof-of-concept developped by the foundation itslef. If it is not installed, it should be listed in Supported modules . Just click the install to install it on your device. The github repo will already be pre-completed and you simply have to click install a second time.

Once the module is installed, a new tab called CHAT.IXIshould appear in the IXI MODULES menu. Click on it to configure the module.

Sometimes that menu does not appear automatically. Simply refresh the page and it should pop up.

There, you can change your password and the username. For clarity, please use the same username as in discord if possible.

Once this is done, go back to the MANAGE MODULES tab and click Launch next to Chat.ixi. You will likely first be greeted by an error message. Just discard it. After that, the chat will ask you for the password (the one you just changed). You can now start chatting!

b. Report.ixi

Report.ixi is a very useful tool to assess the health of the global Ict network, gather some information that can be used for simulations or simply enable the creation of sick network visualizers.

Cool visualizer of the Ict network by Olaz (olaz preton#0333), based on report.ixi data.

This module was created and is maintained by two community members (testIT#4170 and ixuz#6751). To install it, go in the MANAGE MODULES tab and click install third party module . Then use the following repository address: trifel/Report.ixi and install.

Once the module is installed, a new tab called report.ixi should appear in the IXI MODULES menu. Click on it to configure the module.

Start by putting a proper name. The convention we all adopted is <name> (ict-<#>) please use the same name as on discord so we can warn you if there is a problem with your node. The <#> is the number of your Ict device (useful if people have multiple Icts). The numbering starts at 0. So for example

lambtho (ict-0)
lambtho (ict-1)
...

Then make sure that the ICT REST API PASSWORD is the same as the one you used for the ICT configuration. If it was not the same, hit save after changing it and refresh the page. This will auto-complete the neighbor field and ease the rest of the configuration.
Finally, in the Neighbor field, make sure that each reportPort parameter is set properly to the ones given by your neighbors.

Obviously, if you whish to use ports that are different from the default ones for the GUI or for Report, change those fields as well (and do not forget to adapt your port-forwarding rules in your router/firewall).

Finally hit save. Ict will reload the module automatically. Report.ixi works in the background, you will not need to interact with it in any special way. You can watch in detail the health of your node on report website: https://www.ictreport.com .

4. Control Ict, interpret the logs,…

Ict controls

Currently, there is no way to control Ict directly from the GUI. So the control can only be achieved through the terminal.
For easier management, the install script makes Ict run as a services. That means you can safely close the terminal or the ssh connection and it will continue running.

You can start, display the status, stop or restart Ict respectively with the following commands:

sudo systemctl start ict
sudo systemctl status ict
sudo systemctl stop ict
sudo systemctl restart ict

You can also display the logs with (press Ctrl+ C to quit those logs)

journalctl -fu ict

Note that the logs can also be accessed directly in the wbeGUI.

Ict logs

The logs should normally look like that

Typical Ict logs

Every minute, Ict will print five metrics for each neighbor. They correspond to what happened only during that last minute.

  1. ALL: total number of transactions received from the neighbor. This number should be different from 0 (0 would mean that the connection is not working between you two). A low value indicates that the neighbor is poorly connected to the rest of the network.
  2. NEW: total number of new transactions received from the neighbor. A transaction is considered new only if it was never seen before by your device. So if I receive a transaction A from N1 first then from N2 a bit later, it will only be counted in new for N1 and not for N2. (But it will be counted in ALL for both).
  3. REQ (requested): total number of requested transactions from your node to your neighbor. This happen if you receive a transaction whose trunk or branch is not already known to you. In that situation your Ict will try to request those information from your neighbors.
  4. INV (invalid): total number of invalid transactions received from the neighbor. It should be 0 or close to 0 at all time. High values indicates a bad neighbor.
  5. IGN (ignored): total number of ignored transactions. If a neighbor sends many transactions in comparisons with the other neighbors, some will be ignored as it is will be flagged as spam.

5. Keeping everything up-to-date

To keep everything up-to-date, simply get back to your home folder with cd .
Then update the all-in-one installer by successively typing

cd ict-install
sudo git pull

It might tell you that the all-in-one script is already up to date. It is fine, just continue the execution, the script will automatically pull the latest version of Ict anyway.

Finally run the install script all over again:

sudo bash install-ict.sh RELEASE

I hope you found all the information you needed in this tutorial. Thanks a lot to the other community members that help make Ict the very nice project we have now, and obviously thanks a lot to Microhash for his hard work and precious explanation about Ict.

If you still have some issues, do not hesitate to join the #ict-help channel of IOTA’s Discord server and ask your questions. Lots of people will gladly help you sort this out.

Tips in IOTA are always very much welcomed. I will be split them with community member active in the development of Ict.

TCO9AVVRVAVHMSHWHNGHNNYXJXPQUKXEPBALLLNZTLLRHIEOYEGWBZEBWPPGCVBFILAVRMNMSBPUBZYKBZDIEXADUW

Lambtho

Written by

Lambtho

PhD in Aerospace Engineering, crypto enthousiast, strong interest in IoT and IOTA.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade