Seite wählen

NETWAYS Blog

i-doit API

Als IT-Dienstleister bieten wir nicht nur Web Services oder Schulungen, sondern unter anderem auch Hosting an. Im Hosting-Bereich ist eine umfassende und geordnete IT-Dokumentation zwingend erforderlich um ein reibungsloses Arbeiten zu ermöglichen.  Als Lösung wird eine sog. CMDB (Configuration Management Database) eingesetzt, welche nicht nur als eine Inventarisierungs-Datenbank dient, sondern auch die gegenseitigen Abhängigkeiten der Objekte verwaltet. I-doit ist eine solche CMDB.
Seit der i-doit Version 1.8 ist die API kein Bestandteil der Pro-Version mehr und wird als separates Modul ausgeliefert welches frei verfügbar ist. Infolge dessen hab ich ein Azubiprojekt bekommen bei dem man die Funktionsweise einer API kennenlernen kann. Ich zeige im ersten Teil der i-doit API Serie wie man einen Request  über den curl – Befehl versendet.

Hat man die API über die Web GUI von i-doit konfiguriert kann man über folgende URL, welche an die Basis-URL angehängt wird, zugreifen:

/src/jsonrpc.php

Die Programmierschnittstelle kann auf Daten der CMDB über das JSON-Format zugreifen, d.h. es werden JSON-RPC Requests per HTTP-Post an i-doit geschickt und als JSON-RPC Response (mit HTTP-Header application/json) zurückgegeben. Somit kann man entweder über den curl – Befehl oder über einen RESTClient (z.B. als Firefox-Addon) die API ansprechen.
Ein beispielhafter Aufbau eines Request könnte folgendermaßen aussehen :

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "cmdb.objects.read",
  "params": {
    "apikey": "random_key",
    "filter": {
      "type": "4"
    }
  }
}
  • jsonrpc – version: Da i-doit ausschließlich die Version 2.0 des RPC-Request untersützt
  • id: Ein optionaler skalarer Wert (True, False, String, Numer) welcher aber nicht Null sein darf. Lässt man diesen Parameter aus, so wird lediglich eine Mitteilung verschickt, sodass der Server keine Rückmeldung generiert
  • method: Die zu aufrufende Methode
  • params: Parameter welche an die Methode übergeben werden
curl -s --data '{"jsonrpc":"2.0","id":"1","method":"cmdb.objects.read","params": \
{"apikey":"random_key","filter":{"type":"4"}}}' \
--header "Content-Type: application/json" \
 | python -m json.tool

Mit diesem Request lesen wir alle Objekte in der CMDB aus welche dem Typ 4 (Rack) entsprechen:

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [{
    "cmdb_status": "6",
    "cmdb_status_title": "in operation",
    "created": "2018-01-05 11:32:13",
    "id": "33",
    "image": "https://example-idoit-web-gui.de/images/objecttypes/something.png",
    "status": "2",
    "sysid": "SYSID_[RANDOMNUMBER_3849274329]",
    "title": "RacknameXYZ",
    "type": "4",
    "type_group_title": "Infrastructure",
    "type_title": "Rack",
    "updated": "2018-01-11 13:38:09"
  },
  {
    ...
    ...
  }]
}

Um z.B. alle Informationen einer Kategorie eines Objektes auslesen zu können, benutzt man die Methode cmdb.category.read:

curl -s --data '{"jsonrpc":"2.0","id":"1","method":"cmdb.category.read","params": \
{"apikey":"random_key","objID":"1234","category":"C__CATG__MODEL"}' \
--header "Content-Type: application/json" \
 | python -m json.tool

Response:

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [{
    "description": "",
    "firmware": "",
    "id": "307",
    "manufacturer": {
      "const": null,
      "id": "5",
      "title": "Random_Manufacturer_Name",
      "title_lang": "Random_Manufacturer_Name"
    },
  "objID": "Uniqe-Object-ID",
  "productid": "",
  "serial": "1235265477457",
  "service_tag": "",
  "title": {
    "const": null,
    "id": "71",
    "title": "XYZ1234",
    "title_lang": "XYZ1234"
  }
  }]
}

Eine ausführliche Liste aller in i-doit benutzten Kategorien kann man unter folgendem URL-Anhang aufrufen:


Darüber hinaus kann man über die i-doit API nicht nur Daten aus einer CMDB herauslesen, sondern auch erstellen, aktualisieren oder löschen. Diese Methoden werde ich im Teil 2 dieser Serie abhandeln.
 
Quellen: i-doit Knowledge Base


SMSEagle Revision 2: Einführung gelungen!

Wie unter unseren Kunden bekannt, haben wir die Produkte des polnischen Herstellers Proximus, den SMSEagle seit mehr als 1,5 Jahren im Portfolio. Das linuxbasierte SMS Gateway gibt es in 2 verschiedenen Versionen. Der Unterschied: Beim SMSEagle NXS-9700 3G handelt es sich um ein Gateway für eine, beim SMSEagle NXS-9750 Dualmodem um ein Gateway für zwei Simkarten.
Neulich berichteten wir bereits darüber, dass beide SMSEagle durch verbesserte Versionen ersetzt würden. Die Resonanz nach wenigen Monaten der Einführung ist sehr positiv! Unsere Kunden sind begeistert vom Produkt und das macht uns natürlich sehr glücklich. Denn was gut für unsere Kunden ist, ist auch gut für uns! Persönlich gefiel mir zusätzlich, dass die Umverpackung auch auf unsere Anregung hin angepasst wurde und nun alle Komponenten sicher und attraktiv in einer Verpackung verstaut sind. Vorher war das Netzteil immer separat beigelegt worden.

