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
avi.vs.se() Returns the UUID of the service engine handling the request
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( [parse] ) 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_attribute Removes the existing cookie attributes value in the HTTP response
avi.http.remove_cookie( name1, [name2, ...] ) Removes 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.get_active_server_list( pool ) Returns the IP addresses of all active servers in a pool
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
avi.ssl.set_ssl_profile() This API can be used to change the SSL profile to a different profile based on some factors like Client IP, TLS servername, and more
avi.ssl.set_ssl_certificate This API can be used to change the SSL key and certificate to a different object based on factors like Client IP, TLS servername, and more
avi.ssl.set_pki_profile This API can be used to change the PKI profile of the initial or the renegotiated TLS session based on factors like Client IP, TLS servername, HTTP host or URI etc.
avi.ssl.renegotiate() This API can be used to renegotiate TLS connection with the client after changing the PKI profile, mode and frequency based on factors like Client IP, TLS servername, HTTP host or URI and more
avi.ssl.client_cert_verify_error() This API is used to get the result of the client certificate authentication and CRL checks.
avi.ssl.client_cert_verify_error_string() This API accepts a verify error code and returns an error string associated with that error code
avi.ssl.get_client_cert_verify_mode() This API is used to get the client certificate authentication mode.
avi.ssl.client_cert_verified() This API is used to find out whether if client certificate verification is complete.
avi.ssl.clear_client_cert_verify_error() This API is used to clear SSL client certificate verification error on the TLS connection
avi.ssl.log_client_cert_verify_error() This API is used to log the client certificate authentication failure. The error is added to the application log as a significance.
avi.ssl.remove_session() This API is used to clear SSL session cache entry of the TLS connection
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
avi.utils.get_ip_reputation(ip_addr) Used to check IP reputation of a given IP address

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 ().

Document Revision History

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