Referencia de la API de extensiones de Citrix ADC

Los comportamientos son una formalización de patrones programables comunes que están disponibles en un dispositivo Citrix ADC. Por ejemplo, un servidor virtual TCP admite un comportamiento de cliente TCP y un comportamiento de servidor TCP. Un comportamiento es un conjunto predefinido de funciones de devolución de llamada. Puede implementar comportamientos proporcionando funciones de devolución de llamada. Por ejemplo, un comportamiento de cliente TCP puede consistir en la función on_data, que procesa el flujo de datos TCP.

Comportamiento del cliente TCP

on_data: Función de devolución de llamada para eventos de datos de cliente TCP. La devolución de llamada toma dos argumentos:

• ctxt: Contexto de procesamiento de cliente TCP
• carga útil: Carga útil de evento
  • payload.data: Datos TCP recibidos, disponibles como una secuencia de bytes

Comportamiento del servidor TCP

on_data: Función de devolución de llamada para eventos de datos del servidor TCP, la devolución de llamada toma dos argumentos:

• ctxt: Contexto de procesamiento del servidor TCP
• carga útil: Carga útil de evento
  • payload.data: Datos tcp recibidos, disponibles como una secuencia de bytes

Contexto de cliente TCP

El contexto que se pasa a las devoluciones de llamada de evento de cliente TCP:

• ctxt.output: El siguiente contexto de procesamiento en el proceso. Los controladores de devolución de llamada de extensión pueden enviar datos de tipo ns.tcp.stream a ctxt.output mediante los eventos DATA, que significa mensaje parcial o EOM que significa mensaje final del protocolo. El evento EOM puede o no tener datos TCP con él. Un evento EOM con datos TCP se puede enviar sin un evento DATA anterior para enviar un mensaje de protocolo completo y marcar el final del mensaje. La decisión de equilibrio de carga se toma, aguas abajo por el servidor virtual de equilibrio de carga, en los primeros datos recibidos. Una nueva decisión de equilibrio de carga se toma después de la recepción del mensaje EOM. Por lo tanto, para transmitir datos de mensajes de protocolo, envíe varios eventos DATA con el último evento como EOM. Todos los eventos DATA contiguos y los siguientes eventos EOM se envían a la misma conexión de servidor seleccionada por la decisión de equilibrio de carga en el primer evento DATA de la secuencia.

• ctxt.input: El contexto de procesamiento anterior en el proceso de donde provienen los datos de flujo TCP.

• ctxt:hold(data): Función para almacenar los datos para su procesamiento futuro. Al llamar a la retención con datos, los datos se almacenan en el contexto. Más tarde, cuando se reciben más datos en el mismo contexto, los datos recién recibidos se anexan a los datos almacenados anteriormente y el flujo de datos combinado se pasa a la función de devolución de llamada on_data. Después de llamar a una retención, la referencia de datos ya no es utilizable y da error en cualquier uso.

• ctxt.vserver: El contexto del servidor virtual.

• ctxt.client: Contexto de procesamiento de conexión de cliente. Este contexto de procesamiento se puede utilizar para enviar datos al cliente, y para obtener alguna información relacionada con la conexión, como dirección IP, puertos de origen y destino.

• ctxt:close (): Cierra la conexión del cliente enviando FIN al cliente. Después de llamar a esta API, el contexto de procesamiento del cliente ya no es utilizable y da error en cualquier uso.

Contexto del servidor TCP

El contexto que se pasa a las devoluciones de llamada de eventos del servidor TCP:

• ctxt.output: El siguiente contexto de procesamiento en el proceso. Los controladores de devolución de llamada de extensión pueden enviar datos de tipo ns.tcp.stream a ctxt.output mediante los eventos DATA, que significa mensaje parcial o EOM que significa mensaje final del protocolo.

• ctxt.input: El contexto de procesamiento anterior en el proceso de donde provienen los datos de flujo TCP.

