This section lists out the Layer 4 DataScript functions available on NSX Advanced Load Balancer.

String

Description

avi.l4.read()

Read the payload from the socket buffer.

avi.l4.collect()

Gather the num_bytes before subjecting the payload to the DataScript.

avi.dns.read Lists DNS values.

avi.vs.log()

Log the passed message to the connection log.

avi.vs.close.conn()

Close the current TCP/UDP connection.

avi.vs.client_port()

Returns the client's source port.

avi.vs.client_ip

Returns the client's IP address.

avi.vs.persist()

Load balances the request to the optional provided pool or the pool attached to the virtual service.

avi.pool.get_server_info()

Returns the server's IP address and port.

avi.pool.get_server_ip()

Returns the server's IP address.

avi.poolgroup.select

Selects a pool group for the current request.

Note:

The aforementioned APIs are not supported for IP groups, and string groups. However, the DataScripts are supported for pool groups.

avi.l4.read

Function

avi.l4.read()

Description

The function avi.vs.read has been renamed as avi.l4.read. It reads the payload from the socket buffers and returns a stream of bytes.

This API is a must to read the payload and operate on it.

The number of bytes that can be read cannot exceed 65000. This API can be used in conjunction with avi.l4.collect. The API will display an error if enough bytes are not present in the socket.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

Number of bytes

Returns

Returns the payload after L4 (TCP/UDP) as stream of bytes

Example

payload = avi.l4.read() - Reads all bytes from socket buffer
payload = avi.l4.read(10) - Reads 10 bytes from socket buffer
payload = avi.l4.read(0) - Reads all bytes from socket buffer

avi.l4.collect

Function

avi.l4.collect(num_bytes)

Description

Gathers num_bytes before subjecting the payload to the datascript.

If num_bytes are not gathered before TCP/UDP idle timeouts, the connection would be closed by the idle timers.

This API/DataScript will keep yielding till num_bytes are available.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

Number of bytes

Returns

Number of bytes currently buffered

Example

Buffered = avi.l4.collect(1000)  
Payload = avi.l4.read(200)

avi.dns.read

Function

avi.dns.read( )

Description

Returns DNS VS event types.

Events

  • VS_DATASCRIPT_EVT_DNS_REQUEST
  • VS_DATASCRIPT_EVT_DNS_RESPONSE

Parameter

None

Returns

DNS values in boolean.

Example

ip = avi.dns.read()

avi.vs.log

Function

avi.vs.log()

Description

Logs the message passed to the connection log. This will be shown as ds_log in the connection log API.

The maximum length of the string that can be logged is 256.

This API can be invoked multiple times, resulting in the message being concatenated.

Messages will not be concatenated only during a memory crunch.

By default, all logs are non-significant but can be upgraded by passing a preset value `avi.SIG_ENABLE` as the last argument.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

Accepts an arbitrary number of parameters. Logs may contain any arbitrary combination of string, number, Boolean, and nil values.

Returns

No return value

Example 1

avi.vs.log("hello ", num, " you!")

Output: hello 2 you!

This is generated as a non-significant log.

Example 2

avi.vs.log("hello ", num, " you!", avi.SIG_ENABLE)

Output: "hello 2 you!"

This is generated as a significant log.

avi.vs.client_port

Function

avi.vs.client_port()

Description

Returns the client's source port.

Events

VS_DATASCRIPT_EVT_L4_REQUEST

Parameter

None

Returns

String containing client’s source port

Example

if avi.vs.client_port() == “60000" then
   avi.vs.close_conn()
end

avi.vs.client_ip

Function

avi.vs.client_ip()

Description

Returns the client's IP address.

Events

VS_DATASCRIPT_EVT_L4_REQUEST

Parameter

None

Returns

String containing client’s source IP.

Example

if avi.vs.client_ip() == "10.1.1.1" then
   avi.vs.close_conn()
end

avi.vs.table_insert

Function

avi.vs.table_insert( [table_name,] key, value [, lifetime] )

Description

The table API is used to store and retrieve custom data.The avi.vs.table_insert API stores the value in a key-value store for the key. This key-value store is unique for every virtual service and is mirrored across all SEs hosting the virtual service.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

If the optional table_name is not specified, the key-value pair is stored in a default table for the virtual service. When it is specified, a new table with the custom name will be used.

A virtual service with multiple tables can have the same key name with different values for each table.The key is used to look up the value.The value is the custom data to be stored. The optional lifetime flag must be a positive integer, indicating the length of time in seconds this record should exist.

When the time runs out, the key and value are silently discarded. If the lifetime flag is not specified, the default value of 300 seconds is used. Minimum lifetime supported is 300s.

Returns

Returns the boolean value true if the insertion is a success and false if the insertion is a failure.

Example

if radius_username == “myuser” then
   avi.vs.table_insert(radius_username, “10.2.3.4:1812”, 3600)
end
Note:

Inserting a key that already exists will reset the lifetime of the key. The value associated with the key will remain same and not be overwritten.

avi.vs.table_remove

Function

avi.vs.table_remove( [table_name,] key)

Description

The table API is used to store and retrieve custom data.

The avi.vs.table_remove API removes a specified key/value pair from the data store for the specified key.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

If the optional table_name is not specified, the key-value pair is stored in a default table for the virtual service. When it is specified, a custom table will be searched. The key is used to search for the table entry to be deleted.

