MaSSHandra Installation on Ubuntu 18.04 with LetsEncrypt

In this article I will describe how to get MaSSHandra running on an Ubuntu 18.04.
As alwaysI recommend not running the service natively on your server but rather to run it in a VM.

See: virtualization with KVM


First things first.
Update your sources and install pending updates.

sudo apt update -y && sudo apt upgrade -y

Now we install the following packages:

  • Sendmail - will be used to send emails to the MaSSHandra users
  • NodeJS - will run the services
  • npm - Node packet manager, will be used to update NodeJS
  • mysql - an SQL Server, that is going to hold MaSSHandras data

sudo apt install -y sendmail nodejs npm apache2 mysql

Now we empty the npm cache and install the current version of node.

sudo npm cache clean -f
sudo npm install -g n

The command node -v should now be showing a Version above 10.0.

Clone the git repo to your home diretory.
git clone

Now we create a few directories MaSSHandra is going to use.

sudo mkdir /etc/networkmaps/
sudo mkdir /sendmail/
sudo mkdir /sendmail/queue/
sudo mkdir /sendmail/sent/
sudo mkdir /diagrams/

SQL Database

First we are going to harden the SQL Database a bit.
Mysql comes with a script that is going to interactivley ask you a few settings to make it a bit more secure.

sudo mysql_secure_installation

Now login to mysql.

sql -u root -p

Create a database that MaSSHandra will later use to handle users.
create database users;

You can ofcourse use another database name then users if you want.
Just make sure that you use this altered name on the database import and later when configurung the config.json.

Logoff by typing


Import the sql database included in the git repo.
There are no users in there, however a bunch of tables that will handle users, passwords (binary64 with salt), diagrams and permissions.

mysql -u root -p users < ~/networkmaps/database_schema/users.sql

Now log back into mysql.
sql -u root -p

We will now create a SQL user that MaSSHandra can use to access the database.
Please change "YourMasshandraSqlPassword".
Here you can use a username of your choice that later will be put in the config.json.

CREATE USER 'masshandra'@'localhost' IDENTIFIED BY 'YourMasshandraSqlPassword';
GRANT ALL ON Users.* TO 'masshandra'@'localhost' IDENTIFIED BY 'YourMasshandraSqlPassword' WITH GRANT OPTION;

Then reload the sql permissions and exit mysql.


To secure our webserver with valid SSL certificates we generate an certificate using LetsEncrypt
Ubuntu comes with certbot installed nativley.

sudo certbot certonly -d

MaSSHandra configuration

So far so prepearing.
Lets now head over to tweaking masshandras settings.

MaSSHandra is expecting a configuration file at /etc/networkmaps/config.json
So we copy the example config included in the git repo to that location.

sudo cp ~/networkmaps/docs/sample_config.json /etc/networkmaps/config.json

In it, change the settings marked in red:

