Citrix ADC Erweiterungen API-Referenz

Verhaltensweisen sind eine Formalisierung gängiger programmierbarer Muster, die auf einer Citrix ADC 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. Beispielsweise kann ein TCP-Clientverhalten aus der Funktion on_data bestehen, die den TCP-Datenstrom verarbeitet.

TCP-Clientverhalten

on_data - Funktion Callback für TCP-Client-Datenereignisse. Der Rückruf nimmt zwei Argumente an:

• ctxt - TCP-Clientverarbeitungskontext
• Nutzlast — Ereignisnutzlast
  • payload.data - Empfangene TCP-Daten, verfügbar als Bytestrom

Verhalten des TCP-Servers

on_data - Funktion Callback für TCP-Server-Datenereignisse, nimmt der Callback zwei Argumente:

• ctxt - TCP-Server Verarbeitungskontext
• Nutzlast — Ereignisnutzlast
  • payload.data - empfangene TCP-Daten, verfügbar als Bytestrom

TCP-Clientkontext

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

• ctxt.output - Der nächste Verarbeitungskontext in der Pipeline. Extension-Callback-Handler können ns.tcp.stream-Typdaten an ctxt.output senden, indem sie die Ereignisse DATA verwenden, was Teilnachricht oder EOM bedeutet, was das Ende der Protokollnachricht bedeutet. Das EOM-Ereignis kann TCP-Daten enthalten oder nicht. Ein EOM-Ereignis mit TCP-Daten kann ohne vorheriges DATA-Ereignis gesendet werden, um eine ganze Protokollnachrichtsdaten zu senden und das Ende der Nachricht zu markieren. Die Entscheidung für den Lastausgleich wird nachgeschaltet vom virtuellen Lastausgleichsserver bei den ersten empfangenen Daten getroffen. Nach Erhalt der EOM-Nachricht wird eine neue Lastausgleichsentscheidung getroffen. Um Protokollnachrichtendaten zu streamen, senden Sie mehrere DATA Ereignisse mit dem letzten Ereignis als EOM. Alle zusammenhängenden DATA-Ereignisse und die folgenden EOM-Ereignisse werden an dieselbe Serververbindung gesendet, die durch die Lastenausgleichsentscheidung für das erste DATA-Ereignis in der Sequenz ausgewählt wurde.

• ctxt.input - Der vorherige Verarbeitungskontext in der Pipeline, von dem die TCP-Streamdaten stammen.

• ctxt:hold (data) - Funktion, um die Daten für die zukünftige Verarbeitung zu speichern. Beim Aufruf von Hold mit Daten werden die Daten im Kontext gespeichert. Später, wenn 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 Haltefunktion ist die Datenreferenz nicht mehr verwendbar und gibt Fehler bei jeder Verwendung.

• ctxt.vserver - Der virtuelle Serverkontext.

• ctxt.client — Verarbeitungskontext der Clientverbindung. 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ßen Sie die Clientverbindung, indem Sie FIN an den Client senden. Nach dem Aufruf dieser API ist der Client Verarbeitungskontext nicht mehr verwendbar und gibt Fehler bei jeder Verwendung.

TCP-Serverkontext

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

• ctxt.output — Der nächste Verarbeitungskontext in der Pipeline. Extension-Callback-Handler können ns.tcp.stream-Typdaten an ctxt.output senden, indem sie die Ereignisse DATA verwenden, was Teilnachricht oder EOM bedeutet, was das Ende der Protokollnachricht bedeutet.

• ctxt.input - Der vorherige Verarbeitungskontext in der Pipeline, von dem die TCP-Streamdaten stammen.

• ctxt:hold (data) - Funktion, um die Daten für die zukünftige Verarbeitung zu speichern. Beim Aufruf von Hold mit Daten werden die Daten im Kontext gespeichert. Später, wenn 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 Haltefunktion ist die Datenreferenz nicht mehr verwendbar und gibt Fehler bei jeder Verwendung.

• ctxt.vserver - Der virtuelle Serverkontext.

• ctxt.server - Serververbindungskontext. 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 die Serververbindung nur für andere Clientverbindungen im Serverkontext wiederverwendet werden kann. Diese API kann nur verwendet werden, wenn ein EOM-Ereignis (in ns.send () API) verwendet wird, um die Daten im Client-Kontext zu senden. Andernfalls löst 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 mehr Daten auf dieser 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 Lastenausgleichsentscheidung für diesen Client ausgewählt ist, wird dieselbe Serververbindung zum Senden der Clientdaten verwendet. Nach der Verwendung dieser API wird die Serververbindung nicht mehr an die Clientverbindung gebunden, für die sie geöffnet wurde, und kann für eine neue Lastausgleichsentscheidung für jede andere Clientverbindung 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 Citrix ADC 12.1 Build 49.xx und höher verfügbar.

• ctxt:close () — Schließen Sie die Serververbindung, indem Sie FIN an den Server senden. 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 Citrix ADC 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 virtuellen Server-Leistungsindikators, der als Argument übergeben wird. Derzeit werden die folgenden integrierten Leistungsindikatoren unterstützt.
  • - invalid_messages — Anzahl der ungültigen Anforderungen/Antworten auf diesem virtuellen Server.
  • - invalid_messages_dropped — Anzahl der ungültigen Anforderungen/Antworten, die von diesem virtuellen Server gelöscht wurden.
• vserver.params - Die konfigurierten Parameter für den virtuellen Benutzerserver. Parameter bieten Konfigurierbarkeit von Erweiterungen. Der Erweiterungscode kann auf Parameter zugreifen, die in der CLI angegeben sind, um einen virtuellen Benutzerserver hinzuzufügen.

Clientverbindungskontext

Client-Verbindungsverarbeitungskontext, um verbindungsbezogene Informationen zu erhalten.

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

Serververbindungskontext

Serververbindungskontext, um verbindungsbezogene Informationen abrufen zu können.

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

TCP-Kontext

TCP-Kontext arbeitet mit 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 - Ziel-IP-Adresse Kontext.

Hinweis: Diese API ist in Citrix ADC 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 Zeichenfolge von Bytes in Netzwerreihenfolge (4 Bytes für IPv4 und 16 Bytes für IPv6).
• <address>.version- Gibt 4 für IPv4 und 6 für IPv6 zurück.
• <address>:subnet(<prefix value>)- Gibt die Subnetzadressenzeichenfolge nach dem Anwenden der Präfixnummer zurück.
  • Für IPv4-Adresse muss der Wert zwischen 0 und 32 liegen.
  • Bei 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. API überprüft die Version des Arguments und führt entsprechende Fehlerüberprüfung durch.
• address>:eq(<address string>) - Gibt true oder false zurück, je nachdem, ob das Argument äquivalent zum Adressobjekt ist. API überprüft die Version der Argumente.

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

SSL-Kontext

Der SSL-Kontext stellt Informationen zur Frontend-SSL-Verbindung bereit.

• ssl.cert — SSL-Zertifikatskontext. Für die Clientverbindung stellt sie Clientzertifikatkontext bereit und stellt für die Serververbindung Serverzertifikatkontext 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-Chiffriername als Zeichenfolge, wenn von einer SSL-Verbindung aufgerufen wird, andernfalls gibt NULL-Zeichenfolge.
• ssl.cipher_bits — Anzahl der Bits im kryptografischen Schlüssel.

SSL-Zertifikatkontext

• Cert.version — Versionsnummer des Zertifikats. Wenn die Verbindung nicht SSL-basiert, gibt 0 zurück.
• Cert.valid_not_before — Datum im Zeichenfolgenformat, vor dem das Zertifikat ungültig ist.
• Cert.valid_not_after — Datum im Zeichenfolgenformat, 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 abgelaufenes Zertifikat zurück.
• Cert.to_pem — Zertifikat im Binärformat.

• cert.issuer - Distinguished Name (DN) 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 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 Erweiterung des Authority Key Identifier des X.509 V3 Zertifikats.

  • auth_keyid.exists - TRUE, wenn das Zertifikat eine Erweiterung des Authority Key Identifier 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 trennt.

  Es folgt ein 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 Autoritätsschlüssel-Identifikators als Blob.
