Documentation matters or why OSMC made me write NSClient++ API docs

Last year I learned about the new HTTP API in NSClient++. I stumbled over it in a blog post with some details, but there were no docs. Instant thought “a software without docs is crap, throw it away”. I am a developer myself, and I know how hard it is to put your code and features into the right shape. And I am all for Open Source, so why not read the source code and reverse engineer the features.

I’ve found out many things, and decided to write a blog post about it. I just had no time, and the old NSClient++ documentation was written in ASCIIDoc. A format which isn’t easy to write, and requires a whole lot knowledge to format and generate readable previews. I skipped it, but I eagerly wanted to have API documentation. Not only for me when I want to look into NSClient++ API queries, but also for anyone out there.


Join the conversation

I met Michael at OSMC 2016 again, and we somehow managed to talk about NSClient++. “The development environment is tricky to setup”, I told him, “and I struggle with writing documentation patches in asciidoc.”. We especially talked about the API parts of the documentation I wanted to contribute.

So we made a deal: If I would write documentation for the NSClient++ API, Michael will go for Markdown as documentation format and convert everything else. Michael was way too fast in December and greeted me with shiny Markdown. I wasn’t ready for it, and time goes by. Lately I have been reviewing Jean’s check_nscp_api plugin to finally release it in Icinga 2 v2.7. And so I looked into NSClient++, its API and my longstanding TODO again.

Documentation provides facts and ideally you can walk from top to down, and an API provides so many things to tell. The NSClient API has a bonus: It renders a web interface in your browser too. While thinking about the documentation structure, I could play around with the queries, online configuration and what not.


Write and test documentation

Markdown is a markup language. You’ll not only put static text into it, but also use certain patterns and structures to render it in a beautiful representation, just like HTML.

A common approach to render Markdown is seen on GitHub who enriched the original specification and created “GitHub flavoured Markdown“. You can easily edit the documentation online on GitHub and render a preview. Once work is done, you send a pull request in couple of clicks. Very easy 🙂

If you are planning to write a massive amount of documentation with many images added, a local checkout of the git repository and your favourite editor comes in handy. vim handles markdown syntax highlighting already. If you have seen GitHub’s Atom editor, you probably know it has many plugins and features. One of them is to highlight Markdown syntax and to provide a live preview. If you want to do it in your browser, switch to

NSClient++ uses MKDocs for rendering and building docs. You can start an mkdocs instance locally and test your edits “live”, as you would see them on

Since you always need someone who guides you, the first PR I sent over to Michael was exactly to highlight MKDocs inside the 🙂


Already have a solution in mind?

Open the documentation and enhance it. Fix a typo even and help the developers and community members. Don’t move into blaming the developer, that just makes you feel bad. Don’t just wait until someone else will fix it. Not many people love to write documentation.

I kept writing blog posts and wiki articles as my own documentation for things I found over the years. I once stopped with GitHub and Markdown and decided to push my knowledge upstream. Every time I visit the Grafana module for Icinga Web 2 for example, I can use the docs to copy paste configs. Guess what my first contribution to this community project was? 🙂

I gave my word to Michael, and you’ll see how easy it is to write docs for NSClient++ – PR #4.


Lessions learned

Documentation is different from writing a book or an article in a magazine. Take the Icinga 2 book as an example: It provides many hints, hides unnecessary facts and pushes you into a story about a company and which services to monitor. This is more focussed on the problem the reader will be solving. That does not mean that pure documentation can’t be easy to read, but still it requires more attention and your desire to try things.

You can extend the knowledge from reading documentation by moving into training sessions or workshops. It’s a good feeling when you discuss the things you’ve just learned at, or having a G&T in the evening. A special flow – which I cannot really describe – happens during OSMC workshops and hackathons or at an Icinga Camp near you. I always have the feeling that I’ve solved so many questions in so little time. That’s more than I could ever write into a documentation chapter or into a thread over at 🙂

Still, I love to write and enhance documentation. This is the initial kickoff for any howto, training or workshop which might follow. We’re making our life so much easier when things are not asked five times, but they’re visible and available as URL somewhere. I’d like to encourage everyone out there to feel the same about documentation.



Ever thought about “ah, that is missing” and then forgot to tell anyone? Practice a little and get used to GitHub documentation edits, Atom, vim, MkDocs. Adopt that into your workflow and give something back to your open source project heroes. Marianne is doing great with Icinga 2 documentation already! Once your patch gets merged, that’s pure energy, I tell you 🙂

I’m looking forward to meet Michael at OSMC 2017 again and we will have a G&T together for sure. Oh, Michael, btw – you still need to join your Call for Papers. Could it be something about the API with a link to the newly written docs in the slides please? 🙂

