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, ...] ) | 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.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) |