Référence de l’API des extensions NetScaler

Les comportements sont une formalisation de modèles programmables courants disponibles sur une appliance NetScaler. Par exemple, un serveur virtuel TCP prend en charge un comportement de client TCP et un comportement de serveur TCP. Un comportement est un ensemble prédéfini de fonctions de rappel. Vous pouvez implémenter des comportements en fournissant des fonctions de rappel. Par exemple, le comportement d’un client TCP peut consister en la fonction on_data, qui traite le flux de données TCP.

Comportement du client TCP

on_data - fonction de rappel pour les événements de données du client TCP. Le callback prend deux arguments :

• ctxt - Contexte de traitement du client TCP
• charge utile : charge utile de l’événement
  • payload.data - Données TCP reçues, disponibles sous forme de flux d’octets

Comportement du serveur TCP

on_data - fonction de rappel pour les événements de données du serveur TCP, le rappel prend deux arguments :

• ctxt - Contexte de traitement du serveur TCP
• charge utile : charge utile de l’événement
  • payload.data - données TCP reçues, disponibles sous forme de flux d’octets

Contexte du client TCP

Le contexte qui est transmis aux rappels d’événements du client TCP :

• ctxt.output - Le contexte de traitement suivant dans le pipeline. Les gestionnaires de rappel d’extensions peuvent envoyer des données de type ns.tcp.stream à ctxt.output à l’aide des événements DATA, qui signifie un message partiel ou EOM, qui signifie un message de fin de protocole. L’événement EOM (fin du message) peut avoir ou non des données TCP avec elle. Un événement EOM (fin du message) avec des données TCP peut être envoyé sans un événement DATA précédent pour envoyer un message de protocole entier et marquer la fin du message. La décision d’équilibrage de charge est prise, en aval par le serveur virtuel d’équilibrage de charge, sur les premières données reçues. Une nouvelle décision d’équilibrage de charge est prise après la réception du message EOM. Ainsi, pour diffuser des données de message de protocole, envoyez plusieurs événements DATA avec le dernier événement comme EOM (fin du message). Tous les événements DATA contigus et les événements EOM (fin du message) suivants sont envoyés à la même connexion serveur sélectionnée par la décision d’équilibrage de charge sur le premier événement DATA de la séquence.

• ctxt.input - Le contexte de traitement précédent dans le pipeline d’où proviennent les données du flux TCP.

• ctxt:hold (data) - Fonction permettant de stocker les données pour un traitement ultérieur. Lors d’un appel en attente avec des données, les données sont stockées dans le contexte. Plus tard, lorsque d’autres données sont reçues dans le même contexte, les données nouvellement reçues sont ajoutées aux données précédemment stockées et le flux de données combiné est ensuite transmis à la fonction de rappel on_data. Après l’appel d’une mise en attente, la référence de données n’est plus utilisable et génère des erreurs à chaque utilisation.

• ctxt.vserver - Le contexte du serveur virtuel.

• ctxt.client  : contexte de traitement de la connexion client. Ce contexte de traitement peut être utilisé pour envoyer des données au client et pour récupérer certaines informations relatives à la connexion, telles que l’adresse IP, les ports source et de destination.

• ctxt:close () — Ferme la connexion client en envoyant FIN au client Après avoir appelé cette API, le contexte de traitement du client n’est plus utilisable et génère des erreurs à chaque utilisation.

Contexte du serveur TCP

Le contexte qui est transmis aux rappels d’événements du serveur TCP :

• ctxt.output — Le contexte de traitement suivant dans le pipeline. Les gestionnaires de rappel d’extensions peuvent envoyer des données de type ns.tcp.stream à ctxt.output à l’aide des événements DATA, qui signifie un message partiel ou EOM, qui signifie un message de fin de protocole.

• ctxt.input - Le contexte de traitement précédent dans le pipeline d’où proviennent les données du flux TCP.

