cloudsync.query

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: filters

filters

Type: array Default: []

List of filters for query results. See API documentation for "Query Methods" for more guidance.

 No Additional Items
Each item of this array must be:
Type: object

Examples:

[
    [
        "name",
        "=",
        "bob"
    ]
]

[
    [
        "OR",
        [
            [
                [
                    "name",
                    "=",
                    "bob"
                ]
            ],
            [
                [
                    "name",
                    "=",
                    "larry"
                ]
            ]
        ]
    ]
]
Parameter 2: options

options

Type: object
Default:
{ "extra": {}, "order_by": [], "select": [], "count": false, "get": false, "offset": 0, "limit": 0, "force_sql_filters": false }

Query options including pagination, ordering, and additional parameters.

 No Additional Properties

Extra

Type: object Default: {}

Extra options are defined on a per-endpoint basis and are described in the documentation for the associated query method.

Order By

Type: array of string Default: []

An array of field names describing the manner in which query results should be ordered. The field names may also have one of more of the following special prefixes: - (reverse sort direction), nulls_first: (place any null values at the head of the results list), nulls_last: (place any null values at the tail of the results list).

No Additional Items
Each item of this array must be:
Type: string

Example:

[
    "size",
    "-devname",
    "nulls_first:-expiretime"
]

Select

Type: array Default: []

An array of field names specifying the exact fields to include in the query return. The dot character . may be used to explicitly select only subkeys of the query result.

No Additional Items
Each item of this array must be:

Type: string
Type: array
No Additional Items
Each item of this array must be:
Type: object

Example:

[
    "username",
    "Authentication.status"
]

Count

Type: boolean Default: false

Return a numeric value representing the number of items that match the specified query-filters.

Get

Type: boolean Default: false

Return the JSON object of the first result matching the specified query-filters. The query fails if there specified query-filters return no results.

Offset

Type: integer Default: 0

This specifies the beginning offset of the results array. When combined with the limit query-option it may be used to implement pagination of large results arrays. WARNING: some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.

Limit

Type: integer Default: 0

This specifies the maximum number of results matching the specified query-filters to return. When combined wtih the offset query-option it may be used to implement pagination of large results arrays.

WARNING: Some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.

Force Sql Filters

Type: boolean Default: false

Force use of SQL for result filtering to reduce response time. May not work for all methods.

Result


Type: array of object
No Additional Items
Each item of this array must be:

CloudSyncQueryResultItem

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for this cloud storage configuration.

Description

Type: string

The name of the task to display in the UI.

Path

Type: string

The local path to back up beginning with /mnt or /dev/zvol.

CloudCredentialEntry

Type: object

Cloud credentials to use for each backup.

 No Additional Properties

Id

Type: integer

Unique identifier for the cloud credential.

Name

Type: string

Human-readable name for the cloud credential.

Must be at least 1 characters long

Provider


Cloud provider configuration including type and authentication details.

AzureBlobCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Microsoft Azure Blob storage.

Must be one of:
  • "AZUREBLOB"
Specific value: "AZUREBLOB"

Account

Type: string

Azure Blob Storage account name for authentication.

Must be at least 1 characters long

Key

Type: string

Azure Blob Storage access key for authentication.

Must be at least 1 characters long

Endpoint

Default: ""

Custom Azure Blob Storage endpoint URL. Empty string for default endpoints.

Type: const
Must be one of:
  • ""
Specific value: ""
Type: stringFormat: uri

Must be at least 1 characters long

Must be at most 2083 characters long

B2CredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Backblaze B2 storage.

Must be one of:
  • "B2"
Specific value: "B2"

Account

Type: string

Backblaze B2 account ID for authentication.

Must be at least 1 characters long

Key

Type: string

Backblaze B2 application key for authentication.

Must be at least 1 characters long

BoxCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Box cloud storage.

Must be one of:
  • "BOX"
Specific value: "BOX"

Client Id

Type: string Default: ""

Box OAuth application client ID.

Client Secret

Type: string Default: ""

Box OAuth application client secret.

Token

Type: string

Box OAuth access token for API authentication.

Must be at least 1 characters long

DropboxCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Dropbox storage.

Must be one of:
  • "DROPBOX"
Specific value: "DROPBOX"

Client Id

Type: string Default: ""

Dropbox OAuth application client ID.

Client Secret

Type: string Default: ""

Dropbox OAuth application client secret.

Token

Type: string

Dropbox OAuth access token for API authentication.

Must be at least 1 characters long

FTPCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for FTP.

Must be one of:
  • "FTP"
Specific value: "FTP"

Host

Type: string

FTP server hostname or IP address.

Must be at least 1 characters long

Port

Type: integer Default: 21

FTP server port number.

User

Type: string

FTP username for authentication.

Must be at least 1 characters long

Pass

Type: string

FTP password for authentication.

GoogleCloudStorageCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Google Cloud Storage.

Must be one of:
  • "GOOGLE_CLOUD_STORAGE"
Specific value: "GOOGLE_CLOUD_STORAGE"

Service Account Credentials

Type: string

JSON service account credentials for Google Cloud Storage authentication.

Must be at least 1 characters long

GoogleDriveCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Google Drive.

Must be one of:
  • "GOOGLE_DRIVE"
Specific value: "GOOGLE_DRIVE"

Client Id

Type: string Default: ""

OAuth client ID for Google Drive API access.

Client Secret

Type: string Default: ""

OAuth client secret for Google Drive API access.

Token

Type: string

OAuth access token for Google Drive authentication.

Must be at least 1 characters long

Team Drive

Type: string Default: ""

Google Drive team drive ID or empty string for personal drive.

GooglePhotosCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Google Photos.

Must be one of:
  • "GOOGLE_PHOTOS"
Specific value: "GOOGLE_PHOTOS"

Client Id

Type: string Default: ""

OAuth client ID for Google Photos API access.

Client Secret

Type: string Default: ""

OAuth client secret for Google Photos API access.

Token

Type: string

OAuth access token for Google Photos authentication.

Must be at least 1 characters long

HTTPCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for HTTP.

Must be one of:
  • "HTTP"
Specific value: "HTTP"

Url

Type: stringFormat: uri

HTTP URL for file access.

Must be at least 1 characters long

Must be at most 2083 characters long

HubicCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Hubic.

Must be one of:
  • "HUBIC"
Specific value: "HUBIC"

Token

Type: string

OAuth access token for Hubic authentication.

Must be at least 1 characters long

MegaCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for MEGA.

Must be one of:
  • "MEGA"
Specific value: "MEGA"

User

Type: string

MEGA username for authentication.

Must be at least 1 characters long

Pass

Type: string

MEGA password for authentication.

Must be at least 1 characters long

OneDriveCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for OneDrive.

Must be one of:
  • "ONEDRIVE"
Specific value: "ONEDRIVE"

Client Id

Type: string Default: ""

OAuth client ID for OneDrive API access.

Client Secret

Type: string Default: ""

OAuth client secret for OneDrive API access.

Token

Type: string

OAuth access token for OneDrive authentication.

Must be at least 1 characters long

Drive Type

Type: enum (of string)

Type of OneDrive to access.

Must be one of:
  • "PERSONAL"
  • "BUSINESS"
  • "DOCUMENT_LIBRARY"

Drive Id

Type: string

OneDrive drive identifier.

PCloudCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for pCloud.

Must be one of:
  • "PCLOUD"
Specific value: "PCLOUD"

Client Id

Type: string Default: ""

OAuth client ID for pCloud API access.

Client Secret

Type: string Default: ""

OAuth client secret for pCloud API access.

Token

Type: string

OAuth access token for pCloud authentication.

Must be at least 1 characters long

Hostname

Type: string Default: ""

pCloud hostname or empty string for default.

S3CredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for S3-compatible storage.

Must be one of:
  • "S3"
Specific value: "S3"

Access Key Id

Type: string

S3 access key ID for authentication.

Must be at least 1 characters long

Secret Access Key

Type: string

S3 secret access key for authentication.

Must be at least 1 characters long

Endpoint

Type: string Default: ""

S3-compatible endpoint URL or empty string for AWS S3.

Region

Type: string Default: ""

S3 region or empty string for default.

Skip Region

Type: boolean Default: false

Whether to skip region validation.

Signatures V2

Type: boolean Default: false

Whether to use AWS Signature Version 2.

Max Upload Parts

Type: integer Default: 10000

Maximum number of parts for multipart uploads.

SFTPCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for SFTP.

Must be one of:
  • "SFTP"
Specific value: "SFTP"

Host

Type: string

SFTP server hostname or IP address.

Must be at least 1 characters long

Port

Type: integer Default: 22

SFTP server port number.

User

Type: string

SFTP username for authentication.

Must be at least 1 characters long

Pass

Default: null

SFTP password for authentication or null for key-based auth.

Type: string
Type: null

Private Key

Default: null

SSH private key ID for authentication or null for password auth.

Type: integer
Type: null

StorjIxCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Storj decentralized storage.

Must be one of:
  • "STORJ_IX"
Specific value: "STORJ_IX"

Access Key Id

Type: string

Storj S3-compatible access key ID for authentication.

Must be at least 1 characters long

Secret Access Key

Type: string

Storj S3-compatible secret access key for authentication.

Must be at least 1 characters long

Endpoint

Type: stringFormat: uri Default: "https://gateway.storjshare.io/"

Storj gateway endpoint URL for S3-compatible access.

Must be at least 1 characters long

Must be at most 2083 characters long

SwiftCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for OpenStack Swift storage.

Must be one of:
  • "OPENSTACK_SWIFT"
Specific value: "OPENSTACK_SWIFT"

User

Type: string

Swift username for authentication.

Must be at least 1 characters long

Key

Type: string

Swift password or API key for authentication.

Must be at least 1 characters long

Auth

Type: string

Swift authentication URL endpoint.

Must be at least 1 characters long

User Id

Type: string Default: ""

Swift user ID for authentication.

Domain

Type: string Default: ""

Swift domain name for authentication.

Tenant

Type: string Default: ""

Swift tenant name for multi-tenancy.

Tenant Id

Type: string Default: ""

Swift tenant ID for multi-tenancy.

Tenant Domain

Type: string Default: ""

Swift tenant domain name.

Region

Type: string Default: ""

Swift region name for geographic distribution.

Storage Url

Type: string Default: ""

Swift storage URL endpoint.

Auth Token

Type: string Default: ""

Swift authentication token for pre-authenticated access.

Application Credential Id

Type: string Default: ""

Swift application credential ID for authentication.

Application Credential Name

Type: string Default: ""

Swift application credential name for authentication.

Application Credential Secret

Type: string Default: ""

Swift application credential secret for authentication.

Auth Version


Swift authentication API version.

  • 0: Legacy auth
  • 1: TempAuth
  • 2: Keystone v2.0
  • 3: Keystone v3
  • null: Auto-detect

Type: enum (of integer)
Must be one of:
  • 0
  • 1
  • 2
  • 3
Type: null

Endpoint Type


Swift endpoint type to use.

  • public: Public endpoint (default)
  • internal: Internal network endpoint
  • admin: Administrative endpoint
  • null: Use default

Type: enum (of string)
Must be one of:
  • "public"
  • "internal"
  • "admin"
Type: null

WebDavCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for WebDAV servers.

Must be one of:
  • "WEBDAV"
Specific value: "WEBDAV"

Url

Type: stringFormat: uri

WebDAV server URL endpoint.

Must be at least 1 characters long

Must be at most 2083 characters long

Vendor

Type: enum (of string)

WebDAV server vendor type for compatibility optimizations.

  • NEXTCLOUD: Nextcloud server
  • OWNCLOUD: ownCloud server
  • SHAREPOINT: Microsoft SharePoint
  • OTHER: Generic WebDAV server
Must be one of:
  • "NEXTCLOUD"
  • "OWNCLOUD"
  • "SHAREPOINT"
  • "OTHER"

User

Type: string

WebDAV username for authentication.

Pass

Type: string

WebDAV password for authentication.

YandexCredentialsModel

Type: object
No Additional Properties

Type

Type: const

Cloud provider type identifier for Yandex Disk storage.

Must be one of:
  • "YANDEX"
Specific value: "YANDEX"

Client Id

Type: string Default: ""

Yandex OAuth application client ID.

Client Secret

Type: string Default: ""

Yandex OAuth application client secret.

Token

Type: string

Yandex OAuth access token for API authentication.

Must be at least 1 characters long

CloudTaskAttributes

Type: object

Additional information for each backup, e.g. bucket name.

 No Additional Properties

Bucket

Type: string

Name of the cloud storage bucket or container.

Must be at least 1 characters long

Folder

Type: string

Path within the cloud storage bucket to use as the root directory for operations.

Fast List

Type: boolean

Valid only for some providers. Use fewer transactions in exchange for more RAM. This may also speed up or slow down your transfer. See https://rclone.org/docs/#fast-list for more details.

Bucket Policy Only

Type: boolean

Valid only for GOOGLECLOUDSTORAGE provider. Access checks should use bucket-level IAM policies. If you want to upload objects to a bucket with Bucket Policy Only set then you will need to set this.

Chunk Size

Type: integer

Valid only for DROPBOX provider. Upload chunk size in MiB. Must fit in memory. Note that these chunks are buffered in memory and there might be a maximum of --transfers chunks in progress at once. Dropbox Business accounts can have monthly data transfer limits per team per month. By using larger chunk sizes you will decrease the number of data transfer calls used and you'll be able to transfer more data to your Dropbox Business account.

Value must be greater or equal to 5 and strictly lesser than 150

Acknowledge Abuse

Type: boolean

Valid only for GOOGLE_DRIVER provider. Allow files which return cannotDownloadAbusiveFile to be downloaded. If downloading a file returns the error "This file has been identified as malware or spam and cannot be downloaded" with the error code "cannotDownloadAbusiveFile" then enable this flag to indicate you acknowledge the risks of downloading the file and TrueNAS will download it anyway.

Region

Type: string

Valid only for S3 provider. S3 Region.

Encryption

Type: enum (of null or string)

Valid only for S3 provider. Server-Side Encryption.

Must be one of:
  • null
  • "AES256"

Storage Class

Type: enum (of string)

Valid only for S3 provider. The storage class to use.

Must be one of:
  • ""
  • "STANDARD"
  • "REDUCED_REDUNDANCY"
  • "STANDARD_IA"
  • "ONEZONE_IA"
  • "INTELLIGENT_TIERING"
  • "GLACIER"
  • "GLACIER_IR"
  • "DEEP_ARCHIVE"

CloudCron

Type: object

Cron schedule dictating when the task should run.

 No Additional Properties

Minute

Type: string Default: "00"

Hour

Type: string Default: "*"

"00" - "23"

Dom

Type: string Default: "*"

"1" - "31"

Month

Type: string Default: "*"

"1" (January) - "12" (December)

Dow

Type: string Default: "*"

"1" (Monday) - "7" (Sunday)

Pre Script

Type: string

A Bash script to run immediately before every backup.

Post Script

Type: string

A Bash script to run immediately after every backup if it succeeds.

Snapshot

Type: boolean

Whether to create a temporary snapshot of the dataset before every backup.

Include

Type: array of string

Paths to pass to restic backup --include.

 No Additional Items
Each item of this array must be:
Type: string

Must be at least 1 characters long

Exclude

Type: array of string

Paths to pass to restic backup --exclude.

 No Additional Items
Each item of this array must be:
Type: string

Must be at least 1 characters long

Args

Type: string

(Slated for removal).

Enabled

Type: boolean

Can enable/disable the task.

Job


Information regarding the task's job state, e.g. progress.

Type: object
Type: null

Locked

Type: boolean

A locked task cannot run.

Bwlimit

Type: array of object

Schedule of bandwidth limits.

 No Additional Items
Each item of this array must be:

CloudSyncBwlimit

Type: object
No Additional Properties

Time

Type: string

Time at which the bandwidth limit takes effect in 24-hour format.
Examples:

"00:00"

"06:30"

"18:00"

"23:00"

Bandwidth


Bandwidth limit in bytes per second (upload and download).

Type: integer

Value must be strictly greater than 0

Type: null

Transfers


Maximum number of parallel file transfers. null for default.

Type: integer

Value must be strictly greater than 0

Type: null

Direction

Type: enum (of string)

Direction of the cloud sync operation.

  • PUSH: Upload local files to cloud storage
  • PULL: Download files from cloud storage to local storage
Must be one of:
  • "PUSH"
  • "PULL"

Transfer Mode

Type: enum (of string)

How files are transferred between local and cloud storage.

  • SYNC: Synchronize directories (add new, update changed, remove deleted)
  • COPY: Copy files without removing any existing files
  • MOVE: Move files (copy then delete from source)
Must be one of:
  • "SYNC"
  • "COPY"
  • "MOVE"

Encryption

Type: boolean

Whether to encrypt files before uploading to cloud storage.

Filename Encryption

Type: boolean

Whether to encrypt filenames in addition to file contents.

Encryption Password

Type: string

Password for client-side encryption. Empty string if encryption is disabled.

Encryption Salt

Type: string

Salt value for encryption key derivation. Empty string if encryption is disabled.

Create Empty Src Dirs

Type: boolean

Whether to create empty directories in the destination that exist in the source.

CloudSyncQueryResultItem

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for this cloud storage configuration.

Description

Type: string

The name of the task to display in the UI.

Path

Type: string

The local path to back up beginning with /mnt or /dev/zvol.

Type: object

Cloud credentials to use for each backup.

Type: object

Additional information for each backup, e.g. bucket name.

Type: object

Cron schedule dictating when the task should run.

Pre Script

Type: string

A Bash script to run immediately before every backup.

Post Script

Type: string

A Bash script to run immediately after every backup if it succeeds.

Snapshot

Type: boolean

Whether to create a temporary snapshot of the dataset before every backup.

Include

Type: array of string

Paths to pass to restic backup --include.

 No Additional Items
Each item of this array must be:
Type: string

Must be at least 1 characters long

Exclude

Type: array of string

Paths to pass to restic backup --exclude.

 No Additional Items
Each item of this array must be:
Type: string

Must be at least 1 characters long

Args

Type: string

(Slated for removal).

Enabled

Type: boolean

Can enable/disable the task.

Job


Information regarding the task's job state, e.g. progress.

Type: object
Type: null

Locked

Type: boolean

A locked task cannot run.

Bwlimit

Type: array

Schedule of bandwidth limits.

 No Additional Items
Each item of this array must be:
Type: object

Transfers


Maximum number of parallel file transfers. null for default.

Type: integer

Value must be strictly greater than 0

Type: null

Direction

Type: enum (of string)

Direction of the cloud sync operation.

  • PUSH: Upload local files to cloud storage
  • PULL: Download files from cloud storage to local storage
Must be one of:
  • "PUSH"
  • "PULL"

Transfer Mode

Type: enum (of string)

How files are transferred between local and cloud storage.

  • SYNC: Synchronize directories (add new, update changed, remove deleted)
  • COPY: Copy files without removing any existing files
  • MOVE: Move files (copy then delete from source)
Must be one of:
  • "SYNC"
  • "COPY"
  • "MOVE"

Encryption

Type: boolean

Whether to encrypt files before uploading to cloud storage.

Filename Encryption

Type: boolean

Whether to encrypt filenames in addition to file contents.

Encryption Password

Type: string

Password for client-side encryption. Empty string if encryption is disabled.

Encryption Salt

Type: string

Salt value for encryption key derivation. Empty string if encryption is disabled.

Create Empty Src Dirs

Type: boolean

Whether to create empty directories in the destination that exist in the source.
Type: integer


Required roles: CLOUD_SYNC_READ