"comment": "This file is expected to be in /etc/networkmaps",
"timers": {
"usertimeout": 3600,
"savediagram": 300
"use_ssl_socket": true,
"use_ssl": true,
"socket": {
"address": "IP OF YOUR SERVER",
"port": "3000",
"cert": "/etc/letsencrypt/live/",
"key": "/etc/letsencrypt/live/"

"hostname": "",
"port": 3000
"hostname": "",
"port": 443
"database": "users",
"host": "localhost",
"user": "masshandra",
"password": "YourMasshandraSqlPassword"
"path": "/diagrams/"
"queue": "/sendmail/queue/",
"sent": "/sendmail/sent/",
"server": "your.mailserver",
"port": 465,
"is_secured": true,
"user": "mailuser@your.mailserver",
"password": "YourMailPassword",
"from": " <>"

Starting the server

Now we start the services that will open a websocket on :3000 and handle the emails.

sudo node ~/networkmaps/server.js
sudo node ~/networkmaps/smtp_daemon.js

Remember that you can send the processes to the background by appending & to the command.
Leave them as they are if you want to debug.

When you now head over to your MaSSHandra instance and register a user, you sould see some logs.

Once you confirmed the Email you should be able to login and use MaSSHandra.



I want to present to you a nice YouTube series about VxLAN.

As you can find in my Juniper artikle V-Lan configuration the IEEE 802.1X standard enlarges the frame on Layer-2.
Even if at a first glance adding another 32Bit to every frame seems qute oversized, you will eventually run into its limits.
VxLAN is a way to wrap Layer-2 Traffic inside Layer-4 UDP traffic to surpass V-Lan's limitations.



Ich möchte euch jetzt diese Tolle YouTube Serie zu VxLAN's ans Herz legen.

Wie Ihr in meinem Juniper Artikel V-Lan Konfiguration nachlesen könnt, wird mit dem Standard IEEE 802.1X das Frame auf Layer-2 erweitert.
Auch wenn eine Erweiterung um 32Bit erstmal stark überdimensioniert wirkt, erreicht man auch irgendwann dessen Limits.
VxLAN ist eine Möglichkeit, wie man Layer-2 Traffic in Layer-4 UDP Paketen Kapseln kann um diese Limitierungen von V-Lans zu umgehen.

Viel Spaß damit,

[HP / Aruba ] Troubleshooting V-Lan issues / finding physical devices

In this article I want to show you how to find out where physical devices are connected to in a network using HP Switches.
Typical scenario, will happen from time to time:

  • A customer reports that a user cannot access resource X
  • You check his IP and see that he or she has a lease from a wrong network

Usually this means that the user is connected to a port configured with a wrong v-lan on it.
If there is a clean documentation that issue should be quite easy to solve.
Unfortunately you sometimes have to deal with customers that seem to have guerilla cabeling written in thier company policy or that have taken over a bad IT infrastructure. You will find a cable that runs into a (hopefully) labeled port in the wall and then ends up somewhere in some switch.
How do you find out what port has to be reconfigured in order for the customer to be able to work?

First find out the MAC Address of the device you want to find in your network.
At a windows machine use ipconfig, on Linux / Apple use ifconfig or ip.

Now login to one of the customers switches using SSH.
Check if LLDP is active.

show lldp config

If not you should enable LLDP on all devices first.
More details can be found here.

Then check the MAC Address Table of the Switch for the MAC Address of the device you are looking for.

show mac-address <MAC>

The Switch knows that MAC on port 49...
Port 49 on a 48 Port Switch is quite a Dead Giveaway that you are looking at a glas uplink to another switch.

Lets look at the MAC Table of port 49.
(Or rather filter for devices at that port)

show mac-address ethernet <Interface>

As expected there are quite a lot of devices there.
Lets check LLDP what is behind Port 49.

show lldp info remote-device ethernet <Interface>

Aha, another switch.
This way you can hop from device to device until you found out what port this device is connected to.

The you can change the v-lan config of that interface and everything should work as expected for the user.


... and if in that case you are not on-site, good night!


[HP / Aruba ] V-Lan Probleme beheben / Physische Geräte hinter Ports finden

In diesem Artikel möchte ich euch kurz zeigen, wie Ihr ein angeschlossenes Physisches Gerät in einem Netz findet, dass auf HP Switches setzt.
Typisches Scenario, tritt immer wieder auf:

  • Ein Kunde meldet sich, da er auf Ressource X nicht zugreifen kann
  • Ihr schaut euch seine IP an und er hat einen Lease aus einem Falschen Netz

In der Regel bedeutet das, dass auf dem Port an dem er angeschlossen ist eine falsche V-Lan Konfiguration liegt.
Wenn es eine saubere Dokumentation gibt sollte das Problem schnell gelöst sein.
Leider hat man es ab und zu mit Kunden zu tun, bei denen Guerillaverkabelung Firmenpolitik zu sein scheint oder die einfach beim Einzug eine Schrott IT übernommen haben. Da geht dann ein Kabel in eine (hoffentlich) beschriftete Dose in der Wand die dann irgendwie irgendwo in einem der vielen Switche im Haus endet.
Wie bekommt man also raus, welchen Port man umkonfigurieren muss um den Anwender arbeitsfähig zu bekommen?

Zunächst schaut Ihr euch die MAC Adresse des Gerätes an, das Ihr finden wollt.
Unter Windows nutzt Ihr dazu ipconfig, auf Linux / Apple nutzt Ihr ifconfig oder ip.

Jetzt loggt ihr euch auf einem der HP Switche des Kunden per SSH ein.
Prüft, ob LLDP aktiv ist.

show lldp config

Falls nicht, sollte Ihr zunächst auf allen Geräten LLDP einschalten.
Details dazu findet Ihr hier.

Sucht dann im MAC Address Table des Switches nach der MAC Adresse des Gerätes das Ihr sucht.

show mac-address <MAC>

Das Gerät ist dem Switch auf Port 49 bekannt...
Port 49 ist auf einem 48 Port Switch ein ziemlicher Dead Giveaway dafür, dass es sich um einen Glas Uplink zu einem anderen Switch handelt.

Schauen wir uns mal den MAC Address Table von Port 49 an.

show mac-address ethernet <Interface>

Wie erwartet tümmelt sich hier einiges.
Schauen wir doch mal mit LLDP was sich hinter Port 49 befindet.

show lldp info remote-device ethernet <Interface>

Aha, ein weiterer Switch.
So könnt Ihr euch von Gerät zu Gerät hangeln, bis ihr gefunden habt auf welchem Port euer Gerät hängt.

Dann könnt Ihr die V-Lan config anpassen und schon klaptts auch mit den Nachbarn.


... wenn ihr dann nicht vor Ort seid, gute Nacht.


Creating a network diagram

In this article I want to show you how you can visualize an existing evironment in a network plan.

Network plans help colleagues who are not familiar with a network understanding it faster.
They are also very useful to explain certain issues to someone or visualize why a certain investment is important.

Informationen gathering

At first you will have to collect a lot of information about the network you want to visualize.
A resource that we often tend to forget about is the already existing documentation that might exist.
It might not be complete or out of date but can contain valuable information.

Check the (hardware) firewall
-> What networks do exist
-> How many Uplinks are there
-> Upstreaming Device(es)

Find a way into the network
-> VPN
-> Remote Access to a server or client
-> Scan the network

Check the networking devices
-> What devices are there (Vendor, Model, IP)
-> Do you have login credentials and do they work?
-> How are the devices interconnected (cdp, lldp)

Check the servers
-> Physical or virtual?
-> In wich Networks are the Servers located?
-> What do they do?

Check other devices
-> Access Points
-> Phone Systems / IP-Phones
-> Conferencing Systems
-> Printers

Once you got all these Infos available you can begin creating the network plan.


What type of network diagram

It is important that you are aware of what style to choose for what purpose.
Is it for example enough to provide an abstract view of the network?

Should the networks be visualized?

Should buildings be part of the plan?

We can scale this up until we visualize infrastructures that span across continents, you get the point.

Do you maybe want a floorplan that is showing the devices?
(Good for planing wifi)

As you can see the type of network plan depends on what it is going to be used for.
Do you want to provide an overview over a virtualisation structure with lots of hypervisors, lots of networks and a ton of servers?
Then you probably want to have an abstract plan showing the structure of the logical Network.

Is the plan supposed to be used by a technician to be able to find physical devices at a location?
Then you probably want a plan that is as close to the physical reality as possible.

These concepts nearly always get mixed to some point.
However when you have really complex plans, it might be better to have two or more separate plans suited for the right purpose.
When you are trying to force every available information into one network plan you can end up making it unreadable and therefor unuseful.

As you can see, creating a network diagram is a form of art in itself.

Creating the network diagram

I am currently using the non-free software Visio from Microsoft to create network diagrams.

Draw by LibreOffice would be a good free alternative.

You could also just use GIMP if you want to create a network diagram, its up to you.
At this point I assume you already made up your mind what type of diagram you want to create and what software you are going to use.

If you are going to use floorplans or want to visualize buldings / floors, start by doing that.
Once that is complete feed all the information you gathered in the information gathering process into the network plan.
Start at the Internet Uplink and then go down the Line.

Uplink > Router > Firewall > Switch(es) > Devices attached to the Switches (Servers, Clients etc.)

It is a good idea to write important IP addresses and hostnames into the network diagrams.
Also it is a good idea to not only write down physical servers but also virtualized ones.

End-User devices can usually be culminated into a group.
(20 Workstations, 15 mobile devices, etc.)


Netzwerkplan erstellen

In diesem Artikel möchte ich euch zeigen, wie man eine Bestehende Umgebung in einem Netzwerkplan abbilden kann.

Netzwerkpläne helfen Kollegen die sich in der Umgebung nicht auskennen, diese schneller zu verstehen.
Sind sie sehr nützlich um jemandem Probleme im Netzwerk zu erklären oder zu visualisieren wieso eine bestimmte Investition notwendig ist.

Informationen Sammeln

Als erstes müsst ihr versuchen so viele Informationen zusammenzutragen wie möglich.
Eine Ressource die oft vergessen wird ist in Erfahrung zu bringen, ob es bereits einen Netzplan oder eine Dokumentation gibt.

Auch wenn diese vielleicht nicht vollständig oder aktuell ist, kann es die Aufgabe erleichtern.

Firewall Checken
-> Welche Netze gibt es
-> Wieviele Uplinks
-> Upstreaming Device(es)

Einen Weg in das Netz finden
-> VPN
-> Remote Access zu einem Server oder client
-> Netz(e) scannen

Netzwerk Geräte Checken
-> Welche Geräte gibt es im Netz (Hersteller, Modell)
-> Gibt es logindaten und funktionieren diese auch?
-> Wie sind die Geräte miteinander verbunden (cdp, lldp)

Server Checken
-> Physisch oder virtualisiert?
-> In welchen Netzen stehen die Server?
-> Was machen die Server?

Andere Geräte Checken
-> Access Points
-> TK-Anlagen / Telefone
-> Konferenzsysteme
-> Drucker

Wenn all diese Informationen zusammengetragen wurden können wir mit der Erstellung des Netzwerkplans beginnen


Netzplantyp Planen

Wichtig ist, dass ihr euch darüber klar werdet in welchem Stil ihr den Netzwerkplan anlegen wollt.

Reicht eine Abstrakte Ansicht des Netzes?

Sollen die Netze mit abgebildet werden?

Sollen mehrere Gebäude eingezeichnet sein?

Diese Skalierung lässt sich fortführen, bis man bei der Abbildung von Standorten auf mehreren Kontinenten angekommen ist.

Wollt ihr einen Raumplan haben, auf dem die Geräte abgebildet sind?
(Gut für das Planen und visualisieren von Wifi-Ausleuchtung)

Wie Ihr seht, hängt die Art des Netzwerkplanes stark davon ab, wofür er benutzt wird.
Wollt ihr eine Übersicht über eine Virtualisierungsinfrastruktur mit vielen Servern und Netzen abbilden bietet sich eine abstrakte Ansicht an.

Soll der Plan von Technikern genutzt werden um beim Kunden Geräte finden zu können bietet sich eine an der physischen Realität gehaltener Netzwerkplan an.

Diese Konzepte treten fast immer in gemischter Form auf.
Bei sehr komplexen Konstellationen kann das auch mal nicht mehr in einem Plan abzubilden sein.
Dann sollten separate Netzwerkpläne für den Jeweiligen Zweck erstellt werden.

Wer versucht alle Informationen auf Biegen und Brechen in einem Netzplan unterzubringen wird diesen bis zur Unkenntlichkeit überladen und damit den Nutzen eines solchen ad Absurdum führen.

Ihr merkt schon, das erstellen des Netzwerkplans ist eine Kunst an sich.


Netzwerkplan erstellen

Ich setze zurzeit auf das Kostenpflichtige Programm Visio von Microsoft um Netzpläne zu erstellen.

Draw von LibreOffice wäre eines der kostenfreien Alternativprodukte.

Prinzipiell könnt ihr auch mit Gimp einen Netzwerkplan erstellen.
An diesem Punkt gehe ich davon aus, dass Ihr euch Gedanken darüber gemacht habt, was euer Plan abbilden soll und welche Software Ihr dafür einsetzt.

Falls Gebäude oder Raumpläne in den Raum sollen, solltet Ihr damit anfangen.
Anschließend füttert Ihr den Netzwerkplan mit allen Informationen, die bei der Informationsbeschaffungsphase angefallen sind.
Beginnt beim Internet Uplink und arbeitet euch dann der Reihe nach vor.

Uplink > Router > Firewall > Switch(es) > Geräte die an den Switches hängen (Server, Clients etc.)

Es sinnvoll wichtige IP Adressen und die Hostnames der Geräte mit im Plan vermerken.
Auch sollte man nicht nur physische Server sondern auch virtualisierte Server mit einzuzeichnen.

Endgeräte kann man in der Regel zusammenfassen (20 Workstations, 15 mobile devices, etc.)


Documentation is everything

When a project or environment is reaching a certain size a good documentation is incredibly important.
I personally think that even for small projects a clean documentation is important, but I wont't go into that now.

If there is no well organized documentation you will run into several issues:
- Working hours will get "burned" searching for information
- Passwords get missing, resulting in issues
- Key knowledge held by single people ("Well, working in that network you just have to know XYZ, you know now!")
- New colleagues cannot get up to pace without help, again burning time
- etc...

I could continue but I guess you get the point.
The obvious reason for writing things down is the human tendency to forget things.
However the most important reason is that there are more then one person tasked with planning, enhancing, maintenance and fixing urgent issues.
When changes are not immediately and completely documented, the other people working in the environment cannot rely on the information they have.
This WILL backfire, trust me.

A good documentation should should be designed to enable a person unfamiliar with the documented matter:
- Get a quick overview over the complete situation
- Get access to the available data in a structured and searchable manner
- Just have to look in one place

What you should avoid:
- Different files that have to be searched like Version_pre_2016, Networkplan_old, see documentation XY
- Old data like a not documented change of the contact person
- Incorrect data like the wrong device models. If you are not sure don't write it down!

A documentation should at least consist of the following parts:
- Textdocumentation
- Network Diagram
- Complete documentation

Good would be as well the following conponents:
- Hardware Inventory
- Software (license) Inventory
- Clear defined On- and Offboardingprocesses


Dokumentation ist alles

Ab einer bestimmten Firmen- oder Projektgröße ist eine saubere Dokumentation unglaublich wichtig.
Ich finde ehrlich gesagt, dass auch Kleinstprojekte sauber dokumentiert gehören, will dieses Fass jetzt aber nicht aufmachen.

Wenn es keine gut organisierte Dokumentation gibt, kommt es zu vielen Problemen:
- Arbeitszeit wird "verbrannt" durch Suchen von Informationen
- Passwörter verschwinden, daraus erwachsen Folgeprobleme
- Personen sammeln Herrschaftswissen an ("Ja das musst du halt wissen in dem Netz")
- Neue Kollegen können sich nicht selbst einlernen
- usw.

Ich könnte diese Liste noch wesentlich länger werden lassen.
Der offensichtlichen Grund sich Dinge aufzuschreiben ist die menschliche Vergesslichkeit.
Dennoch kommen die meisten Probleme eher daher, dass mehr als eine Person mit Planung, Ausbau, Wartung und Fehlersuche innerhalb einer Umgebung betraut sind.
Wenn Änderungen nicht sofort und vollständig dokumentiert werden, können die anderen beteiligten Personen sich nicht mehr auf die Ihnen vorliegenden Informationen verlassen.
Das wird definitiv zu Problemen führen.

Eine gute Dokumentation sollte den Anspruch haben, dass eine Person die nicht mit dem dokumentierten Sachverhalt vertraut ist:
- Schnell einen Überblick über die Gesamtsituation erhält
- Die Daten in strukturierter und durchsuchbarer Form vorfindet
- An nur einem Ort suchen muss

Was vermieden werden sollte:
- Verschiedene Dateien in denen gesucht werden muss wie Version_vor_2016, Netzplan_alt, siehe Dokumentation XY
- Veraltete Daten z.b. ein nicht dokumentierter Ansprechpartnerwechsel
- Inkorrekte Daten wie falsche Modellnummern bei Geräten. Schreibt lieber nichts auf, wenn Ihr euch nicht sicher seid!

Eine Dokumentation sollte Mindestens aus folgenden Teilen bestehen:
- Textdokumentation
- Netzwerkplan
- Gesamtdokumentation

Gut wären auch folgende weitere Komponenten:
- Hardware Inventarliste
- Software (Lizenz) Inventarliste
- Klar definierte On- und Offboardingprozesse


Not all Uplinks are made equal

In this article I want to remind you of an effect that we sometimes tend to forget.
I am talking about the limited publicly available IPv4 addresses.

If you want to privately host a service like VPN, or have a customer that only has a consumer line, you should be aware of this fact.
To handle the problem of having more end-users then public IPs the Internet Service Providers are using a technique called NAT.
When an ISP is "natting" their users, it is called Carrier Grade NAT.
This means that the large pool of internal IP (v4 or v6) addresses is being translated to a smaller pool of public addresses before being transmitted.

This results in multiple end-users using the same public IP at the same time.
The ISP only has to remember what open port belongs to what session e.g. internal IP.
NAT in a nutshell. (pun not intended)

In addition to that most of the consumer lines today only use IPv6.
In order to make IPv4 services available to hier customers the ISPs are using what is called a DS (Dual Stack) Lite Tunnel.
This is resulting in the private IPv6 address facing one of the public IPv4 addresses of the ISP.
The IPv4 packets get encapsulated in IPv6 and then forwarded to the ISP sending it out as IPv4.
The other way around the IPv4 response is then again encapsulated by the ISP and forwarded to the customer.

So much for the background of whats going on.
Lets say I am checking what IPv4 address i am currently surfing on and try to connect to it using port 8080.
My ISP is not expecting anyone to contact him on that IP on port 8080 (since he is most likely not holding a session there) and cannot tell wich one of the end-users I want to contact.
The packets get dropped or rejected.

You will have to tell your ISP that you want to provide services over the internet and ask him to deactivate or rather change the Carrier Grade NAT for you.
Consumer hotlines usually know this as "changing / disabling the DS Lite Tunnel" or simply "enable port forwarding".

If the ISP is going to do that for you depends on the number of public IPs that the provider has available.
As far as I know you have no right to claim, that the your carrier deactivates the NAT for you.
Since hardly any of the end-users are asking for this however, ISPs normally have no problems enableing this 1:1 NAT for you.

Once this has been setup, the request to 8080 (or any other) can be directly associated to your internal IP and gets forwarded.

Please remember that will also have to enable port forwarding in your router behind the consumer line, as this one is also using NAT to masquerade your internal IP Addresses.
Also on some consumer devices there are settings like "filters" or "parenting controls" that limit fiddle with your portforwardings.
It's actually quite a s**t-show to properly configure some of these end-user routers.

Also your public IP most likely rotates, just saying.