Layer 4 DataScript Functions

This section lists out the Layer 4 DataScript functions available on Avi 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. A pool can be a specific pool name or an expression that evaluates to a valid pool name. 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. 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	The optional `pool` is a specific pool name or an expression that evaluates to a valid pool name. The server parameter (a string) is the IPv4 address of the server, in quotes. 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()