s3.update

Update the S3 service configuration.

Changing the listeners, the reactor thread count or the region restarts the S3 service, draining in-flight requests for up to 30 seconds. Every other change applies with a reload, the certificate included: a different one, or the UI certificate changing while the service follows it, rotates in place.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: data

data

Type: object

S3 service configuration changes to apply.

 No Additional Properties

Listeners

Type: array of object

Where the S3 service listens, at most eight entries, each an address and port served in plaintext or over TLS. An empty list listens on every address on port 9000 in plaintext. Changing it restarts the service.

 No Additional Items
Each item of this array must be:

S3Listener

Type: object
No Additional Properties

Address

Type: string

IP address to listen on, from s3.bindip_choices: a static address, a loopback or a wildcard.

Must be at least 1 characters long

Port

Type: integer Default: 9000

TCP port to listen on.

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

Tls

Type: boolean Default: false

Serve this address over TLS with certificate, which must then be set. Plaintext otherwise. A multi-homed system may serve a storage network in the clear and a management network over TLS.

Servers

Type: integer

Reactor threads serving the listen addresses, each with its own io_uring ring and every address shared between them. At most eight, and no more than the system has CPUs. Each thread carries its own connection pool and buffering, so more of them cost memory. Changing it restarts the service.

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

Certificate


ID of the certificate the TLS listeners serve. null serves them with the UI certificate (system.general.ui_certificate), so a renewal or a change there reaches the S3 service too.

Type: integer
Type: null

Region

Type: string

Region name echoed to clients. Empty accepts whatever a client signs for.

Log Level

Type: enum (of string)

Least serious log record the S3 service keeps. INFO adds one record per request.

Must be one of:
  • "ERROR"
  • "WARNING"
  • "NOTICE"
  • "INFO"
  • "DEBUG"

Default Audit


Actions audited on every bucket that does not set its own audit, or ALL. An empty list audits nothing. Requires an Enterprise license.

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"
Type: const
Specific value: "ALL"

Default Audit Overflow

Type: enum (of string)

What an audited request gets when no audit record slot is free, on buckets that do not set their own. DROP sheds the record, BACKPRESSURE answers the client with a retryable 503.

Must be one of:
  • "DROP"
  • "BACKPRESSURE"

Global Grants

Type: array of object

Grants that apply to every bucket, replacing the current list.

 No Additional Items
Each item of this array must be:

S3Grant

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"

S3Entry

Type: object

The updated S3 service configuration.

 No Additional Properties

Id

Type: integer

Placeholder identifier. Not used as there is only one.

Listeners

Type: array of object Default: []

Where the S3 service listens, at most eight entries, each an address and port served in plaintext or over TLS. An empty list listens on every address on port 9000 in plaintext. Changing it restarts the service.

 No Additional Items
Each item of this array must be:

S3Listener

Type: object
No Additional Properties

Address

Type: string

IP address to listen on, from s3.bindip_choices: a static address, a loopback or a wildcard.

Must be at least 1 characters long

Port

Type: integer Default: 9000

TCP port to listen on.

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

Tls

Type: boolean Default: false

Serve this address over TLS with certificate, which must then be set. Plaintext otherwise. A multi-homed system may serve a storage network in the clear and a management network over TLS.

Servers

Type: integer Default: 1

Reactor threads serving the listen addresses, each with its own io_uring ring and every address shared between them. At most eight, and no more than the system has CPUs. Each thread carries its own connection pool and buffering, so more of them cost memory. Changing it restarts the service.

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

Certificate

Default: null

ID of the certificate the TLS listeners serve. null serves them with the UI certificate (system.general.ui_certificate), so a renewal or a change there reaches the S3 service too.

Type: integer
Type: null

Region

Type: string Default: ""

Region name echoed to clients. Empty accepts whatever a client signs for.

Log Level

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

Least serious log record the S3 service keeps. INFO adds one record per request.

Must be one of:
  • "ERROR"
  • "WARNING"
  • "NOTICE"
  • "INFO"
  • "DEBUG"

Default Audit

Default: []

Actions audited on every bucket that does not set its own audit, or ALL. An empty list audits nothing. Requires an Enterprise license.

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"
Type: const
Specific value: "ALL"

Default Audit Overflow

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

What an audited request gets when no audit record slot is free, on buckets that do not set their own. DROP sheds the record, BACKPRESSURE answers the client with a retryable 503.

Must be one of:
  • "DROP"
  • "BACKPRESSURE"

Global Grants

Type: array of object Default: []

Grants that apply to every bucket. A DENY here suspends the principal everywhere, outranking every bucket grant. Listing buckets never needs one of these.

 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.


Required roles: SHARING_S3_WRITE