DataScript: Functions

Introduction

DataScripts are comprised of any number of function or method calls which can be used to inspect and act on traffic flowing through a virtual service. DataScript’s functions are exposed via Lua libraries and grouped into modules: string, vs, http, pool, ssl and crypto. Other Lua libraries may also be used, following the documentation from lua.org. The following functions are available.

DataScript

String Description
string.beginswith( source, target ) Search for string in beginning of a string
string.contains( source, target ) Search contains a string in another string
string.endswith( source, target ) Search for string at the end of a string
string.len( source ) Returns number of characters in string
string.lower( source ) Change a string to lower case
string.split( source_string, delimiter ) Parses a string into substrings
string.sub( source, begin, [end] ) Extract a sub-string from a string
string.upper( source ) Change a string to upper case
L4
avi.l4.read(num_bytes) Read the payload from the socket buffer. This function is available starting with 18.2.5.
avi.l4.collect(num_bytes) Gather the num_bytes before subjecting the payload to the DataScript. This function is available starting with 18.2.5.
VS
avi.vs.analytics.counter(metric_name, [operation], [value]) Creates and manipulates a counter-type metric. Refer to User-defined Metrics.
avi.vs.analytics.gauge(metric_name, [operation], [value]) Creates and manipulates a gauge-type metric. Refer to User-defined Metrics.
avi.vs.analytics.get_metric(metric_name, metric_type) Return the user-defined metric value if one with the given name and given type exists. Refer to User-defined Metrics.
avi.vs.client_ip( ) Returns the client IP address
avi.vs.client_port( ) Returns the client source port
avi.vs.close_conn([reset]) Close the current TCP/UDP connection
avi.vs.ip( ) Returns IP address of the VS
avi.vs.log( ) Write a custom log to VS > client logs
avi.vs.name( ) Returns the name of the VS
avi.vs.port( ) Returns the VS port of the connection
avi.vs.persist(key, [lifetime], [pool]) Creates peristence entry using the key used after load balancing traffic
avi.vs.rate_limit( type, string_to_limit, [defer_action=False] ) Rate limits entities of various kinds.
avi.vs.reqvar.* Set a global variable usable across events
avi.vs.table_insert( [table_name,] key, value [, lifetime] ) Store custom data in a time based table
avi.vs.table_lookup( [table_name,] key [, lifetime_exten] ) Lookup data in a table
avi.vs.table_refresh( [table_name,] key [, lifetime_exten] ) Update the expire time for a table entry
avi.vs.table_remove( [table_name,] key ) Remove data from a table
avi.vs.get_open_conns() Returns the total number of open connections per service engine attached to the current virtual service
avi.vs.se_count() Returns the total number of service engines attached to the current virtual service
HTTP
avi.http.add_cookie( table ) Insert a new cookie
avi.http.add_header( name, value ) Insert a new header and value
avi.http.close_conn( [reset] ) Close or reset a TCP connection
avi.http.cookie_exists( name, [context] ) Validate if a cookie already exists
avi.http.disable() Upgrade (disable) HTTP processing for the current connection, which will subsequently be treated as layer 4 TCP
avi.http.get_cookie( name [, context] ) Return the values of a cookie
avi.http.get_cookie_names ( [context] ) Return the names of cookies
avi.http.get_header( [[name] [context]] ) Return header names or their values
avi.http.get_host_tokens( [start [, end]] ) Return a subsection of the host
avi.http.get_path( [false] ) Returns the URI's path /path.index.htm
avi.http.get_path_tokens( [start [, end]] ) Return a subsection of the path
avi.http.get_query( [arg_name | avi.QUERY_TABLE] [, decode] ) Returns the URI's query ?a=1&b=2
avi.http.get_req_body([size_in_kb]) Returns part or all of the client request body.
avi.http.get_request_id() Returns the request ID.
avi.http.get_reqvar() Gets (reads) data stored in a variable via the avi.http.set() function.
avi.http.get_response_body(size [, offset]) Gets (reads) a specified number of kilobytes from the buffered response body starting at the specified kilobyte offset.
avi.http.get_uri( [false] ) Returns the URI (path plus query)
avi.http.get_userid( ) Returns the user ID for the session
avi.http.hostname( ) Return the hostname requested by client
avi.http.internal_status() Returns HTTP status as a string
avi.http.method( ) Return the client's request method
avi.http.protocol( ) Returns the session protocol, http or https
avi.http.redirect( uri [,status] ) Redirect a request
avi.http.remove_cookie( name1, [name2, ...] ) Remove an existing cookie
avi.http.remove_header( name ) Remove all instances of a header
avi.http.replace_cookie( table ) Replace an existing cookies values
avi.http.replace_header( name, value ) Replace an existing header's value
avi.http.response( status, [headers, [body]] ) Send a defined HTTP response page
avi.http.saml_session_decrypt( ) Returns a string of the decrypted SAML session cookie if it exists; else nil
avi.http.scheme( ) Returns http:// or https://
avi.http.secure( ) Returns on for https, nil for http
avi.http.set_path( new_uri ) Modify the path of a request
avi.http.set_query( integer | string | table ) Modify the query of a request
avi.http.set_reqvar() Sets (write) arbitrary data from an HTTP request event into a variable. These variables have scope across the HTTP_REQ and HTTP_RESP events.
avi.http.set_response_body_buffer_size(size) Sets the maximum response body to be buffered.
avi.http.set_server_timeout( time ) Set a custom timeout value for a particular request.
avi.http.set_uri( new_uri ) Change the URI
avi.http.set_userid( ) Sets the user ID for the session
avi.http.status( ) Returns status code to be sent to client
avi.http.update_cookie() Modify the existing cookie attributes value in the HTTP response.
avi.http.disable_auth Disables the client authentication
Pool
avi.pool.get_server_status( pool, server, port ) Returns the up/down status of the server
avi.pool.get_servers( pool ) Returns up and total server count
avi.pool.select( pool [, server [, port]] ) Pick a specific pool
avi.pool.server_ip( ) Returns the IP of the selected server
avi.pool.get_server_info() Returns the IP address and port of the server
avi.poolgroup.select( pool ) Pick a specific pool group
avi.pool.chash( string ) Sets the string value that the consistent hash load-balancing algorithm hashes on to choose a server within the selected pool
Groups
avi.ipgroup.contains( ipgroup, ip-address ) Compare an IP address against IPs within an IP Group
avi.stringgroup.beginswith( stringgroup, string ) Compare a string against a list of strings within a string group
avi.stringgroup.contains( stringgroup, string ) Compare a string against a list of strings within a string group
avi.stringgroup.equals( stringgroup, string ) Compare a string against a list of strings within a string group
avi.stringgroup.endswith( stringgroup, string ) Compare a string against a list of strings within a string group
SSL
avi.ssl.cipher( [true] ) Return the SSL ciphers and settings
avi.ssl.client_cert( [ [avi.CLIENT_CERT] [, avi.CLIENT_CERT_FINGERPRINT] [, avi.CLIENT_CERT_SUBJECT] [, avi.CLIENT_CERT_ISSUER] [, avi.CLIENT_CERT_SERIAL]] ) Returns the client's certificate, or part of it
avi.ssl.protocol( ) Return the SSL version
avi.ssl.server_name( ) Return SNI name field
Crypto
avi.crypto.decrypt( ciphertext, key [, iv [, algo]] ) Decrypt content
avi.crypto.encrypt( plaintext, key [, iv [, algo]] ) Encrypt content
Utilities
avi.utils.base64_decode( string ) Decode content
avi.utils.base64_encode( string ) Encode content
avi.utils.get_geo_from_ip (ip_string, [flag]) Used to extract geolocation database information
avi.utils.ip.addr (ipaddr, netmask) Accepts an IP address and netmask and returns the network address
avi.utils.murmur_hash ( string )
avi.utils.sha1_hash ( string )
avi.utils.md5_hash ( string )
Hash content
avi.utils.rand_bytes( num_bytes ) Generate cryptographically secure random bytes

Note: DataScripts can hash arbitrary data using one of three functions supporting their corresponding named hashing methods: MurmurHash, SHA-1, and MD5.
For more information, refer to DataScript: avi.utils.murmur_hash (), avi.utils.sha1_hash (), avi.utils.md5_hash ().

Starting with Avi Vantage version 21.1, SSL DataScript Events and APIS are introduced to add SSL Handshake level events to read/write parameters to control the SSL handshake and change attributes like SSL profile, certificates, PKI settings, renegotiate, and more. To know the events and the associated events refer to the SSL DataScript Events and APIs article.

Document Revision History

Date Change Summary
December 07, 2020 Updated the content for avi.http.disable_auth(Version 20.1.3)