• cert.pk_algorithm - Name des öffentlichen Schlüsselalgorithmus, der vom Zertifikat verwendet wird.
• cert.pk_size - Größe des öffentlichen Schlüssels, der im Zertifikat verwendet wird.
• 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 ausgegeben.
• cert.signature_algorithm - Name des kryptografischen Algorithmus, der von der Zertifizierungsstelle zum Signieren dieses Zertifikats verwendet wird.
• cert.subject_keyid - Betreff KeyID des Client-Zertifikats. Wenn keine Subject KeyID vorhanden ist, gibt dies ein Null-Längen-Textobjekt.
• cert.subject - Distinguished Name des Subjekts als Name-Wert. Ein Gleichheitszeichen (=) trennt Namen und Werte und ein Schrägstrich (/) trennt Name-Wert-Paare.

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

Citrix ADC-Bibliotheken

• ns.tcp.stream - String ähnliche Bibliothek für die Verarbeitung von TCP-Daten als Bytestrom. Die maximale Größe der TCP-Streamdaten, mit denen diese APIs arbeiten können, beträgt 128 KB. Die Bibliotheksfunktionen ns.tcp.stream können auch im üblichen Erweiterungsobjektorientierten Stil des Aufrufs aufgerufen werden. Zum Beispiel ist data:len () identisch mit ns.tcp.stream.len (data)
  • ns.tcp.stream.len (data) - Gibt die Länge der Daten in Bytes zurück, ähnlich wie Luas string.len
  • ns.tcp.stream.find (data, pattern, [init])- Funktion ähnlich wie Luas string.find. Darüber hinaus führt es auch einen Teilabgleich am Ende der Daten durch. Bei partieller Übereinstimmung wird der Startindex zurückgegeben und der Endindex wird null.
  • ns.tcp.stream.split (data, length) - Teilt die Daten in zwei Chunks, der erste Chunk ist von der angegebenen Länge. Nach einer erfolgreichen Aufteilung sind die ursprünglichen Daten nicht mehr als TCP-Datenstrom nutzbar. Jeder Versuch, es auf diese Weise zu verwenden, verursacht einen Fehler.
  • ns.tcp.stream.byte (data[, i [, j]])- Funktion ähnlich wie Luas string.byte. Gibt die internen numerischen Codes der Zeichendaten[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 fortgesetzt wird.
  • ns.tcp.stream.match (data, pattern,[init])- Funktion ähnlich wie Luas string.match. Sucht nach der ersten Übereinstimmung des Musters in String s.

• ns.send (processing_ctxt, event_name, event_data) - Generische Funktion, um Ereignisse an einen Verarbeitungskontext zu senden. Ereignisdaten sind eine Lua-Tabelle, die beliebige Inhalte haben kann. Der Inhalt hängt vom Ereignis 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) - Mit einem Aufruf von pipe () API kann Erweiterungscode Quellkontext mit einem Zielkontext verbinden. Nach einem Aufruf von Pipe gehen alle Ereignisse, die vom Quellkontext an das nächste Modul in der Pipeline gesendet werden, direkt in den Zielkontext. Diese API wird normalerweise vom Modul verwendet, das den pipe () aufruft, 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 nach dem Anwenden der Maskenzeichenfolge zurück.
  • ns.inet.aton (address_str) - Gibt den numerischen Wert der Adresse als Zeichenfolge von Bytes in Netzwerreihenfolge zurück (4 Bytes für IPv4 und 16 für IPv6).
  • ns.inet.ntoa (byte_str) - Konvertiert numerischen Byte-Wert als eine Zeichenfolge von Bytes in Adresszeichenfolge.
  • ns.inet.ntohs (number) - Konvertieren Sie die angegebene Netzwerk-Byte-Reihenfolge in Host-Byte-Reihenfolge. Wenn die Eingabe größer als 2^16 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.htons (number) - Konvertiert die angegebene Host-Byte-Reihenfolge in Netzwerk-Byte-Reihenfolge. Wenn die Eingabe größer als 2^16 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.ntohl (number) - Konvertiert die angegebene Netzwerk-Byte-Reihenfolge in Host-Byte-Reihenfolge. Wenn die Eingabe größer als 2^32 - 1 ist, wird ein Fehler ausgegeben.
  • ns.inet.htonl (number) - Konvertiert die angegebene Host-Byte-Reihenfolge in Netzwerk-Byte-Reihenfolge. 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.