PS: Ask my colleagues here at NETWAYS about customer documentation I keep writing. It simply avoids to explain every little detail in mails, tickets and whatnot. Reduce the stress level and make everyone happy with awesome documentation. That’s my spirit 🙂

Michael Friedrich

Autor: Michael Friedrich

Michael ist seit vielen Jahren Icinga Developer und hat sich Ende 2012 in das Abenteuer NETWAYS gewagt. Ein Umzug von Wien nach Nürnberg mit der Vorliebe, österreichische Köstlichkeiten zu importieren - so mancher Kollege verzweifelt an den süchtig machenden Dragee-Keksi. Oder schlicht am österreichischen Dialekt der gerne mit Thomas im Büro intensiviert wird ("Jo eh."). Wenn sich Michael mal nicht im Monitoring-Portal helfend meldet, arbeitet er am nächsten LEGO-Projekt oder geniesst das schöne Nürnberg. Oder - at an Icinga Camp near you 😉

Monthly Snap April > NETWAYS Web Services, Braintower, OSBConf, Teamweekend, AKCP, OSDC, GitLab CE, Galera, GitHub, Puppet

In April, Isabel startet with announcing a new Software Update for Braintower and Martin K. continued with a new NETWAYS Web Services tool: Rocket.Chat Hosting.

Then Julia announced the call for papers for the Open Source Backup Conference 2017 in Cologne while Marius wrote about the end of Ubuntu 12.04 LTS.

Later in April, Marius H. gave some practical tips for the Galera Cluster and Dirk wrote about contributing to projects on GitHub.

Then Martin K. presented the next NETWAYS Web Services App, GitLab CE Hosting, and Julia told about the latest OSDC-News.

Furthermore, Catharina reviewed the team event of the commercial departments while Noah told us how to block some Google searches in Google Chrome.

Lennart gave an insight in the monitoring project at htp GmbH and Daniel introduced himself.

Towards the end of April, Isabel told about the latest news concerning the AKCP sensorProbe 2+ and Martin S. explained external monitoring by the Icinga2 satellites at NETWAYS Web Services.

Last but not least, Jean reported on monitoring powershell scripts with Icinga 2, while Lennart went on with part 2 of automated monitoring with Puppet.

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.

Monthly Snap December > OSMC, Nicolaus poem, Icinga 2.6, Robocop, Clustershell and Foreman-API, Icinga 2, OSDC, Ceph, Linux, Ansible, OMSA

In the beginning of December Dirk gave us a detailed summary of the first, second and third OSMC days, while Julia gave an account of the evening event at the Indabahn.

On the 6th of December, the St. Nicolaus day, we read Julias version of a Nicolaus poem. A couple of days later Gunnar gave us an insight into Icinga 2.6.

Then Markus Frosch introduced the Robocop, and Marius informed us about Clustershell and Foreman-API.

In parts 1 and 2 Lennart wrote about the organisation of Icinga 2 host- and service objects, whereas Julia informed us about the Early Bird phase and the Call for papers for the Open Source Data Center Conference.

Martin wrote about S3 and Swift with the Ceph object, and Alexander about Black Magic for GNU/Linux-Nerds.

At the end of the month Julia reminded us of the Ansible training, and Tim reported on OMSA issues, solutions and xkcd.

Lukas Stegmeier

Autor: Lukas Stegmeier

Lukas hat im September 2016 seine Ausbildung zum Veranstaltungskaufmann bei NETWAYS gestartet. Er freut sich auf eine spannende Ausbildung und ist schon ganz gespannt auf unsere Firmenfeste. Zuhause hebt er den Geräuschpegel durch regelmäßiges Schlagzeugspielen enorm an und sportlich verausgabt sich Lukas seit 12 Jahren intensiv beim Fußball.

Fully packed to reduce heating – OSMC 2016 – Tag 3

Nach zwei interessanten Tagen mit Vorträgen ging es heute zum Abschluss wieder ans gemeinsame Hacken beim Hackathon. In einer kurzen Vorstellungsrunde kristallisierten sich bereits die Themen heraus und es ging sofort ans umgruppieren um den gemeinsamen Interessen zu folgen.

Neben viel Erfahrungsaustausch, migrierten Monitoringumgebungen, internen Skripten rund um Icinga 2, umgebungsspezifischen “Icinga Web 2”-Modulen und Prototypen wie “Icinga 2”-SNMP-MIBs und Debian-Packages für NSClient++, gibt es auch tatsächlich Ergebnisse zu vermelden.


