# Core Settings

LLMS index: [llms.txt](/llms.txt)

---

<a id="core-settings"></a>
<a id="minio-server-envvar-core"></a>

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

You can establish or modify settings by defining:

- an *environment variable* on the host system prior to starting or restarting the MinIO Server. Refer to your operating system’s documentation for how to define an environment variable.
- a *configuration setting* using [`mc admin config set`](/reference/minio-mc-admin/mc-admin-config/#mc.admin.config.set).

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

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

> [!WARNING]
> **Important**
>
> Each configuration setting controls fundamental MinIO behavior and functionality. MinIO **strongly recommends** testing configuration changes in a lower environment, such as DEV or QA, before applying to production.

## MinIO Server CLI Options {#minio-server-cli-options}

**Environment Variable**

#### `MINIO_OPTS` {#envvar.MINIO_OPTS}

*envvar*

**Configuration Setting**

There is no configuration setting for this variable, as these settings apply at server startup.

*Optional*

Set a string of [parameters](/reference/minio-server/#minio-server-parameters) to use when starting the MinIO Server.

For Unix-like systems using the recommended MinIO `systemd` service, use the `/etc/default/minio` file and create an environment variable `MINIO_OPTS` for specifying parameters to append to the `minio` systemd process:

```shell
# Editing /etc/default/minio

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

For systems running `minio` on the command line, `MINIO_OPTS` is optional. To use it, declare the environment variable using standard shell semantics, then reference the environment variable when starting up the MinIO Server:

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

minio server $MINIO_OPTS ...

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

> [!WARNING]
> **Important**
>
> The `minio server` command does not read `$MINIO_OPTS` directly. The variable only functions if used as described above.

## Storage Volumes {#storage-volumes}

**Environment Variable**

#### `MINIO_VOLUMES` {#envvar.MINIO_VOLUMES}

*envvar*

The directories or drives the [`minio server`](/reference/minio-server/#command-minio.server) process uses as the storage backend.

Functionally equivalent to setting [`minio server DIRECTORIES`](/reference/minio-server/#minio.server.DIRECTORIES). Use this value when configuring MinIO to run using an environment file.

**Configuration Setting**

This setting does not have a configuration setting option.

## Environment Variable File Path {#environment-variable-file-path}

**Environment Variable**

#### `MINIO_CONFIG_ENV_FILE` {#envvar.MINIO_CONFIG_ENV_FILE}

*envvar*

Specifies the full path to the file the MinIO server process uses for loading environment variables.

For `systemd`-managed files, set this value to the path of the environment file (`/etc/default/minio`) to direct MinIO to reload changes to that file when using [`mc admin service restart`](/reference/minio-mc-admin/mc-admin-service/#mc.admin.service.restart) to restart the deployment.

**Configuration Setting**

This setting does not have a configuration setting option.

## Workers for Expiration {#workers-for-expiration}

**Environment Variable**

#### `MINIO_ILM_EXPIRY_WORKERS` {#envvar.MINIO_ILM_EXPIRY_WORKERS}

*envvar*

Specifies the number of workers to make available to expire objects configured with ILM rules for expiration. When not set, MinIO defaults to using up to half of the available processing cores available.

**Configuration Setting**

This setting does not have a configuration setting option.

## Domain {#domain}

**Environment Variable**

#### `MINIO_DOMAIN` {#envvar.MINIO_DOMAIN}

*envvar*

Enables Virtual Host-style requests to the MinIO deployment. Set the value to the Fully Qualified Domain Name (FQDN) for MinIO to accept incoming virtual host requests.

Omitting this setting directs MinIO to only accept the default path-style requests.

For example, consider a MinIO deployment with an assigned FQDN of `minio.example.net`.

- With path-style lookups, applications can access the bucket using its full path as `minio.example.net/mybucket`.
- With virtual-host lookups, application can access the bucket as a virtual host as `mybucket.minio.example.net/`.

> [!WARNING]
> **Important**
>
> If you configure `MINIO_DOMAIN`, you **must** consider all subdomains of the specified FQDN as exclusively assigned for use as bucket names. Any MinIO services which conflict with those domains, such as replication targets, may exhibit unexpected or undesired behavior as a result of the collision.
>
> For example, if setting `MINIO_DOMAIN=minio.example.net`, you **cannot** assign any subdomains of `minio.example.net` (in the form of `*.minio.example.net`) to any MinIO service or target. This includes hostnames for use with [bucket](/administration/bucket-replication/#minio-bucket-replication), [batch](/administration/batch-framework-job-replicate/#minio-batch-framework-replicate-job), or [site replication](/operations/replication/multi-site-replication/#minio-site-replication-overview).

**Configuration Setting**

This setting does not have a configuration setting option.

<a id="minio-scanner-speed-options"></a>

## Scanner Speed {#scanner-speed}

**Environment Variable**

#### `MINIO_SCANNER_SPEED` {#envvar.MINIO_SCANNER_SPEED}

*envvar*

**Configuration Setting**

#### `scanner speed` {#mc-conf.scanner.speed}

*mc-conf*

Manage the maximum wait period for the [scanner](/operations/concepts/scanner/#minio-concepts-scanner) when balancing MinIO read/write performance to scanner processes.

MinIO utilizes the [scanner](/operations/concepts/scanner/#minio-concepts-scanner) for [bucket replication](/administration/bucket-replication/#minio-bucket-replication), [site replication](/operations/replication/multi-site-replication/#minio-site-replication-overview), [lifecycle management](/administration/object-management/object-lifecycle-management/#minio-lifecycle-management), and [healing](/operations/concepts/healing/#minio-concepts-healing) tasks.

Valid values include:

<table>
  <tbody>
    <tr>
      <td><p><code>fastest</code></p></td>
      <td><p>Removes scanner wait on read/write latency, allowing the scanner to operate at full-speed and IOPS consumption.
This setting may result in reduced read and write performance.</p></td>
    </tr>
    <tr>
      <td><p><code>fast</code></p></td>
      <td><p>Sets a short scanner wait time on read/write latency, allowing the scanner to operate at a higher speed and IOPS consumption.
This setting may result in reduced read and write performance.</p></td>
    </tr>
    <tr>
      <td><p><code>default</code></p></td>
      <td><p>Sets a moderate scanner wait time on read/write latency, allowing the scanner to operate at a balanced speed and IOPS consumption.
This setting seeks to maintain read and write performance while allowing ongoing scanner activity.</p></td>
    </tr>
    <tr>
      <td><p><code>slow</code></p></td>
      <td><p>Sets a medium scanner wait time on read/write latency, where the scanner operates at a reduced speed and IOPS consumption.
This setting allows better read and write performance while reducing scanner performance.</p><p>May impact scanner-dependent features, such as lifecycle management and replication.</p></td>
    </tr>
    <tr>
      <td><p><code>slowest</code></p></td>
      <td><p>Sets a large scanner wait time on read/write latency, where the scanner operates at a substantially lower speed and IOPS consumption.
This setting prioritizes read and write operations at the potential cost of scanner operations.</p><p>May impact scanner-dependent features, such as lifecycle management and replication.</p></td>
    </tr>
  </tbody>
</table>

## Batch Replication {#batch-replication}

**Configuration Setting**

This setting does not have a configuration setting option.

## Data Compression {#data-compression}

The following section documents settings for enabling data compression for objects. See [Data Compression](/administration/object-management/data-compression/#minio-data-compression) for tutorials on using these configuration settings.

All of the settings in this section fall under the following top-level key:

#### `compression` {#mc-conf.compression}

*mc-conf*

### Enable Compression {#enable-compression}

**Environment Variable**

##### `MINIO_COMPRESSION_ENABLE` {#envvar.MINIO_COMPRESSION_ENABLE}

*envvar*

**Configuration Setting**

##### `compression enable` {#mc-conf.compression.enable}

*mc-conf*

*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 {#allow-encryption}

**Environment Variable**

##### `MINIO_COMPRESSION_ALLOW_ENCRYPTION` {#envvar.MINIO_COMPRESSION_ALLOW_ENCRYPTION}

*envvar*

**Configuration Setting**

##### `compression allow_encryption` {#mc-conf.compression.allow_encryption}

*mc-conf*

*Optional*

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

> [!NOTE]
> **Encrypting compressed objects may compromise security**
>
> MinIO strongly recommends against encrypting compressed objects. If you require encryption, carefully evaluate the risk of potentially leaking information about the contents of encrypted objects.

### Compression Extensions {#compression-extensions}

**Environment Variable**

##### `MINIO_COMPRESSION_EXTENSIONS` {#envvar.MINIO_COMPRESSION_EXTENSIONS}

*envvar*

**Configuration Setting**

##### `compression extensions` {#mc-conf.compression.extensions}

*mc-conf*

*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"`.

> [!NOTE]
> **Changed: RELEASE.2024-03-15T01-07-19Z**
>
> Specify `"*"` to direct MinIO to compress all supported file types.

MinIO does not support compressing file types on the [Excluded File Types](/administration/object-management/data-compression/#minio-data-compression-excluded-types) list, even if explicitly specified in this argument.

### Compression MIME Types {#compression-mime-types}

**Environment Variable**

##### `MINIO_COMPRESSION_MIME_TYPES` {#envvar.MINIO_COMPRESSION_MIME_TYPES}

*envvar*

**Configuration Variable**

##### `compression mime_types` {#mc-conf.compression.mime_types}

*mc-conf*

*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"`.

> [!NOTE]
> **Default excluded files**
>
> Some types of files cannot be significantly reduced in size. MinIO will *not* compress these, even if specified in an [`mime_types`](#mc-conf.compression.mime_types) argument. See [Excluded types](/administration/object-management/data-compression/#minio-data-compression-excluded-types) for details.

### Comments {#comments}

**Environment Variable**

This setting does not have an environment variable option. Use the configuration setting instead.

**Configuration Setting**

##### `compression comment` {#envvar.compression.comment}

*envvar*

*Optional*

Specify a comment to associate with the data compression configuration.

## Erasure Stripe Size {#erasure-stripe-size}

**Environment Variable**

#### `MINIO_ERASURE_SET_DRIVE_COUNT` {#envvar.MINIO_ERASURE_SET_DRIVE_COUNT}

*envvar*

**Configuration Variable**

This setting does not have a configuration setting option.

*Optional*

The [erasure set size](/operations/concepts/erasure-coding/#minio-ec-basics) to apply for all drives in a given [server pool](/glossary/#term-server-pool).

If you set this value, you **must** do so *before* you initialize the cluster The selected stripe size is **immutable** after the cluster has been initialized and affects any future server pools added to the cluster.

[MinIO SUBNET](https://min.io/pricing?jmp=docs) users should log in and open an issue to discuss stripe size settings prior to implementing them in any environment.

> [!CAUTION]
> **Warning**
>
> **Do not** change the stripe size setting unless directed to by MinIO engineering.
>
> Changes to stripe size have significant impact to deployment functionality, availability, performance, and behavior. MinIO’s stripe selection algorithms set appropriate defaults for the majority of workloads. Changing the stripe size from this default is unusual and generally not necessary or advised.

## Maximum Object Versions {#maximum-object-versions}

**Environment Variable**

#### `MINIO_API_OBJECT_MAX_VERSIONS` {#envvar.MINIO_API_OBJECT_MAX_VERSIONS}

*envvar*

**Configuration Setting**

#### `api object_max_versions` {#mc-conf.api.object_max_versions}

*mc-conf*

*Optional*

Defines the default maximum versions to allow per object.

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

> [!NOTE]
> **Note**
>
> MinIO versions from `RELEASE.2023-08-04T17-40-21Z` to `RELEASE.2024-03-26T22-10-45Z` had a default limit of 10,000 object versions. This setting can be used to override that limit to another value.

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.

## Client Source Address Trust {#client-source-address-trust}

**Environment Variable**

#### `MINIO_API_TRUSTED_PROXIES` {#envvar.MINIO_API_TRUSTED_PROXIES}

*envvar*

Specifies which peers may tell the server where a request came from.

By default MinIO believes the `X-Forwarded-For`, `X-Real-IP` and RFC 7239 `Forwarded` headers from any peer, so a client with direct network access to the API port can set its own apparent source address. That address feeds `aws:SourceIp` policy conditions, the audit log `remotehost` field, and event notification `Host` fields.

Set this to a comma-separated list of addresses or CIDR blocks to believe forwarded headers **only** from those peers. The forwarding chain is then read right to left past listed hops, which also discards the client-supplied left-most entry that an appending proxy leaves in place — the stock nginx `$proxy_add_x_forwarded_for` recipe and HAProxy's added second header line both produce one.

Set this to `none` to believe no forwarding header at all and always use the peer address.

> [!NOTE]
> **Note**
>
> Unset is the default and preserves the historical behaviour, so this setting is inert until you configure it.
>
> List **the proxies themselves, not the subnet they sit in.** Listed entries are skipped while walking the chain, so a range that also covers clients lets those clients forge. Multi-node deployments must include their own node addresses, because MinIO forwards some requests between nodes. Loopback is always trusted as a peer so FTP and SFTP keep attributing their sessions. A malformed value, or one that names no proxy at all, stops startup.

If you use `IpAddress` or `NotIpAddress` policy conditions, they are not enforceable until this setting names your proxies, or the deployment is otherwise unreachable except through them.

**Configuration Setting**

This setting does not have a configuration setting option.

## Legacy Bucket Resource Matching {#legacy-bucket-resource-matching}

**Environment Variable**

#### `MINIO_API_LEGACY_BUCKET_RESOURCE_MATCH` {#envvar.MINIO_API_LEGACY_BUCKET_RESOURCE_MATCH}

*envvar*

Set to `on` to restore the historical matching of IAM policy resources for bucket-level requests.

By default, twelve bucket-level write actions are not authorized through an object-only resource pattern such as `arn:aws:s3:::mybucket/*`. See [Bucket and Object Resources](/administration/identity-access-management/policy-based-access-control/#bucket-and-object-resources) for the action list and for the policy change that grants them properly.

Setting this to `on` returns to matching bucket-level requests against the string `mybucket/`, which an object pattern also matches. It is read once at startup and is intended as a temporary measure while stored policies are updated.

> [!WARNING]
> **This restores an over-grant**
>
> The historical matching is what allowed a principal holding only `s3:*` on `arn:aws:s3:::mybucket/*` to rewrite the bucket policy — including making the bucket public — or to delete the bucket. The switch is all-or-nothing: enabling it for one action reopens all twelve.

**Configuration Setting**

This setting does not have a configuration setting option.