• ctxt:hold(data): Función para almacenar los datos para su procesamiento futuro. Al llamar a la retención con datos, los datos se almacenan en el contexto. Más tarde, cuando se reciben más datos en el mismo contexto, los datos recién recibidos se anexan a los datos almacenados anteriormente y el flujo de datos combinado se pasa a la función de devolución de llamada on_data. Después de llamar a una retención, la referencia de datos ya no es utilizable y da error en cualquier uso.

• ctxt.vserver: El contexto del servidor virtual.

• ctxt.server: Contexto de procesamiento de conexión de servidor. Este contexto de procesamiento se puede utilizar para enviar datos al servidor y para obtener información relacionada con la conexión, como dirección IP, puertos de origen y destino.

• ctxt:reuse_server_connection () : Esta API se utiliza para permitir que la conexión del servidor se reutilice para otras conexiones de cliente solo en el contexto del servidor. Esta API solo se puede utilizar si se utiliza un evento EOM (en la API ns.send ()) para enviar los datos en el contexto del cliente. De lo contrario, el dispositivo ADC genera un error.

  Para permitir que otros clientes reutilicen una conexión de servidor, se debe llamar a esta API al final de cada mensaje de respuesta. Después de llamar a esta API, si se reciben más datos en esta conexión de servidor, se trata como un error y se cierra la conexión del servidor. Si no se utiliza esta API, la conexión del servidor solo se puede utilizar para el cliente para el que se abrió. Además, si se selecciona el mismo servidor para otra decisión de equilibrio de carga para ese cliente, se utiliza la misma conexión de servidor para enviar los datos del cliente. Después de utilizar esta API, la conexión del servidor deja de vincularse a la conexión del cliente para la que se abrió y se puede volver a utilizar para una nueva decisión de equilibrio de carga para cualquier otra conexión del cliente. Después de llamar a esta API, el contexto del servidor ya no es utilizable y arroja un error en cualquier uso.

  Nota: Esta API está disponible en Citrix ADC 12.1, compilación 49.xx y versiones posteriores.

• ctxt:close (): Cierra la conexión del servidor enviando FIN al servidor. Después de llamar a esta API, el contexto de procesamiento del cliente ya no es utilizable y muestra un error en cualquier uso.

  Nota: Esta API está disponible en Citrix ADC 12.1, compilación 50.xx y versiones posteriores.

Contexto de servidor virtual

El contexto del servidor virtual de usuario disponible a través de los contextos pasados a devoluciones de llamada:

• vserver:counter_increment (counter_name): Incrementa el valor de un contador de servidor virtual pasado como argumento. Actualmente se admiten los siguientes contadores integrados.
  • - invalid_messages: Número de solicitudes/respuestas no válidas en este servidor virtual.
  • - invalid_messages_Dropped: Número de solicitudes o respuestas no válidas descartadas por este servidor virtual.
• vserver.params: Los parámetros configurados para el servidor virtual del usuario. Los parámetros proporcionan la configurabilidad de las extensiones. El código de extensión puede acceder a los parámetros especificados en la CLI para agregar un servidor virtual de usuario.

Contexto de conexión de cliente

Contexto de procesamiento de conexión de cliente para obtener información relacionada con la conexión.

• client.ssl: Contexto SSL
• client.tcp: Contexto TCP
• client.is_ssl: True si la conexión del cliente está basada en SSL

Contexto de conexión de servidor

Contexto de procesamiento de conexión del servidor para obtener información relacionada con la conexión.

• server.ssl: Contexto SSL
• server.tcp: Contexto TCP
• server.is_ssl: True si la conexión del servidor está basada en SSL

Contexto TCP

El contexto TCP opera en el protocolo TCP.

• tcp.srcport: Puerto de origen como número
• tcp.dstport: Puerto de destino como un número

Contexto de IP

El contexto IP funciona con datos de protocolo IP o IPv6.

• ip.src: Contexto de dirección IP de origen.
• ip.dst: Contexto de dirección IP de destino.

Nota: Esta API está disponible en Citrix ADC 12.1, compilación 51.xx y versiones posteriores.

Contexto de dirección IP

El contexto de la dirección IP funciona con datos de direcciones IP o IPv6.

• <address>.to_s: La cadena de dirección en la notación ASCII apropiada.
• <address>.to_n: El valor numérico de la dirección como una cadena de bytes en orden de red (4 bytes para IPv4 y 16 bytes para IPv6).
• <address>.version: Devuelve 4 para IPv4 y 6 para IPv6.
• <address>:subnet(<prefix value>): Devuelve la cadena de dirección de subred después de aplicar el número de prefijo.
  • Para la dirección IPv4, el valor debe estar entre 0 y 32
  • Para la dirección IPv6, el valor debe estar entre 0 y 128.
• <address>:apply_mask(<mask string>): Devuelve la cadena de dirección después de aplicar la cadena de máscara. API valida la versión del argumento y realiza la comprobación de errores adecuada.
• address>:eq(<address string>): Devuelve verdadero o falso basado en si el argumento es equivalente al objeto de dirección. API valida la versión de los argumentos.

Nota: Esta API está disponible en Citrix ADC 12.1, compilación 51.xx y versiones posteriores.

Contexto de SSL

El contexto SSL proporciona información relacionada con la conexión SSL frontend.

• ssl.cert: Contexto de certificado SSL. Para la conexión de cliente, proporciona contexto de certificado de cliente y para la conexión de servidor, proporciona contexto de certificado de servidor.

• ssl.version: Un número que representa la versión del protocolo SSL de la transacción actual, de la siguiente manera:

  • - 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: Nombre de cifrado SSL como cadena si se invoca desde una conexión SSL, de lo contrario da cadena NULL.
• ssl.cipher_bits: Número de bits en clave criptográfica.

Contexto de certificado SSL

• cert.version: Número de versión del certificado. Si la conexión no está basada en SSL, devuelve 0.
• cert.valid_not_before: Fecha en formato de cadena antes de la cual el certificado no es válido.
• CERT.VALID_NOT_After: Fecha en formato de cadena después de la cual el certificado ya no es válido.
• Cert.days_to_Expirate: Número de días antes de los cuales el certificado es válido. Devuelve -1 para el certificado caducado.
• Cert.to_PEM: Certificado en formato binario.

• cert.issuer: Nombre distinguido (DN) del emisor en el certificado como una lista nombre-valor. Un signo igual (“=”) es el delimitador para el nombre y el valor, y la barra diagonal (“/”) es el delimitador que separa los pares nombre-valor.

  A continuación se muestra un ejemplo del DN devuelto: /C =us/o=miempresa/ou=www.mycompany.com/cn=www.mycompany.com/emailAddress= myuserid@mycompany.com

• cert.auth_keyid: Extensión del identificador de clave de contexto de autoridad del certificado X.509 V3.

  • auth_keyid.exists: TRUE si el certificado contiene una extensión de identificador de clave de autoridad.

  • auth_keyid.issuer_name: Emisor Distinguido Nombre en el certificado como una lista nombre-valor. Un signo igual (“=”) es el delimitador para el nombre y el valor, y la barra diagonal (“/”) es el delimitador que separa los pares nombre-valor.

  He aquí un ejemplo: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

  • auth_keyid.keyid: Campo KeyIdentifier del identificador de clave de autoridad como un blob
  • auth_keyid.cert_serialnumber: Campo SerialNumber del identificador de clave de autoridad como un blob.
• cert.pk_algorithm: Nombre del algoritmo de clave pública utilizado por el certificado.
• cert.pk_size: Tamaño de la clave pública utilizada en el certificado.
• cert.serialnumber: Número de serie del certificado de cliente. Si se trata de una transacción que no sea SSL o hay un error en el certificado, esto da una cadena vacía.
• cert.signature_algorithm: Nombre del algoritmo criptográfico utilizado por la CA para firmar este certificado.
• cert.subject_keyid: Sujeto KeyID del certificado de cliente. Si no hay Subject KeyID, esto da un objeto de texto de longitud cero.
• cert.subject: Nombre distinguido del sujeto como nombre-valor. Un signo igual (“=”) separa nombres y valores y una barra diagonal (“/”) delimita los pares nombre-valor.