* Das neue Puppet Module für Icinga 2 erhielt Unterstützung für SLES 12 (Pull-Request on Github)
* Die “Icinga 2”-Vagrant-Boxes erhalten Proxy-Support (Pull-Request on Github)
* Der Prototyp eines Elastic-Icinga-Beat (Prototype on Github)
* Das mit Dashing-Icinga2 zur Verfügung gestellte Dashboard wurde um weitere Funktionalitäten erweitert (Commit bereits gemerged)
* Das “Icinga Web 2”-Module NagVis wurde erweitert, unter anderem um Zoom für Dashboards (Commit bereits gemerged)
* Icinga Web 2 kann nun konfiguriert werden um Standalone zu laufen (Patch verfügbar)
* Neben einem kleinen Fix wurde dem Foreman-Smart-Proxy Monitoring-Plugin beigebracht Hosts in Icinga 2 anzulegen (Feature-Branch auf Github)
* Einen adaptiven Http-Check (Repository auf Github)

Ich würde es bei diesem Output als einen erfolgreichen Hackathon bezeichnen!

P.S.: Wer viel auf Github unterwegs ist, dem möchte ich noch den Artikel zum Erstellen eigener Labels ans Herz legen. Der erwähnte Smart-Proxy hat nun farblich korrekte Labels für Icinga 2 und Zabbix.

Dirk Götz

Autor: Dirk Götz

Dirk ist Red Hat Spezialist und arbeitet bei NETWAYS im Bereich Consulting für Icinga, Nagios, Puppet und andere Systems Management Lösungen. Früher war er bei einem Träger der gesetzlichen Rentenversicherung als Senior Administrator beschäftigt und auch für die Ausbildung der Azubis verantwortlich.

Monthly Snap November > Icinga 2 Director, OSMC, HW group Updates, AVTECH, Request Tracker, Foreman, Ceph, Git, Icinga 2 API, Braintower

SnspIn November, Thomas Gelf began with announcing the Icinga Director 1.2.0 release.

Isabel informs about new HW group Updates and the new Firmware for AVTECH Room Alert 3E.

Then Julia H. said thank you to our OSMC sponsors and wrote about why to join the OSMC Hackathon

Jennifer told us why we visualize while Markus Waldmüller presents the auto-provisioning with Foreman

Furthermore, Michael reviewed the PuppetConf in San Diego and told why Git Squash is magic.

Christian announced our availability of Request Tracker starter packages and Martin K. informed what to know about the Puppet Enterprise 3.8 End of Life

Towards the end of November, Tobias gave an Icinga 2 API Cheat Sheet, while Tim gave a Ceph training review.

Finally, Isabel wrote about the new Braintower Software and Updates.



Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.

Casino Royale – Abendveranstaltung OSMC 2016

indabahn_1Nachdem der erste Vortragstag überstanden war, liefen alle Teilnehmer unter der Führung von Bernd zum Hauptbahnhof in Nürnberg, um den Tag bei der Abendveranstaltung in gemütlicher Runde ausklingen zu lassen. Über einen roten Teppich kamen alle in den modernen Club „Indabahn“ im Bahnhofsgebäude und konnten nach Bernd‘s Opening allerhand Leckereien – als Flying Buffet serviert – verzehren.

Dann wurden viele neue Kontakte geknüpft, sich angeregt unterhalten und auch der ein oder andere Gin Tonic geschlürft und natürlich noch James‘ Geburtstag zelebriert. Nach der Nachspeise konnten die Teilnehmer ihr Glück beim Roulette spielen herausfordern und die am Anfang ausgegebenen Jetons verprassen. An den Gewinner Stefan K. einen herzlichen Glückwunsch! Es hat allen riesigen Spaß gemacht.

Als sich die Indabahn gegen Mitternacht so langsam leerte, machte der harte Kern noch eine nächtliche Wanderung zurück zum Hotel und stieß dabei wie schon so oft „zufällig“ auf den bei den Konferenzteilnehmern allseits beliebten „Checkpoint Jenny“. Jenny kennt uns schon und hat uns wie immer sehr herzlich aufgenommen. Hier nahm der Abend dann feucht fröhlich seinen Lauf und ging schließlich auch früher oder später zu Ende. Nach einer für alle eher kurzen Nacht gingen die Vorträge heute Morgen in die zweite Runde. Wir hoffen, die Teilnehmer waren nicht allzu müde und hatten einen interessanten dritten Konferenztag. Gestern Abend stand dann noch das Abendessen für die Teilnehmer am heutigen Hackathon an.

Fortsetzung und Bilder folgen…

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.