Referencia de API de extensiones de NetScaler

Los comportamientos son una formalización de los patrones programables comunes que están disponibles en un dispositivo NetScaler. 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, el comportamiento de un 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 clientes TCP. La devolución de llamada utiliza dos argumentos:

• ctxt: contexto de procesamiento de clientes TCP
• cargaútil — carga útil del evento
  • payload.data: datos TCP recibidos, disponibles como un flujo 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 utiliza dos argumentos:

• ctxt: contexto de procesamiento del servidor TCP
• cargaútil — carga útil del evento
  • payload.data: datos tcp recibidos, disponibles como un flujo de bytes

Contexto de cliente TCP

El contexto que se pasa a las llamadas de eventos del cliente TCP:

• ctxt.output : el siguiente contexto de procesamiento de la canalización. Los gestores de devolución de llamadas de extensiones pueden enviar datos del tipo ns.tcp.stream a ctxt.output mediante los eventos DATA, que significa mensaje parcial, o EOM, que significa mensaje de fin de protocolo. El evento EOM puede o no incluir datos TCP. Se puede enviar un evento EOM con datos TCP sin un evento DATA anterior para enviar los datos de un mensaje de protocolo completo y marcar el final del mensaje. La decisión de equilibrio de carga la toma, posteriormente, el servidor virtual de equilibrio de carga, sobre la base de los primeros datos recibidos. Tras recibir el mensaje de EOM, se toma una nueva decisión de equilibrio de carga. 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 de EOM se envían a la misma conexión de servidor seleccionada por la decisión de equilibrio de carga del primer evento DATA de la secuencia.

• ctxt.input : el contexto de procesamiento anterior en la canalización de donde provienen los datos del flujo TCP.

• ctxt:hold (data) : función para almacenar los datos para su procesamiento futuro. Cuando se suspende la llamada con datos, los datos se almacenan en el contexto. Posteriormente, cuando se reciben más datos en el mismo contexto, los datos recién recibidos se añaden a los datos almacenados anteriormente y el flujo de datos combinado se pasa a la función de devolución de llamada on_data. Tras solicitar una suspensión, la referencia de datos ya no se puede utilizar y muestra un error en cualquier uso.

• ctxt.vserver: el contexto del servidor virtual.

• ctxt.client : contexto de procesamiento de la conexión del cliente. Este contexto de procesamiento se puede utilizar para enviar datos al cliente y obtener información relacionada con la conexión, como la dirección IP y los 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 se puede utilizar y muestra un error en cualquier uso.

Contexto del servidor TCP

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

• ctxt.output : el siguiente contexto de procesamiento de la canalización. Los gestores de devolución de llamadas de extensiones pueden enviar datos del tipo ns.tcp.stream a ctxt.output mediante los eventos DATA, que significa mensaje parcial, o EOM, que significa mensaje de fin de protocolo.

• ctxt.input : el contexto de procesamiento anterior en la canalización de donde provienen los datos del flujo TCP.

• ctxt:hold (data) : función para almacenar los datos para su procesamiento futuro. Cuando se suspende la llamada con datos, los datos se almacenan en el contexto. Posteriormente, cuando se reciben más datos en el mismo contexto, los datos recién recibidos se añaden a los datos almacenados anteriormente y el flujo de datos combinado se pasa a la función de devolución de llamada on_data. Tras solicitar una suspensión, la referencia de datos ya no se puede utilizar y muestra un error en cualquier uso.

• ctxt.vserver: el contexto del servidor virtual.

• ctxt.server : contexto de procesamiento de conexiones al servidor. Este contexto de procesamiento se puede utilizar para enviar datos al servidor y obtener información relacionada con la conexión, como la dirección IP y los 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 únicamente en el contexto del servidor. Esta API solo se puede usar si se usa un evento EOM (en la API ns.send ()) para enviar los datos en el contexto del cliente. De lo contrario, el dispositivo ADC generará 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. Tras 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 al servidor. Si no se usa esta API, la conexión al servidor solo se puede usar para el cliente para el que se abrió. Además, si se selecciona el mismo servidor para tomar otra decisión de equilibrio de carga para ese cliente, se utilizará la misma conexión de servidor para enviar los datos del cliente. Tras utilizar esta API, la conexión del servidor deja de estar vinculada a la conexión del cliente para la que se abrió y se puede volver a utilizar para tomar una nueva decisión de equilibrio de carga para cualquier otra conexión de cliente. Después de llamar a esta API, el contexto del servidor ya no se puede utilizar y arroja un error en cualquier uso.

  Nota: Esta API está disponible en la versión 49.xx y versiones posteriores de NetScaler 12.1.

• ctxt:close () — Cierra la conexión al servidor enviando FIN al servidor. Tras llamar a esta API, el contexto de procesamiento del cliente ya no se puede utilizar y muestra un error en cualquier uso.

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

Contexto de vserver

El contexto del servidor virtual del usuario disponible a través de los contextos pasados a las 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_drop — Número de solicitudes/respuestas no válidas descartadas por este servidor virtual.
• vserver.params: los parámetros configurados para el servidor virtual del usuario. Los parámetros permiten configurar 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 del cliente

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

• client.ssl — contexto SSL
• client.tcp — contexto TCP
• client.is_ssl — Cierto si la conexión del cliente está basada en SSL

Contexto de conexión al servidor

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

• server.ssl — contexto SSL
• server.tcp — contexto TCP
• server.is_ssl — Cierto si la conexión al servidor está basada en SSL

Contexto TCP

El contexto TCP funciona en el protocolo TCP.

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

Contexto IP

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

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

Nota: Esta API está disponible en la versión 51.xx y versiones posteriores de NetScaler 12.1.

Contexto de direcciones IP

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

• <address>.to_s - La cadena de direcciones en la notación ASCII correspondiente.
• <address>.to_n - El valor numérico de la dirección como 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 direcciones 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 comprendido entre 0 y 128.
• <address>:apply_mask(<mask string>) - Devuelve la cadena de dirección después de aplicar la cadena de máscara. La API valida la versión del argumento y comprueba los errores de forma adecuada.
• address>:eq(<address string>) - Devuelve verdadero o falso en función de si el argumento es equivalente al objeto de dirección. La API valida la versión de los argumentos.

Nota: Esta API está disponible en la versión 51.xx y versiones posteriores de NetScaler 12.1.

Contexto SSL

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

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

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

Contexto del 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 a partir de la cual el certificado deja de ser válido.
• cert.days_to_expire : 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 distintivo (DN) del emisor en el certificado como lista de nombres y valores. 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=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

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

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

  • auth_keyid.issuer_name: nombre distintivo del emisor en el certificado como lista de nombres y valores. El signo igual (“=”) es el delimitador del nombre y el valor, y la barra oblicua (“/”) es el delimitador que separa los pares nombre-valor.

  El siguiente es 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 en forma de bloque
  • auth_keyid.cert_serialnumber: campo SerialNumber del identificador de clave de autoridad en forma de bloque.
• 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 es SSL o hay un error en el certificado, se mostrará una cadena vacía.
• cert.signature_algorithm: nombre del algoritmo criptográfico utilizado por la CA para firmar este certificado.
• cert.subject_keyid: identificador clave del asunto del certificado de cliente. Si no hay ningún Subject KeyID, se obtiene un objeto de texto de longitud cero.
• cert.subject : nombre distintivo del sujeto como nombre-valor. Un signo igual (“=”) separa los nombres de los valores y una barra oblicua (“/”) delimita los pares nombre-valor.

El siguiente es un ejemplo: /C =US/o=mycompany/ou=www.mycompany.com/cn=www.mycompany.com/emailAddress= myuserid@mycompany.com

Bibliotecas de NetScaler

• ns.tcp.stream : biblioteca tipo cadena para manejar datos TCP como un flujo de bytes. El tamaño máximo de los datos de flujo TCP en los que pueden funcionar estas API es de 128 KB. Las funciones de la biblioteca ns.tcp.stream también se pueden invocar con 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 a la cadena string.len de Lua
  • ns.tcp.stream.find (data, pattern [, init]) : función similar a la cadena string.find de Lua. Además, también hace una coincidencia parcial al final de los datos. Tras una coincidencia parcial, se devuelve el índice inicial y el índice final pasa a ser cero.
  • ns.tcp.stream.split (data, length) : divide los datos en dos fragmentos, el primero tiene la longitud especificada. Tras una división correcta, los datos originales ya no se pueden utilizar como flujo de datos TCP. Cualquier intento de usarlo de esa manera provoca un error.
  • ns.tcp.stream.byte (data [, i [, j]]) : función similar a 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 string.match 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 de 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 se puede utilizar. 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. Tras una llamada a canalización, todos los eventos que se envían desde el contexto de origen al siguiente módulo de la canalización van directamente al contexto de destino. El módulo que realiza la llamada pipe () suele utilizar esta API para eliminarse de la canalización.

• ns.inet : biblioteca de 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 un valor de byte numérico como una cadena de bytes en una cadena de direcciones.
  • ns.inet.ntohs (número) : convierte el orden de bytes de la red dado en el orden de bytes del host. Si la entrada es mayor que 2^16 - 1, arroja un error.
  • ns.inet.htons (número) : convierte el orden de bytes del host dado en el orden de bytes de la red. Si la entrada es mayor que 2^16 - 1, arroja un error.
  • ns.inet.ntohl (number) : convierte el orden de bytes de la red dado en el orden de bytes del host. Si la entrada es mayor que 2^32 - 1, arroja un error.
  • ns.inet.htonl (number) : convierte el orden de bytes del host dado en el orden de bytes de la red. Si la entrada es mayor que 2^32 - 1, arroja un error.
  • ns.inet.subnet (address_str, subnet_value): devuelve la cadena de dirección de la subred después de aplicar la subred determinada .