Inline File Validation with Lua Script

For general information about inline file validation, see Overview of Inline File Validation

To use a Lua script for inline file validation, the administrator creates a base-64 encoded Lua action script and sets the path to that script in the GUI or in the <transfer> section of aspera.conf. During the inline validation, ascp automatically generates a request; the parameters for the Lua call are passed to a Lua script defined in aspera.conf.

The parameters for Lua calls are passed to Lua scripts by using the array 'env_table'. The following is an example request body:

env_table["startstop"] = "running"
env_table["xfer_id"] = "AAAA-BBBB"
env_table["session_id"] = "1111-2222"
env_table["host"] = "10.0.258.12"
env_table["client_ip"] = "10.0.125.04"
env_table["user"] = "admin"
env_table["userid"] = 24
env_table["direction"] = "send"
env_table["target_rate_kbps"] = 0
env_table["min_rate_kbps"] = 0
env_table["rate_policy"] = "fair"
env_table["cipher"] = "aes-128"
env_table["cookie"] = "xyz"
env_table["manifest_file"] = "/data/manifests/aspera-transfer-1234.txt"
env_table["file"] = "/data/home/luke/test.mpg"
env_table["size"] = 1000000
env_table["start_byte"] = 0
env_table["bytes_written"] = 0
env_table["tags"] = "tags"
env_table["file_name_encoding"] = "utf8"
env_table["file_csum"] = "a1000abf882"
env_table["file_csum_type"] = "sha2-256"

Lua Request Body Parameters and Values

Field Description Values
"startstop" Sets the type of validation start, stop, or running
"xfer_id" Value used to identify a transfer session String
"session_id" Value used to identify a validation session String
"host" Server hostname or IP address Hostname or IP address
"client_ip" Client IP address IP address
"user" SSH account login name String
"user_id" Value used to identify the user String
"direction" Direction of transfer (send or receive) send or recv
"target_rate_kbps" Target rate (in kbps) for file transfer with ascp Integer
"min_rate_kbps" Minimum rate (in kbps) for file transfer with ascp Integer
"rate_policy" Defines the ascp rate policy. This value is taken from the default configuration in the GUI or aspera.conf, if not defined here. fixed, fair, high, or low
"cipher" The encryption cipher for file data. String; AES128, ANY, or NONE
"cookie" The cookie sent to the client system String
"manifest_file" Path to manifest file, which contains a list of transferred files. The command for this in ascp is --file-manifest-path=file_path Filepath
"file" Path to file being validated Filepath
"size" Allowable file size Integer (up to 64-bit)
"start_byte"   Integer
"bytes_written"   Integer
"tags" The JSON request passes the supplied tag values to ascp, which in turn passes the tags to the validator.  
"file_name_encoding"   String
"file_csum" File checksum String
"file_csum_type" File checksum type md5, sha1, or any

The returned values from Lua can be used to indicate validation success, validation failure, the script error, or to change the file destination:

Status Lua return value
Validation success No value or LRET_OK
Change file destination LRET_REDIRECT_DST followed by a new destination path for the file. This option is only available at file transfer start, returning it at any other state results in an error.
Validation failure LRET_INVALID, optionally followed by a failure description string
Script error LRET_ERROR followed by an error number or error description string

Lua File Interfaces

Three Lua file interfaces allow Lua scripts to reference files: lua_stat, lua_file_delete, and lua_rename.

Lua Logging Interface

You can output simple text strings (format strings are not supported) to the Aspera logs using the ascp log interfaces. For example, to log when the Lua script started, enter the following line in a Lua script:

lua_log("Lua script started")

This produces the following log entry:

xxxxxx LOG lua: Lua script started

The following ascp logging functions are supported:

To use the ascp log functions in your Lua script, replace as with lua.