Référence de l’API des extensions Citrix ADC

Les comportements sont une formalisation des modèles programmables courants disponibles sur une appliance Citrix ADC. 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, un comportement 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 rappel prend deux arguments :

• ctxt - Contexte de traitement 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 callback pour les événements de données du serveur TCP, le callback 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 d’un flux d’octets

Contexte client TCP

Le contexte qui est passé aux rappels d’événement client TCP :

• ctxt.output - Le contexte de traitement suivant dans le pipeline. Les gestionnaires de rappel d’extension peuvent envoyer des données de type ns.tcp.stream à ctxt.output en utilisant les événements DATA, ce qui signifie un message partiel ou EOM (fin du message) qui signifie la fin du message 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 (fin du message). 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 pour stocker les données pour un traitement ultérieur. En appelant hold 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 avoir appelé un blocage, la référence de données n’est plus utilisable et donne une erreur sur toute 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 des informations liées à la connexion comme 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 donne une erreur sur toute utilisation.

Contexte du serveur TCP

Le contexte qui est passé aux rappels d’événement du serveur TCP :

• ctxt.output — Le contexte de traitement suivant dans le pipeline. Les gestionnaires de rappel d’extension peuvent envoyer des données de type ns.tcp.stream à ctxt.output en utilisant les événements DATA, ce qui signifie un message partiel ou EOM (fin du message) qui signifie la fin du message 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 pour stocker les données pour un traitement ultérieur. En appelant hold 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 avoir appelé un blocage, la référence de données n’est plus utilisable et donne une erreur sur toute 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 des informations liées à la connexion comme 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 serveur pour d’autres connexions client dans le contexte serveur uniquement. Cette API ne peut être utilisée que si un événement EOM (fin du message) est utilisé (dans l’API ns.send ()) pour envoyer les données dans le contexte client. Sinon, l’appliance ADC génère une erreur.

  Pour permettre la réutilisation d’une connexion serveur 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 plus de données sont reçues sur cette connexion serveur, ceci est traité comme une erreur et la connexion 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. En outre, si le même serveur est sélectionné pour une autre décision d’équilibrage de charge pour ce client, la même connexion 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 sur toute utilisation.

  Remarque : Cette API est disponible dans Citrix ADC 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 sur toute utilisation.

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

Contexte Vserver

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. Actuellement, les compteurs intégrés suivants sont pris en charge.
  • - invalid_messages — Nombre de demandes/réponses non valides sur ce serveur virtuel.
  • - invalid_messages_chuté — Nombre de demandes/réponses non valides abandonnées par ce serveur virtuel.
• vserver.params - Paramètres configurés pour le serveur virtuel utilisateur. Les paramètres fournissent la configurabilité des extensions. Le code d’extension peut accéder aux paramètres spécifiés dans l’interface de ligne de commande pour ajouter un serveur virtuel utilisateur.

Contexte de connexion 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 — True 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 — True si la connexion au serveur est basée sur SSL

Contexte TCP

Le contexte TCP fonctionne sur le protocole TCP.

• tcp.srcport — Port source sous forme de nombre
• tcp.dstport - Port de destination en tant que nombre

Contexte IP

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

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

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

Contexte d’adresse IP

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

• <address>.to_s - Chaîne d’adresse dans la notation ASCII appropriée.
• <address>.to_n - La valeur numérique des adresses sous forme de chaîne d’octets dans l’ordre du réseau (4 octets pour IPv4 et 16 octets pour IPv6).
• <address>.version - Retourne 4 pour IPv4 et 6 pour IPv6.
• <address>:subnet(<prefix value>) - Retourne la chaîne d’adresse de sous-réseau après avoir appliqué le 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>) - Retourne la chaîne d’adresse après l’application de la chaîne de masque. API valide la version de l’argument et effectue la vérification des erreurs appropriée.
• address>:eq(<address string>) - Retourne true ou false selon que l’argument est équivalent à l’objet address. L’API valide la version des arguments.

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

Contexte SSL

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

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

• ssl.version - Un nombre qui représente la version du protocole SSL de la transaction actuelle, 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 - Nom de chiffrement SSL sous forme de chaîne s’il est invoqué à partir d’une connexion SSL, sinon donne une chaîne NULL.
• ssl.cipher_bits — Nombre de bits dans la clé cryptographique.

Contexte de 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 le certificat expiré.
• Cert.to_PEM — Certificat au format binaire.

• cert.issuer - Nom distinctif (DN) de l’émetteur dans le certificat en tant que liste nom-valeur. Un 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 — Extension de l’identificateur de clé d’autorité du certificat X.509 V3.

  • auth_keyid.exists - TRUE si le certificat contient une extension d’identificateur de clé d’autorité.

  • auth_keyid.issuer_name - Nom unique de l’émetteur dans le certificat en tant que liste nom-valeur. Un 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’Authority Key Identifier en tant que blob
  • auth_keyid.cert_serialnumber - Champ SerialNumber de l’identificateur de clé d’autorité en tant que blob.
• cert.pk_algorithm - Nom de l’algorithme de 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 - Sujet keyID du certificat client. S’il n’y a pas d’ID de clé d’objet, cela donne un objet texte de longueur nulle.
• cert.subject - Nom unique du sujet en tant que nom-valeur. Un signe égal (« = ») sépare les noms et les 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 Citrix ADC

• ns.tcp.stream - bibliothèque de type chaîne pour gérer les données TCP comme un 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 bibliothèque ns.tcp.stream peuvent également être appelées dans le style habituel d’appel orienté objet d’extension. Par exemple, data:len () est identique à ns.tcp.stream.len (data)
  • ns.tcp.stream.len (data) - Retourne la longueur des données en octets, similaire à String.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’index de début est renvoyé et l’index de fin devient nul.
  • ns.tcp.stream.split (data, length) - Fractionne les données en deux morceaux, le premier morceau est 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 façon provoque 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 à string.sub de Lua. Retourne 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 de motif dans la chaîne s.

• ns.send (processing_ctxt, event_name, event_data) - Fonction générique pour envoyer des événements dans un contexte de traitement. Les données d’événement sont une table Lua qui peut avoir 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 de l’utiliser provoque une erreur.

• ns.pipe (src_ctxt, « ctxt ») - En utilisant une API d’appel à pipe (), le code d’extension peut connecter le contexte source à un contexte de destination. Après un appel au canal, tous les événements qui sont envoyés du contexte source au module suivant du pipeline vont directement dans le 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) - Retourne la valeur numérique des adresses 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 la valeur d’octet numérique en tant que chaîne d’octets en chaîne d’adresse.
  • ns.inet.ntohs (number) - Convertit l’ordre d’octets réseau donné en ordre d’octets 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 hôte donné en ordre des octets réseau. Si l’entrée est supérieure à 2^16 - 1, génère une erreur.
  • ns.inet.ntohl (number) - Convertit l’ordre d’octets réseau donné en ordre d’octets hôte. Si l’entrée est supérieure à 2^32 - 1, lance une erreur.
  • ns.inet.htonl (number) - Convertit l’ordre des octets hôte donné en ordre des octets réseau. Si l’entrée est supérieure à 2^32 - 1, lance une erreur.
  • ns.inet.subnet (address_str, subnet_value) — Retourne la chaîne d’adresse de sous-réseau après avoir appliqué un sous-réseau donné.