Inline Validation with Orchestrator |
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"
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 |
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.
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.