API-Referenz für NetScaler-Erweiterungen

Verhalten ist eine Formalisierung gängiger programmierbarer Muster, die auf einer NetScaler-Appliance verfügbar sind. Ein virtueller TCP-Server unterstützt beispielsweise ein TCP-Clientverhalten und ein TCP-Serververhalten. Ein Verhalten ist ein vordefinierter Satz von Callback-Funktionen. Sie können Verhaltensweisen implementieren, indem Sie Callback-Funktionen bereitstellen. Ein TCP-Clientverhalten kann beispielsweise aus der Funktion on_data bestehen, die den TCP-Datenstrom verarbeitet.

Verhalten des TCP-Clients

on_data — Funktionsrückruf für TCP-Client-Datenereignisse. Der Callback benötigt zwei Argumente:

• ctxt - Verarbeitungskontext für TCP-Clients
• Nutzlast — Event-Payload
  • payload.data — Empfangene TCP-Daten, verfügbar als Byte-Stream

Verhalten des TCP-Servers

on_data — Funktionsrückruf für TCP-Serverdatenereignisse, der Callback benötigt zwei Argumente:

• ctxt - Kontext für die TCP-Serververarbeitung
• Nutzlast — Event-Payload
  • payload.data — empfangene TCP-Daten, verfügbar als Byte-Stream

TCP-Clientkontext

Der Kontext, der an die TCP-Client-Event-Callbacks übergeben wird:

• ctxt.output — Der nächste Verarbeitungskontext in der Pipeline. Callback-Handler für Erweiterungen können Daten vom Typ ns.tcp.stream an ctxt.output senden, indem sie die Ereignisse DATA verwenden, was eine partielle Nachricht bedeutet, oder EOM, was eine Nachricht am Ende des Protokolls bedeutet. Das EOM-Ereignis kann TCP-Daten enthalten oder auch nicht. Ein EOM-Ereignis mit TCP-Daten kann ohne vorheriges DATA-Ereignis gesendet werden, um die gesamten Protokollnachrichtendaten zu senden und das Ende der Nachricht zu markieren. Die Entscheidung für den Lastenausgleich wird stromabwärts vom virtuellen Lastausgleichsserver anhand der ersten empfangenen Daten getroffen. Nach Erhalt der EOM-Nachricht wird eine neue Load-Balancing-Entscheidung getroffen. Um Protokollnachrichtendaten zu streamen, senden Sie also mehrere DATA-Ereignisse, wobei das letzte Ereignis als EOM gilt. Alle aufeinanderfolgenden DATA-Ereignisse und die folgenden EOM-Ereignisse werden an dieselbe Serververbindung gesendet, die bei der Lastausgleichsentscheidung für das erste DATA-Ereignis in der Sequenz ausgewählt wurde.

• ctxt.input — Der vorherige Verarbeitungskontext in der Pipeline, aus dem die TCP-Stream-Daten stammen.

• ctxt:hold (data) — Funktion zum Speichern der Daten für die zukünftige Verarbeitung. Wenn ein Anruf mit Daten unterbrochen wird, werden die Daten im Kontext gespeichert. Wenn später mehr Daten im gleichen Kontext empfangen werden, werden neu empfangene Daten an die zuvor gespeicherten Daten angehängt und der kombinierte Datenstrom wird dann an die on_data-Callback-Funktion übergeben. Nach dem Aufruf einer Sperre ist die Datenreferenz nicht mehr verwendbar und gibt bei jeder Verwendung einen Fehler aus.

• ctxt.vserver — Der virtuelle Serverkontext .

• ctxt.client — Kontext für die Verarbeitung von Clientverbindungen. Dieser Verarbeitungskontext kann verwendet werden, um Daten an den Client zu senden und einige verbindungsbezogene Informationen wie IP-Adresse, Quell- und Zielports abzurufen.

• ctxt:close () — Schließt die Client-Verbindung, indem FIN an den Client gesendet wird. Nach dem Aufrufen dieser API ist der Client-Verarbeitungskontext nicht mehr verwendbar und gibt bei jeder Verwendung einen Fehler aus.

TCP-Serverkontext

Der Kontext, der an die TCP-Serverereignisrückrufe übergeben wird:

• ctxt.output — Der nächste Verarbeitungskontext in der Pipeline. Callback-Handler für Erweiterungen können Daten vom Typ ns.tcp.stream an ctxt.output senden, indem sie die Ereignisse DATA verwenden, was eine partielle Nachricht bedeutet, oder EOM, was eine Nachricht am Ende des Protokolls bedeutet.

• ctxt.input — Der vorherige Verarbeitungskontext in der Pipeline, aus dem die TCP-Stream-Daten stammen.

• ctxt:hold (data) — Funktion zum Speichern der Daten für die zukünftige Verarbeitung. Wenn ein Anruf mit Daten unterbrochen wird, werden die Daten im Kontext gespeichert. Wenn später mehr Daten im gleichen Kontext empfangen werden, werden neu empfangene Daten an die zuvor gespeicherten Daten angehängt und der kombinierte Datenstrom wird dann an die on_data-Callback-Funktion übergeben. Nach dem Aufruf einer Sperre ist die Datenreferenz nicht mehr verwendbar und gibt bei jeder Verwendung einen Fehler aus.

• ctxt.vserver — Der virtuelle Serverkontext .

• ctxt.server — Kontext für die Verarbeitung von Serververbindungen. Dieser Verarbeitungskontext kann verwendet werden, um Daten an den Server zu senden und einige verbindungsbezogene Informationen wie IP-Adresse, Quell- und Zielports abzurufen.

• ctxt:reuse_server_connection () — Diese API wird verwendet, um zu ermöglichen, dass die Serververbindung nur im Serverkontext für andere Client-Verbindungen wiederverwendet werden kann. Diese API kann nur verwendet werden, wenn ein EOM-Ereignis (in der ns.send () API) verwendet wird, um die Daten im Client-Kontext zu senden. Andernfalls gibt die ADC-Appliance einen Fehler aus.

  Damit eine Serververbindung von anderen Clients wiederverwendet werden kann, muss diese API am Ende jeder Antwortnachricht aufgerufen werden. Wenn nach dem Aufruf dieser API weitere Daten über diese Serververbindung empfangen werden, wird dies als Fehler behandelt und die Serververbindung wird geschlossen. Wenn diese API nicht verwendet wird, kann die Serververbindung nur für den Client verwendet werden, für den sie geöffnet wurde. Wenn derselbe Server für eine weitere Lastausgleichsentscheidung für diesen Client ausgewählt wird, wird dieselbe Serververbindung verwendet, um die Client-Daten zu senden. Nach der Verwendung dieser API ist die Serververbindung nicht mehr an die Client-Verbindung gebunden, für die sie geöffnet wurde, und kann für eine neue Lastausgleichsentscheidung für jede andere Client-Verbindung wiederverwendet werden. Nach dem Aufruf dieser API ist der Serverkontext nicht mehr verwendbar und löst bei jeder Verwendung einen Fehler aus.

  Hinweis: Diese API ist in NetScaler 12.1 Build 49.xx und höher verfügbar.

• ctxt:close () — Schließt die Serververbindung, indem FIN an den Server gesendet wird. Nach dem Aufruf dieser API ist der Client-Verarbeitungskontext nicht mehr verwendbar und zeigt bei jeder Verwendung einen Fehler an.

  Hinweis: Diese API ist in NetScaler 12.1 Build 50.xx und höher verfügbar.

Vserver-Kontext

Der virtuelle Benutzerserverkontext, der über die an Callbacks übergebenen Kontexte verfügbar ist:

• vserver:counter_increment (counter_name) — Erhöht den Wert eines als Argument übergebenen virtuellen Serverzählers. Derzeit werden die folgenden integrierten Zähler unterstützt.
  • - invalid_messages — Anzahl der ungültigen Anfragen/Antworten auf diesem virtuellen Server.
  • - invalid_messages_dropped — Anzahl der ungültigen Anfragen/Antworten, die von diesem virtuellen Server gelöscht wurden.
• vserver.params — Die konfigurierten Parameter für den virtuellen Benutzerserver. Parameter ermöglichen die Konfigurierbarkeit von Erweiterungen. Der Erweiterungscode kann auf Parameter zugreifen, die in der CLI angegeben sind, um einen virtuellen Benutzerserver hinzuzufügen.

Kontext der Client-Verbindung

Kontext zur Verarbeitung von Client-Verbindungen, um verbindungsbezogene Informationen abzurufen.

• client.ssl — SSL-Kontext
• client.tcp — TCP-Kontext
• client.is_ssl — True, wenn die Client-Verbindung SSL-basiert ist

Kontext der Serververbindung

Kontext zur Verarbeitung von Serververbindungen, um verbindungsbezogene Informationen abzurufen.

• server.ssl — SSL-Kontext
• server.tcp — TCP-Kontext
• server.is_ssl — True, wenn die Serververbindung SSL-basiert ist

TCP-Kontext

Der TCP-Kontext arbeitet mit dem TCP-Protokoll.

• tcp.srcport — Quellport als Zahl
• tcp.dstport - Zielport als Zahl

IP-Kontext

Der IP-Kontext funktioniert mit IP- oder IPv6-Protokolldaten.

• ip.src — Quell-IP-Adresskontext.
• ip.dst — Kontext der Ziel-IP-Adresse.

Hinweis: Diese API ist in NetScaler 12.1 Build 51.xx und höher verfügbar.

IP-Adresskontext

Der IP-Adresskontext funktioniert mit IP- oder IPv6-Adressdaten.

• <address>.to_s - Die Adresszeichenfolge in der entsprechenden ASCII-Notation.
• <address>.to_n - Der numerische Wert der Adresse als Bytefolge in Netzwerkreihenfolge (4 Byte für IPv4 und 16 Byte für IPv6).
• <address>.version - Gibt 4 für IPv4 und 6 für IPv6 zurück.
• <address>:subnet(<prefix value>) - Gibt die Subnetzadresszeichenfolge zurück, nachdem die Präfixnummer angewendet wurde.
  • Für eine IPv4-Adresse muss der Wert zwischen 0 und 32 liegen
  • Für eine IPv6-Adresse muss der Wert zwischen 0 und 128 liegen.
• <address>:apply_mask(<mask string>) - Gibt die Adresszeichenfolge nach dem Anwenden der Maskenzeichenfolge zurück. Die API validiert die Version des Arguments und führt eine entsprechende Fehlerprüfung durch.
• address>:eq(<address string>) - Gibt „Wahr“ oder „Falsch“ zurück, je nachdem, ob das Argument dem Adressobjekt entspricht. Die API validiert die Version der Argumente.

Hinweis: Diese API ist in NetScaler 12.1 Build 51.xx und höher verfügbar.

SSL-Kontext

Der SSL-Kontext enthält Informationen zur Frontend-SSL-Verbindung.

• ssl.cert — SSL-Zertifikatskontext. Für die Clientverbindung stellt es den Client-Zertifikatskontext und für die Serververbindung den Serverzertifikatskontext bereit.

• ssl.version — Eine Zahl, die die SSL-Protokollversion der aktuellen Transaktion darstellt, wie folgt:

  • - 0: The transaction is not SSL-based
  • - 0x002: The transaction is SSLv2
  • - 0x300: The transaction is SSLv3
  • - 0x301: The transaction is TLSv1
  • - 0x302: The transaction is TLSv1.1
  • - 0x303: The transaction is TLSv1.2
• ssl.cipher_name — SSL-Verschlüsselungsname als Zeichenfolge, wenn er von einer SSL-Verbindung aus aufgerufen wird, andernfalls gibt er eine NULL-Zeichenfolge zurück.
• ssl.cipher_bits — Anzahl der Bits im kryptografischen Schlüssel.

Kontext des SSL-Zertifikats

• cert.Version — Versionsnummer des Zertifikats. Wenn die Verbindung nicht SSL-basiert ist, wird 0 zurückgegeben.
• cert.valid_not_before — Datum im Zeichenkettenformat, vor dem das Zertifikat nicht gültig ist.
• cert.valid_not_after — Datum im Zeichenkettenformat, nach dem das Zertifikat nicht mehr gültig ist.
• cert.days_to_EXPIRE — Anzahl der Tage, vor denen das Zertifikat gültig ist. Gibt -1 für ein abgelaufenes Zertifikat zurück.
• cert.to_PEM — Zertifikat im Binärformat.

• cert.issuer — Distinguished Name (DN) des Emittenten im Zertifikat als Namenswertliste. Ein Gleichheitszeichen („=“) ist das Trennzeichen für den Namen und den Wert, und der Schrägstrich („/“) ist das Trennzeichen, das die Name-Wert-Paare voneinander trennt.

  Es folgt ein Beispiel für den zurückgegebenen DN: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

• cert.auth_keyid — Kontext der Authority Key Identifier-Erweiterung des X.509 V3-Zertifikats.

  • auth_keyid.exists — TRUE, wenn das Zertifikat eine Authority Key Identifier-Erweiterung enthält.

  • auth_keyid.issuer_name — Distinguished Name des Ausstellers im Zertifikat als Name-Wert-Liste. Ein Gleichheitszeichen (=) ist das Trennzeichen für den Namen und den Wert, und der Schrägstrich ( / ) ist das Trennzeichen, das die Name-Wert-Paare voneinander trennt.

  Beispiel: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

  • auth_keyid.keyid — KeyIdentifier-Feld des Authority Key Identifier als Blob
  • auth_keyid.cert_serialnumber — Feld SerialNumber des Authority Key Identifier als Blob.
• cert.pk_algorithm — Name des vom Zertifikat verwendeten Public-Key-Algorithmus.
• cert.pk_size — Größe des im Zertifikat verwendeten öffentlichen Schlüssels.
• cert.serialnumber — Seriennummer des Client-Zertifikats. Wenn es sich um eine Nicht-SSL-Transaktion handelt oder ein Fehler im Zertifikat vorliegt, wird eine leere Zeichenfolge zurückgegeben.
• cert.signature_algorithm — Name des kryptografischen Algorithmus, der von der CA verwendet wird, um dieses Zertifikat zu signieren.
• cert.subject_keyid — Subject KeyID des Client-Zertifikats. Wenn es keine Subject KeyID gibt, ergibt dies ein Textobjekt der Länge Null.
• cert.subject — Distinguished Name des Subjekts als Namenswert. Ein Gleichheitszeichen (=) trennt Namen und Werte und ein Schrägstrich ( / ) trennt Name-Wert-Paare.

Beispiel: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

NetScaler-Bibliotheken

• ns.tcp.stream — Stringähnliche Bibliothek zur Behandlung von TCP-Daten als Byte-Stream. Die maximale Größe der TCP-Stream-Daten, mit denen diese APIs arbeiten können, beträgt 128 KB. Die Funktionen der ns.tcp.stream-Bibliothek können auch im üblichen objektorientierten Aufrufstil von Erweiterungen aufgerufen werden. Beispielsweise ist data:len() dasselbe wie ns.tcp.stream.len(data)
  • ns.tcp.stream.len (data) - Gibt die Länge der Daten in Byte zurück, ähnlich wie bei Luas String.len
  • ns.tcp.stream.find (data, pattern [, init]) — Funktion ähnlich wie Luas string.find. Darüber hinaus führt es auch einen teilweisen Abgleich am Ende der Daten durch. Bei teilweiser Übereinstimmung wird der Startindex zurückgegeben und der Endindex wird Null.
  • ns.tcp.stream.split (data, length) - Teilt die Daten in zwei Blöcke auf, der erste Block hat die angegebene Länge. Nach einer erfolgreichen Aufteilung sind die Originaldaten nicht mehr als TCP-Datenstrom nutzbar. Jeder Versuch, es auf diese Weise zu verwenden, führt zu einem Fehler.
  • ns.tcp.stream.byte(data[, i [, j]]) - Function similar to Lua’s string.byte. Gibt die internen numerischen Codes der Zeichen data [i], data [i+1],…, data [j] zurück.
  • ns.tcp.stream.sub (data, i [, j]) — Funktion ähnlich wie Luas string.sub. Gibt die Teilzeichenfolge von s zurück, die bei i beginnt und bis j andauert.
  • ns.tcp.stream.match (data, pattern, [, init]) — Funktion ähnlich wie Luas string.match. Sucht nach der ersten Musterübereinstimmung in der Zeichenfolge s.

• ns.send(processing_ctxt, event_name, event_data) — Generische Funktion zum Senden von Ereignissen an einen Verarbeitungskontext. Event-Daten sind eine Lua-Tabelle, die beliebigen Inhalt haben kann. Die Inhalte hängen von der Veranstaltung ab. Nachdem die ns.send () -API aufgerufen wurde, ist die Datenreferenz nicht mehr verwendbar. Jeder Versuch, es zu verwenden, verursacht einen Fehler.

• ns.pipe(src_ctxt, dest_ctxt) — Mithilfe eines Aufrufs der pipe()-API kann Erweiterungscode den Quellkontext mit einem Zielkontext verbinden. Nach einem Pipe-Aufruf gehen alle Ereignisse, die vom Quellkontext an das nächste Modul in der Pipeline gesendet werden, direkt an den Zielkontext. Diese API wird normalerweise von dem Modul verwendet, das den pipe()-Aufruf ausführt, um sich selbst aus der Pipeline zu entfernen.

• ns.inet — Bibliothek für Internetadressen.

  • ns.inet.apply_mask (address_str, mask_str) — gibt die Adresszeichenfolge zurück, nachdem die Maskenzeichenfolge angewendet wurde .
  • ns.inet.aton (address_str) — Gibt den numerischen Wert der Adresse als Bytefolge in Netzwerkreihenfolge zurück (4 Byte für IPv4 und 16 Byte für IPv6).
  • ns.inet.ntoa (byte_str) — Konvertiert einen numerischen Bytewert als Bytefolge in eine Adresszeichenfolge.
  • ns.inet.ntohs (number) — Konvertiert die angegebene Netzwerk-Bytereihenfolge in die Host-Bytereihenfolge. Wenn die Eingabe größer als 2^16 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.htons (number) - Konvertiert die angegebene Host-Bytereihenfolge in die Netzwerk-Bytereihenfolge. Wenn die Eingabe größer als 2^16 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.ntohl (number) — Konvertiert die angegebene Netzwerk-Bytereihenfolge in die Host-Bytereihenfolge. Wenn die Eingabe größer als 2^32 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.htonl (number) - Konvertiert die angegebene Host-Bytereihenfolge in die Netzwerk-Bytereihenfolge. Wenn die Eingabe größer als 2^32 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.subnet (address_str, subnet_value) — Gibt die Subnetzadressenzeichenfolge nach Anwendung des angegebenen Subnetzes zurück.