Verbesserung der Revision 2 auf einen Blick:

  • schnellerer Prozessor (quad-core ARM A53)
  • mehr Hauptspeicher (1GB RAM)
  • neuerer Linux Kernel 4.4

Wer bereits SMSEagle in seinem Netzwerk im Einsatz hat und nun um neue Komponenten erweitern möchte, muss dich wegen der Kompatibilität keine Gedanken machen. Natürlich gibt es auch weiterhin die Möglichkeit, die Garantie um 24 Monate zu verlängern. Der Aufpreis ist gering und es lohnt sich! Schauen Sie doch einfach mal im NETWAYS Shop vorbei – hier können Sie zwischen den Versionen mit und ohne Garantieverlängerung wählen und sehen recht schnell, dass es eine Überlegung wert ist.
Hier noch die Geräte auf einen Blick:

  • SMSEagle NXS-9700 3G (UMTS)
  • HTTP API
  • 1x GSM/UMTS-Rundstrahlantenne (3.5dBi)
  • AC/DC Adapter (input voltage: 100-240V)
  • Schnellstart-Anleitung
  • 12 Monate Herstellergarantie (Garantieverlängerung um weitere 24 Monate möglich, bitte Variante wählen)
  • freier Zugang zu kostenlosen Software Upgrades während der Garantiezeit

 
 
 

  • SMSEagle NXS-9750 3G (dual modem)
  • HTTPApi
  • 2x GSM/UMTS-Rundstrahlantenne (3.5dBi )
  • AC/DC Adapter (input voltage: 100-240V)
  • Schnellstart-Anleitung
  • 12 Monate Herstellergarantie (Garantieverlängerung um weitere 24 Monate möglich, bitte Variante wählen)
  • freier Zugang zu kostenlosen Software Upgrades während der Garantiezeit
  • Failover-Mechanismus (automatisches Task-switching zwischen den Modems, bei erkanntem Problem)
  • Failover Support (HA Cluster von zwei Geräten möglich)

 
 
Wir freuen uns auf Ihre Fragen und Ihren nächsten Besuch in Ihrem NETWAYS Shop!
 

Braintower SMS Gateway – SMS für Alle

Im NETWAYS Shop bieten wir SMS Gateways an. Einer unserer liebsten Hersteller ist hier Braintower aus St. Ingbert im schönen Saarland. Das Braintower SMS Gateway ist einer unserer Bestseller. Der automatisierte Versand von SMS Nachrichten über eine HTTP API zeichnet jedes Braintower SMS Gateway aus.
Dank übersichtlich gestaltetem Web-Interface und Adressbuchfunktion wird es einfach wie nie zuvor, SMS an einzelne Telefonnummern oder Kontakte zu senden. Zur Sicherheit Ihrer Datenübertragungen wird dabei standardmäßig HTTPS genutzt.
Das Braintower SMS Gateway ist im NETWAYS Shop in zwei Varianten erhältlich.

  • Erlaubt die Anbindung an z.B. Monitoring Server über API (kompatibel zu MultiTech iSMS )
  • Sendet und empfängt SMS
  • Zahlreiche Software-Optionen verfügbar

Überschaubares Stand-Alone-Gerät. Die Desktop Edition kann überall im Netzwerk stehen.

Das 19″ Gerät ist explizit für den Einbau ins Rack konzipiert.
Sie benötigen ein Angebot? Gerne! Schreiben Sie uns dazu einfach eine kurze E-Mail an shop@netways.de.

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 dillinger.io.

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 https://docs.nsclient.org.

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

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 monitoring-portal.org 🙂
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.
 

Conclusion

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 🙂

PHP Error – php_network_getaddresses

Ein Problem zu dem es viele Lösungsansätze gibt, ist folgender PHP Fehler. Er tritt beispielsweise auf, beim Verbinden auf externe Anwendungen oder APIs:
php_network_getaddresses: getaddrinfo failed: No address associated with hostname
Im Netz kursieren Teilweise die wildesten Lösungsansätze. Da ich vor kurzem mit eben diesem Problem konfrontiert wurde, möchte ich meine Erfahrung mit euch teilen. In der „php.ini“ gibt es einen Parameter, der diesen Fehler verursachen kann.
Dieser kann unterschiedlich gefüllt sein und ist per default leer.
disable_functions = pcntl_alarm,pcntl_fork,,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,,pcntl_signal,,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,,pcntl_exec,pcntl_getpriority,pcntl_setpriority
Um obigen Fehler zu beheben, kann es also reichen, sich diesen Parameter anzusehen und notfalls sogar komplett zu leeren.