Documentation

Metrics and Logging Settings

This page covers settings that control behavior related to MinIO metrics and logging. See Metrics and Alerts for more information.

These settings configure publishing regular minio server logs and audit logs to an HTTP webhook. See Publish Server or Audit Logs to an External Service for more complete documentation.

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.

  • a configuration setting using the MinIO Console’s Administrator > Settings pages.

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.

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.

Prometheus Authentication

This setting controls how MinIO authenticates to Prometheus.

MINIO_PROMETHEUS_AUTH_TYPE

This setting does not have a configuration setting option.

Specifies the authentication mode for the Prometheus scraping endpoints.

  • jwt - Default MinIO requires that the scraping client specify a JWT token for authenticating requests.

    Use mc admin prometheus generate to generate the necessary JWT bearer tokens.

  • public MinIO does not require that scraping clients authenticate their requests.

Server Logs

The following section documents settings for configuring MinIO to publish minio server logs to an HTTP webhook endpoint. See Publish Server Logs to HTTP Webhook for more complete documentation and tutorials on using these settings.

Defining Multiple Endpoints

You can specify multiple webhook endpoints as log targets by appending a unique identifier _ID for each set of related logging environment variables. For example, the following settings define two distinct server logs webhook endpoints:

export MINIO_LOGGER_WEBHOOK_ENABLE_PRIMARY="on"
export MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_PRIMARY="TOKEN"
export MINIO_LOGGER_WEBHOOK_ENDPOINT_PRIMARY="http://webhook-1.example.net"

export MINIO_LOGGER_WEBHOOK_ENABLE_SECONDARY="on"
export MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_SECONDARY="TOKEN"
export MINIO_LOGGER_WEBHOOK_ENDPOINT_SECONDARY="http://webhook-2.example.net"
mc admin config set logger_webhook:primary \
   endpoint="http://webhook-01.example.net" [ARGUMENTS=VALUE ...]

mc admin config set logger_webhook:secondary \
   endpoint="http://webhook-02.example.net" [ARGUMENTS=VALUE ...]

Settings

Enable

MINIO_LOGGER_WEBHOOK_ENABLE

Specify "on" to enable publishing minio server logs to the HTTP webhook endpoint.

Requires specifying MINIO_LOGGER_WEBHOOK_ENDPOINT.

logger_webhook

The top level key for the configuration settings to configure logging to an HTTP webhook endpoint.

Endpoint

Required

MINIO_LOGGER_WEBHOOK_ENDPOINT
logger_webhook endpoint

The HTTP endpoint of the webhook.

Auth Token

Optional

MINIO_LOGGER_WEBHOOK_AUTH_TOKEN

An authentication token of the appropriate type for the endpoint. Omit for endpoints which do not require authentication.

To allow for a variety of token types, MinIO creates the request authentication header using the value exactly as specified. Depending on the endpoint, you may need to include additional information.

For example: for a Bearer token, prepend Bearer:

set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"

Modify the value according to the endpoint requirements. A custom authentication format could resemble the following:

set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"

Consult the documentation for the desired service for more details.

This environment variable corresponds with the logger_webhook auth_token configuration setting.

logger_webhook auth_token

An authentication token of the appropriate type for the endpoint. Omit for endpoints which do not require authentication.

To allow for a variety of token types, MinIO creates the request authentication header using the value exactly as specified. Depending on the endpoint, you may need to include additional information.

For example: for a Bearer token, prepend Bearer:

   mc admin config set myminio logger_webhook   \
      endpoint="https://webhook-1.example.net"  \
      auth_token="Bearer 1a2b3c4f5e"

Modify the value according to the endpoint requirements. A custom authentication format could resemble the following:

   mc admin config set myminio logger_webhook   \
        endpoint="https://webhook-1.example.net"  \
      auth_token="ServiceXYZ 1a2b3c4f5e"

Consult the documentation for the desired service for more details.

Client Certificate

Optional

Requires also setting the Client Key.

