a step by step guide for beginners (Part 2) — managing your node (updated for hornet version 1.02 and HORC 1.03 on 30.05.21)
I hope you found the first part of the guide useful in which i explained you the basic setup of an IOTA Node using Nuriels playbook script on a VPS, and you should now already have a fully working IOTA Hornet node connected to some peers and processing transactions. The first part of the guide:
Managing your Hornet Node with HORC
Now its time to learn a bit more how you can use and manage functions of the node, how to update the node software and how to handle problems and errors should they appear.
To manage the basic functionality of the node Nuriel has implemented a command line tool that will help you to do basic functions without typing in code… exactly as we like it to be as non developers. To access this tool we need to connect to the operation system of our node using the secure SSH login method with the Putty-tool. So please open Putty. Clicking on the ‘saved session’ that you created before and the “load” button will load the connection configuration to access the operation system of your node on your VPS server.
If you do this, in the “host name” field the IP address of your VPS server should appear. Click on “open” and the black screen of the Putty command line will open, asking you to login. Remember, our login is the superuser “root” and the passphrase is the one you created when creating the SSH key. Type it in (you will not see the letters when you type for security reasons).
And to access the tool that allows you to control the hornet node functions type in
horc
and press enter. This screen will appear:
Which gives you an overview over all the functions you are able to control.
If you open HORC and see that an update for the HORC software tool is available, so lets do this first to make sure that we have the latest functionality. Navigate towards menu “h) Update HORC and node scripts” with the cursor keys of your keyboard.
Pressing enter opens this:
And pressing enter again starts the update. An installation routine will be executed. It finishes with this screen and pressing enter brings you back to the menu.
a) Update Hornet Software
From time to time the IOTA protocol or the hornet node software gets updates to implement new features or to improve the protocol. It is your duty to carry out this update because only nodes that run the latest software can be considered fully functional and safe. So you should be following the official IOTA channels in which essential updates to the node software will be published. This is mainly the #hornet-dev channel in the IOTA Discord server :
or the Hornet teams official twitter account:
It is important that you keep up to date with the developments.
So as soon as you see that a new version of the hornet software is published you can use the “HORC” tool to do this update.
So if you choose point a) now you will see this
Which means an update now is not possible, but if a new version is available it will update your node in an automated process.
b) Hornet plugins (for developers!)
Plugins are small pieces of software that are packed into the hornet software and execute own functionality. We have the option to use or not use those plugins and their functions. You should absolutely not do anything in this menu until you really understand those plugins. So i highly recommend you to not do anything there. If you choose point b) of the “horc” main menu you will see this screen:
c) Hornet services
Services are prebuild functions that run “as a service” inside the node software. Choosing point c) and pressing enter offers you 2 choices:
a) Hornet
b) Nginx
Choosing “a) Hornet” opens this:
a) Status will show you something like that:
which will provide you all basic information about the current status of your node — it can be a useful file if you ever run into some trouble and need help from a more experienced community member (ask in #hornet-discussion in the Discord) to present this. Pressing the key “q” will bring you back to the Hornet services menu.
b) Start
Will start the hornet node when the node is stopped
c) Stop
Will securely stop the hornet node
d) Restart
Will securely stop the Hornet node and start it again
e) Disable start on reboot
Normally your Hornet node will automatically restart if your VPS operating system gets restarted. This command stops the automatic restart logic. So if maybe your VPS Server goes offline for a service, or because of a problem at your VPS provider the hornet node will wait until you initiate to start the node again with “b) Start”
f) Enable start on reboot
Will implement the auto — start logic when your VPS boots up.
g) View logs
This is a very useful function to find out what’s going on if you see an unexpected behavior on your node (like being out of sync or unhealthy, etc…). A good hint on how to navigate in the logs is printed already in the main menu view:
So you can navigate through the log output upwards (back in time) with the “up-key” on your keyboard, pressing “shift-g” brings you back to the newest entry. Leave the log output with “q”. A dev or more experienced community member might be able to help you with your node if you can find “error” or “warning” messages in the log output.
Choosing “Hornet-services” menu b) Nginx will show this:
What is Nginx?
Nginx is a Reverse Proxy Server service. It is one of the largest and best know providers of such a service in the world and is used by large company Websites like Netflix, Wordpress and Dropbox to balance the traffic load to their websites. A reverse proxy serves as a single gateway to multiple services or servers behind the gateway and protects the services and servers behind this gateway from malicious actors. It serves as part receptionist, directing incoming requests to the right department, and part bouncer, keeping intrusive eyes away from your internal infrastructure.
Nginx is preconfigured from the Nuriel playbook script and starts together with hornet.
Choosing “a) Status” shows you normally that status is loaded and active — all fine.
“q” brings you back to the main menu.
The other menu functions of the service are exact the same as before described for the “Hornet service”. g) View logs will not show you a “live output” but instead an event log. Very likely this will be empty.
d) Configure Files (caution!)
The next “horc” menu point — files….
Files are the “code” of your hornet software and offer access to everything your node does. This is why you should only do anything here if you understand what you are doing. It is very easy to completely destroy your hornet installation in this files.
a) Hornet system config
DO NOT TOUCH THIS FILE, dont even open it unless you are really aware of what’ s going on.
b) Hornet Main config
Be very very careful when you try to edit this file.
You can do various changings to your Node behaviour, but better leave this until you would call yourself an experienced user. Nuriels Playbook offers for most functions an easier option.
c) Hornet peers config
Here you could configure fixed peers for your node instead of using the function in the Hornet dashboard, but i recommend to use the dashboard function. Every peer that you add in the dashboard with an alias will directly also be saved in this file.
d) choose editor
The ability to choose different file editors for Linux command, Nano is preconfigured.
e) View per process memory usage
Gives you an overview how much memory single program processes use, can be useful to locate errors.
f) Rerun Playbook installation
This is a good idea if you run into trouble that you cannot fix, if you accidently maybe changed a setting or a parameter and are not able to fix it anymore. It provides a “factory reset” for your node software if you choose “yes”.
g) Clean unused Docker images
Mainly can free a bit disk space if you run low on storage. If you did several “reruns” of the playbook software it leaves unused program images in your storage, this function removes it and frees the disk space.
h) update HORC and node scripts
Updates the horc application and the Nuriel playbook as described at the beginning of this guide.
i) Enable https / certificate
This is a useful service if you own already a domain name and want to use this domain for your server. With enabled https certificate you will also be able to use your own node as an entry node for your own transactions using the IOTA Firefly wallet.
j) Get Node info
Will show you a quick overview of the status of your node, similar as the hornet dashboard would do.
l) Get new Snapshot db
This function will delete your Nodes Transaction database and download the last recent snapshot to start with a clean fresh database for your Node. So if your Node crashed because of storage limitations you can use this Function to clean it up and start fresh.
m) Set db maximum size
Here you can define how much storage in your VPS Database is used by the node to store Transaction Data. So you can decide yourself if you want to invest in a large SSD storage to keep a lot of data or choose a maybe cheaper VPS and keep less data locally stored
So pretty easy… if you have a larger SSD and no problem just set a larger size here in GB and you will store more data…
Default is set to 25GB so this should be enough for most of the current VPS setups.
n) Peers
Here you can add or delete and list peers, similar as you would do it in the Hornet dashboard. I recommend to use the Hornet dashboard for this case.
o) Update config.json
This function allows you to restore your configuration file to the default values and configurations that have been used for the Playbook, or to update the config file if there have been changes from the hornet Team. You can use this function if you tried modifications on the config.json file yourself , made a mistake and want to revert changes.
p) Set new peer id
You can use this function if you want to obtain a new peer id. Maybe you accidently revealed you peer id publicly and now get a lot of random unknown neighbors. To many neighbors can lead to reach the processing limits of your node and that can lead to loose sync with the network. So if you want to be only connected to your “known peers” use this function.
There will be no confirmation screen after the main menu, so it will execute directly!
Afterwards inform your known neighbors that you have a new Node ID so they can update their peering info for you. Never reveal your peering ID publicly or post it on social media.
z) Configure this script
DO NOT USE THIS!
So this was the tutorial about the HORC control tool of your node and i hope you found it useful and con now manage a bit more of your nodes functions.
You can also find more detailed information and a lot of further useful tips around troubleshooting in Nuriels amazing playbook guide here:
nuriel77/hornet-playbook: Ansible Playbook for Hornet IOTA Full Node (github.com)
As always, if you have questions you can contact me in the IOTA Discord:
If i could help you with this guide and you want to donate something, feel free to send to this IOTA address:
iota1qqjn97wql48n6kvcdunngnvjtus8pjtd0keyd8l54qxp9v7vjdv66cwgmcv
As this article series is aiming for beginners i am not going to deep into some topics, but if you would like to increase the security of your node installation further in the future, i recommend this article. It was written for the old IOTA network nodes, but all recommendations can be also used for the current set of Nodes:
https://iri-playbook.readthedocs.io/en/feat-docker/securityhardening.html
