Core Settings

This page covers settings that control core behavior of the MinIO AIStor process.

You can establish or modify settings by defining:

• an environment variable on the host system prior to starting or restarting the AIStor Server. Refer to your operating system’s documentation for how to define an environment variable.
• a configuration setting using mc admin config set.

If you define both an environment variable and the similar configuration setting, MinIO AIStor uses the environment variable value.

Some settings have only an environment variable or a configuration setting, but not both.

Server CLI options

# Editing /etc/default/minio

MINIO_OPTS=' --console-address=":9001" --ftp="address=:8021" --ftp="passive-port-range=30000-40000" '

export MINIO_ARGS=' --console-address=":9001" --ftp="address=:8021" --ftp="passive-port-range=30000-40000" '

minio server ...

# The above is equivalent to running the following:
# minio server --console-address=":9001" \
#              --ftp="address=:8021"     \
#              --ftp="passive-port-range=30000-40000"

MinIO AIStor license

Storage volumes

Address

Console Address

Environment variable file path

Domain

Configure virtual-host-style requests

Setting MINIO_DOMAIN alone is not sufficient. Because each bucket is addressed as a subdomain of the configured domain (mybucket.minio.example.net), the surrounding DNS and TLS configuration must also resolve and secure those subdomains.

To support virtual-host-style addressing for a domain such as minio.example.net:

1. Set MINIO_DOMAIN on every MinIO AIStor node.

   Set the environment variable to the domain (or comma-separated list of domains) on each server in the deployment and restart the nodes so the setting takes effect.

   export MINIO_DOMAIN=minio.example.net

2. Create a wildcard DNS record.

   Add a wildcard DNS entry that resolves *.minio.example.net to the deployment (or to the load balancer in front of it), in addition to the existing record for the bare minio.example.net domain. Without the wildcard record, requests to mybucket.minio.example.net cannot reach the deployment.

3. Use a TLS certificate that covers the wildcard domain.

   Virtual-host-style requests are sent to bucket subdomains, so the TLS certificate presented by MinIO AIStor (or by the load balancer terminating TLS) must include both the bare domain and the wildcard domain in its Subject Alternative Name (SAN) list:

   • minio.example.net
   • *.minio.example.net

   A certificate issued only for minio.example.net causes TLS hostname-verification errors when clients connect to mybucket.minio.example.net. Wildcard certificates match only a single label, so a nested path such as mybucket.sub.minio.example.net is not covered.

4. Configure any load balancer or proxy to forward the wildcard host.

   If a load balancer or reverse proxy sits in front of the deployment, configure it to route *.minio.example.net to the MinIO AIStor nodes and to preserve the original Host header so MinIO AIStor can resolve the bucket from the request.

After completing these steps, applications can address buckets either by path (minio.example.net/mybucket) or as a virtual host (mybucket.minio.example.net).

Scanner speed

Data compression

The following section documents settings for enabling data compression for objects. See Data Compression for tutorials on using these configuration settings.

All of the settings in this section fall under the compression top-level key.

Enable compression

Optional

Set to on to enable data compression for new objects. Defaults to off.

Enabling or disabling data compression does not change existing objects.

Allow encryption

Optional

Set to on to encrypt objects after compressing them. Defaults to off.

Compression extensions

Optional

Comma-separated list of the file extensions to compress. Setting a new list of file extensions replaces the previously configured list. Defaults to ".txt, .log, .csv, .json, .tar, .xml, .bin".

Specify "*" to direct MinIO AIStor to compress all supported file types.

MinIO AIStor does not support compressing file types on the Excluded File Types list, even if explicitly specified in this argument.

Compression MIME types

Optional

Comma-separated list of the MIME types to compress. Setting a new list of types replaces the previously configured list. Defaults to "text/*, application/json, application/xml, binary/octet-stream".

Comments

Optional

Specify a comment to associate with the data compression configuration.

Erasure set drive count

Maximum drive usage

Optional

The maximum percentage of drive capacity that can be used before MinIO AIStor returns HTTP 507 (Insufficient Storage) errors for new write operations.

Specify a value between 50 and 99. Defaults to 99.

When drive usage exceeds this threshold, the following operations return 507 errors:

• Single object uploads (PUT)
• Multipart uploads
• Copy operations
• Append operations

Other operations continue normally, including:

• Healing
• Decommissioning
• Rebalancing
• Listing operations
• Metadata updates

This setting helps prevent drives from becoming completely full, which can cause operational issues.

Requires AIStor Server RELEASE.2026-02-02T23-40-11Z or later.

Drive operation timeout

Optional

The maximum time to wait for a single drive operation to complete. Defaults to 30s.

Specify a Go duration string (for example, 30s, 1m, 2m30s). The minimum duration allowed is 1s.

Increase this value for deployments with slower storage (such as HDDs) or high-latency network-attached storage. Decrease this value to fail faster on unresponsive drives.

Drive pre-allocation

Optional

Enables file pre-allocation using posix_fallocate when writing objects. Defaults to off.

Set to on to pre-allocate disk space before writing data. This can reduce fragmentation on some filesystems and improve write performance for large objects.

Maximum object versions

Optional

Defines the default maximum versions to allow per object.

By default, MinIO AIStor allows up to the maximum value of an Int64 versions per object, or over 9.2 quintillion.

Arbitrarily high versions per objects may cause performance degradation on some operations, such as LIST. This is especially true on systems running budget hardware or spinning drives (HDD). Applications or workloads which produce thousands or more versions per object may require design or architecture review to mitigate potential performance degradations.

Setting a limit of no more than 100 should provide enough versions for most typical use cases.

Cross-origin resource sharing (CORS)

Cross-Origin Resource Sharing (CORS) is a browser security mechanism that controls which web domains can access your object storage from client-side JavaScript. When a web application running on one domain attempts to access objects in MinIO AIStor from a different domain, the browser checks CORS policies to determine if the request should be allowed. See the Mozilla CORS documentation for more information.

MinIO AIStor supports two levels of CORS configuration:

• Global CORS: Applies to all API endpoints and buckets using server-level settings
• Bucket-specific CORS: Fine-grained control per bucket with up to 100 rules using mc cors commands

Bucket-level CORS configurations override the global settings.

Global CORS allowed origins

Optional

Specify a comma-separated list of origins allowed to access the MinIO AIStor deployment. Defaults to * (all origins).

When set to *, MinIO AIStor allows requests from any origin. For production deployments, specify explicit origins for better security.

Allow credentials with wildcard origins

Optional

Controls whether credentials are allowed when wildcard origin (*) is configured. Defaults to on for backwards compatibility.

When set to on and cors_allow_origin is *, MinIO AIStor echoes back the requesting origin with Access-Control-Allow-Credentials: true. While browsers accept this, it does not follow the CORS specification correctly.

When set to off, MinIO AIStor does not return the Access-Control-Allow-Origin header for wildcard configurations, providing stricter CORS compliance.

O_DIRECT writes

Control O_DIRECT behavior for read and write operations. O_DIRECT bypasses the operating system page cache, reading from and writing directly to the disk.

Valid values:

• on or read+write - Enable O_DIRECT for both reads and writes.
• read - Enable O_DIRECT for reads only. Writes go through the page cache.
• write - Enable O_DIRECT for writes only. Reads go through the page cache.
• off - Disable O_DIRECT for both reads and writes.

The default value is on.

Root access

Enable or disable root credential access for all API calls, including S3 and admin operations.

Valid values are on or off.

The default value is on.

Synchronous events

Enable synchronous bucket notifications. When enabled, MinIO AIStor waits for notification delivery before completing the API response.

Valid values are on or off.

The default value is off.

Thread pressure check

Enable or disable thread pressure monitoring for health endpoints. When enabled, MinIO AIStor tracks goroutine usage relative to system limits and can report health degradation through health check responses.

Valid values are on or off.

The default value is on.

Thread pressure warning threshold

Set the thread pressure warning threshold as a ratio between 0 and 1. When thread usage exceeds this ratio of the system limit, MinIO AIStor logs a warning.

The default value is 0.50.

Thread pressure critical threshold

Set the thread pressure critical threshold as a ratio between 0 and 1. When thread usage exceeds this ratio, health endpoints return HTTP 429 (Too Many Requests).

The default value is 0.85.

Maximum concurrent API requests

Optional

Set the maximum number of concurrent S3 and admin API requests allowed across all nodes of the cluster. The configured value is divided across the total node count to size each node’s per-node request pool.

The default value is auto, where MinIO AIStor automatically calculates the limit based on available host RAM. See Memory Requirements for the formula used to derive the per-node limit.

Set an explicit integer to override the auto-derived limit. Reducing the concurrent request limit is a common tuning step for deployments using spinning (HDD) drives with high-concurrency workloads, where converting random I/O into sequential I/O improves drive efficiency.

mc admin config set ALIAS api requests_max=1600
mc admin service restart ALIAS

Or set the equivalent environment variable:

export MINIO_API_REQUESTS_MAX=1600

List quorum

Optional

Set the minimum acceptable quorum for list operations.

Valid values are optimal, reduced, disk, strict, and auto.

The default value is strict.

Stale multipart upload expiry

Optional

Set the duration after which an in-progress multipart upload with no activity is considered stale and eligible for automatic cleanup. Accepts a Go duration string such as 24h.

The default value is 24h.

Stale multipart upload cleanup interval

Optional

Set how often MinIO AIStor scans for and removes stale multipart uploads. Accepts a Go duration string such as 6h.

The default value is 6h.

POST policy clock skew

Optional

Set how far in the past a POST policy expiration may be and still be accepted. Accepts a non-negative Go duration string such as 15m. A negative value is rejected at startup.

The default value is 0s, which matches Amazon S3: an expired policy is refused.

Raise this only to tolerate clients whose clocks lag or whose signatures are cached. Because the value extends the window in which a signed policy stays usable, keep it as small as the affected clients allow.

Cluster readiness deadline

Optional

Set the deadline for the cluster readiness check. Accepts a Go duration string such as 10s.

The default value is 10s.

Remote transport deadline

Optional

Set the deadline for API requests on remote transports while proxying between federated instances. Accepts a Go duration string such as 2h.

The default value is 2h.

Trash cleanup interval

Optional

Set how often MinIO AIStor permanently deletes objects from the .trash folder. Accepts a Go duration string such as 5m.

The default value is 5m.

Trusted upstream proxies

Optional

Specify a comma-separated list of upstream proxy IPs or CIDRs whose X-Forwarded-For, X-Real-IP, and RFC 7239 Forwarded headers are honored when deriving the client source IP. The derived source IP is used to evaluate aws:SourceIp IAM and bucket-policy conditions.

Accepted values:

• An empty value (the legacy default) trusts all proxies. This preserves backward compatibility but allows any authenticated caller to spoof their source IP by injecting a forged forwarded header.
• - trusts no proxies. Forwarded headers are ignored entirely and the immediate TCP peer is always used as the source IP. Use this when no reverse proxy sits in front of MinIO AIStor.
• A comma-separated list of IPs or CIDRs trusts only those peers. The X-Forwarded-For chain is walked right-to-left, and the first hop outside the trusted set becomes the source IP. Requests from untrusted peers are not rejected; they simply cannot dictate the source IP.

Remote NTP server

Optional

Set a remote NTP server endpoint used as the time source instead of the system clock when computing object-lock and retention dates.

By default, MinIO AIStor uses the server’s system time to compute retention dates.

Parquet S3 Select

Optional

Enable S3 Select support for Parquet-formatted objects.

The default value is off as a security mitigation, since hostile crafted Parquet input can crash the server. While disabled, the server rejects Parquet queries with the error parquet format parsing not enabled on server.

Set to on to enable Parquet S3 Select queries. Only enable this in controlled environments where it is safe to assume no hostile content can be uploaded to the cluster.

Extended object naming

Optional