MINIO_LOGGER_WEBHOOK_CLIENT_CERT
logger_webhook client_cert

The path to the mTLS certificate to use for authenticating to the webhook logger.

Client Key

Optional

Required if you define the Client Certificate.

MINIO_LOGGER_WEBHOOK_CLIENT_KEY
logger_webhook client_key

The path to the mTLS certificate key to use to authenticate with the webhook logger service.

Proxy

Optional

MINIO_LOGGER_WEBHOOK_PROXY
logger_webhook proxy

New in version MinIO: RELEASE.2023-02-22T18-23-45Z

Define a proxy to use for the webhook logger when communicating from MinIO to external webhooks.

Queue Directory

Optional

New in version RELEASE.2023-05-18T00-05-36Z.

MINIO_LOGGER_WEBHOOK_QUEUE_DIR
logger_webhook queue_dir

Specify the directory path, such as /opt/minio/events, to enable MinIO’s persistent event store for undelivered messages. The MinIO process must have read, write, and list access on the specified directory.

MinIO stores undelivered events in the specified store while the webhook service is offline and replays the stored events when connectivity resumes.

Queue Size

Optional

MINIO_LOGGER_WEBHOOK_QUEUE_SIZE
logger_webhook queue_size

An integer value to use for the queue size for logger webhook targets.

Webhook Audit Logs

The following section documents environment variables for configuring MinIO to publish audit logs to an HTTP webhook endpoint. See Publish Audit Logs to HTTP Webhook for more complete documentation and tutorials on using these environment variables.

Multiple Targets

You can specify multiple webhook endpoints as audit log targets by appending a unique identifier _ID for each set of related logging settings.

For example, the following commands set two distinct audit log webhook endpoints:

export MINIO_AUDIT_WEBHOOK_ENABLE_PRIMARY="on"
export MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_PRIMARY="TOKEN"
export MINIO_AUDIT_WEBHOOK_ENDPOINT_PRIMARY="http://webhook-1.example.net"
export MINIO_AUDIT_WEBHOOK_CLIENT_CERT_SECONDARY="/tmp/cert.pem"
export MINIO_AUDIT_WEBHOOK_CLIENT_KEY_SECONDARY="/tmp/key.pem"

export MINIO_AUDIT_WEBHOOK_ENABLE_SECONDARY="on"
export MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_SECONDARY="TOKEN"
export MINIO_AUDIT_WEBHOOK_ENDPOINT_SECONDARY="http://webhook-1.example.net"
export MINIO_AUDIT_WEBHOOK_CLIENT_CERT_SECONDARY="/tmp/cert.pem"
export MINIO_AUDIT_WEBHOOK_CLIENT_KEY_SECONDARY="/tmp/key.pem"
audit_webhook

The top-level configuration key for defining an HTTP webhook target for publishing MinIO audit logs.

Use mc admin config set to set or update an HTTP webhook target. Specify additional optional arguments as a whitespace (" ")-delimited list.

mc admin config set audit_webhook \
   endpoint="http://webhook.example.net" [ARGUMENTS=VALUE ...]

You can specify multiple HTTP webhook targets by appending [:name] to the top-level key. For example, the following commands set two distinct HTTP webhook targets as primary and secondary respectively:

mc admin config set audit_webhook:primary \
   endpoint="http://webhook-01.example.net" [ARGUMENTS=VALUE ...]


mc admin config set audit_webhook:secondary \
   endpoint="http://webhook-02.example.net" [ARGUMENTS=VALUE ...]

Settings

Enable

MINIO_AUDIT_WEBHOOK_ENABLE

Specify "on" to enable publishing audit logs to the HTTP webhook endpoint.

Requires specifying MINIO_AUDIT_WEBHOOK_ENDPOINT.

Configure an audit webhook to enable it. There is not a separate enable configuration setting.

Endpoint

Required

MINIO_AUDIT_WEBHOOK_ENDPOINT
audit_webhook endpoint

