sharing.s3.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.

Value must be greater or equal to 0

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.

Value must be greater or equal to 0 and lesser or equal to 10000

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:

SharingS3Entry

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for the bucket.

Name

Type: string

Bucket name must be three to 63 characters of lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit, no adjacent dots, and not an IP address.

Must match regular expression: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$

Must be at least 3 characters long

Must be at most 63 characters long

Dataset

Type: string

The ZFS dataset of the bucket. The location of S3 data within the dataset depends on the layout field.

Must be at least 1 characters long

Layout

Type: enum (of string) Default: "BUCKET"

This create-time mutable field determines where S3 objects are located within the share. If set to BUCKET (the default), then the S3 share is a conventional S3 bucket that supports writes through the S3 protocol. Data must be accessed through the s3data directory inside the dataset. If set to DATASET, then the entire dataset contents are exposed as S3 objects, but S3 protocol access is restricted to read only operations. This setting is available to S3 protocol access to non-S3 data, for example, SMB or NFS shares.

Must be one of:
  • "BUCKET"
  • "DATASET"

Enabled

Type: boolean Default: true

Whether the bucket is served. Changing it reloads the S3 service.

Owner

Type: string

Account that owns the bucket and bypasses its grants, owns the s3data directory when the S3 service creates it, and owns every object written under the BUCKET_OWNER_ENFORCED object ownership setting.

Must be at least 1 characters long

Owner Uid

Type: integer

The uid that owns the bucket.

Grants

Type: array of object Default: []

Who may access the bucket and how, beyond its owner.

 No Additional Items
Each item of this array must be:

S3GrantEntry

Type: object
No Additional Properties

Principal Type

Type: enum (of string)

Who the grant applies to. A user, a group, or everyone with a valid access key.

Must be one of:
  • "USER"
  • "GROUP"
  • "EVERYONE"

Xid

Default: null

The uid of the user or the gid of the group. Required for USER and GROUP, forbidden for EVERYONE.

Type: integer
Type: null

Access

Type: enum (of string)

What the grant allows. READONLY, WRITEONLY and READWRITE allow the matching operations. DENY refuses every operation for the principal and outranks the bucket owner.

Must be one of:
  • "READONLY"
  • "WRITEONLY"
  • "READWRITE"
  • "DENY"

Name

Type: string

Name of the user or group the grant applies to, resolved for display. Empty for EVERYONE.

Permissions Model

Type: enum (of string) Default: "S3"

How the S3 service treats the filesystem permissions on the bucket's tree. When S3 is set, access is solely determined by the bucket's grants and object ACL if the object_ownership bucket configuration field is not set to BUCKET_OWNER_ENFORCED. In this configuration, filesystem ACLs are not evaluated by the S3 server. When MULTIPROTOCOL is set, filesystem ACLs are enforced in addition to S3 protocol access control mechanisms. S3 shares with DATASET layout default to the MULTIPROTOCOL permissions model.

Must be one of:
  • "S3"
  • "MULTIPROTOCOL"

Object Ownership

Type: enum (of string) Default: "BUCKET_OWNER_ENFORCED"

S3 Object Ownership, the bucket-level setting that controls ownership of objects uploaded to the bucket and disables or enables ACLs, and what GetBucketOwnershipControls reports. BUCKET_OWNER_ENFORCED (the default): ACLs are disabled, and the bucket owner automatically owns and has full control over every object in the bucket. ACLs no longer affect permissions to data in the bucket, and the bucket uses its grants to define access control. Requests to set or update ACLs fail with AccessControlListNotSupported; requests to read ACLs are supported. Only uploads with bucket owner full control ACLs, or uploads that do not specify an ACL, are accepted. BUCKET_OWNER_PREFERRED: the bucket owner owns and has full control over new objects that other accounts write to the bucket with the bucket-owner-full-control canned ACL. Objects uploaded with other ACLs are owned by the writing account. ACLs can be updated and can grant permissions. OBJECT_WRITER: the account that uploads an object owns the object, has full control over it, and can grant other users access to it through ACLs. A MULTIPROTOCOL bucket is always OBJECT_WRITER whatever is given here, and its ACLs stay disabled: the other protocols' users own the filesystem permissions on the tree.

Must be one of:
  • "BUCKET_OWNER_ENFORCED"
  • "BUCKET_OWNER_PREFERRED"
  • "OBJECT_WRITER"

Versioning

Type: enum (of string) Default: "OFF"

Bucket versioning state. One-way: a bucket that has been ENABLED or SUSPENDED cannot return to OFF here, only move between those two, so its stored versions never go unreachable. sharing.s3.force_disable_versioning is the one destructive way back, and it destroys every prior object version. NOTE: this is a licensed feature.

Must be one of:
  • "OFF"
  • "ENABLED"
  • "SUSPENDED"

Snapshot Versions

Type: array of string Default: []

Patterns over the names of the bucket dataset's ZFS snapshots, * and ? the only metacharacters, each matched against a whole name. Every snapshot a pattern selects serves each object's state frozen in it as a read-only version: listed by ListObjectVersions and read by its version id. Empty serves none. Requires versioning to be ENABLED or SUSPENDED.

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

Must be at least 1 characters long

Snapshot Versions Max

Type: integer Default: 64

How many of the newest selected snapshots one ListObjectVersions listing consults. Bounds the listing alone: a selected snapshot beyond it still serves by its version id.

Value must be greater or equal to 1 and lesser or equal to 4294967295

Multipart Etag

Type: enum (of string) Default: "MINTED"

ETag format for objects created by multipart upload. MINTED gives the object an opaque token. COMPOSITE gives it the standard S3 multipart ETag, built from the MD5 of each part. Choose COMPOSITE if a client verifies or resumes uploads by computing that ETag itself and comparing.

Must be one of:
  • "COMPOSITE"
  • "MINTED"

Object Lock

Type: boolean Default: false

Whether object lock is enabled. Requires versioning to be ENABLED and a permissions model other than MULTIPROTOCOL: a locked bucket is the S3 service's alone. One-way: the lock is latched on the bucket's dataset and cannot be disabled once enabled. NOTE: this is a licensed feature.

Object Lock Default Mode

Default: null

Retention mode of the default object lock rule, or null for no default rule.

Type: enum (of string)
Must be one of:
  • "GOVERNANCE"
  • "COMPLIANCE"
Type: null

Object Lock Default Days

Default: null

Retention period of the default object lock rule in days, up to 36500 (a hundred years).

Type: integer

Value must be greater or equal to 1 and lesser or equal to 36500

Type: null

Audit

Default: null

Actions audited on this bucket, ALL, or an empty list to audit nothing. null inherits the service's default_audit. CreateBucket and ListAllMyBuckets never match here — the service default_audit governs both — while DeleteBucket does match this bucket's own deletion. NOTE: this is a licensed feature.

Type: array of enum (of string)
No Additional Items
Each item of this array must be:
Type: enum (of string)
Must be one of:
  • "GetObject"
  • "PutObject"
  • "DeleteObject"
  • "GetObjectTagging"
  • "PutObjectTagging"
  • "DeleteObjectTagging"
  • "ListBucket"
  • "GetBucketLocation"
  • "ListBucketMultipartUploads"
  • "ListMultipartUploadParts"
  • "AbortMultipartUpload"
  • "PutObjectRetention"
  • "PutObjectLegalHold"
  • "ListAllMyBuckets"
  • "GetObjectAcl"
  • "PutObjectAcl"
  • "GetBucketAcl"
  • "PutBucketAcl"
  • "PutBucketVersioning"
  • "CreateBucket"
  • "DeleteBucket"
Type: const
Specific value: "ALL"
Type: null

Audit Overflow

Default: null

Overflow behavior for this bucket's audit records, or null to inherit the service's default.

Type: enum (of string)
Must be one of:
  • "DROP"
  • "BACKPRESSURE"
Type: null

Locked

Default: null

Whether the bucket's dataset is locked. Read only.

Type: boolean
Type: null

Default: null

Storage tier in which the bucket's dataset is located. This field is read-only; configure the dataset's tier via zfs.tier.dataset_set_tier. NOTE: this is a licensed feature. Will be null if TrueNAS is unlicensed, if tiering is disabled, or if the pool has no SPECIAL vdev.

TierInfo

Type: object
No Additional Properties

Tier Type

Type: enum (of string)

Storage performance tier for this share.

Must be one of:
  • "REGULAR"
  • "PERFORMANCE"

Default: null

Most recent rewrite job for this share's dataset, or null if no job history exists.

ZfsTierRewriteJobEntry

Type: object
No Additional Properties

Tier Job Id

Type: string

Rewrite job identifier in dataset_name@job_uuid format.

Must be at least 1 characters long

Dataset Name

Type: string

ZFS dataset this job is operating on.

Must be at least 1 characters long

Job Uuid

Type: string

Unique identifier for this rewrite job.

Must be at least 1 characters long

Status

Type: enum (of string)

Current lifecycle state of the job.

  • COMPLETE - All files in the dataset have been processed.
  • RUNNING - Job is actively processing files.
  • QUEUED - Job is waiting for a free execution slot (see max_concurrent_jobs).
  • CANCELLED - Job was stopped via zfs_tier_job.cancel. Not resumable.
  • STOPPED - Job was RUNNING but its process is no longer active (e.g. daemon restart). This state is computed on read and is never written to persistent storage.
  • ERROR - Job halted due to an unrecoverable error. Use zfs_tier_job.recover to retry failed files.
Must be one of:
  • "COMPLETE"
  • "RUNNING"
  • "QUEUED"
  • "CANCELLED"
  • "STOPPED"
  • "ERROR"
Type: null
Type: null

SharingS3Entry

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for the bucket.

Name

Type: string

Bucket name must be three to 63 characters of lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit, no adjacent dots, and not an IP address.

Must match regular expression: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$

Must be at least 3 characters long

Must be at most 63 characters long

Dataset

Type: string

The ZFS dataset of the bucket. The location of S3 data within the dataset depends on the layout field.

Must be at least 1 characters long

Layout

Type: enum (of string) Default: "BUCKET"

This create-time mutable field determines where S3 objects are located within the share. If set to BUCKET (the default), then the S3 share is a conventional S3 bucket that supports writes through the S3 protocol. Data must be accessed through the s3data directory inside the dataset. If set to DATASET, then the entire dataset contents are exposed as S3 objects, but S3 protocol access is restricted to read only operations. This setting is available to S3 protocol access to non-S3 data, for example, SMB or NFS shares.

Must be one of:
  • "BUCKET"
  • "DATASET"

Enabled

Type: boolean Default: true

Whether the bucket is served. Changing it reloads the S3 service.

Owner

Type: string

Account that owns the bucket and bypasses its grants, owns the s3data directory when the S3 service creates it, and owns every object written under the BUCKET_OWNER_ENFORCED object ownership setting.

Must be at least 1 characters long

Owner Uid

Type: integer

The uid that owns the bucket.

Grants

Type: array Default: []

Who may access the bucket and how, beyond its owner.

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

Permissions Model

Type: enum (of string) Default: "S3"

How the S3 service treats the filesystem permissions on the bucket's tree. When S3 is set, access is solely determined by the bucket's grants and object ACL if the object_ownership bucket configuration field is not set to BUCKET_OWNER_ENFORCED. In this configuration, filesystem ACLs are not evaluated by the S3 server. When MULTIPROTOCOL is set, filesystem ACLs are enforced in addition to S3 protocol access control mechanisms. S3 shares with DATASET layout default to the MULTIPROTOCOL permissions model.

Must be one of:
  • "S3"
  • "MULTIPROTOCOL"

Object Ownership

Type: enum (of string) Default: "BUCKET_OWNER_ENFORCED"

S3 Object Ownership, the bucket-level setting that controls ownership of objects uploaded to the bucket and disables or enables ACLs, and what GetBucketOwnershipControls reports. BUCKET_OWNER_ENFORCED (the default): ACLs are disabled, and the bucket owner automatically owns and has full control over every object in the bucket. ACLs no longer affect permissions to data in the bucket, and the bucket uses its grants to define access control. Requests to set or update ACLs fail with AccessControlListNotSupported; requests to read ACLs are supported. Only uploads with bucket owner full control ACLs, or uploads that do not specify an ACL, are accepted. BUCKET_OWNER_PREFERRED: the bucket owner owns and has full control over new objects that other accounts write to the bucket with the bucket-owner-full-control canned ACL. Objects uploaded with other ACLs are owned by the writing account. ACLs can be updated and can grant permissions. OBJECT_WRITER: the account that uploads an object owns the object, has full control over it, and can grant other users access to it through ACLs. A MULTIPROTOCOL bucket is always OBJECT_WRITER whatever is given here, and its ACLs stay disabled: the other protocols' users own the filesystem permissions on the tree.

Must be one of:
  • "BUCKET_OWNER_ENFORCED"
  • "BUCKET_OWNER_PREFERRED"
  • "OBJECT_WRITER"

Versioning

Type: enum (of string) Default: "OFF"

Bucket versioning state. One-way: a bucket that has been ENABLED or SUSPENDED cannot return to OFF here, only move between those two, so its stored versions never go unreachable. sharing.s3.force_disable_versioning is the one destructive way back, and it destroys every prior object version. NOTE: this is a licensed feature.

Must be one of:
  • "OFF"
  • "ENABLED"
  • "SUSPENDED"

Snapshot Versions

Type: array of string Default: []

Patterns over the names of the bucket dataset's ZFS snapshots, * and ? the only metacharacters, each matched against a whole name. Every snapshot a pattern selects serves each object's state frozen in it as a read-only version: listed by ListObjectVersions and read by its version id. Empty serves none. Requires versioning to be ENABLED or SUSPENDED.

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

Must be at least 1 characters long

Snapshot Versions Max

Type: integer Default: 64

How many of the newest selected snapshots one ListObjectVersions listing consults. Bounds the listing alone: a selected snapshot beyond it still serves by its version id.

Value must be greater or equal to 1 and lesser or equal to 4294967295

Multipart Etag

Type: enum (of string) Default: "MINTED"

ETag format for objects created by multipart upload. MINTED gives the object an opaque token. COMPOSITE gives it the standard S3 multipart ETag, built from the MD5 of each part. Choose COMPOSITE if a client verifies or resumes uploads by computing that ETag itself and comparing.

Must be one of:
  • "COMPOSITE"
  • "MINTED"

Object Lock

Type: boolean Default: false

Whether object lock is enabled. Requires versioning to be ENABLED and a permissions model other than MULTIPROTOCOL: a locked bucket is the S3 service's alone. One-way: the lock is latched on the bucket's dataset and cannot be disabled once enabled. NOTE: this is a licensed feature.

Object Lock Default Mode

Default: null

Retention mode of the default object lock rule, or null for no default rule.

Type: enum (of string)
Must be one of:
  • "GOVERNANCE"
  • "COMPLIANCE"
Type: null

Object Lock Default Days

Default: null

Retention period of the default object lock rule in days, up to 36500 (a hundred years).

Type: integer

Value must be greater or equal to 1 and lesser or equal to 36500

Type: null

Audit

Default: null

Actions audited on this bucket, ALL, or an empty list to audit nothing. null inherits the service's default_audit. CreateBucket and ListAllMyBuckets never match here — the service default_audit governs both — while DeleteBucket does match this bucket's own deletion. NOTE: this is a licensed feature.

Type: array of enum (of string)
No Additional Items
Each item of this array must be:
Type: enum (of string)
Must be one of:
  • "GetObject"
  • "PutObject"
  • "DeleteObject"
  • "GetObjectTagging"
  • "PutObjectTagging"
  • "DeleteObjectTagging"
  • "ListBucket"
  • "GetBucketLocation"
  • "ListBucketMultipartUploads"
  • "ListMultipartUploadParts"
  • "AbortMultipartUpload"
  • "PutObjectRetention"
  • "PutObjectLegalHold"
  • "ListAllMyBuckets"
  • "GetObjectAcl"
  • "PutObjectAcl"
  • "GetBucketAcl"
  • "PutBucketAcl"
  • "PutBucketVersioning"
  • "CreateBucket"
  • "DeleteBucket"
Type: const
Specific value: "ALL"
Type: null

Audit Overflow

Default: null

Overflow behavior for this bucket's audit records, or null to inherit the service's default.

Type: enum (of string)
Must be one of:
  • "DROP"
  • "BACKPRESSURE"
Type: null

Locked

Default: null

Whether the bucket's dataset is locked. Read only.

Type: boolean
Type: null

Default: null

Storage tier in which the bucket's dataset is located. This field is read-only; configure the dataset's tier via zfs.tier.dataset_set_tier. NOTE: this is a licensed feature. Will be null if TrueNAS is unlicensed, if tiering is disabled, or if the pool has no SPECIAL vdev.

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

SharingS3QueryResultItem

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for the bucket.

Name

Type: string

Bucket name must be three to 63 characters of lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit, no adjacent dots, and not an IP address.

Must match regular expression: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$

Must be at least 3 characters long

Must be at most 63 characters long

Dataset

Type: string

The ZFS dataset of the bucket. The location of S3 data within the dataset depends on the layout field.

Must be at least 1 characters long

Layout

Type: enum (of string)

This create-time mutable field determines where S3 objects are located within the share. If set to BUCKET (the default), then the S3 share is a conventional S3 bucket that supports writes through the S3 protocol. Data must be accessed through the s3data directory inside the dataset. If set to DATASET, then the entire dataset contents are exposed as S3 objects, but S3 protocol access is restricted to read only operations. This setting is available to S3 protocol access to non-S3 data, for example, SMB or NFS shares.

Must be one of:
  • "BUCKET"
  • "DATASET"

Enabled

Type: boolean

Whether the bucket is served. Changing it reloads the S3 service.

Owner

Type: string

Account that owns the bucket and bypasses its grants, owns the s3data directory when the S3 service creates it, and owns every object written under the BUCKET_OWNER_ENFORCED object ownership setting.

Must be at least 1 characters long

Owner Uid

Type: integer

The uid that owns the bucket.

Grants

Type: array of object

Who may access the bucket and how, beyond its owner.

 No Additional Items
Each item of this array must be:

S3GrantEntry

Type: object
No Additional Properties

Principal Type

Type: enum (of string)

Who the grant applies to. A user, a group, or everyone with a valid access key.

Must be one of:
  • "USER"
  • "GROUP"
  • "EVERYONE"

Xid

Default: null

The uid of the user or the gid of the group. Required for USER and GROUP, forbidden for EVERYONE.

Type: integer
Type: null

Access

Type: enum (of string)

What the grant allows. READONLY, WRITEONLY and READWRITE allow the matching operations. DENY refuses every operation for the principal and outranks the bucket owner.

Must be one of:
  • "READONLY"
  • "WRITEONLY"
  • "READWRITE"
  • "DENY"

Name

Type: string

Name of the user or group the grant applies to, resolved for display. Empty for EVERYONE.

Permissions Model

Type: enum (of string)

How the S3 service treats the filesystem permissions on the bucket's tree. When S3 is set, access is solely determined by the bucket's grants and object ACL if the object_ownership bucket configuration field is not set to BUCKET_OWNER_ENFORCED. In this configuration, filesystem ACLs are not evaluated by the S3 server. When MULTIPROTOCOL is set, filesystem ACLs are enforced in addition to S3 protocol access control mechanisms. S3 shares with DATASET layout default to the MULTIPROTOCOL permissions model.

Must be one of:
  • "S3"
  • "MULTIPROTOCOL"

Object Ownership

Type: enum (of string)

S3 Object Ownership, the bucket-level setting that controls ownership of objects uploaded to the bucket and disables or enables ACLs, and what GetBucketOwnershipControls reports. BUCKET_OWNER_ENFORCED (the default): ACLs are disabled, and the bucket owner automatically owns and has full control over every object in the bucket. ACLs no longer affect permissions to data in the bucket, and the bucket uses its grants to define access control. Requests to set or update ACLs fail with AccessControlListNotSupported; requests to read ACLs are supported. Only uploads with bucket owner full control ACLs, or uploads that do not specify an ACL, are accepted. BUCKET_OWNER_PREFERRED: the bucket owner owns and has full control over new objects that other accounts write to the bucket with the bucket-owner-full-control canned ACL. Objects uploaded with other ACLs are owned by the writing account. ACLs can be updated and can grant permissions. OBJECT_WRITER: the account that uploads an object owns the object, has full control over it, and can grant other users access to it through ACLs. A MULTIPROTOCOL bucket is always OBJECT_WRITER whatever is given here, and its ACLs stay disabled: the other protocols' users own the filesystem permissions on the tree.

Must be one of:
  • "BUCKET_OWNER_ENFORCED"
  • "BUCKET_OWNER_PREFERRED"
  • "OBJECT_WRITER"

Versioning

Type: enum (of string)

Bucket versioning state. One-way: a bucket that has been ENABLED or SUSPENDED cannot return to OFF here, only move between those two, so its stored versions never go unreachable. sharing.s3.force_disable_versioning is the one destructive way back, and it destroys every prior object version. NOTE: this is a licensed feature.

Must be one of:
  • "OFF"
  • "ENABLED"
  • "SUSPENDED"

Snapshot Versions

Type: array of string

Patterns over the names of the bucket dataset's ZFS snapshots, * and ? the only metacharacters, each matched against a whole name. Every snapshot a pattern selects serves each object's state frozen in it as a read-only version: listed by ListObjectVersions and read by its version id. Empty serves none. Requires versioning to be ENABLED or SUSPENDED.

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

Must be at least 1 characters long

Snapshot Versions Max

Type: integer

How many of the newest selected snapshots one ListObjectVersions listing consults. Bounds the listing alone: a selected snapshot beyond it still serves by its version id.

Value must be greater or equal to 1 and lesser or equal to 4294967295

Multipart Etag

Type: enum (of string)

ETag format for objects created by multipart upload. MINTED gives the object an opaque token. COMPOSITE gives it the standard S3 multipart ETag, built from the MD5 of each part. Choose COMPOSITE if a client verifies or resumes uploads by computing that ETag itself and comparing.

Must be one of:
  • "COMPOSITE"
  • "MINTED"

Object Lock

Type: boolean

Whether object lock is enabled. Requires versioning to be ENABLED and a permissions model other than MULTIPROTOCOL: a locked bucket is the S3 service's alone. One-way: the lock is latched on the bucket's dataset and cannot be disabled once enabled. NOTE: this is a licensed feature.

Object Lock Default Mode


Retention mode of the default object lock rule, or null for no default rule.

Type: enum (of string)
Must be one of:
  • "GOVERNANCE"
  • "COMPLIANCE"
Type: null

Object Lock Default Days


Retention period of the default object lock rule in days, up to 36500 (a hundred years).

Type: integer

Value must be greater or equal to 1 and lesser or equal to 36500

Type: null

Audit


Actions audited on this bucket, ALL, or an empty list to audit nothing. null inherits the service's default_audit. CreateBucket and ListAllMyBuckets never match here — the service default_audit governs both — while DeleteBucket does match this bucket's own deletion. NOTE: this is a licensed feature.

Type: array of enum (of string)
No Additional Items
Each item of this array must be:
Type: enum (of string)
Must be one of:
  • "GetObject"
  • "PutObject"
  • "DeleteObject"
  • "GetObjectTagging"
  • "PutObjectTagging"
  • "DeleteObjectTagging"
  • "ListBucket"
  • "GetBucketLocation"
  • "ListBucketMultipartUploads"
  • "ListMultipartUploadParts"
  • "AbortMultipartUpload"
  • "PutObjectRetention"
  • "PutObjectLegalHold"
  • "ListAllMyBuckets"
  • "GetObjectAcl"
  • "PutObjectAcl"
  • "GetBucketAcl"
  • "PutBucketAcl"
  • "PutBucketVersioning"
  • "CreateBucket"
  • "DeleteBucket"
Type: const
Specific value: "ALL"
Type: null

Audit Overflow


Overflow behavior for this bucket's audit records, or null to inherit the service's default.

Type: enum (of string)
Must be one of:
  • "DROP"
  • "BACKPRESSURE"
Type: null

Locked


Whether the bucket's dataset is locked. Read only.

Type: boolean
Type: null


Storage tier in which the bucket's dataset is located. This field is read-only; configure the dataset's tier via zfs.tier.dataset_set_tier. NOTE: this is a licensed feature. Will be null if TrueNAS is unlicensed, if tiering is disabled, or if the pool has no SPECIAL vdev.

TierInfo

Type: object
No Additional Properties

Tier Type

Type: enum (of string)

Storage performance tier for this share.

Must be one of:
  • "REGULAR"
  • "PERFORMANCE"

Default: null

Most recent rewrite job for this share's dataset, or null if no job history exists.

Type: object
Type: null
Type: null

SharingS3QueryResultItem

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for the bucket.

Name

Type: string

Bucket name must be three to 63 characters of lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit, no adjacent dots, and not an IP address.

Must match regular expression: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$

Must be at least 3 characters long

Must be at most 63 characters long

Dataset

Type: string

The ZFS dataset of the bucket. The location of S3 data within the dataset depends on the layout field.

Must be at least 1 characters long

Layout

Type: enum (of string)

This create-time mutable field determines where S3 objects are located within the share. If set to BUCKET (the default), then the S3 share is a conventional S3 bucket that supports writes through the S3 protocol. Data must be accessed through the s3data directory inside the dataset. If set to DATASET, then the entire dataset contents are exposed as S3 objects, but S3 protocol access is restricted to read only operations. This setting is available to S3 protocol access to non-S3 data, for example, SMB or NFS shares.

Must be one of:
  • "BUCKET"
  • "DATASET"

Enabled

Type: boolean

Whether the bucket is served. Changing it reloads the S3 service.

Owner

Type: string

Account that owns the bucket and bypasses its grants, owns the s3data directory when the S3 service creates it, and owns every object written under the BUCKET_OWNER_ENFORCED object ownership setting.

Must be at least 1 characters long

Owner Uid

Type: integer

The uid that owns the bucket.

Grants

Type: array

Who may access the bucket and how, beyond its owner.

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

Permissions Model

Type: enum (of string)

How the S3 service treats the filesystem permissions on the bucket's tree. When S3 is set, access is solely determined by the bucket's grants and object ACL if the object_ownership bucket configuration field is not set to BUCKET_OWNER_ENFORCED. In this configuration, filesystem ACLs are not evaluated by the S3 server. When MULTIPROTOCOL is set, filesystem ACLs are enforced in addition to S3 protocol access control mechanisms. S3 shares with DATASET layout default to the MULTIPROTOCOL permissions model.

Must be one of:
  • "S3"
  • "MULTIPROTOCOL"

Object Ownership

Type: enum (of string)

S3 Object Ownership, the bucket-level setting that controls ownership of objects uploaded to the bucket and disables or enables ACLs, and what GetBucketOwnershipControls reports. BUCKET_OWNER_ENFORCED (the default): ACLs are disabled, and the bucket owner automatically owns and has full control over every object in the bucket. ACLs no longer affect permissions to data in the bucket, and the bucket uses its grants to define access control. Requests to set or update ACLs fail with AccessControlListNotSupported; requests to read ACLs are supported. Only uploads with bucket owner full control ACLs, or uploads that do not specify an ACL, are accepted. BUCKET_OWNER_PREFERRED: the bucket owner owns and has full control over new objects that other accounts write to the bucket with the bucket-owner-full-control canned ACL. Objects uploaded with other ACLs are owned by the writing account. ACLs can be updated and can grant permissions. OBJECT_WRITER: the account that uploads an object owns the object, has full control over it, and can grant other users access to it through ACLs. A MULTIPROTOCOL bucket is always OBJECT_WRITER whatever is given here, and its ACLs stay disabled: the other protocols' users own the filesystem permissions on the tree.

Must be one of:
  • "BUCKET_OWNER_ENFORCED"
  • "BUCKET_OWNER_PREFERRED"
  • "OBJECT_WRITER"

Versioning

Type: enum (of string)

Bucket versioning state. One-way: a bucket that has been ENABLED or SUSPENDED cannot return to OFF here, only move between those two, so its stored versions never go unreachable. sharing.s3.force_disable_versioning is the one destructive way back, and it destroys every prior object version. NOTE: this is a licensed feature.

Must be one of:
  • "OFF"
  • "ENABLED"
  • "SUSPENDED"

Snapshot Versions

Type: array of string

Patterns over the names of the bucket dataset's ZFS snapshots, * and ? the only metacharacters, each matched against a whole name. Every snapshot a pattern selects serves each object's state frozen in it as a read-only version: listed by ListObjectVersions and read by its version id. Empty serves none. Requires versioning to be ENABLED or SUSPENDED.

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

Must be at least 1 characters long

Snapshot Versions Max

Type: integer

How many of the newest selected snapshots one ListObjectVersions listing consults. Bounds the listing alone: a selected snapshot beyond it still serves by its version id.

Value must be greater or equal to 1 and lesser or equal to 4294967295

Multipart Etag

Type: enum (of string)

ETag format for objects created by multipart upload. MINTED gives the object an opaque token. COMPOSITE gives it the standard S3 multipart ETag, built from the MD5 of each part. Choose COMPOSITE if a client verifies or resumes uploads by computing that ETag itself and comparing.

Must be one of:
  • "COMPOSITE"
  • "MINTED"

Object Lock

Type: boolean

Whether object lock is enabled. Requires versioning to be ENABLED and a permissions model other than MULTIPROTOCOL: a locked bucket is the S3 service's alone. One-way: the lock is latched on the bucket's dataset and cannot be disabled once enabled. NOTE: this is a licensed feature.

Object Lock Default Mode


Retention mode of the default object lock rule, or null for no default rule.

Type: enum (of string)
Must be one of:
  • "GOVERNANCE"
  • "COMPLIANCE"
Type: null

Object Lock Default Days


Retention period of the default object lock rule in days, up to 36500 (a hundred years).

Type: integer

Value must be greater or equal to 1 and lesser or equal to 36500

Type: null

Audit


Actions audited on this bucket, ALL, or an empty list to audit nothing. null inherits the service's default_audit. CreateBucket and ListAllMyBuckets never match here — the service default_audit governs both — while DeleteBucket does match this bucket's own deletion. NOTE: this is a licensed feature.

Type: array of enum (of string)
No Additional Items
Each item of this array must be:
Type: enum (of string)
Must be one of:
  • "GetObject"
  • "PutObject"
  • "DeleteObject"
  • "GetObjectTagging"
  • "PutObjectTagging"
  • "DeleteObjectTagging"
  • "ListBucket"
  • "GetBucketLocation"
  • "ListBucketMultipartUploads"
  • "ListMultipartUploadParts"
  • "AbortMultipartUpload"
  • "PutObjectRetention"
  • "PutObjectLegalHold"
  • "ListAllMyBuckets"
  • "GetObjectAcl"
  • "PutObjectAcl"
  • "GetBucketAcl"
  • "PutBucketAcl"
  • "PutBucketVersioning"
  • "CreateBucket"
  • "DeleteBucket"
Type: const
Specific value: "ALL"
Type: null

Audit Overflow


Overflow behavior for this bucket's audit records, or null to inherit the service's default.

Type: enum (of string)
Must be one of:
  • "DROP"
  • "BACKPRESSURE"
Type: null

Locked


Whether the bucket's dataset is locked. Read only.

Type: boolean
Type: null


Storage tier in which the bucket's dataset is located. This field is read-only; configure the dataset's tier via zfs.tier.dataset_set_tier. NOTE: this is a licensed feature. Will be null if TrueNAS is unlicensed, if tiering is disabled, or if the pool has no SPECIAL vdev.

Type: object
Type: null
Type: integer


Required roles: SHARING_S3_READ