aspera-cli 4.21.1 → 4.22.0

data/lib/aspera/transfer/spec.schema.yaml

@@ -0,0 +1,753 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/IBM/aspera-cli/tree/main/lib/aspera/transfer/spec.schema.yaml
+$comment: >-
+  The original file is the YAML file.
+  `x-` fields documented in command_line_builder.rb
+title: Aspera Transfer Specification
+description: Information defining an Aspera transfer.
+type: object
+required:
+- destination_root
+- direction
+- paths
+- remote_host
+- remote_user
+properties:
+  apply_local_docroot:
+    description: Apply local docroot to source paths.
+    x-agents:
+    - direct
+    - transferd
+    x-cli-switch: true
+  cipher:
+    description: In transit encryption algorithms.
+    enum:
+    - none
+    - aes-128
+    - aes-192
+    - aes-256
+    - aes-128-cfb
+    - aes-192-cfb
+    - aes-256-cfb
+    - aes-128-gcm
+    - aes-192-gcm
+    - aes-256-gcm
+    default: none
+    x-cli-option: "-c"
+    x-cli-convert: remove_hyphen
+  content_protection:
+    description: Enable client-side encryption at rest. (CSEAR, content protection)
+    enum:
+    - encrypt
+    - decrypt
+    x-cli-option: "--file-crypt"
+  content_protection_password:
+    description: "Specifies CSEAR password. (content protection)"
+    type: string
+    x-cli-envvar: ASPERA_SCP_FILEPASS
+  cookie:
+    description: Metadata for transfer specified by application
+    type: string
+    x-cli-envvar: ASPERA_SCP_COOKIE
+  create_dir:
+    description: Specifies whether to create new directories.
+    type: boolean
+    x-cli-option: "-d"
+    x-cli-switch: true
+  delete_before_transfer:
+    description: >-
+      Before transfer, delete files that exist at the destination but not at the source.
+
+      The source and destination arguments must be directories that have matching names.
+
+      Objects on the destination that have the same name but different type or size as objects
+      on the source are not deleted.
+    x-cli-switch: true
+  delete_source: # duplicate of remove_after_transfer ?
+    description: Remove SRC files after transfer success
+    type: boolean
+    x-agents:
+    - node
+    - direct
+    - transferd
+    x-cli-option: "--remove-after-transfer"
+    x-cli-switch: true
+  destination_root:
+    description: Destination root directory.
+    x-cli-special: true
+  destination_root_id:
+    description: >-
+      The file ID of the destination root directory.
+
+      Required when using Bearer token auth for the destination node.
+    type: string
+    x-agents:
+    - transferd
+  direction:
+    description: 'Direction of transfer (on client side)'
+    enum:
+    - send
+    - receive
+    x-cli-option: "--mode"
+    x-cli-convert:
+      receive: recv
+      send: send
+  exclude_newer_than:
+    description: >-
+      Exclude files, but not directories, from the transfer if they are newer
+      than the specified number of seconds added to the source computer's epoch.
+
+      e.g. "-86400" for newer than a day back.
+    type: string
+  exclude_older_than:
+    description: >-
+      Exclude files, but not directories, from the transfer if they are older
+      than the specified number of seconds added to the source computer's epoch.
+
+      e.g. "-86400" for older than a day back.
+    type: string
+  fail_bad_filepass:
+    description: Fail on bad file decryption passphrase.
+    type: boolean
+    x-cli-switch: true
+    x-agents:
+    - direct
+    - transferd
+  fasp_port:
+    description: Specifies fasp (UDP) port.
+    type: integer
+    default: 33001
+    x-cli-option: "-O"
+  fasp_proxy:
+    description: Proxy for communications between the remote server and the (local) client. 
+    type: object
+    x-agents:
+    - transferd
+  file_checksum:
+    description: "Enable checksum reporting for transferred files by specifying the hash to use."
+    enum:
+    - sha-512
+    - sha-384
+    - sha-256
+    - sha1
+    - md5
+    - none
+    default: none
+    x-agents:
+    - node
+    - direct
+  http_fallback:
+    description: When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.
+    type:
+    - boolean
+    - string
+    x-cli-option: "-y"
+    x-cli-convert:
+      force: F
+      true: 1
+      false: 0
+  http_fallback_port:
+    description: Specifies http port when no cipher is used
+    type: integer
+    x-cli-option: "-t"
+  https_fallback_port:
+    description: Specifies https port when cipher is used
+    type: integer
+    x-cli-option: "-t"
+  icos:
+    description: Configuration parameters for IBM Cloud Object Storage (ICOS).
+    type: object
+    x-agents:
+    - transferd
+  lock_min_rate:
+    description: "TODO: remove ?"
+    type: boolean
+    x-agents:
+    - connect
+  lock_min_rate_kbps:
+    description: >-
+      If true, lock the minimum transfer rate to the value set for min_rate_kbps.
+
+      If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
+    type: boolean
+    x-agents:
+    - transferd
+    - connect
+  lock_rate_policy:
+    description: If true, lock the rate policy to the default value.
+    type: boolean
+    x-agents:
+    - transferd
+    - connect
+  lock_target_rate:
+    description: "TODO: remove ?"
+    type: boolean
+    x-agents:
+    - connect
+  lock_target_rate_kbps:
+    description: >-
+      If true, lock the target transfer rate to the default value set for target_rate_kbps.
+
+      If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
+    type: boolean
+    x-agents:
+    - transferd
+    - connect
+  min_rate_cap_kbps:
+    description: >-
+      The highest minimum rate that an incoming transfer can request, in kilobits per second.
+
+      Client minimum rate requests that exceed the minimum rate cap are ignored.
+
+      The default value of unlimited applies no cap to the minimum rate. (Default: 0)
+    type: integer
+    x-agents:
+    - connect
+    - transferd
+  move_after_transfer:
+    description: >-
+      The relative path to which the files will be moved after the transfer at the source side.
+      Available as of 3.8.0.
+    type: string
+    x-agents:
+    - direct
+    - node
+    - transferd
+  multi_session:
+    description: >-
+      Use multi-session transfer. max 128.
+
+      Each participant on one host needs an independent UDP (-O) port.
+
+      Large files are split between sessions only when transferring with resume_policy=none.
+    type: integer
+    x-cli-option: "-C"
+    x-cli-special: true
+  multi_session_threshold:
+    description: >-
+      Split files across multiple ascp sessions if their size in bytes is greater than
+      or equal to the specified value.
+
+      (0=no file is split)
+    type: integer
+    x-agents:
+    - direct
+    - node
+    - transferd
+  overwrite:
+    description: >-
+      Overwrite files at the destination with source files of the same name based 
+      on the policy:
+      
+      - always – Always overwrite the file.
+      
+      - never – Never overwrite the file.
+      If the destination contains partial files that are older or the same 
+      as the source files and resume is enabled, the partial files resume transfer.
+      Partial files with checksums or sizes that differ from the source files 
+      are not overwritten.
+      
+      - diff – Overwrite the file if it is different from the source, 
+      depending on the compare method (default is size). 
+      If the destination is object storage, diff has the same effect as always. 
+      If resume is not enabled, partial files are overwritten if they are different 
+      from the source, otherwise they are skipped. 
+      If resume is enabled, only partial files with different sizes or checksums 
+      from the source are overwritten; otherwise, files resume. 
+      
+      - diff+older – Overwrite the file if it is older and different from the source, 
+      depending on the compare method (default is size). 
+      If resume is not enabled, partial files are overwritten if they are older 
+      and different from the source, otherwise they are skipped. 
+      If resume is enabled, only partial files that are different and older than 
+      the source are overwritten, otherwise they are resumed. 
+      
+      - older – Overwrite the file if its timestamp is older than the source timestamp. 
+
+      If you set an overwrite policy of diff or diff+older, difference is determined 
+      by the value set for resume_policy:
+      
+      "none" - the source and destination files are always considered different and 
+      the destination file is always overwritten
+      
+      "attributes" - the source and destination files are compared based on file attributes 
+      
+      "sparse_checksum" - the source and destination files are compared based on sparse checksums, (currently file size)
+      
+      "full_checksum" - the source and destination files are compared based on full checksums 
+    default: diff
+    enum:
+    - never
+    - always
+    - diff
+    - older
+    - diff+older
+  password:
+    description: >-
+      Password for local Windows user when transfer user associated with node api user is not
+      the same as the one running asperanoded.
+
+      Allows impersonating the transfer user and have access to resources (e.g. network shares).
+
+      Windows only, node api only.
+    type: string
+    x-agents:
+    - node
+  paths:
+    description: Array of path to the source (required) and a path to the destination (optional).
+    type: array
+    x-cli-special: true
+  precalculate_job_size:
+    description: Specifies whether to precalculate the job size.
+    type: boolean
+    x-cli-switch: true
+  preserve_access_time:
+    description: >-
+      Preserve the source-file access timestamps at the destination.
+
+      Because source access times are updated by the transfer operation,
+      the timestamp that is preserved is the one just before to the transfer.
+    x-cli-switch: true
+  preserve_acls:
+    description: "Preserve access control lists."
+    enum:
+    - none
+    - native
+    - metafile
+    default: none
+    x-agents:
+    - direct
+    - transferd
+  preserve_creation_time:
+    description: >-
+      (Windows only) Preserve source-file creation timestamps at the destination.
+
+      Only Windows systems retain information about creation time.
+
+      If the destination is not a Windows computer, this option is ignored.
+    x-cli-switch: true
+  preserve_extended_attrs:
+    description: "Preserve the extended attributes."
+    enum:
+    - none
+    - native
+    - metafile
+    default: none
+    x-agents:
+    - transferd
+    x-cli-option: "--preserve-xattrs"
+  preserve_file_owner_gid:
+    description: Preserve the group ID for a file owner
+    type: boolean
+    x-agents:
+    - transferd
+    - direct
+    x-cli-switch: true
+  preserve_file_owner_uid:
+    description: Preserve the user ID for a file owner
+    type: boolean
+    x-agents:
+    - transferd
+    - direct
+    x-cli-switch: true
+  preserve_modification_time:
+    description: >-
+      Set the modification time, the last time a file or directory was modified (written),
+      of a transferred file to the modification of the source file or directory.
+
+      Preserve source-file modification timestamps at the destination.
+    x-cli-switch: true
+  preserve_remote_acls:
+    description: "Preserve remote access control lists."
+    enum:
+    - none
+    - native
+    - metafile
+    default: none
+    x-agents:
+    - transferd
+    - direct
+    x-cli-option: "--remote-preserve-acls"
+  preserve_remote_extended_attrs:
+    description: "Preserve remote extended attributes."
+    enum:
+    - none
+    - native
+    - metafile
+    default: none
+    x-agents:
+    - transferd
+    - direct
+    x-cli-option: "--remote-preserve-xattrs"
+  preserve_source_access_time:
+    description: Preserve the time logged for when the source file was accessed
+    type: boolean
+    x-agents:
+    - transferd
+    - direct
+    x-cli-switch: true
+  preserve_times:
+    description: Preserve file timestamps.
+    type: boolean
+    x-agents:
+    - transferd
+    - node
+    - direct
+    x-cli-option: "-p"
+  rate_policy:
+    description: >-
+      The transfer rate policy to use when sharing bandwidth.
+      Allowable values:
+      
+      - high : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.
+      
+      - fair : (Default) Share bandwidth equally with other traffic.
+      
+      - low : Use only unused bandwidth.
+      
+      - fixed : Transfer at the target rate, regardless of the actual network capacity.
+      Do not share bandwidth.
+      Aspera recommends that you do not use this setting except under special circumstances, 
+      otherwise the destination storage can be damaged. 
+    enum:
+    - low
+    - fair
+    - high
+    - fixed
+    x-cli-option: "--policy"
+  remote_access_key:
+    description: The access key ID of the access key that was used to construct the bearer token that is used to authenticate to the remote node.
+    type: string
+    x-agents:
+    - transferd
+  remote_host:
+    description: IP or fully qualified domain name of the remote server
+    x-cli-option: "--host"
+  remote_password:
+    description: SSH session password
+    x-cli-envvar: ASPERA_SCP_PASS
+  remote_user:
+    description: Remote user. Default value is "xfer" on node or connect.
+    x-cli-option: "--user"
+  remove_after_transfer:
+    description: Remove SRC files after transfer success
+    type: boolean
+    x-agents:
+    - direct
+    - node
+    - transferd
+    x-cli-switch: true
+  remove_empty_directories:
+    description: Specifies whether to remove empty directories.
+    type: boolean
+    x-agents:
+    - direct
+    - node
+    - transferd
+    x-cli-switch: true
+  remove_empty_source_dir:
+    description: Remove empty source subdirectories and remove the source directory itself, if empty.
+    type: boolean
+    x-agents:
+    - transferd
+  remove_empty_source_directory:
+    description: Remove empty source subdirectories and remove the source directory itself, if empty.
+    type: boolean
+    x-agents:
+    - direct
+    x-cli-switch: true
+  remove_skipped:
+    description: Must also have remove_after_transfer set to true, Defaults to false, if true, skipped files will be removed as well.
+    type: boolean
+    x-agents:
+    - direct
+    - connect
+    - node
+    x-cli-switch: true
+  proxy:
+    description: >-
+      Specify the address of the Aspera high-speed proxy server.
+
+      dnat(s)://[user[:password]@]server:port
+
+      Default ports for DNAT and DNATS protocols are 9091 and 9092.
+
+      Password, if specified here, overrides the value of environment variable ASPERA_PROXY_PASS.
+    x-agents:
+    - direct
+    - noded
+  resume_policy:
+    description: >-
+      If a transfer is interrupted or fails to finish,
+      this policy directs the transfer to resume without retransferring the files.
+      Allowable values:
+      
+      - none : Always re-transfer the entire file
+      
+      - attrs : Compare file attributes and resume if they match, and re-transfer if they do not
+      
+      - sparse_csum : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not
+      
+      - full_csum : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not. 
+
+      Note: transferd uses values: attributes, sparse_checksum, full_checksum.
+    default: faspmgr:none;other:sparse_csum
+    enum:
+    - none
+    - attrs
+    - sparse_csum
+    - full_csum
+    x-cli-option: "-k"
+    x-cli-convert:
+      none: 0
+      attrs: 1
+      sparse_csum: 2
+      full_csum: 3
+  retry_duration:
+    description: Specifies how long to wait before retrying transfer. (e.g. "5min")
+    $comment: "TODO: check this."
+    type:
+    - integer
+    - string
+    x-agents:
+    - transferd
+  save_before_overwrite:
+    description: >-
+      If a transfer would result in an existing file <filename>.<ext> being overwritten,
+      move that file to <filename>.yyyy.mm.dd.hh.mm.ss.index.<ext>
+      (where index is set to 1 at the beginning of each new second and
+      incremented for each file saved in this manner during the same second) in the same directory 
+      before writing the new file.
+
+      File attributes are maintained in the renamed file.
+    x-cli-switch: true
+    x-agents:
+    - direct
+    - node
+    - transferd
+  skip_duplicate_check:
+    description: Don't check for duplicate files at the destination.
+    type: boolean
+    x-agents:
+    - transferd
+    - direct
+    x-cli-option: "--skip-dir-traversal-dupes"
+    x-cli-switch: true
+  skip_special_files:
+    description: >-
+      All assets other than files, directories and symbolic links are considered special.
+      A transfer will fail if the user attempts to transfer special assets.
+      If true, ascp skips special assets and proceeds with the transfer of all other assets. 
+    type: boolean
+    x-agents:
+    - transferd
+    - direct
+    x-cli-switch: true
+  source_root:
+    description: >-
+      Path to be prepended to each source path.
+
+      This is either a conventional path or it can be a URI but only if there is no root defined.
+    x-cli-option: "--source-prefix64"
+    x-cli-convert: base64
+  source_root_id:
+    description: >-
+      The file ID of the source root directory.
+      Required when using Bearer token auth for the source node.
+    type: string
+    x-agents:
+    - transferd
+    - node
+  src_base:
+    description: >-
+      Specify the prefix to be stripped off from each source object.
+
+      The remaining portion of the source path is kept intact at the destination.
+
+      Special care must be taken when used with cloud storage.
+    x-agents:
+    - direct
+    - node
+    - transferd
+    x-cli-option: "--src-base64"
+    x-cli-convert: base64
+  src_base64:
+    description: The folder name below which the directory structure is preserved (base64 encoded).
+    type: string
+    x-agents:
+    - transferd
+    - direct
+    x-cli-option: "--src-base64"
+  ssh_port:
+    description: Specifies SSH (TCP) port.
+    default: "direct:22, other:33001"
+    type: integer
+    x-cli-option: "-P"
+  ssh_private_key:
+    description: >-
+      Private key used for SSH authentication.
+
+      Shall look like: -----BEGIN RSA PRIV4TE KEY-----&bsol;nMII...
+
+      Note the JSON encoding: &bsol;n for newlines.
+    x-agents:
+    - direct
+    - transferd
+    x-cli-envvar: ASPERA_SCP_KEY
+  ssh_private_key_passphrase:
+    description: The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.
+    type: string
+    x-agents:
+    - transferd
+    - direct
+    x-cli-envvar: ASPERA_SCP_PASS
+  ssh_private_key_path:
+    description: Path to private key for SSH.
+    type: string
+    x-agents:
+    - transferd
+    - direct
+    x-cli-option: "-i"
+  ssh_args:
+    description: Array of arguments to pass to SSH. Use with caution.
+    type: array
+    x-agents:
+    - transferd
+    x-cli-option: "-i"
+  symlink_policy:
+    description: "Handle source side symbolic links"
+    enum:
+    - follow
+    - copy
+    - copy+force
+    - skip
+    default: follow
+    x-cli-option: "--symbolic-links"
+  tags:
+    description: >-
+      Metadata for transfer as JSON.
+      Key `aspera` is reserved.
+      Key `aspera.xfer_retry` specifies a retry timeout for node api initiated transfers.
+    type: object
+    x-cli-option: "--tags64"
+    x-cli-convert: json64
+  tags64:
+    description: >-
+      Metadata for transfer as JSON.
+      Key `aspera` is reserved.
+      Key `aspera.xfer_retry` specifies a retry timeout for node api initiated transfers.
+    type: string
+    x-agents:
+    - transferd
+    - direct
+  target_rate_cap_kbps:
+    description: >-
+      Maximum target rate for incoming transfers, in kilobits per second. 
+      Returned by upload/download_setup node API.
+    type: integer
+    x-agents:
+    - connect
+    - transferd
+  target_rate_kbps:
+    description: Specifies desired speed for the transfer.
+    type: integer
+    x-cli-option: "-l"
+  title:
+    description: Title of the transfer.
+    type: string
+    x-agents:
+    - node
+    - connect
+    - transferd
+  token:
+    description: 'Authorization token: Bearer, Basic or ATM (Also arg -W)'
+    x-cli-envvar: ASPERA_SCP_TOKEN
+  use_ascp4:
+    description: Specify version of protocol. Do not use ascp4.
+    type: boolean
+    default: false
+    x-agents:
+    - direct
+    - node
+    - transferd
+    x-cli-special: true
+  use_system_ssh:
+    description: TODO, comment...
+    type: string
+    x-agents:
+    - transferd
+    - direct
+    x-cli-option: "-SSH"
+  keepalive:
+    description: The session is running in persistent session mode.
+    x-agents:
+    - transferd
+    - direct
+    x-cli-switch: true
+  dgram_size:
+    description: UDP datagram size in bytes
+    type: integer
+    x-cli-option: "-Z"
+  min_rate_kbps:
+    description: Set the minimum transfer rate in kilobits per second.
+    type: integer
+    default: 0
+    x-cli-option: "-m"
+  sshfp:
+    description: Check it against server SSH host key fingerprint.
+    x-cli-option: "--check-sshfp"
+  target_rate_percentage:
+    description: "TODO: remove ?"
+    x-agents: []
+  rate_policy_allowed:
+    description: "Specifies most aggressive rate policy that is allowed.\nReturned by node API."
+    enum:
+    - low
+    - fair
+    - high
+    - fixed
+    x-agents:
+    - connect
+  fasp_url:
+    description: Only used in Faspex.
+    x-agents: []
+  authentication:
+    description: 'value=token for SSH bypass keys, else password asked if not provided.'
+    x-agents:
+    - connect
+  cipher_allowed:
+    description: returned by node API. Valid literals include "aes-128" and "none".
+    x-agents:
+    - connect
+  obfuscate_file_names:
+    description: HTTP Gateway obfuscates file names when set to true.
+    type: boolean
+    x-agents:
+    - httpgw
+  wss_enabled:
+    description: Server has Web Socket service enabled
+    type: boolean
+    x-cli-special: true
+  wss_port:
+    description: TCP port used for websocket service feed
+    type: integer
+    x-cli-special: true
+  compression:
+    description: ascp4 only, 0 / 1?
+    type: integer
+    x-agents: []
+  read_threads:
+    description: ascp4 only
+    type: integer
+    x-agents: []
+  write_threads:
+    description: ascp4 only
+    type: integer
+    x-agents: []
+  xfer_max_retries:
+    description: >-
+      Maximum number of retries, for node API initiated transfers.
+      Shall not exceed aspera.conf `transfer_manager_max_retries` (default 5).
+    type: integer
+    x-agents:
+    - node