The HTTP endpoint of the webhook.

Auth Token

Optional

MINIO_AUDIT_WEBHOOK_AUTH_TOKEN
audit_webhook auth_token

An authentication token of the appropriate type for the endpoint. Omit for endpoints which do not require authentication.

To allow for a variety of token types, MinIO creates the request authentication header using the value exactly as specified. Depending on the endpoint, you may need to include additional information.

For example, for a Bearer token, prepend Bearer:

set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"

Modify the value according to the endpoint requirements.

A custom authentication format could resemble the following:

set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
mc admin config set myminio audit_webhook       \
         endpoint="http://webhook.example.net"  \
         auth_token="Bearer 1a2b3c4f5e"

Modify the value according to the endpoint requirements.

A command for a custom authentication format could resemble the following:

mc admin config set myminio audit_webhook       \
         endpoint="http://webhook.example.net"  \
         auth_token="ServiceXYZ 1a2b3c4f5e"

Consult the documentation for the desired service for more details.

Client Certificate

Optional

MINIO_AUDIT_WEBHOOK_CLIENT_CERT

Requires also specifying MINIO_AUDIT_WEBHOOK_CLIENT_KEY.

audit_webhook client_cert

Requires also specifying client_key.

The x.509 client certificate to present to the HTTP webhook. Omit for webhooks which do not require clients to present a known TLS certificate.

Client Key

Optional

MINIO_AUDIT_WEBHOOK_CLIENT_KEY

Requires also specifying MINIO_AUDIT_WEBHOOK_CLIENT_CERT.

audit_webhook client_key

Requires specifying client_cert.

The x.509 private key to present to the HTTP webhook. Omit for webhooks which do not require clients to present a known TLS certificate.

Queue Directory

Optional

MINIO_AUDIT_WEBHOOK_QUEUE_DIR
audit_webhook queue_dir

New in version RELEASE.2023-05-18T00-05-36Z.

Specify the directory path, such as /opt/minio/events, to enable MinIO’s persistent event store for undelivered messages. The MinIO process must have read, write, and list access on the specified directory.

MinIO stores undelivered events in the specified store while the webhook service is offline and replays the stored events when connectivity resumes.

Queue Size

Optional

MINIO_AUDIT_WEBHOOK_QUEUE_SIZE
audit_webhook queue_size

An integer value to use for the queue size for audit webhook targets. The default is 100000 events.

Kafka Audit Logs

The following section documents environment variables for configuring MinIO to publish audit logs to a Kafka broker.

audit_kafka

The top-level configuration key for defining a Kafka broker target for publishing MinIO audit logs.

Use mc admin config set to set or update a Kafka audit target. Specify additional optional arguments as a whitespace (" ")-delimited list.

mc admin config set audit_kafka \
   brokers="https://kafka-endpoint.example.net:9092" [ARGUMENTS=VALUE ...]

Settings

Enable

Required

MINIO_AUDIT_KAFKA_ENABLE

Set to "on" to enable the target.

Set to "off" to disable the target.

There is not a configuration setting for this value. Use the environment variable to disable a configured audit webhook target.

Brokers

Required

MINIO_AUDIT_KAFKA_BROKERS
audit_kafka brokers

A comma-separated list of Kafka broker addresses:

brokers="https://kafka-1.example.net:9092,https://kafka-2.example.net:9092"

At least one broker must be online and reachable by the MinIO server to initialize and send audit log events. MinIO checks each specified broker in order of specification.

Topic

Required

MINIO_AUDIT_KAFKA_TOPIC
audit_kafka topic

The name of the Kafka topic to associate to MinIO audit log events.

TLS

Optional

MINIO_AUDIT_KAFKA_TLS
audit_kafka tls

Set to "on" to enable TLS connectivity to the specified Kafka brokers.

Defaults to "off".

TLS Skip Verify

Optional

MINIO_AUDIT_KAFKA_TLS_SKIP_VERIFY
audit_kafka tls_skip_verify

Set to "on" to direct MinIO to skip verification of the Kafka broker TLS certificates.

You can use this option for enabling connectivity to Kafka brokers using TLS certificates signed by unknown parties, such as self-signed or corporate-internal Certificate Authorities (CA).

MinIO by default uses the system trust store and the contents of the MinIO CA directory for verifying remote client TLS certificates.

Defaults to "off" for strict verification of TLS certificates.

SASL

Optional

MINIO_AUDIT_KAFKA_SASL

Requires specifying MINIO_AUDIT_KAFKA_SASL_USERNAME and MINIO_AUDIT_KAFKA_SASL_PASSWORD.

audit_kafka sasl

Requires specifying sasl_username and sasl_password.

Set to "on" to direct MinIO to use SASL to authenticate against the Kafka brokers.

SASL Username

Optional

MINIO_AUDIT_KAFKA_SASL_USERNAME

Requires specifying MINIO_AUDIT_KAFKA_SASL and MINIO_AUDIT_KAFKA_SASL_PASSWORD.

audit_kafka sasl_username

Requires specifying sasl and sasl_password.

The SASL username MinIO uses for authentication against the Kafka brokers.

SASL Password

Optional

MINIO_AUDIT_KAFKA_SASL_PASSWORD

Requires specifying MINIO_AUDIT_KAFKA_SASL and MINIO_AUDIT_KAFKA_SASL_USERNAME.

audit_kafka sasl_password

Requires specifying sasl and sasl_username.

The SASL password MinIO uses for authentication against the Kafka brokers.

SASL Mechanism

Optional

MINIO_AUDIT_KAFKA_SASL_MECHANISM

Important

The PLAIN authentication mechanism sends credentials in plain text over the network. Use MINIO_AUDIT_KAFKA_TLS or to enable TLS connectivity to the Kafka brokers and ensure secure transmission of SASL credentials.

audit_kafka sasl_mechanism

Important

The PLAIN authentication mechanism sends credentials in plain text over the network. Use tls to enable TLS connectivity to the Kafka brokers and ensure secure transmission of SASL credentials.

The SASL mechanism MinIO uses for authentication against the Kafka brokers.

Defaults to plain.

TLS Client Auth

Optional

MINIO_AUDIT_KAFKA_TLS_CLIENT_AUTH

Requires specifying MINIO_AUDIT_KAFKA_CLIENT_TLS_CERT and MINIO_AUDIT_KAFKA_CLIENT_TLS_KEY.

audit_kafka tls_client_auth

Requires specifying client_tls_cert and client_tls_key.

Set to "on" to direct MinIO to use mTLS to authenticate against the Kafka brokers.

Client TLS Certificate

Optional

MINIO_AUDIT_KAFKA_CLIENT_TLS_CERT
audit_kafka client_tls_cert

The path to the TLS client certificate to use for mTLS authentication.

Client TLS Key

Optional

MINIO_AUDIT_KAFKA_CLIENT_TLS_KEY
audit_kafka client_tls_key

The path to the TLS client private key to use for mTLS authentication.

Version

Optional

MINIO_AUDIT_KAFKA_VERSION
audit_kafka version

The version of the Kafka broker MinIO expects at the specified endpoints.

MinIO returns an error if the Kakfa broker version does not match those specified to this setting.

Comment

Optional

MINIO_AUDIT_KAFKA_COMMENT
audit_kafka comment

A comment to associate with the configuration.

Queue Directory

Optional

MINIO_AUDIT_KAFKA_QUEUE_DIR
audit_kafka queue_dir

Specify the directory path to enable MinIO’s persistent event store for undelivered messages, such as /opt/minio/events.

MinIO stores undelivered events in the specified store while the Kafka service is offline and replays the stored events when connectivity resumes.

Queue Size

Optional

MINIO_AUDIT_KAFKA_QUEUE_SIZE
audit_kafka queue_size

Specify the maximum limit for undelivered messages. Defaults to 100000.