Returns

No value returned.

Example

if radius_username == “myuser” then
   avi.vs.table_remove(radius_username)
end

avi.vs.table_lookup

Function

avi.vs.table_lookup( [table_name,] key [, lifetime_exten] )

Description

The table API is used to store and retrieve custom data.

The avi.vs.table_lookup API looks up a key and returns the corresponding value. This key-value store is unique for every virtual service and is mirrored across all service engines hosting the virtual service.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

If the optional table_name is not specified, the key is looked up in the default table for the virtual service.

When it is specified, a custom table will be searched. The key is used to look up the value. The optional lifetime_exten flag must be a positive integer, indicating the length of time, in seconds, that should be added to the current lifetime parameter for the key.

When not specified, the default value of 300 seconds is used. This means that by default, looking up the value of a key will extend the lifetime of a key by an additional 300 seconds.

To lookup the key without impacting the expiration set the lifetime_exten flag to 0.

Returns

Returns the value of the looked up string. If the string is not valid, the value returned is nil.

Example

radius_username = “myuser”
if avi.vs.table_lookup(radius_username) then
   avi.vs.log(“Radius username ”..radius_username)
end

avi.vs.table_refresh

Function

avi.vs.table_refresh( [table_name,] key [, lifetime_exten] )

Description

Refreshes the lifetime of the entry for the key in the key/value store.

Events

VS_DATASCRIPT_EVT_L4_REQUESTVS_DATASCRIPT_EVT_L4_RESPONSE

Parameter

Looks up the key in the default virtual service table unless another table name is specified through the optional table name. The key is used to search for the desired table entry. The optional lifetime_exten, a positive integer, is the value in seconds to extend the entry's lifetime in the key/value store. When it is not specified, the default value of 300 seconds is used to extend the entry's lifetime. The lifetime would now be set to lifetime_exten.

Returns

Returns the boolean value true if the refresh is a success and false if the refresh a failure.

Example

if avi.vs.client_ip() == "10.1.1.1" then
   avi.vs.table_refresh(“my_table”,”my_key”, 3600)
end

avi.pool.get_server_status

Function

avi.pool.get_server_status(pool, server, port)

Description

Determine the status of the server listening at a specified port

Events

VS_DATASCRIPT_EVT_L4_REQUEST

Parameter

All three parameter fields are required.

  1. A pool can be a specific pool name or an expression that evaluates to a valid pool name.

  2. The server flag is the IPv4 address of the server, in quotes. The port flag forwards the connection to a specific service port of the server.

  3. The port must be a number between 0 and 65536 or an expression that evaluates to a valid port number.

Returns

Return value 0 indicates the server is down. Return value 1 indicates the server is up.

Example

if avi.pool.get_server_status("tcp-test-pool", "10.52.44.50", "80") == 0 then
   avi.vs.log(“Server is DOWN”)
end

avi.pool.select

Function

avi.pool.select( [pool [, server [, port]]] )

Description

Selects an optional pool or a specific server and port within a pool for the current request. If no argument is present, default pool will be used.

Events

VS_DATASCRIPT_EVT_L4_REQUEST

Parameter

  1. The optional pool is a specific pool name or an expression that evaluates to a valid pool name.

  2. The server parameter (a string) is the IPv4 address of the server, in quotes.

  3. The port parameter (an integer) forwards the connection to a specific service port of the server. The port must be a number between 0 and 65536, or an expression that evaluates to a valid port number.

Caveats

The pool name, server name or IP, and the server port may be called explicitly, or dynamically determined based on a Lua expression. If the pool name, server, or server port do not exist or are not able to be referenced by the virtual service, an error is generated.

Returns

No value returned

Example 1

Forward the request to an explicit destination.

avi.pool.select("radius",server, 1812)
end
Example 2 Forward the request to the default pool.
avi.pool.select()

avi.pool.get_server_info

Function

avi.pool.get_server_info()

Description

Returns the IP address and port of the server for this request or response

Events

  • VS_DATASCRIPT_EVT_L4_REQUEST

  • VS_DATASCRIPT_EVT_L4_RESPONSE

    Note:

    The get_server_info call in the request could fail if invoked before the LB decision is made.

Parameter

None

Returns

The server's IP address(string) and its port number

Example

ip, port = avi.pool.get_server_info()

avi.pool.get_server_ip

Function

avi.pool.get_server_ip()

Description

Returns the IP address of the server for this request or response

Events

  • VS_DATASCRIPT_EVT_L4_REQUEST

  • VS_DATASCRIPT_EVT_L4_RESPONSE

    Note:

    The get_server_ip call in the request could fail if invoked before the LB decision is made.

Parameter

None

Returns

The server's IP address(string)

Example

ip = avi.pool.get_server_ip()

avi.poolgroup.select

Function

avi.poolgroup.select( poolgroup)

Description

Selects a pool group for the current request. The selection does not take effect if an HTTP request policy was also configured with a switching action to select a pool. The switching action of the HTTP request policy takes precedence over the DataScript's pool group selection.

Events

  • HTTP_REQ

  • VS_DATASCRIPT_EVT_L4_RESPONSE

    Note:

    The get_server_ip call in the request could fail if invoked before the LB decision is made.

Parameter

None

Returns

The server's IP address(string)

Example

ip = avi.pool.get_server_ip()