Document updated to SWARM version 1.0.3.4
IMPORTANT. Previous versions of this guide suggested using port 445 for Bee but this caused problems on some browsers. Port 440 is now preferred (credit oliver#2204).

Installing an Iota Bee node on a Netcup virtual server using SWARM

last change to this doc - 6 Dec 2021

NB TangleDust.com is not an 'official' Iota site. See below for lots of Iota official links. Please note also that Bee is regularly being updated so these instructions may be out of date. See the official Iota Wiki for the latest and best information. If you want to give feedback then the author of these notes is @dumdave on the Iota Discord server.

If you wish to contribute to the preparation and improvement of this guide and others coming on the TangleDust.com website then please demonstrate the efficiency of the Iota network by donating a little to this Iota address, but remember that most credit should go to the clever creators of SWARM, and of Bee itself, not the maker of a guide to using SWARM!

iota1qp2fgd7nn00x09lnru7lzya3a72khuqrw25yafc3ehhuz2ucykpgk8m0hum

Iota Hornet and Iota Bee nodes

An Iota node is software that runs on a server and is connected to the internet. It maintains a database recording the state of the Iota network and it gives access for transactions on that network. Some transactions are just simple data messages, some transactions are financial using the Miota token that has a value and may be purchased at exchanges.

Hornet and Bee both carry out the same function. They are connected to the existing Iota network. Bee is designed for use on smaller devices (maybe a Raspberry PI) and Hornet is designed primarily for relatively more powerful servers. Note that all Iota servers use comparatively inexpensive hardware, certainly as compared to those needed for many 'crypto' networks.

Even though Bee can run on less powerful devices, many find it useful to run Bee first on a virtual server like this as part of the learning curve. It can be run alongside Hornet on the same server so it need not add cost to a project.

There is another node, Goshimmer, which is connected to the future Iota network, but these notes concern themselves only with the existing network, and in particular the Bee node. If you wish to install a Goshimmer or Hornet node then please see the guides below.

Guide 1. Notes on installing an Iota Hornet Node with SWARM
Guide 2. Notes on installing an Iota Goshimmer Node with SWARM
Guide 3. Notes on installing an Iota Wasp Node with SWARM

SWARM Script

SWARM is an interactive shell script written using 'whiptail'. This provides a user-friendly menu to perform virtually all of the necessary actions. It is produced by TangleBay. For interest, you can see their Github at the following address, though please follow the guide below for installation etc.

Please note that SWARM can also install the two other Iota nodes, Goshimmer and Hornet, as well as Wasp which is for Iota Smart Contracts.

github.com/TangleBay/swarm

Support by Iota and TangleBay

If you are planning to install an Iota node then you are strongly advised to join the Iota Discord which has channels covering each and every aspect of the Iota project and hundreds of enthusiastic members who will give you advice. Tanglebay also has a Discord for more specific issues to do with SWARM - they also offer other useful services. The Iota website is also a good starting point.

www.iota.org

Netcup Virtual Server

These notes are based on an installation on a Netcup virtual server running Ubuntu, but obviously are applicable to other similar server setups. Why Netcup, located in Karlsruhe, Germany? The cost for a one year contract was Euro 72.61 (including VAT) as at Oct 2021 - about GBP 62 or USD 84.

www.netcup.eu/vserver/vps.php

Netcup Server pricing

You may find the process of ordering a little different because of their 'know your customer' procedures. So (a) place your order online. Be sure to complete all of the requested details inc. phone numbers. (b) be contacted while they check who you are. (c) receive an invoice and access to your Customer Control Panel (d) pay the invoice (e) get access to your Server Control Panel. They are quite used to dealing with English speakers so no need to brush up on your German first. All interfaces are naturally available in English!

NB The Server Control Panel is also useful later if you need to reboot the server because you cannot get access. It has a Powercycle option that does the trick! Use the Control option on the left menu.

Netcup Server Control Panel

Installing Ubuntu is trivial. Select the server, go to Media on the lefthand menu then Images on the top menu. On the main screen select the Distribution 'Ubuntu 20.04 LTS' then follow the menu options.

There are many steps needed after that to set up a secure SSH connection, but notes on that are available in many places. These notes continue on from a situation where SSH has already been setup

Uncomplicated Firewall

One thing that is worth mentioning is the need for a firewall, in this case 'ufw'. The key commands at the Terminal are in this form:

sudo apt install ufw => the installation

sudo ufw status => see which ports are allowed and disallowed

sudo ufw allow 22/tcp => or just sudo ufw allow 22 (or deny)

The Iota Wiki has various information for ports for Bee, so please check whether the information below is correct there.

wiki.iota.org/bee/getting_started/getting_started

The only required port to open for Bee is 15600 as below. See the wiki link above for more information.

p2p: 15600 (Gossip protocol port)

REST HTTP API port: 14265 TCP (optional)

NB If you are using the reverse proxy (see below) with Bee on port 440 then that also needs to be open so that you can access the dashboard etc.

Installing SWARM

Check with the SWARM Github site Readme for the latest information if in doubt. That currently suggests using:

curl -sL https://raw.githubusercontent.com/tanglebay/swarm/master/installer.sh | sudo bash -

After that, simply typing 'swarm' (quote marks not needed) at any time in Terminal while connected to your server should trigger the script and give you the menu below. Just use the arrow keys and Enter to navigate around. To exit a screen usually you use right arrow to get to Cancel and then press Enter.

NB If typing swarm does not start it, then there is likely to be a problem with the Path statement. Ask on the Tanglebay Discord if help is needed.

Note that you can expect SWARM to evolve so screens may change.

The first option on the main menu 'SWARM Menu' and then option 5 for 'Manage SWARM' allows you to update SWARM itself as necessary.

SWARM Main Menu

Installing an Iota Bee Node using SWARM

As these notes are concerned with installing an Iota Bee node, select 3 on the front page of the SWARM Menu to get to this:

SWARM Bee Menu

The first step is to Install Bee, so select option 4 to get to this menu.

SWARM Bee Install Menu

Finally, select Option 2 to trigger the installation of Bee. Once that is done, back at the Bee menu shown above select option 1 'Bee Info' which should confirm that there is now a running Bee installation by showing a screen like this one, though note that this has been running for a while. Also note that you may need to add 'peers' - see below.

SWARM Bee Info screen

The Iota Bee Dashboard

Although it cannot be accessed easily yet on a remote server, it is worth looking at the Iota Bee dashboard to show why it is useful. There is usually a login screen first, which looks like this:

Bee dashboard 1



Once logged in there are a lot more options and information screens. Be aware that for Bee you may need to add some 'peers' before it becomes active - more about that below. [The Hornet node usually has 'autopeering' which gets peers for you]

Bee dashboard 1



Setting up Reverse Proxy with SWARM

If you plan to set up other Iota nodes like Hornet, Goshimmer and Wasp (there is no problem in principle in having them on the same server) then it is best to set up their Reverse Proxy at the same time as the Bee one. SWARM goes through a process that includes using 'letsencrypt' to set up the SSL certificate for the domain you are using, which it ideally only needs to do once if you are using a single host name as below.

For example, if the Netcup setup being used for these notes was given the host name: v2202110158313xxxxxx.ultrasrv.de and if Bee, Hornet, Goshimmer and Wasp were setup on the server they could be accessed by different ports as below.

In other words, the reverse proxy needs to use just the port number to distinguish where to redirect to. More information on this is below, but SWARM will arrange it all with no further input once you have supplied your choice of port numbers and told it the host name.

Hornet dashboard: https://v2202110158313xxxxxx.ultrasrv.de:444/dashboard

Bee dashboard: https://v2202110158313xxxxxx.ultrasrv.de:440/dashboard

Wasp dashboard: https://v2202110158313xxxxxx.ultrasrv.de:446/dashboard

Goshimmer dashboard: https://v2202110158313xxxxxx.ultrasrv.de:447/dashboard

NB If you are installing Wasp then there will be a 5th port needed for the Wasp API (e.g. 448)

Returning to SWARM, from the home page of the menu, select Proxy Menu. Be sure to have listed a port number for each of the items that you plan to install. If it is only Bee then you need only one port number.

SWARM Reverse Proxy

IMPORTANT. You first need to configure the port settings before you deploy the reverse proxy, so be sure to first select Option 2 as below.

SWARM Configure Proxy

That takes you to this page, where you repeat the same procedure for each node that you have installed or plan to install. IMPORTANT. You also need to set a port for the Landing Page (see below) - it can also be port 440, as Bee, as the Proxy can tell the difference between web addresses ending 'ultrasrv.de:440' and those ending 'ultrasrv.de:440/dashboard'.

SWARM Configure Proxy Bee

For example, for Bee you have this menu page which asks you in turn for the Bee domain and the Bee port. In this case the domain is: v2202110158313xxxxxx.ultrasrv.de and the port is: 440

SWARM Configure Proxy Bee settings

Remember that there is also a Proxy Settings option for the Landing Page (see above for port) - which is where SWARM will install the following. Note that it is dynamic with three options: Green=active Red=inactive Grey=not installed. Clicking on any of the images should take you to the Dashboard of the relevant node.

SWARM Landing Page 1

Deploying the Reverse Proxy

Now that you have entered the port settings etc, the reverse proxy can be deployed by SWARM. It uses 'nginx' for which the docs are here if you need to dig into what is happening. Further below there is more detail on the relevant files used etc but be aware that if you use SWARM it may reset any changes you make to fit the settings you entered through SWARM. [See also SWARM Watchdog below]

https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/

Returning to the SWARM menu, select 4 for the Proxy Installer as in the screen below.

SWARM Proxy Installer

You then have a menu to select the actual install. If all goes well then this should run and do several things. (a) Get an SSL certificate, (b) Run nginx and set up the reverse proxy by putting files into the /etc/nginx/sites-enabled folder, (c) Set up a landing page to make it easy to navigate between the nodes and to monitor their condition.

SWARM Proxy Installer page 2

Congratulations. You should now have access to the dashboard of your Bee node. There is some more useful information below on the config.json file and the nginx reverse proxy files, but there are two more things to do.

Adding Peers

Any Iota node needs other Iota nodes to 'gossip' to. That means, to exchange information about messages arriving from elsewhere on the network, and to pass on any information about what is happening directly on the node itself. Obviously each node cannot communicate directly with too many other nodes so it is usual to have about 4 peer nodes though 2 can be fine and more than 4 is commonly seen.

Both Bee and Hornet used to have to add the address details of some peers to their settings in order to work. Hornet has introduced 'autopeering' which handles this for you. It is believed that with Bee, peers still need to be added 'by hand' although autopeering is planned. Luckily SWARM once again has a menu option to make this easy. Go to the Bee menu again and select option 2 Bee Configuration.

SWARM Bee menu

This takes you to another menu where you are offered a choice between Bee configuration and Advanced configuration. Option 1 is what is needed to set up peers. NOTE. It is possible to add peers directly in the Bee node but SWARM will probably just remove them again at some point if they are not entered here within SWARM.

SWARM Bee configuration choice menu

The next screen gives you a range of interesting options including (2) setting up your username and password for the dashboard. For the moment though select 1 for 'peers'.

SWARM Bee configuration menu

Finally this is the 'peers' screen. Option 1 would show peers already set up, so is probably blank at this stage. Select 'Peer 1' in order to enter your first peer - which raises the question of where peers can be found!

SWARM Bee peers menu

For each peer there are two required items of information.

The 'alias' is just a simple text description of that peer as meaningful to you e.g. London5

The 'address' is the significant part - see the next section, nodesharing, for more on that.

SWARM Bee peer entry menu

Nodesharing channel on the Iota Discord

Join the Iota Discord and go to the 'nodesharing' channel. As at 3 Nov 2021 there were several people with Bee nodes seeking peers to connect to.

Peer addresses will resemble this form (this one is not genuine so do not copy):

"/ip4/49.17.165.93/tcp/15600/p2p/12D3KooWRAdseyBbrYZ7Htebj4mFrA6gFJjSXg9nufyWchEby"

There is also a 'dns' format using domain name rather than ip address. The 15600 is for the gossip port, p2p is peer-to-peer, and the final string is the node identity you will find on the home page of your Bee node once you are logged in.

With nodesharing on the Iota Discord, somebody gives you their node address and in return you give them yours. If someone asks why you are not using 'autopeering' simply explain that you are running a Bee node.

SWARM Watchdog

Watchdogs are used to monitor if a system is running and to take appropriate action if not. SWARM implements a watchdog system. Go to the SWARM menu home page and select 1 then you should find the following screen where you select 2 to Configure SWARM.

Configure SWARM page

This page lets you decide whether to enable or disable Watchdog, and if you do enable it then to decide on the settings you'd prefer for various aspects of the installation. It is a very powerful tool so it is wise to spend a little time looking around here, particularly if you wish to make edits of some settings and do not want SWARM resetting them for you.

Configure SWARM Watchdog

This was a typical Watchdog 'info' page from SWARM v0.9.9 which shows just how much Watchdog is able to do.

Typical SWARM Watchdog info

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

End notes on Iota Bee Node Installation with SWARM

IMPORTANT. DO NOT MAKE CHANGES DIRECTLY TO THE CONFIG FILE IF USING SWARM - SWARM WILL USUALLY OVERRIDE THEM

The Bee Config file (toml format)

The config file for the installation of Bee is at: /var/lib/bee and note that it is in 'toml' form rather than json. You need the one called 'config.chrysalis-mainnet.toml' or possibly 'config.toml'. If you have the correct one then it will show the peers you have entered. The config file looks like this (NB various random changes made to seeds, keys etc out of habit so do not rely on those). Note that the dashboard is on local port 8082, relevant for the nginx reverse proxy file lower down.


identity   = "cda6ed45b290a097ddssec23ce13e86a1749fcafe96defSCW1d9se3>
alias      = "Bee"
bech32_hrp = "iota"
network_id = "chrysalis-mainnet"

[logger]
color_enabled = true
[[logger.outputs]]
name              = "stdout"
level_filter      = "info"
target_filters    = []
target_exclusions = []
[[logger.outputs]]
name              = "warn.log"
level_filter      = "warn"
target_filters    = []
target_exclusions = []

[network]
bind_address            = "/ip4/0.0.0.0/tcp/15601"
reconnect_interval_secs = 30
max_unknown_peers       = 0

[network.peering]
[[network.peering.peers]]
address  = "/ip4/65.13.245.133/tcp/15600/p2p/12D3KdebASWeWf9B3ZkAmT5vzqFz>
alias    = "layers1"
[[network.peering.peers]]
address  = "/ip4/23.12.195.45/tcp/15600/p2p/12D3KSDevrgyBbrYZ7Htebj4desrA6g>
alias    = "layers2"
#[[network.peering.peers]]
#address  = ""
#alias    = ""
#[[network.peering.peers]]
#address  = ""
#alias    = ""
#[[network.peering.peers]]
#address  = ""
#alias    = ""
#[[network.peering.peers]]
#address  = ""
#alias    = ""

[protocol]
minimum_pow_score = 4000
[protocol.coordinator]
public_key_count  = 2
[[protocol.coordinator.public_key_ranges]]
public_key  = "a9b46fe743df783JJ8f&6b34241f5913cf249d75bed3aafd65e"
start       = 0
end         = 777600
[[protocol.coordinator.public_key_ranges]]
public_key  = "365fb85e7568b9b32f7359d6cbaf*&Hngad0ecbad32d77beaf5d"
start       = 0
end         = 1555200
[[protocol.coordinator.public_key_ranges]]
public_key  = "ba6d07d1a1FTGB435f9f7d1b736ea9e0fcb8de400bf855dba7f2a"
start       = 552960
end         = 2108160
[[protocol.coordinator.public_key_ranges]]
public_key  = "760d88e112c0fd210cfJUKMSSf7e18c456c2fb9646cabb2e13e36"
start       = 1333460
end         = 2888660
[[protocol.coordinator.public_key_ranges]]
public_key  = "7bac2209b576ea2235539358HSDEd2f2fc35a663c760449e65eba9f8"
start       = 2111060
end         = 3666260
[[protocol.coordinator.public_key_ranges]]
public_key  = "edd9c639a719325e465346b8SEDDb7d476dd87fc949c0e8df516"
start       = 2888660
end         = 4443860

[protocol.workers]
status_interval       = 10
milestone_sync_count  = 200

[rest_api]
bind_address          = "/ip4/0.0.0.0/tcp/14266"
feature_proof_of_work = true
public_routes         = [
    "/health",
    "/api/v1/info",
    "/api/v1/tips",
    "/api/v1/messages",
    "/api/v1/messages/:messageId",
    "/api/v1/messages/:messageId/metadata",
    "/api/v1/messages/:messageId/raw",
    "/api/v1/messages/:messageId/children",
        "/api/v1/outputs/:outputId",
    "/api/v1/addresses/:address",
    "/api/v1/addresses/ed25519/:address",
    "/api/v1/addresses/:address/outputs",
    "/api/v1/addresses/ed25519/:address/outputs",
    "/api/v1/receipts",
    "/api/v1/receipts/:milestoneIndex",
    "/api/v1/treasury",
    "/api/v1/transactions/:transactionId/included-message",
    "/api/v1/milestones/:milestoneIndex",
    "/api/v1/milestones/:milestoneIndex/utxo-changes",
]
allowed_ips = [
    "127.0.0.1",
    "::1"
]
white_flag_solidification_timeout = 2

[snapshot]
full_path         = "./snapshots/mainnet/latest-full_snapshot.bin"
delta_path        = "./snapshots/mainnet/latest-delta_snapshot.bin"
download_urls     = [
    "https://chrysalis-dbfiles.iota.org/snapshots/hornet/"
]
depth             = 50
interval_synced   = 8640
interval_unsynced = 1000

[pruning]
enabled         = true
delay           = 60480
prune_receipts  = false

[storage]
path = "./storage/mainnet"

[tangle]
below_max_depth = 15

[mqtt]
address = "tcp://localhost:1883"

[dashboard]
bind_address    = "/ip4/0.0.0.0/tcp/8082"

[dashboard.auth]
session_timeout = 86400
user            = "adminq"
password_salt   = "a808fe1db2e430edesvfrgc8504667d192cf22216c1d8b7f759e7bfb053d>
password_hash   = "bff332fda7a96cb2afsed456wwq545fb9a29e3ed493167cb9845c99e1b23e>

                


_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _



IMPORTANT. DO NOT MAKE CHANGES DIRECTLY TO THE REVERSE PROXY FILE IF USING SWARM - SWARM WILL USUALLY OVERRIDE THEM

The Bee Reverse Proxy File

As described above, the reverse proxy setup by SWARM uses nginx so the files are in: /etc/nginx/sites-enabled where there is one for each different port setting on the main domain. If you have all of the nodes set by SWARM then it will contain all of these

bee default goshimmer hornet wasp-api wasp-dashboard

An example Bee file is below with a few lines removed to make the remainder clearer. Notice that at the top there is the domain name, and at the bottom it is listening on port 440 which was defined earlier in SWARM as the Bee reverse proxy port. The next most important areas are the 'location' sections. The one with 'dashboard' in does a 'proxy pass' to local port 8082. That was the port set in the config.json file above for the dashboard.

Also see the third location section which redirects the default request on port 440 to the SWARM landing page at /var/www/html/swarm-nodes/ NB This one may not be in the SWARM settings



server {
        server_name v2202110158313xxxxxx.ultrasrv.de;

        server_tokens off;
        ssl_session_cache shared:SSL:32m;
        add_header Strict-Transport-Security 'max-age=63072000; includeSubdomai>
        add_header 'Access-Control-Allow-Headers' 'Authorization,Accept,Origin,>
        add_header 'Access-Control-Allow-Methods' 'GET,HEAD,PUT,PATCH,POST,DELE>
        proxy_headers_hash_max_size 512;
        proxy_headers_hash_bucket_size 128;

        location /health {
                auth_basic off;
                proxy_pass http://localhost:14266/health;
                proxy_pass_request_headers on;
                proxy_set_header        Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Real-SslId $ssl_session_id;
                proxy_set_header        X-Forwarded-For   $proxy_add_x_forwarde>
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_set_header        X-Forwarded-Host  $host;
                proxy_set_header        X-Forwarded-Port  $server_port;
        }

        location ~ ^/api/v1/(info|tips|messages|treasury|transactions|milestone>
                auth_basic off;
                proxy_pass http://localhost:14266;
                default_type  application/json;
                proxy_pass_request_headers on;
                proxy_set_header        Host $host;
                proxy_set_header        X-Forwarded-Host  $host;
                proxy_set_header        X-Forwarded-Port  $server_port;
        }

        location ~ ^/(static|auth|branding|ws|dashboard|explorer|visualizer|ana>
                rewrite /dashboard / break;
                proxy_pass http://localhost:8082;
                proxy_http_version  1.1;
                proxy_cache_bypass  $http_upgrade;
                proxy_set_header        X-Forwarded-Host  $host;
                proxy_set_header        X-Forwarded-Port  $server_port;
                proxy_set_header Connection "keep-alive";
        }

        location / {
                gzip off;
                alias /var/www/html/swarm-nodes/;
                index index.html;
                try_files $uri $uri/ =404;
        }

    listen [::]:440 ssl http2;
    listen 440 ssl http2;
    ssl_certificate /etc/letsencrypt/live/v2202110158313xxxxxx.ultrasrv.de/full>
    ssl_certificate_key /etc/letsencrypt/live/v2202110158313xxxxxx.ultrasrv.de/>
}


        

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _