COS Aspera is a library that enables you to transfer files to your storage instance using the ascp command line utility and ATS transfer technology.
It can do the following:
- Initiate FASP uploads and downloads (transfers) to and from your storage instance
- Monitor transfer progress and other statistics for FASP transfers
- Change the transfer rate and adaptive policy on-the-fly (while a transfer is running)
- Authenticate a transfer
- Cancel a transfer
Background
Each FASP file transfer runs as its own process (ascp), which reports statistics to interested applications through a local port. By default, COS Aspera only manage transfers it initiates. To start a transfer using COS Aspera, create a transfer spec and submit it with the startTransfer API. To receive transfer event notifications, register a callback object derived from ITransferReporter before starting the transfer. With each notification, you receive the current statistics of the session as well as the statistics for the last transferred file, if available
Aspera Events (received via callback)
INIT
Sent after socket is opened.
Fields:
- Type: INIT
- Direction: Direction of transfer (Send | Receive).
- Operation: Indicates a transfer or just a bandwidth measurement (Transfer | BWMeasurement).
- SessionId: Unique identifier for this session.
- UserStr: Application-specified identifier.
- Cookie: Application-specified string.
Example:
- FASPMGR 2
- Type: INIT
- Direction: Send
- Operation: Transfer
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- UserStr: 5492958869869553497
- Cookie: My data
SESSION
Sent after SSH has connected and ascp processes have negotiated.
Fields:
- Type: SESSION
- Adaptive: Transfer policy (Adaptive | Fixed | Trickle).
- Priority: Transfer priority (1: high | 2: regular).
- Cookie: Application-specified string.
- Destination: Path where files will transfer to.
- Direction: Direction of transfer (Send | Receive).
- Encryption: Use encryption (Yes) or not (No).
- Host: Remote server address.
- Operation: Indicates a transfer or just a bandwidth measurement (Transfer | BWMeasurement | Stream).
- Port: UDP port for fasp.
- Rate: Target rate (Kbps|%) (% in case it is non-zero in the context of bw measurement).
- MinRate: Minimum rate (Kbps|%) (% in case it is non-zero in the context of bw measurement).
- Remote: Is this process acting as the server (Yes) or the client (No).
- RateCap: Maximal target rate allowed (enforced by server).
- MinRateCap: Maximal minimum rate allowed (enforced by server).
- PolicyCap: Transfer policy allowed (enforced by server).
- PriorityCap: Transfer priority allowed (enforced by server).
- RateLock: Indicates if changing the target rate is allowed (enforced by server).
- MinRateLock: Indicates if changing the minimum rate is allowed (enforced by server).
- PolicyLock: Indicates if changing the transfer policy(priority) is allowed (enforced by server).
- SessionId: Unique identifier for this session.
- Source: The first source argument.
- Token: Security token.
- User: For authentication.
- UserStr: Application-specified identifier.
- RetryTimeout: Retry timeout in secs (specified with -o RetryTimeout option}.
- FallbackProtocol: Alternate protocol to use in case of fasp failure.
- XferId: Value of xfer_id tag specified by –tags
- XferRetry: Value of xfer_retry tag specified by –tags
- Tags: Metatags in json format specified by –tags
Example:
- FASPMGR 2
- Type: SESSION
- Adaptive: Adaptive
- Cookie: My data
- Destination: C:/Temp
- Direction: Send
- Encryption: No
- Host: 192.168.1.173
- MinRate: 0
- Operation: Transfer
- Priority: 2
- Port: 33001
- Rate: 1500
- Remote: No
- ServiceLevel: 1000000
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- Source: C:/Temp/AsperaConnect-1.1.1.0.exe
- Token: 8499385
- User: Administrator
- UserStr: 5492958869869553497
- RetryTimeout: 60
- FallbackProtocol: http
NOTIFICATION
Sent after path MTU and bandwidth measurement (if any). Also sent when Precalc is enabled.
Fields:
- Type: NOTIFICATION
- Adaptive: Transfer policy (Adaptive | Fixed | Trickle).
- Priority: Transfer priority (1: high | 2: regular).
- BWMeasurement: Measured bandwidth (Kbps), if any
- MinRate: Minimum rate (Kbps).
- PMTU: Path MTU value.
- Rate: Target rate (Kbps).
- SessionId: Unique identifier for this session.
- UserStr: Application-specified identifier.
Example:
- FASPMGR 2
- Type: NOTIFICATION
- Adaptive: Adaptive
- BWMeasurement: 1487
- MinRate: 0
- PMTU: 1492
- Priority: 2
- Rate: 1500
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- UserStr: 5492958869869553497
Sent after calculating job size (if PreCalculateJobSize flag is set)
Fields:
- Type: NOTIFICATION
- Rate: Target rate (Kbps).
- MinRate: Minimum rate (Kbps).
- SessionId: Unique identifier for this session.
- Adaptive: Transfer policy (Adaptive | Fixed | Trickle).
- UserStr: Application-specified identifier.
- PreTransferFiles: # of regular files.
- PreTransferDirs: # of directories.
- PreTransferSpecial: # of special files.
- PreTransferFailed: # of files/directories with errors.
- PreTransferBytes: total job size in bytes.
Example:
- FASPMGR 2
- Type: NOTIFICATION
- Rate: 10000
- MinRate: 0
- SessionId: 15057ecd-0de8-4d4e-83df-758009780c2d
- Adaptive: Fixed
- PreTransferFiles: 1
- PreTransferBytes: 104857600
STATS
Periodic statistics message.
Fields:
- Type: STATS
- Bytescont: Contiguous bytes at destination for this file
- StartByte: Offset in the file where we resumed (0 if not a resume)
- Delay: Last rtt measurement.
- Elapsedusec: Aggregate time elapsed.
- File: File name
- FileBytes: Aggregate written.
- Loss: Aggregate bytes lost.
- SessionId: Unique identifier for this session.
- Size: File size.
- TransferBytes: Aggregate transferred this session.
- UserStr: Application-specified identifier.
- Written: File written.
- StartByte: first byte in a file to be transferred (offset in case of resuming transfer with -k)
- EndByte: last byte in a file to be transferred (meaningful in the context of range transfer)
- FaspFileArgIndex: command line argument index that specified this file (if argument was a directory, many files can have the same FaspFileArgIndex). In persistent mode, argument is ever increasing.
- FaspFileID: hash of FaspFileArgIndex, source file path, and destination file path
Example:
- FASPMGR 2
- Type: STATS
- Bytescont: 0
- StartByte: 0
- Delay: 0
- Elapsedusec: 0
- File: AsperaConnect-1.1.1.0.exe
- FileBytes: 0
- Loss: 0
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- Size: 6162042
- TransferBytes: 0
- UserStr: 5492958869869553497
- Written: 0
- FaspFileArgIndex: 3
- FaspFileID: 52361574-d28b5e4b-83877b86-97fe091a-ebe6703b
STOP
Fields:
- All fields defined for STATS (above)
- FileChecksum: Hexadecimal string of file checksum (if checksum enabled)
- FileChecksumType: Checksum algorithm (md5 | sha1) (if checksum enabled)
Example:
- FASPMGR 2
- Type: STOP
- StartByte: 0
- Delay: 8
- Elapsedusec: 15084185
- File: AsperaConnect-1.1.1.0.exe
- FileBytes: 5736852
- Loss: 0
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- Size: 6162042
- TransferBytes: 5736852
- UserStr: 5492958869869553497
- Written: 6162042
- FaspFileArgIndex: 3
- FaspFileID: 52361574-d28b5e4b-83877b86-97fe091a-ebe6703b
- FileChecksum: 080690692698a1e3dec9924b44b94ed4
- FileChecksumType: md5
SKIP
All fields defined for STOP (above), file data not populated
Example:
- FASPMGR 2
- Type: SKIP
- File: aspera.aspx
- Size: 0
- Loss: 0
- Elapsedusec: 2021190
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- TransferBytes: 0
- FileBytes: 0
- Delay: 0
ARGSTOP
All files associated with a command line source parameter (file path or directory) or a single line entry in a file-list, or a source/destination pair from a file-pair list have been processed
Fields:
- Type: ARGSTOP
- File: source file or directory path
- FaspFileArgIndex: Index associated with this source argument
- UserStr: If specified on ascp command line
- ArgTransfersAttempted: Count of files associated with this argument
- ArgTransfersPassed: Count of files transferred or skipped
- ArgTransfersSkipped: If any of the files in ArgTransfersPassed were skipped, the count of these. This field is omitted if zero.
- ArgTransfersFailed: Count of files that had errors
Example:
- FASPMGR 2
- Type: ARGSTOP
- File: sourcedir
- FaspFileArgIndex: 1
- ArgTransfersStatus: Complete
- ArgTransfersAttempted: 2
- ArgTransfersPassed: 2
DONE
Indicates completion of the session.
Fields:
- Type : DONE
- Delay: Last rtt measurement.
- Elapsedusec: Aggregate time elapsed.
- Loss: Aggregate bytes lost.
- SessionId: Unique identifier for this session.
- FileBytes: Aggregate written.
- ArgScansAttempted: Source arguments handled.
- ArgScansCompleted: Source arguments completed.
- PathScansAttempted: Source paths attempted.
- PathScansFailed: Source paths failed.
- PathScansIrregular: Source paths pointing to irregular files (i.e. char/block devices).
- PathScansExcluded: Source paths excluded due to matching exclude arguments.
- DirScansCompleted: Source directory scans completed.
- FileScansCompleted: Source file scans completed.
- DirCreatesAttempted: Destination directory creates attempted.
- DirCreatesFailed: Destination directory creates failed.
- DirCreatesPassed: Destination directory already exists or successfully created.
- TransfersAttempted: File transfers initiated.
- TransfersFailed: File transfers with errors.
- TransfersPassed: File transfers successfully completed or skipped.
- TransfersSkipped: File transfers skipped (i.e. file already at the destination, overwrite policy violation etc.).
Example:
- FASPMGR 2
- Type: DONE
- Elapsedusec: 24186433
- FileBytes: 25332042
- Loss: 0
- SessionId: 03ef6778-7997-4fe1-9091-4f92ec29a806
- TransferBytes: 25332042
- UserStr: 5492958869869553497
FILEERROR
An error occurred while transferring this file. This message is sent instead of a STOP.
Example:
- FASPMGR 2
- Type: FILEERROR
- Code: 41
- Delay: 0
- Description: Source: Access is denied.
- Elapsedusec: 0
- File: C:/Temp/IE7-WindowsXP-x86-enu.exe
- FileBytes: 0
- Loss: 0
- SessionId: b87c1d8c-c19d-49b3-94b1-421c243c7650
- Size: 0
- TransferBytes: 0
- UserStr: 5492958869869553497
- Written: 0
- FaspFileArgIndex: 2
- FaspFileID: 2a5725ee-c7f5e0c1-2f43ca0a-1aa9b1d8-00b9ec81
ERROR
One or more errors occurred during the session. This message is sent instead of DONE.
Fields:
- Type : ERROR
- Code : FASP error code.
- Description : Error description.
- Delay: Last rtt measurement.
- Elapsedusec: Aggregate time elapsed.
- Loss: Aggregate bytes lost.
- SessionId: Unique identifier for this session.
- FileBytes: Aggregate written.
- ArgScansAttempted: Source arguments handled.
- ArgScansCompleted: Source arguments completed.
- PathScansAttempted: Source paths attempted.
- PathScansFailed: Source paths failed.
- PathScansIrregular: Source paths pointing to irregular files (i.e. char/block devices).
- PathScansExcluded: Source paths excluded due to matching exclude arguments.
- DirScansCompleted: Source directory scans completed.
- FileScansCompleted: Source file scans completed.
- DirCreatesAttempted: Destination directory creates attempted.
- DirCreatesFailed: Destination directory creates failed.
- DirCreatesPassed: Destination directory already exists or successfully created.
- TransfersAttempted: File transfers initiated.
- TransfersFailed: File transfers with errors.
- TransfersPassed: File transfers successfully completed or skipped.
- TransfersSkipped: File transfers skipped (i.e. file already at the destination, overwrite policy violation etc.).
Example:
- FASPMGR 2
- Type: ERROR
- Code: 27
- Description: One or more files failed
- Elapsedusec: 1005642
- Loss: 0
- SessionId: b87c1d8c-c19d-49b3-94b1-421c243c7650
- UserStr: 5492958869869553497
START FILE
Start a file (with optional range) through mgmt (supported in >=2.6).
Fields:
- Type : START
- Source : Source path
- Destination : Destination path
- FileBytes : Optional file range [(low range):(high range)]
Example:
- FASPMGR 2
- Type: START
- Source: /tmp/in
- Destination: /tmp/out
- FileBytes: 10485760:204857600
STOP FILE
Stop a running file through mgmt (supported in >=2.6).
Fields:
- TYPE : STOP
- Source : File path to stop (as reported in a prior mgmt STAT message).
Example:
- FASPMGR 2
- Type: STOP
- Source: /tmp/out
STOP FASP SESSION
Terminate persistent fasp session.
Fields: