Product Documentation

NetScaler Extensions API Reference

Aug 16, 2017

Behaviors are a formalization of common programmable patterns that are available on a NetScaler appliance. For example, a TCP virtual server supports a TCP client behavior and a TCP server behavior. A behavior is a pre-defined set of callback functions. You can implement behaviors by providing callback functions. For example, a TCP client behavior can consist of the on_data function, which processes the TCP data stream.

Behavior Details

TCP Client Behavior

on_data  - function callback for TCP client data events. The callback takes two arguments:

  • ctxt - TCP client processing context
  • payload – event payload
    • payload.data - TCP data received, available as a stream of bytes    

TCP Server Behavior

on_data - function callback for TCP server data events, the callback takes two arguments:

  • ctxt - TCP server processing context
  • payload – event payload
    • payload.data - tcp data received, available as a stream of bytes    

TCP Client Context

The context that is passed to the TCP client event callbacks:

  • ctxt.output - The next processing context in the pipeline. Extension call back handlers can send ns.tcp.stream type data to ctxt.output using the events DATA, which means partial message or EOM which means end of protocol message. The EOM event may or may not have TCP data with it. An EOM event with TCP data can be sent without a preceding DATA event to send a whole protocol message data and mark the end of message. The load balancing decision is made, downstream by the load balancing virtual server, on the first data received. A new load balancing decision is made after the receipt of the EOM message. So, to stream protocol message data, send multiple DATA events with the last event as EOM. All the contiguous DATA events and the following EOM events are sent to the same server connection selected by the load balancing decision on the first DATA event in the sequence.    
  • ctxt.input - The previous processing context in the pipeline where the TCP stream data is coming from.
  • ctxt.lb - The default load balancing virtual server context responsible for the load balancing. It can be used as the destination context for ns.send calls to send the TCP stream data directly to the load balancing virtual server context. For portability and forward compatibility, ctxt.output should be passed as the destination context to ns.send.
  • ctxt:hold(data) - Function to store the data for future processing. On calling hold with data, the data is stored in the context. Subsequently, when more data is received on the same context, newly received data is appended to the previously stored data and the combined data stream is then passed to the on_data callback function. After calling a hold, the data reference is no longer usable and gives error on any usage.
  • ctxt.vserver - The virtual server context.

TCP Server Context

The context that is passed to the TCP server event callbacks:

  • ctxt.output – The next processing context in the pipeline. Extension call back handlers can send ns.tcp.stream type data to ctxt.output using the events DATA, which means partial message or EOM which means end of protocol message.
  • ctxt.input - The previous processing context in the pipeline where the TCP stream data is coming from.
  • ctxt.to_client - the client connection. It can be used as the destination context for ns.send calls to send the TCP stream data directly to the client connection context. For portability and forward compatibility, ctxt.output should be passed as the destination context to ns.send.
  • ctxt:hold(data) - Function to store the data for future processing. On calling hold with data, the data is stored in the context. Subsequently, when more data is received on the same context, newly received data is appended to the previously stored data and the combined data stream is then passed to the on_data callback function. After calling a hold, the data reference is no longer usable and gives error on any usage.
  • ctxt.vserver - The virtual server context.

Vserver Context

The user virtual server context available through the contexts passed to callbacks:

  • vserver:counter_increment(counter_name) - Increments the value of a virtual server counter passed as argument. Currently the following built-in counters are supported.
    • - invalid_messages – Number of invalid requests/responses on this virtual server.
    • - invalid_messages_dropped – Number of invalid requests/responses dropped by this virtual server.
  • vserver.params - The configured parameters for the user virtual server. Parameters provide configurability of extensions. The extension code can access parameters that are specified in the CLI to add a user virtual server.    

NetScaler Libraries

  • ns.tcp.stream - String like library for handling TCP data as a stream of bytes. The maximum size of TCP stream data on which these APIs can work is 128 KB.The ns.tcp.stream library functions can also be called in the usual extension object oriented style of calling. For example, data:len() is the same as ns.tcp.stream.len(data)
    • ns.tcp.stream.len(data) - Returns length of data in bytes, similar to Lua's string.len
    • ns.tcp.stream.find(data, pattern [, init]) - Function similar to Lua's string.find. In addition, it also does partial matching at the end of data. Upon partial match, the start index is returned and the end index becomes nil.
    • ns.tcp.stream.split(data, length) - Splits the data into two chunks, the first chunk is of the specified length. After a successful split the original data is no longer usable as a TCP data stream. Any attempt to use it that way causes an error.
    • ns.tcp.stream.byte(data[, i [, j]]) - Function similar to Lua's string.byte. Returns the internal numerical codes of the characters data[i], data[i+1], ..., data[j].
    • ns.tcp.stream.sub(data, i [, j]) - Function similar to Lua's string.sub. Returns the substring of s that starts at i and continues until j.
    • ns.tcp.stream.match(data, pattern, [, init]) - Function similar to Lua's string.match. Looks for the first match of pattern in string s.
  • ns.send(processing_ctxt, event_name, event_data) - Generic function to send events to a processing context. Event data is a Lua table that can have any content. The contents depend on the event.  After the ns.send() API is called, the data reference is no longer usable. Any attempt to use it causes an error.
  • ns.pipe(src_ctxt, dest_ctxt) - Using a call to pipe() API, extension code can connect source context to a destination context. After a call to pipe, all the events that are sent from source context to the next module in the pipeline go directly to the destination context. This API is typically used by the module that makes the pipe() call, to remove itself from the pipeline.