He aquí un ejemplo: /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

Bibliotecas de Citrix ADC

• ns.tcp.stream: Cadena como biblioteca para el manejo de datos TCP como una secuencia de bytes. El tamaño máximo de los datos de flujo TCP en los que pueden trabajar estas API es de 128 KB. Las funciones de biblioteca ns.tcp.stream también se pueden llamar en el estilo habitual de llamada orientado a objetos de extensión. Por ejemplo, data:len () es lo mismo que ns.tcp.stream.len (data)
  • ns.tcp.stream.len (data): Devuelve la longitud de los datos en bytes, similar al string.len de Lua
  • ns.tcp.stream.find (data, pattern [, init])- Función similar a la cadena.find de Lua. Además, también hace una coincidencia parcial al final de los datos. Tras la coincidencia parcial, se devuelve el índice inicial y el índice final se convierte en nulo.
  • ns.tcp.stream.split (data, length): Divide los datos en dos fragmentos, el primer fragmento es de la longitud especificada. Después de una división correcta, los datos originales ya no se pueden utilizar como una secuencia de datos TCP. Cualquier intento de usarlo de esa manera causa un error.
  • ns.tcp.stream.byte (data[, i [, j]])- Función similar al string.byte de Lua. Devuelve los códigos numéricos internos de los caracteres data[i], data[i+1],…, data[j].
  • ns.tcp.stream.sub (data, i [, j])- Función similar a string.sub de Lua. Devuelve la subcadena de s que comienza en i y continúa hasta j.
  • ns.tcp.stream.match (data, pattern,[, init]): Función similar a la cadena de Lua. Busca la primera coincidencia de patrón en la cadena s.

• ns.send (processing_ctxt, event_name, event_data): Función genérica para enviar eventos a un contexto de procesamiento. Los datos de eventos son una tabla Lua que puede tener cualquier contenido. El contenido depende del evento. Después de llamar a la API ns.send (), la referencia de datos ya no es utilizable. Cualquier intento de usarlo provoca un error.

• ns.pipe (src_ctxt, dest_ctxt): Mediante una llamada a la API pipe (), el código de extensión puede conectar el contexto de origen a un contexto de destino. Después de una llamada a proceso, todos los eventos que se envían desde el contexto de origen al siguiente módulo del proceso van directamente al contexto de destino. Esta API suele ser utilizada por el módulo que realiza la llamada pipe (), para eliminarse del proceso.

• ns.inet: Biblioteca para direcciones de Internet.

  • ns.inet.apply_mask (address_str, mask_str): Devuelve la cadena de dirección después de aplicar la cadena de máscara.
  • ns.inet.aton (address_str): Devuelve el valor numérico de la dirección como una cadena de bytes en orden de red (4 bytes para IPv4 y 16 para IPv6).
  • ns.inet.ntoa (byte_str): Convierte el valor de byte numérico como una cadena de bytes a la cadena de dirección.
  • ns.inet.ntohs (number): Convertir el orden de bytes de red dado al orden de bytes del host. Si la entrada es mayor que 2^16: 1, entonces arroja un error.
  • ns.inet.htons (number): Convierte el orden de bytes del host dado al orden de bytes de red. Si la entrada es mayor que 2^16: 1, entonces arroja un error.
  • ns.inet.ntohl (number): Convierte el orden de bytes de red dado al orden de bytes del host. Si la entrada es mayor que 2^32: 1, entonces arroja un error.
  • ns.inet.htonl (number): Convierte el orden de bytes del host dado al orden de bytes de red. Si la entrada es mayor que 2^32: 1, entonces arroja un error.
  • ns.inet.subnet (address_str, subnet_value): Devuelve la cadena de dirección de subred después de aplicar una subred dada.