• ctxt:hold (data) - Fonction permettant de stocker les données pour un traitement ultérieur. Lors d’un appel en attente avec des données, les données sont stockées dans le contexte. Plus tard, lorsque d’autres données sont reçues dans le même contexte, les données nouvellement reçues sont ajoutées aux données précédemment stockées et le flux de données combiné est ensuite transmis à la fonction de rappel on_data. Après l’appel d’une mise en attente, la référence de données n’est plus utilisable et génère des erreurs à chaque utilisation.

• ctxt.vserver - Le contexte du serveur virtuel.

• ctxt.server - Contexte de traitement de la connexion au serveur. Ce contexte de traitement peut être utilisé pour envoyer des données au serveur et pour récupérer certaines informations relatives à la connexion, telles que l’adresse IP, les ports source et de destination.

• ctxt:reuse_server_connection () - Cette API est utilisée pour permettre la réutilisation de la connexion au serveur pour d’autres connexions client dans le contexte du serveur uniquement. Cette API ne peut être utilisée que si un événement EOM est utilisé (dans l’API ns.send ()) pour envoyer les données dans le contexte client. Dans le cas contraire, l’appliance ADC renvoie une erreur.

  Pour permettre à une connexion serveur d’être réutilisée par d’autres clients, cette API doit être appelée à la fin de chaque message de réponse. Après avoir appelé cette API, si d’autres données sont reçues sur cette connexion au serveur, cela est considéré comme une erreur et la connexion au serveur est fermée. Si cette API n’est pas utilisée, la connexion au serveur ne peut être utilisée que pour le client pour lequel elle a été ouverte. De même, si le même serveur est sélectionné pour une autre décision d’équilibrage de charge pour ce client, la même connexion au serveur est utilisée pour envoyer les données du client. Après avoir utilisé cette API, la connexion au serveur cesse d’être liée à la connexion client pour laquelle elle a été ouverte et peut être réutilisée pour une nouvelle décision d’équilibrage de charge pour toute autre connexion client. Après avoir appelé cette API, le contexte du serveur n’est plus utilisable et génère une erreur à chaque utilisation.

  Remarque : Cette API est disponible dans NetScaler 12.1 build 49.xx et versions ultérieures.

• ctxt:close () — Ferme la connexion au serveur en envoyant FIN au serveur Après avoir appelé cette API, le contexte de traitement du client n’est plus utilisable et affiche une erreur à chaque utilisation.

  Remarque : Cette API est disponible dans NetScaler 12.1 build 50.xx et versions ultérieures.

Contexte du serveur virtuel

Le contexte du serveur virtuel utilisateur disponible via les contextes transmis aux rappels :

• vserver:counter_increment (counter_name) - Incrémente la valeur d’un compteur de serveur virtuel passé en argument. Les compteurs intégrés suivants sont actuellement pris en charge.
  • - invalid_messages — Nombre de demandes/réponses non valides sur ce serveur virtuel.
  • - invalid_messages_dropped — Nombre de demandes/réponses non valides supprimées par ce serveur virtuel.
• vserver.params  : paramètres configurés pour le serveur virtuel utilisateur. Les paramètres permettent de configurer les extensions. Le code d’extension peut accéder aux paramètres spécifiés dans la CLI pour ajouter un serveur virtuel utilisateur.

Contexte de connexion du client

Contexte de traitement de la connexion client pour obtenir des informations relatives à la connexion.

• client.ssl — Contexte SSL
• client.tcp — contexte TCP
• client.is_ssl — Vrai si la connexion client est basée sur SSL

Contexte de connexion au serveur

Contexte de traitement de la connexion au serveur pour obtenir des informations relatives à la connexion.

• server.ssl — Contexte SSL
• server.tcp — Contexte TCP
• server.is_ssl — Vrai si la connexion au serveur est basée sur SSL

Contexte TCP

Le contexte TCP fonctionne selon le protocole TCP.

• tcp.srcport — Port source sous forme de numéro
• tcp.dstport - Port de destination sous forme de numéro

Contexte IP

Le contexte IP fonctionne sur les données du protocole IP ou IPv6.

• ip.src - Contexte de l’adresse IP source.
• ip.dst - Contexte de l’adresse IP de destination.

Remarque : Cette API est disponible dans NetScaler 12.1 build 51.xx et versions ultérieures.

Contexte de l’adresse IP

Le contexte d’adresse IP fonctionne sur les données d’adresse IP ou IPv6.

• <address>.to_s - La chaîne d’adresse dans la notation ASCII appropriée.
• <address>.to_n - La valeur numérique de l’adresse sous forme de chaîne d’octets dans l’ordre du réseau (4 octets pour IPv4 et 16 octets pour IPv6).
• <address>.version - Renvoie 4 pour IPv4 et 6 pour IPv6.
• <address>:subnet(<prefix value>) - Renvoie la chaîne d’adresse du sous-réseau après application du numéro de préfixe.
  • Pour l’adresse IPv4, la valeur doit être comprise entre 0 et 32
  • Pour l’adresse IPv6, la valeur doit être comprise entre 0 et 128.
• <address>:apply_mask(<mask string>) - Renvoie la chaîne d’adresse après l’application de la chaîne de masque. L’API valide la version de l’argument et vérifie les erreurs de manière appropriée.
• address>:eq(<address string>) - Renvoie vrai ou faux selon que l’argument est équivalent à l’objet d’adresse. L’API valide la version des arguments.

Remarque : Cette API est disponible dans NetScaler 12.1 build 51.xx et versions ultérieures.

Contexte SSL

Le contexte SSL fournit des informations relatives à la connexion SSL frontale.

• ssl.cert — Contexte du certificat SSL. Pour la connexion client, il fournit le contexte du certificat client et pour la connexion au serveur, il fournit le contexte du certificat serveur.

• ssl.version  : nombre qui représente la version du protocole SSL de la transaction en cours, comme suit :

  • - 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 - Le nom du chiffrement SSL sous forme de chaîne s’il est appelé depuis une connexion SSL, sinon donne une chaîne NULL.
• ssl.cipher_bits — Nombre de bits dans la clé cryptographique.

Contexte du certificat SSL

• cert.version — Numéro de version du certificat. Si la connexion n’est pas basée sur SSL, renvoie 0.
• cert.VALID_NOT_BEFORE — Date au format chaîne avant laquelle le certificat n’est pas valide.
• cert.VALID_NOT_AFTER — Date au format chaîne après laquelle le certificat n’est plus valide.
• cert.days_to_expire — Nombre de jours avant lesquels le certificat est valide. Renvoie -1 pour un certificat expiré.
• cert.to_PEM — Certificat au format binaire.

• cert.issuer - Nom distinctif (DN) de l’émetteur dans le certificat sous forme de liste nom-valeur. Le signe égal (« = ») est le délimiteur du nom et de la valeur, et la barre oblique («/») est le délimiteur qui sépare les paires nom-valeur.

  Voici un exemple du nom distinctif renvoyé : /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

• cert.auth_keyid — Contexte de l’extension Authority Key Identifier du certificat X.509 V3.

  • auth_keyid.exists  : VRAI si le certificat contient une extension Authority Key Identifier.

  • auth_keyid.issuer_name - Nom distinctif de l’émetteur dans le certificat sous forme de liste nom-valeur. Le signe égal (« = ») est le délimiteur du nom et de la valeur, et la barre oblique («/») est le délimiteur qui sépare les paires nom-valeur.

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

  • auth_keyid.keyid - Champ keyIdentifier de l’identifiant de clé d’autorité en tant que blob
  • auth_keyid.cert_serialnumber : champ SerialNumber de l’identifiant de clé d’autorité en tant que blob.
• cert.pk_algorithm  : nom de l’algorithme à clé publique utilisé par le certificat.
• cert.pk_size - Taille de la clé publique utilisée dans le certificat.
• cert.serialnumber - Numéro de série du certificat client. S’il s’agit d’une transaction non SSL ou s’il y a une erreur dans le certificat, cela donne une chaîne vide.
• cert.signature_algorithm : nom de l’algorithme cryptographique utilisé par l’autorité de certification pour signer ce certificat.
• cert.subject_keyid : ID de clé d’objet du certificat client. S’il n’y a pas de Subject KeyID, cela donne un objet de texte de longueur nulle.
• cert.subject - Nom distinctif du sujet en tant que valeur-nom. Un signe égal (« = ») sépare les noms des valeurs et une barre oblique («/») délimite les paires nom-valeur.

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

Bibliothèques NetScaler

• ns.tcp.stream - Bibliothèque de type chaîne pour gérer les données TCP sous forme de flux d’octets. La taille maximale des données de flux TCP sur lesquelles ces API peuvent fonctionner est de 128 Ko. Les fonctions de la bibliothèque ns.tcp.stream peuvent également être appelées dans le style d’appel habituel orienté objet d’extension. Par exemple, data:len () est identique à ns.tcp.stream.len (data)
  • ns.tcp.stream.len (data) - Renvoie la longueur des données en octets, similaire à la chaîne .len de Lua
  • ns.tcp.stream.find (data, pattern [, init]) - Fonction similaire à string.find de Lua. En outre, il effectue également une correspondance partielle à la fin des données. En cas de correspondance partielle, l’indice de départ est renvoyé et l’indice de fin devient nul.
  • ns.tcp.stream.split (data, length) - Divise les données en deux segments, le premier étant de la longueur spécifiée. Après un fractionnement réussi, les données d’origine ne sont plus utilisables en tant que flux de données TCP. Toute tentative de l’utiliser de cette manière entraîne une erreur.
  • ns.tcp.stream.byte (data [, i [, j]]) - Fonction similaire à string.byte de Lua. Renvoie les codes numériques internes des caractères data [i], data [i+1],…, data [j].
  • ns.tcp.stream.sub (data, i [, j]) - Fonction similaire à la chaîne string.sub de Lua. Renvoie la sous-chaîne de s qui commence à i et continue jusqu’à j.
  • ns.tcp.stream.match (data, pattern, [, init]) - Fonction similaire à string.match de Lua. Recherche la première correspondance du modèle dans la chaîne s.

• ns.send (processing_ctxt, event_name, event_data) - Fonction générique permettant d’envoyer des événements vers un contexte de traitement. Les données d’événements sont une table Lua qui peut contenir n’importe quel contenu. Le contenu dépend de l’événement. Une fois l’API ns.send () appelée, la référence de données n’est plus utilisable. Toute tentative d’utilisation entraîne une erreur.

• ns.pipe (src_ctxt, dest_ctxt) - À l’aide d’un appel à l’API pipe (), le code d’extension peut connecter le contexte source à un contexte de destination. Après un appel à pipe, tous les événements envoyés du contexte source au module suivant du pipeline vont directement au contexte de destination. Cette API est généralement utilisée par le module qui fait l’appel pipe (), pour se retirer du pipeline.

• ns.inet — Bibliothèque d’adresses Internet.

  • ns.inet.apply_mask (address_str, mask_str) - renvoie la chaîne d’adresse après l’application de la chaîne de masque.
  • ns.inet.aton (address_str) - Renvoie la valeur numérique de l’adresse sous forme de chaîne d’octets dans l’ordre du réseau (4 octets pour IPv4 et 16 pour IPv6).
  • ns.inet.ntoa (byte_str) - Convertit une valeur d’octet numérique en chaîne d’octets en chaîne d’adresse.
  • ns.inet.ntohs (number) - Convertit l’ordre des octets du réseau donné en ordre des octets de l’hôte. Si l’entrée est supérieure à 2^16 - 1, génère une erreur.
  • ns.inet.htons (number) - Convertit l’ordre des octets de l’hôte donné en ordre des octets du réseau. Si l’entrée est supérieure à 2^16 - 1, génère une erreur.
  • ns.inet.ntohl (number)  : convertit l’ordre des octets du réseau donné en ordre des octets de l’hôte. Si l’entrée est supérieure à 2^32 - 1, lance une erreur.
  • ns.inet.htonl (number)  : convertit l’ordre des octets de l’hôte donné en ordre des octets du réseau. Si l’entrée est supérieure à 2^32 - 1, lance une erreur.
  • ns.inet.subnet (address_str, subnet_value) — Renvoie la chaîne d’adresse du sous-réseau après l’application du sous-réseau donné.