NetScaler Nitro API und PowerShell

Wie ein NetScaler über die Web UI oder über das CLI konfiguriert wird stellt für die meisten sicherlich kein Problem dar. Da wir aber in der IT mehr und mehr über Automatisierung sprechen, wäre es doch auch hilfreich einen NetScaler automatisiert zu konfigurieren. Normalerweise würde ich behaupten, dass ein NetScaler sobald er einmal eingerichtet ist, keine wesentlichen Konfiguration benötigt. Möchte man keine weiteren Dienste über den NetScaler anbieten, benötigt er außer Sicherheitsupdates eigentlich keine weitere Aufmerksamkeit.

Mittlerweile ist diese Aussage aber nur bedingt richtig. Durch die vielen Funktionen, die die aktuelle Version des NetScaler mitbringt, macht es durchaus Sinn immer mal wieder zu überprüfen ob ein bestehender Dienst nicht auch von einem NetScaler profitieren kann. Denkbar wäre z.B. weitere Server automatisiert zu einem virtuellen Load Balancing Server hinzuzufügen, wenn Kapazitätsgrenzen erreicht werden. Per PowerShell lassen sich diese Server relativ schnell auf einem Hypervisor anlegen, konfigurieren und starten. Warum also nicht auch gleich diese Server in den Load Balancing Prozess auf dem NetScaler aufnehmen.

In diesem Beitrag widme ich mich der Automatisierung über die Nitro API, die wir hier mit der Microsoft PowerShell ansprechen werden. Bevor wir uns aber an die PowerShell Beispielskripte machen, schauen wir uns doch zuerst einmal die Nitro API an.

Der erste was bei jeder API von entscheidender Bedeutung ist, ist eine gute Dokumentation der Schnittstelle. Natürlich ist diese unter docs.citrix.com zu finden, aber die komplette Dokumentation ist auf dem NetScaler bereits vorhanden. Wenn wir uns an dem Webinterface anmelden, finden wir unter Downloads auch unter dem Abschnitt NITRO die komplette Dokumentation zum herunterladen.

Bei einem NetScaler 11.1 finden wir einen Link zur Online-Dokumentation auch unter der Karteikarte Documentation im Abschnitt Developer Resources.

Interessanter Weise finden wir hier auch einen Link zu einem NITRO Client, der für erste Versuche schon mal ein ganz guter Anfang ist. Bevor wir jetzt irgendetwas über die NITRO API konfigurieren und Einstellungen ändern, wollen wir uns erstmal damit beschäftigen, Information abzurufen.

