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 <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"] = ""
env_table["client_ip"] = ""
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 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_stat("file_path")

    Used to gather metadata for the single file specified by file_path, where file_path is relative to the docroot, if defined. Metadata output include the following:

    stat_data["exists"] = "true" | "false"
    stat_data["size"] = file_size
    stat_data["blocks"] = file blocks
    stat_data["blocksize"] = block_size
    stat_data["type"] = "Invalid" | "S_IFDIR" | "S_IFREG"  | "S_IFCHR" |"S_IFBLK" | "S_IFIFO" | "S_IFSOCK" | 
                 "S_IFLNK" | "Block stream" | "Custom" | "Unknown"
    stat_data["mode format"] = "Windows format" | "Linux format"
    stat_data["mode"] = filemode (format based on mode format above)
    stat_data["uid"] = uid
    stat_data["gid"] = gid
    stat_data["ctime"] = ctime
    stat_data["mtime"] = mtime
    stat_data["atime"] = atime
  • lua_file_delete("file_path")

    Deletes the single file specified by file_path, where file_path is relative to the docroot, if defined.

  • lua_rename("old_file_path","new_file_path")

    Renames the file specified by old_file_path with the new name specified by new_file_path, both of which are relative to the docroot, if defined.

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:

  • as_log
  • as_err
  • as_dbg1
  • as_dbg2
  • as_dbg3
  • as_dbg4

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