Startup Configuration File

MinIO AIStor supports using a YAML-formatted configuration file for specifying startup server parameters. The configuration file supports specific advanced deployment patterns, such as distributed clusters with non-sequential hostnames, heterogeneous hostname patterns, and multi-NIC internode communication.

Example config.yaml

The following example configuration lists all available fields and example values. Remove any parameters you do not need.

version: v3

# Core settings
address: ":9000"
consoleAddress: ":9001"
rootUser: "minioadmin"
rootPassword: "secret-CHANGE-ME"
license: "/path/to/license.minio"
certsDir: "/etc/minio/certs"

# Behavior settings
api: "S3"
objectNaming: "safe"

# Network tuning
network:
  idleTimeout: "15s"
  readHeaderTimeout: "5s"
  connUserTimeout: "10m"
  dnsCacheTTL: "1h"
  maxIdleConnsPerHost: 2048
  sendBufSize: 4194304
  recvBufSize: 4194304
  writeBufSize: 65536
  readBufSize: 65536

# Storage configuration
storage:
  lazyAccessTime: "24h"

# Logging
log:
  json: false
  dir: ""
  size: 10485760
  compress: false

# FTP server configuration
ftp:
  address: ":8021"
  passivePortRange: "30000-40000"

# SFTP server configuration
sftp:
  address: ":8022"
  sshPrivateKey: "/etc/minio/sftp-key"

# Storage pools
pools:
  - nodes:
      - addresses:
          - "https://rack{1,3,5,7}.example.com:9000"
        path: "/mnt/disk{1...4}"
  - nodes:
      - addresses:
          - "https://rack{2,4,6,8}.example.com:9000"
        path: "/mnt/disk{1...4}"

Minimal configuration example

version: v3
rootUser: "minioadmin"
rootPassword: "secret-CHANGE-ME"
address: ":9000"
pools:
  - nodes:
      - addresses:
          - "https://server{1...4}:9000"
        path: "/mnt/disk{1...4}/"

Parameters

Core settings

The configuration file must include the version and pools fields. All other fields are optional.

Behavior settings

Network configuration

The network object configures network behavior and timeouts. All fields are optional.

Duration values support standard Go duration formats (for example, 30s, 10m, 1h).

Log configuration

The log object configures logging behavior. All fields are optional.

Storage configuration

The storage object configures storage behavior. All fields are optional.

FTP configuration

The ftp object configures the optional FTP server. See File Transfer Protocol for more information.

SFTP configuration

The sftp object configures the optional SFTP server. See File Transfer Protocol for more information.

Pools

The pools field defines the storage pools in the deployment. Each pool contains one or more node definitions with address and path patterns. Ellipsis notation {n...m} is supported in both addresses and paths.

v3 format (recommended)

In v3, each pool contains a nodes array. Each node definition has addresses (one or more NIC address patterns) and a path (disk path pattern).

pools:
  - nodes:
      - addresses:
          - "https://rack{1...4}.example.com:9000"
        path: "/mnt/disk{1...4}"
    setDriveCount: 4

When multiple addresses are listed per node, MinIO AIStor automatically configures multi-NIC internode communication.

You can mix explicit and ellipsis definitions within the same pool:

pools:
  - nodes:
      - addresses:
          - "https://192.168.10.11:9000"
        path: "/mnt/disk{1...4}/"
      - addresses:
          - "https://192.168.10.{12...14}:9000"
        path: "/mnt/disk{1...4}/"
    setDriveCount: 4

v2 format (legacy)

In v2, each pool uses an args array where each element combines the address and path in a single URL string. v2 configurations are auto-migrated to v3 on startup.

pools:
  - args:
      - "https://rack2.example.com:9000/mnt/disk{1...4}"
      - "https://rack4.example.com:9000/mnt/disk{1...4}"
      - "https://198.51.100.10:9000/mnt/disk{1...8}"
      - "https://203.0.113.10:9000/mnt/disk{1...8}"

Pool naming

MinIO AIStor assigns each pool a name that identifies it in administrative commands such as mc admin decommission.

• Single-node pools: When a pool has a single node entry, MinIO AIStor uses the address string directly as the pool name. For example, a pool defined as https://minio-{1...4}.example.net:9000 with path /mnt/disk{1...4} appears with that address in administrative output.

• Multi-node pools: When a pool has multiple node entries (for example, heterogeneous hostnames or IP addresses), MinIO AIStor generates a hash:<hex> identifier from the expanded endpoint layout. This hash-based name appears in the Pools column of commands like mc admin decommission status:

  ┌─────┬──────────────────────┬──────────────────────────────────┬────────┐
  │ ID  │ Pools                │ Capacity                         │ Status │
  │ 1st │ hash:a510f38e84ec12b │  60 TiB (used) / 100 TiB (total) │ Active │
  │ 2nd │ hash:b9c4d2e6f8a01e3 │  40 TiB (used) / 100 TiB (total) │ Active │
  └─────┴──────────────────────┴──────────────────────────────────┴────────┘

  Use the full hash:<hex> string as the pool identifier when running commands that require a pool argument, such as mc admin decommission start.

Pool requirements

• Each pool requires a minimum of 2 nodes with unique, non-repeating hosts.
• Each host in a pool must have the same number of drives as every other host in that pool.
• Mixing local paths and distributed paths is not allowed.

Multi-NIC configuration

MinIO AIStor supports multiple network interfaces (NICs) for internode communication to achieve aggregate bandwidth. When configured, MinIO AIStor distributes internode traffic across all configured NICs using round-robin, effectively multiplying available bandwidth.

How it works

• Requests are distributed round-robin across healthy NICs.
• Each outgoing connection binds to a specific local NIC IP (source binding).
• Failed NICs are temporarily skipped and retried after 30 seconds.
• Supports any number of NICs.

Configuration

In v3, configure multi-NIC by listing multiple address templates per node definition. All address templates must expand to the same number of nodes.

The following example configures 8 nodes with dual NICs and 8 drives each:

version: v3
rootUser: "minioadmin"
rootPassword: "secret-CHANGE-ME"
address: ":9000"
pools:
  - nodes:
      - addresses:
          - "https://192.168.10.{11...18}:9000"  # NIC1 subnet
          - "https://192.168.20.{11...18}:9000"  # NIC2 subnet
        path: "/mnt/disk{1...8}/"

This expands to 8 nodes where each node has two NIC addresses:

Deploy the same config file to all nodes. Each node auto-detects itself by matching NIC IPs against local interfaces, then builds a route map: when communicating with remote node N, NIC position i on the local node connects to NIC position i on node N.

Multi-NIC requirements

• All address templates within a node definition must expand to the same number of nodes.
• Each NIC should be on a separate network or subnet, so the aggregated links do not share a bottleneck.
• Every NIC uses the port from the first address, so set the same port on every address.
• All NIC subnets must be routable to that port on every node.
• Source binding requires appropriate network routing on each node.

Configuration settings and CLI equivalents

The following tables map configuration file fields to their corresponding environment variables and command-line flags, along with the precedence order when the same parameter is configured in multiple ways.

Core settings

Behavior settings

Storage configuration

FTP and SFTP configuration