Wir klicken also auf den Link zum NITRO Client, der sich dann auch in einem neuen Tab öffnet. Beginnen wir doch damit über die API die momentan aktivierten Basic Features abzufragen. Auf der linken Seite des NITRO Clients wählen wir unter Configuration – NS – nsfeature aus. Da wir Informationen abfragen wollen, wählen wir in dem Drop-Down Feld getall aus. Wir bekommen gleich auch den Header (in diesem Fall die Methode GET) sowie die entsprechende URL (https://<FQDN des NetScaler>/nitro/v1/config/nsfeature) angezeigt.

Sobald wir auf den GO Button klicken, bekommen wir die Antwort der API.

Der erste Teil der Antwort im Feld Output sind die HTTP Informationen. In diesem Fall war die Anfrage an die API erfolgreich (HTTP/1.0 200 OK) und der ausgelieferte Content ist im Format application/json. Die eigentliche Antwort fängt mit der ersten geschweiften Klammer an.

Scrollen wir jetzt im Antwortfeld etwas weiter herunter (Formatted sollte ausgewählt werden), finden wir den Eintrag „lb“:false. Was im wesentlichen bedeutet, dass das Feature Load Balancing auf diesem NetScaler nicht aktiviert ist.

Das können wir an der Web UI unter System – Settings – Configure Basic Features auch verifizieren.

Da wir jetzt wissen, dass Load Balancing nicht aktiviert ist, holen wir das mit der NITRO API nach. Diesmal wählen wir aus dem Drop-Down Feld Select Operation den Wert enable aus. Die Methode im Header ist nun kein GET sondern ein POST, da wir ja etwas schreiben wollen.

Natürlich müssen wir auch noch erfassen, was wir eigentlich schreiben wollen. Unter Resource Name tragen wir lb (Load Balancing) ein und ändern den vom Client erzeugten String unter Request Payload auf den folgenden Wert:

object={„params“:{„action“:“enable“},“nsfeature“:{„

feature

„:“lb“}}

Machen wir das nicht, erzeugt die Abfrage einen NetScaler spezifischen Fehler:

{ „errorcode“: 278, „message“: „Invalid argument [name]“, „severity“: „ERROR“ }

Schauen wir uns das in der NetScaler Nitro API Dokumentation an sehen wir, dass das Argument name tatsächlich falsch ist und stattdessen feature das richtige Argument ist.

Ein Klick auf GO aktiviert das Feature, was wir in der Antwort sofort sehen können.

Wenn wir das mit der Web UI überprüfen, sollte das Feature Load Balancing tatsächlich aktiviert sein.

Damit haben wir unsere ersten Schritte mit der NITRO API und dem NITRO Client absolviert. Mit Automatisierung hat das allerdings noch nicht viel zu tun. Allerdings eignet sich der NITRO Client auf dem NetScaler wenn man mal schnell bestimmte API Abfragen überprüfen möchte, bevor man diese in ein Skript schreibt.

Bevor ich jetzt auf die PowerShell eingehe, möchte ich noch eine weitere Möglichkeit zeigen. Da die NITRO API eine standardisierte RESTful API ist, können wir prinzipiell jeden REST Client verwenden. Ein relativ guter Client, der zusätzlich noch Automatisierung unterstützt, ist Postman. Postman ist nicht nur kostenlos, sondern auch für Windows und Mac erhältlich. An dieser Stelle laden wir Postman herunter und installieren die Anwendung.

Schauen wir uns doch die vorangegangenen Schritte mal mit Postman an. Wie vorher beschrieben, wollen wir die aktivierten Features abfragen. Die Methode dafür ist GET und die URL die wir ansprechen lautet https://<NetScaler FQDN>/nitro/v1/config/nsfeatures. In Postman sieht das wie folgt aus.

Wenn wir jetzt auf den Send Button klicken, bekommen wir ein vielleicht ein etwas unerwartetes Ergebnis. Der NetScaler lehnt die Verbindung in diesem Fall einfach ab, weil wir nicht Authentifiziert sind. Warum hat es mit dem NITRO Client funktioniert? Ganz einfach, der NITRO Client lief in einer bereits aufgebauten Verbindung zum NetScaler, weshalb hier keine weitere Authentifizierung nötig war. Verbinden wir uns aber mit einem anderen Client (oder später über die PowerShell) müssen wir uns zuerst authentifizieren.

Wie melden wir uns jetzt allerdings am NetScaler an? Auch das ist simpel, wir nutzen natürlich die NITRI API dafür. Wie das genau geht, verrät uns die Dokumentation im “Getting Started Guide”.

Das ganze sieht dann in Postman wie folgt aus:

Klicken wir nun auf den Send Button und haben auch einen validen Benutzer mit dazugehörigen Passwort angegeben, wird uns der NetScaler authentifizieren.

Das die Authentifizierung erfolgreich war erkennen wir am Status Code 201 sowie an der Session-ID, die auch in einem Cookie abgelegt wird. Führen wir jetzt die Abfrage nach den NetScaler Features erneut aus, sollten wir das gleiche Ergebnis wie mit dem NITRO Client erhalten.

Aus Gründen der Vollständigkeit wollen wir natürlich auch das Feature mit Postman aktivieren. In Postman sieht der Aufruf dann wie folgt aus:

Die Action verpacken wir gleich in der URL indem wir ein ?action=enable an die URL hängen. Im Body senden wir dann nur noch die eigentliche Payload. Wie erwartet, ist das Feature Load Balancing damit aktiviert.

Wer sich jetzt wundert, dass die Antwort keinen Inhalt hat – nun die wesentliche Antwort ist ja da (200 OK), mehr Informationen benötigen wir auch nicht. Aber Vertrauen ist gut, Kontrolle ist besser. Auch das überprüfen wir nochmal mit der Web UI.

Ich möchte jetzt gar nicht weiter auf die Abfragen eingehen. Mit der API Dokumentation sollten jetzt genügend Information vorhanden sein um eigene Abfragen an die NITRO API zu stellen. Allerdings möchte ich noch auf ein paar wesentliche Unterschiede zwischen dem NITRO Client und Postman eingehen.

Prinzipiell lässt sich sagen, dass der NITRO Client für Anfänger wesentlich besser geeignet ist. Durch die Auswahlmöglichkeiten der unterschiedlichen Funktionen und das Vorbelegen der Abfragen kommt man wesentlich schneller zum Ziel. Im Gegensatz dazu, muss man bei Postman die Abfragen mit allen Parametern mit Hilfe der Dokumentation selbst zusammenbauen (und die GUI ist auch ein wenig komplexer). Allerdings lassen sich bei Postman die einmal erstellten Abfrage speichern und automatisiert wieder ausführen. Was dem Konzept der Automatisierung wesentlich näher kommt, als das mit dem NITRO Client möglich ist.

Für eine schnelle Abfrage um eine Funktion oder Konfiguration schnell zu überprüfen, ist der NITRO Client ideal. Wer etwas mehr machen möchte und vielleicht auch die erstellten Abfragen sichern möchte, sollte sich mit Postman auseinandersetzen.

Auf diesem Abschnitt haben die PowerShell Fans nach der langen Einleitung gewartet. Deshalb gleich zu Beginn, der NetScaler hat keine PowerShell Schnittstelle!

Braucht er aber auch nicht, denn das ist das schöne an einer RESTful API. Da wir Standard HTTP mit der API sprechen, können wir alles verwenden was dieses Protokoll beherrscht.  Prinzipiell reicht also ein einfacher Browser. Dieser beherrscht zwar ohne zusätzliche Plugins nicht alle Funktionen, aber einfache GET Abfragen kann standardmäßig. Versucht doch mal die folgende URL in einem Browser aufzurufen:

http://<NetScaler FQDN>/nitro/v1/config/nsfeature

Da wir noch nicht authentifiziert sind, sendet der Browser zuerst eine Anforderung zur Authentifizierung. Sobald wir uns mit Benutzernamen und Passwort angemeldet haben, sieht die Ausgabe im Browser ähnlich aus, wie die vom NITRO Client oder Postman. Und da die PowerShell nativ mit HTTP arbeiten kann, stellt die Kommunikation von PowerShell mit einer RESTful API, wie in unserem Fall die NITRO API, kein wirkliches Problem dar. Die PowerShell stellt uns auch noch mit CovertTo-JSON und Invoke-RestMethod sehr nützliche Funktionen bereit.

Fangen wir mal damit an, dass Beispiel dieses Artikels mal mit PowerShell umzusetzen. Das Beispiel sieht ja wie folgt aus:

1. Anmelden am NetScaler
2. Abrufen der Features (eher unwichtig für dieses Beispiel)
3. Load Balancing aktivieren

Melden wir uns also zuerst mal am NetScaler an. Dazu erstellen wir eine Variable, die wir mit der Payload füllen und gleich in einen JSON konformen String umwandeln.

$body = ConvertTo-JSON @{"login"=@{"username"="admin";"password"="verysecret"}}

Danach schicken wir unsere Anmeldung mit Invoke-RestMethod an unseren NetScaler und speichern die Session in einer globalen Variable, was dann wie folgt aussieht.

Invoke-RestMethod -uri "https://<NetScaler FQDN>/nitro/v1/config/login" -body $body -SessionVariable NSSession `-Headers @{"Content-Type"="application/vnd.com.citrix.netscaler.login+json"} -Method POST
$Script:NSSession = $local:NSSession

In der PowerShell ISE sieht das dann so aus:

Nicht spektakulär, aber wir sind angemeldet. Das Abfragen der Features macht hier jetzt nicht wirklich Sinn, denn wir wollen ja etwas automatisieren. Deshalb überspringen wir diesen Schritt und machen uns gleich daran, Load Balancing zu aktivieren.

Zuerst bauen wir uns wieder die Variable mit der Payload im JSON Format:

$body = ConvertTo-JSON @{"nsfeature"=@{"feature"="lb"}}

Und schicken die Anfrage wieder mit Invoke-RestMethod an den NetScaler:

Invoke-RestMethod -uri "https://<NetScaler FQDN>/nitro/v1/config/nsfeature?action=enable" -body $body -WebSession $NSSession `-Headers @{"Content-Type"="application/vnd.com.citrix.netscaler.nsfeature+json"} -Method POST

Wichtig ist hier, dass wir die zuvor erzeugt globale Session Variable mit übergeben. Das Skript sieht in der Powershell ISE jetzt in etwa so aus:

Das war es im Prinzip bereits schon, das Ergebnis können wir wieder an der Web UI überprüfen. Mal ehrlich, ist doch nicht wirklich schwer. Eine Sache sollten wir aber zwingend noch beachten. Wenn wir solche Skripte ausführen, sollten wir am Schluss natürlich die Session nicht offen lassen sondern uns auch ordentlich wieder abmelden.

Also wieder die Payload vorbereiten:

$body = ConvertTo-JSON @{"logout"=@{}}

Und das ganze an den NetScaler schicken:

Invoke-RestMethod -uri "http://<NetScaler FQDN>/nitro/v1/config/logout" -body $body -WebSession $NSSession `-Headers @{"Content-Type"="application/vnd.com.citrix.netscaler.logout+json"} -Method POST

Hier mal das komplette Skript in der ISE: