Root Access Settings

This page covers settings that control root (superuser) access for the MinIO AIStor process. The root user has complete access and permissions to perform operations on the MinIO AIStor deployment.

Root User and Root Password are required even if you use the MinIO Key Encryption Service or other key management utility.

You can establish or modify settings by defining:

an environment variable on the host system prior to starting or restarting the MinIO 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.

Each configuration setting controls fundamental MinIO AIStor behavior and functionality. Test configuration changes in a lower environment, such as DEV or QA, before applying to production.

Settings

Root user

MINIO_ROOT_USER

This setting does not have a configuration variable setting. Use the Environment Variable instead.

The access key for the root user.

Omitting this value results in using the default minioadmin

NEVER use the default credentials in production environments. MinIO strongly recommends specifying a unique, long, and random MINIO_ROOT_USER value for all environments.

Root user file

MINIO_ROOT_USER_FILE

This setting does not have a configuration variable setting. Use the Environment Variable instead.

Specifies the full path to a file containing the access key for the root user. The file should contain only the access key value with no additional whitespace or newlines.

See file-based environment variables for usage information.

Root password

MINIO_ROOT_PASSWORD

This setting does not have a configuration variable setting. Use the Environment Variable instead.

The secret key for the root user.

Omitting this value results in using the default minioadmin

NEVER use the default credentials in production environments. MinIO strongly recommends specifying a unique, long, and random MINIO_ROOT_PASSWORD value for all environments.

Root password file

MINIO_ROOT_PASSWORD_FILE

This setting does not have a configuration variable setting. Use the Environment Variable instead.

Specifies the full path to a file containing the secret key for the root user. The file should contain only the secret key value with no additional whitespace or newlines.

See file-based environment variables for usage information.

Root API access

MINIO_API_ROOT_ACCESS

api root_access

Specify on to enable and off to disable the root user account. Disabling the root user also disables all access keys created by the root user, the temporary credentials issued to the root user, and all Prometheus bearer tokens generated with the root credentials, but not the service accounts used by site replication. Requests made with the root credentials return Your account is disabled; please contact your administrator. Defaults to on.

A change to the configuration setting takes effect without a restart.

Disabling root API access only disallows authentication with root credentials for public API calls. MinIO AIStor nodes still use the root credentials to authenticate internode cluster communication. Therefore, disabling root API access requires either setting explicit root credentials with the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD environment variables or specifying a KMS configuration to auto-generate root credentials using the KMS.

Because the nodes still use the root credentials, disabling root API access does not remove the need to rotate them. Rotate them as described in Rotate root credentials, using an administrator alias.

Ensure you have at least one other admin user, such as one with the consoleAdmin policy, before disabling the root account. If you do not have another admin user, disabling the root account locks administrative access to the deployment.

You can use this variable to temporarily override the configuration setting and re-enable root access to the deployment.

To recover after an unintentional lock, set MINIO_API_ROOT_ACCESS to on. The environment variable overrides the stored api root_access setting and temporarily re-enables the root account. Then do one of the following:

To keep root access, set api root_access to on, then remove the environment variable.
To keep root access off, create a non-root administrator, then remove the environment variable.

Unique root credentials

For systems with the API root access disabled, MinIO AIStor supports further obfuscation of the root credentials by generating a unique value using a configured external Key Management Service (KMS). These credentials are exclusively for internode authentication and related operations.

MinIO AIStor automatically generates unique root credentials if all of the following conditions are true:

MinKMS or KES Release 2024-03-01T18-06-46Z or later running or set a static key with MINIO_KMS_SECRET_KEY or MINIO_KMS_SECRET_KEY_FILE
Have not defined:
- MINIO_ROOT_USER variable
- MINIO_ROOT_PASSWORD variable
Have:
- connected MinIO AIStor to the KMS
- disabled root access with the MinIO AIStor environment variable

When those conditions are met at startup, MinIO AIStor uses the KMS to generate unique root credentials for the deployment using a hash-based message authentication code (HMAC). These credentials provide a fully obfuscated root credential configuration for infrastructures with specific security requirements.

You cannot rotate these credentials on a cluster that uses a static key (MINIO_KMS_SECRET_KEY or MINIO_KMS_SECRET_KEY_FILE), because a static key cannot create new keys. Migrate the cluster to MinIO KMS or KES before rotating.

Do not replace or delete the static key. The server encrypts its configuration and IAM data with it and cannot read them with any other key. Keep a copy of the static key outside the cluster.

To rotate the generated root credentials, generate a new key in the KMS, then point the default encryption key of the cluster to the new key. For MinIO KMS, update MINIO_KMS_SSE_KEY; for KES, update MINIO_KMS_KES_KEY_NAME. Change the key on every node, restart all nodes together, and keep the previous key in the KMS. The server still needs the previous key to read data encrypted before the change.

The MinKMS API key (MINIO_KMS_API_KEY) is not a root credential. To rotate it, see Identity management in the AIStor Key Manager documentation.

Rotate root credentials

Rotate the root credentials on the schedule your security policy requires, and whenever someone who knows them leaves your organization.

Before you rotate

Keep MINIO_ROOT_USER unchanged and rotate only MINIO_ROOT_PASSWORD. Access keys created by the root user and site replication depend on the root user staying the same.
Changing MINIO_ROOT_PASSWORD signs out every Console user and ends all active temporary credentials. This is intended: users log in again, and applications request new temporary credentials.
Update everything else that connects with the root credentials, such as applications, mc aliases, bucket replication targets, remote tiers, and Prometheus bearer tokens. Use a dedicated user, rather than the root user, for these connections, so that later rotations do not affect them.
Use only letters, digits, and -, _, and . in root credentials. This works with every method of delivering the value.

Rotation steps

Set the new values on every node, in the place where you defined the root credentials.
Restart all nodes together, not one at a time. A node that restarts with new credentials cannot authenticate to nodes that still run the old credentials.
Confirm that the new credentials work and the previous credentials do not:
```
mc alias set myaistor https://myaistor.example.net:9000 ROOT_USER NEW_ROOT_PASSWORD
mc admin user list myaistor
```
If root API access is disabled, the root credentials cannot sign in. Use an administrator alias and confirm with mc admin info that every node and drive is online.

Linux

On a package installation, set the values in /etc/minio/config.env on every node:

MINIO_ROOT_USER=ROOT_USER
MINIO_ROOT_PASSWORD=NEW_ROOT_PASSWORD

Then restart all nodes together with mc admin service restart and an administrator alias:

mc admin service restart myaistor

mc admin service restart applies only values from the file that MINIO_CONFIG_ENV_FILE names, such as /etc/minio/config.env. If you defined the root credentials in /etc/default/minio, the restart keeps the previous values. Run sudo systemctl restart minio on every node at the same time instead.

macOS and Windows

Stop the server, set MINIO_ROOT_USER and MINIO_ROOT_PASSWORD to the new values in the terminal, and start the server again with the same command, as described in Deploy MinIO AIStor on macOS or Deploy AIStor Server on Windows.

Containers

A container keeps the environment it was created with, so docker restart starts it again with the previous values. Recreate the container with the new values instead, as described in Deploy MinIO AIStor as a Container. The data stays in the mounted directory. With Docker Compose, change the values in the environment section and run docker compose up -d.

Kubernetes

The MinIO AIStor Helm chart stores the root credentials in a Kubernetes Secret, and the Operator restarts the server processes on every Pod when that Secret changes. Run helm upgrade with the chart version your release already uses and --reuse-values:

helm upgrade -n OBJECT-STORE-NAMESPACE OBJECT-STORE-NAME minio/aistor-objectstore \
  --version CHART_VERSION \
  --reuse-values \
  --set secrets.accessKey=ROOT_USER \
  --set secrets.secretKey=NEW_ROOT_PASSWORD

Do not omit --reuse-values. Helm then replaces every other value with the chart default, including objectStore.name, which deletes your ObjectStore and creates a new, empty one.

If you manage the Secret yourself with secrets.existingSecret: true, or you deploy on OpenShift, update the config.env key of that Secret instead.

Root Access Settings

On this page