minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-28 19:42:10 +03:00
Code Activity

Breaking up envvars and config settings into separate settings pages (#1028)

Browse Source 
- Creates a slew of folders and pages nested under the mc-server page to store settings.
- Breaks up all of the environment variable options formerly in the mc-server page into these separate pages.
- Moves the config settings formerly in the mc admin config page to the appropriate new settings pages.
- Adds a MiniO Client settings page and document `mc-host-<alias>`

Closes #1017
This commit is contained in:
Daryl White
2023-11-03 07:55:22 -04:00
committed by GitHub
parent 6d2ecc2b8a
commit eb94513104
30 changed files with 6482 additions and 6762 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1241
source/includes/common-mc-admin-config.rst
View File

File diff suppressed because it is too large Load Diff

4
source/operations/monitoring/minio-logging.rst
View File

@ -47,7 +47,7 @@ runtime configuration settings.
MinIO supports specifying the :mc:`minio server` log HTTP webhook endpoint
and associated configuration settings using :ref:`environment variables
<minio-sever-envvar-logging-regular>`.
<minio-server-envvar-logging-regular>`.
The following example code sets *all* environment variables related to
configuring a log HTTP webhook endpoint. The minimum *required* variables
@ -172,7 +172,7 @@ settings:
MinIO supports specifying the audit log HTTP webhook endpoint and
associated configuration settings using :ref:`environment variables
<minio-sever-envvar-logging-audit>`.
<minio-server-envvar-logging-audit>`.
The following example code sets *all* environment variables related to
configuring a audit log HTTP webhook endpoint. The minimum *required*

2755
source/reference/minio-mc-admin/mc-admin-config.rst
View File

File diff suppressed because it is too large Load Diff

1
source/reference/minio-mc.rst
View File

@ -549,6 +549,7 @@ All :ref:`commands <minio-mc-commands>` support the following global options:
:titlesonly:
:hidden:
/reference/minio-mc/minio-client-settings
/reference/minio-mc/mc-alias
/reference/minio-mc/mc-anonymous
/reference/minio-mc/mc-batch

83
source/reference/minio-mc/minio-client-settings.rst Normal file
View File

@ -0,0 +1,83 @@
.. _minio-server-envvar-mc:
=====================
MinIO Client Settings
=====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings for the :ref:`MinIO Client <minio-client>`.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Settings
--------
Host Credentials
~~~~~~~~~~~~~~~~
Use this setting to add a temporary alias to use for `mc` commands.
For example, for use with scripting.
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MC_HOST_<ALIAS>
Replace ``<ALIAS>`` at the end of the environment variable with the ``alias`` to set the host for.
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Use :mc:`mc alias set` to configure an ALIAS.
Examples
++++++++
**Static Credentials**
.. tab-set::
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
export MC_HOST_<alias>=https://<Access Key>:<Secret Key>@<YOUR-S3-ENDPOINT>
.. tab-item:: Example
.. code-block:: shell
:class: copyable
export MC_HOST_myalias=https://Q3AM3UQ867SPQQA43P2F:zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG@play.min.io
**Security Token Service (STS) Credentials**
.. tab-set::
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
export MC_HOST_<alias>=https://<Access Key>:<Secret Key>:<Session Token>@<YOUR-S3-ENDPOINT>
.. tab-item:: Example
.. code-block:: shell
:class: copyable
export MC_HOST_myalias=https://Q3AM3UQ867SPQQA43P2F:zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG:eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJOVUlCT1JaWVRWMkhHMkJNUlNYUiIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTM0ODk2NjI5LCJpYXQiOjE1MzQ4OTMwMjksImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiNjY2OTZjZTctN2U1Ny00ZjU5LWI0MWQtM2E1YTMzZGZiNjA4In0.eJONnVaSVHypiXKEARSMnSKgr-2mlC2Sr4fEGJitLcJF_at3LeNdTHv0_oHsv6ZZA3zueVGgFlVXMlREgr9LXA@play.min.io

2841
source/reference/minio-server/minio-server.rst
View File

File diff suppressed because it is too large Load Diff

43
source/reference/minio-server/settings.rst Normal file
View File

@ -0,0 +1,43 @@
.. _minio-environment-variables:
.. _minio-server-environment-variables:
.. _minio-server-configuration-settings:
=================
Settings Overview
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
The :mc:`minio server` process stores its configuration in the storage backend :mc-cmd:`directory <minio server DIRECTORIES>`.
.. _minio-server-configuration-options:
MinIO Settings
--------------
MinIO settings define runtime behavior of the MinIO :mc:`server <minio server>` process:
You can define many MinIO Server settings in one of two ways:
1. Set :ref:`environment variables <minio-environment-variables>` in the host system prior to launching or restarting the server process.
2. Modify configuration options using the :mc:`mc admin config` command or the :guilabel:`Administrator > Settings` page of the :ref:`MinIO Console <minio-console>`.
.. important::
Settings defined by an environment variable override similar settings defined as configurations with :mc:`mc admin config` or the MinIO Console.
Additional settings include those to customize:
- :ref:`Core settings <minio-server-envvar-core>`
- :ref:`Root credentials <minio-server-envvar-root>`
- :ref:`Storage class <minio-server-envvar-storage-class>`
- :ref:`MinIO Console <minio-server-envvar-console>`
- :ref:`Metrics and logging <minio-server-envvar-metrics-logging>`
- :ref:`Notification targets <minio-server-envvar-notifications>` for use with :ref:`MinIO Bucket Notifications <minio-bucket-notifications>`
- :ref:`Identity and access management solutions <minio-server-envvar-iam>`
- :ref:`Key Encryption Service (KES) <minio-server-envvar-kes>`
- :ref:`Object Lambda functions <minio-server-envvar-object-lambda-webhook>`

252
source/reference/minio-server/settings/console.rst Normal file
View File

@ -0,0 +1,252 @@
.. _minio-server-envvar-console:
======================
MinIO Console Settings
======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings that manage access and behavior for the MinIO Console.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Browser Settings
----------------
The following settings control behavior for the embedded MinIO Console.
MinIO Console
~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_BROWSER
*Optional*
Specify ``off`` to disable the embedded MinIO Console.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Animation
~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_BROWSER_LOGIN_ANIMATION
*Optional*
.. versionadded:: MinIO Server RELEASE.2023-05-04T21-44-30Z
Specify ``off`` to disable the animated login screen for the MinIO Console.
Defaults to ``on``.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Browser Redirect
~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_BROWSER_REDIRECT
.. versionadded:: MinIO Server RELEASE.2023-09-16T01-01-47Z
Specify whether requests from a web browser automatically redirect to the Console address.
Defaults to ``true``.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Browser Redirect URL
~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_BROWSER_REDIRECT_URL
*Optional*
Specify the Fully Qualified Domain Name (FQDN) the MinIO Console listens for incoming connections on.
If you want to host the MinIO Console exclusively from a reverse-proxy service, you must specify the hostname managed by that service.
For example, consider a reverse proxy configured to route ``https://example.net/minio/`` to the MinIO Console.
You must set this environment variable to match that hostname for the Console to both listen and respond to requests using that hostname.
If you omit this variable, the Console listens and responds to all IP addresses or hostnames associated to the host machine on which the MinIO Server runs.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Session Duration
~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_BROWSER_SESSION_DURATION
*Optional*
.. versionadded:: MinIO Server RELEASE.2023-08-23T10-07-06Z
Specify the duration of a browser session for working with the MinIO Console.
MinIO supports the following units of time measurement:
- ``s`` - seconds, "60s"
- ``m`` - minutes, "60m"
- ``h`` - hours, "24h"
- ``d`` - days, "7d"
Defaults to ``12h``.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Server URL
~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_SERVER_URL
*Optional*
Specify the Fully Qualified Domain Name (FQDN) the MinIO Console must use for connecting to the MinIO Server.
The Console also uses this value for setting the root hostname when generating presigned URLs.
This setting may be required if:
- The MinIO Server uses a TLS certificate that does not include the host local IP(s) in the certificate Subject Alternative Name (SAN) *or*
- The Console must use a specific hostname to connect or reference the MinIO Server, e.g. due to a reverse proxy or similar configuration.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Log Query URL
~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_LOG_QUERY_URL
*Optional*
Specify the URL of a PostgreSQL service to which MinIO writes :ref:`Audit logs <minio-logging-publish-audit-logs>`.
The embedded MinIO Console provides a Log Search tool that allows querying the PostgreSQL service for collected logs.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Prometheus Settings
-------------------
The following settings manage how MinIO interacts with your Prometheus service.
Prometheus URL
~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_PROMETHEUS_URL
*Optional*
Specify the URL for a Prometheus service configured to :ref:`scrape MinIO metrics <minio-metrics-collect-using-prometheus>`.
The MinIO Console populates the :guilabel:`Dashboard` with cluster metrics using the ``minio-job`` Prometheus scraping job.
If you are using a standalone MinIO Console process, this variable corresponds with ``CONSOLE_PROMETHEUS_URL``.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Prometheus Job ID
~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_PROMETHEUS_JOB_ID
*Optional*
Specify the custom Prometheus job ID used for :ref:`scraping MinIO metrics <minio-metrics-collect-using-prometheus>`.
MinIO defaults to ``minio-job``.
If you are using a standalone MinIO Console process, this variable corresponds with ``CONSOLE_PROMETHEUS_JOB_ID``.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Prometheus Auth Token
~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_PROMETHEUS_AUTH_TOKEN
*Optional*
Specify the :prometheus-docs:`basic auth token <guides/basic-auth/>` the Console should use to connect to a Prometheus service.
For example, a basic auth token you might use could resemble the following:
.. code-block:: text
eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJwcm9tZXRoZXVzIiwic3ViIjoibWluaW8iLCJleHAiOjQ4NTAwMzg0MDJ9.GZCKR3d0FH2TCvNHSd39HaVfSuQVVV0s8glICBDmhT51V6CQ_hw8gTYlKHJmcpR8aHkqiJwCqcYJhaMmqwe00XY
If you are using a standalone MinIO Console process, this variable corresponds with ``CONSOLE_PROMETHEUS_AUTH_TOKEN``.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.

277
source/reference/minio-server/settings/core.rst Normal file
View File

@ -0,0 +1,277 @@
.. _minio-server-envvar-core:
=============
Core Settings
=============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings that control core behavior of the MinIO process.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Common Settings
---------------
Volumes
~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_VOLUMES
The directories or drives the :mc:`minio server` process uses as the storage backend.
Functionally equivalent to setting :mc-cmd:`minio server DIRECTORIES`.
Use this value when configuring MinIO to run using an environment file.
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Environment Variable File Path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_CONFIG_ENV_FILE
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-cmd:`mc admin service restart` to restart the deployment.
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Workers for Expiration
~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_ILM_EXPIRY_WORKERS
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.
.. tab-item:: Configuration Setting
:sync: config
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Domain
~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_DOMAIN
Set to the Fully Qualified Domain Name (FQDN) MinIO accepts Bucket DNS (Virtual Host)-style requests on.
For example, setting ``MINIO_DOMAIN=minio.example.net`` directs MinIO to accept an incoming connection request to the ``data`` bucket at ``data.minio.example.net``.
If this setting is omitted, the default is to only accept path-style requests. For example, ``minio.example.net/data``.
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
.. _minio-scanner-speed-options:
Scanner Speed
~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_SCANNER_SPEED
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: scanner speed
:delimiter: " "
Manage the maximum wait period for the scanner when balancing MinIO read/write performance to scanner processes.
.. include:: /includes/common/scanner.rst
:start-after: start-scanner-speed-values
:end-before: end-scanner-speed-values
Batch Replication
-----------------
.. tab-set::
.. tab-item:: Environment Variable
.. envvar:: MINIO_BATCH_REPLICATION_WORKERS
*Optional*
Specifying the maximum number of parallel processes to use when performing the batch application job.
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Data Compression
----------------
The following section documents settings for enabling data compression for objects.
See :ref:`minio-data-compression` for tutorials on using these configuration settings.
Allow Encryption
~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_COMPRESSION_ALLOW_ENCRYPTION
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: compression allow_encryption
:delimiter: " "
*Optional*
Set to ``on`` to encrypt objects after compressing them.
Defaults to ``off``.
.. admonition:: Encrypting compressed objects may compromise security
:class: warning
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.
Enable Compression
~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_COMPRESSION_ENABLE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: compression enable
:delimiter: " "
*Optional*
Set to ``on`` to enable data compression for new objects.
Defaults to ``off``.
Enabling or disabling data compression does not change existing objects.
Comments
~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
This setting does not have an environment variable option.
Use the configuration variable instead.
.. tab-item:: Configuration Setting
:selected:
.. envvar:: compression comment
*Optional*
Specify a comment to associate with the data compression configuration.
Compression Extensions
~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_COMPRESSION_EXTENSIONS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: compression extensions
:delimiter: " "
*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"``.
.. admonition:: Default excluded files
:class: note
Some types of files cannot be significantly reduced in size.
MinIO will *not* compress these, even if specified in an :mc-conf:`~compression.extensions` argument.
See :ref:`Excluded types <minio-data-compression-excluded-types>` for details.
Compression MIME Types
~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_COMPRESSION_MIME_TYPES
.. tab-item:: Configuration Variable
:sync: config
.. mc-conf:: compression mime_types
:delimiter: " "
*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"``.
.. admonition:: Default excluded files
:class: note
Some types of files cannot be significantly reduced in size.
MinIO will *not* compress these, even if specified in an :mc-conf:`~compression.mime_types` argument.
See :ref:`Excluded types <minio-data-compression-excluded-types>` for details.

68
source/reference/minio-server/settings/deprecated.rst Normal file
View File

@ -0,0 +1,68 @@
.. _minio-server-envvar-deprecated:
===================
Deprecated Settings
===================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers deprecated settings that control core behavior of the MinIO process.
Settings on this page may be removed at any time.
Users should migrate to the recommended replacement at the earliest opportunity.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Environment Variables
---------------------
The following *environment variables* are deprecated.
They are listed here for historical reference only.
.. envvar:: MINIO_SECRET_KEY
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
The secret key for the :ref:`root <minio-users-root>` user.
This environment variable is *deprecated* in favor of the :envvar:`MINIO_ROOT_PASSWORD` environment variable.
.. warning::
If :envvar:`MINIO_SECRET_KEY` is unset, :mc:`minio` defaults to ``minioadmin``.
**NEVER** use the default credentials in production environments.
MinIO strongly recommends specifying a unique, long, and random :envvar:`MINIO_ACCESS_KEY` value for all environments.
.. envvar:: MINIO_ACCESS_KEY
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
The access key for the :ref:`root <minio-users-root>` user.
This environment variable is *deprecated* in favor of the :envvar:`MINIO_ROOT_USER` environment variable.
.. warning::
If :envvar:`MINIO_ACCESS_KEY` is unset, :mc:`minio` defaults to ``minioadmin``.
**NEVER** use the default credentials in production environments.
MinIO strongly recommends specifying a unique, long, and random :envvar:`MINIO_ACCESS_KEY` value for all environments.
.. envvar:: MINIO_ACCESS_KEY_OLD
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
To perform root credential rotation, modify the :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD` environment variables.
.. envvar:: MINIO_SECRET_KEY_OLD
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
To perform root credential rotation, modify the :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD` environment variables.

26
source/reference/minio-server/settings/iam.rst Normal file
View File

@ -0,0 +1,26 @@
.. _minio-server-envvar-iam:
=======================================
Identity and Access Management Settings
=======================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
The pages in this section document settings for configuring MinIO to work with identity and access management (IAM) solutions.
There is a page of settings for each of the IAM methods MinIO supports.
- :ref:`Active Directory / LDAP <minio-server-envvar-external-identity-management-ad-ldap>`
- :ref:`OpenID <minio-server-envvar-external-identity-management-openid>`
- :ref:`MinIO Identity Management Plugin <minio-server-envvar-external-identity-management-plugin>`
.. toctree::
:titlesonly:
:hidden:
/reference/minio-server/settings/iam/ldap
/reference/minio-server/settings/iam/openid
/reference/minio-server/settings/iam/minio-identity-plugin

369
source/reference/minio-server/settings/iam/ldap.rst Normal file
View File

@ -0,0 +1,369 @@
.. _minio-server-envvar-external-identity-management-ad-ldap:
.. _minio-ldap-config-settings:
================================
Active Directory / LDAP Settings
================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for enabling external identity management using an Active Directory or LDAP service.
See :ref:`minio-authenticate-using-ad-ldap-generic` for a tutorial on using these settings.
.. important::
New in version ``RELEASE.2023-05-26T23-31-54Z``:
:mc:`mc idp ldap` commands are preferred over using configuration settings to configure MinIO to use Active Directory or LDAP for identity management.
MinIO recommends using the :mc:`mc idp ldap` commands for LDAP management operations.
These commands offer better validation and additional features, while providing the same settings as the ``identity_ldap`` configuration key.
See :ref:`minio-authenticate-using-ad-ldap-generic` for a tutorial on using :mc:`mc idp ldap`.
The ``identity_ldap`` configuration settings remains available for existing scripts and other tools.
Examples
--------
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. code-block:: shell
:class: copyable
MINIO_IDENTITY_LDAP_SERVER_ADDR="ldapserver.com:636"
.. note::
``srv_record_name`` automatically identifies the port.
If your AD/LDAP server uses ``DNS SRV Records``, do *not* append the port number to your ``server_addr`` value.
SRV requests automatically include port numbers when returning the list of available servers.
.. tab-item:: Configuration Setting
:sync: config
The following settings are required when defining LDAP using :mc:`mc admin config set`:
- ``enabled``
- ``server_addr``
- ``lookup_bind_dn``
- ``lookup_bind_dn_password``
- ``user_dn_search_base_dn``
- ``user_dn_search_filter``
.. code-block:: shell
:class: copyable
mc admin config set identity_ldap \
enabled="true" \
server_addr="ad-ldap.example.net/" \
lookup_bind_dn="cn=miniolookupuser,dc=example,dc=net" \
lookup_bind_dn_password="userpassword" \
user_dn_search_base_dn="dc=example,dc=net" \
user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))"
Settings
--------
Server Address
~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_SERVER_ADDR
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-server-addr
:end-before: end-minio-ad-ldap-server-addr
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: server_addr
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-server-addr
:end-before: end-minio-ad-ldap-server-addr
Lookup Bind DN
~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: lookup_bind_dn
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-lookup-bind-dn
:end-before: end-minio-ad-ldap-lookup-bind-dn
Lookup Bind Password
~~~~~~~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: lookup_bind_password
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-lookup-bind-password
:end-before: end-minio-ad-ldap-lookup-bind-password
User DN Search Base DN
~~~~~~~~~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: user_dn_search_base_dn
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-user-dn-search-base-dn
:end-before: end-minio-ad-ldap-user-dn-search-base-dn
User DN Search Filter
~~~~~~~~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: user_dn_search_filter
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-user-dn-search-filter
:end-before: end-minio-ad-ldap-user-dn-search-filter
Enabled
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
This setting does not have an environment variable option.
Use the configuration setting instead.
.. tab-item:: Configuration Setting
:selected:
.. mc-conf:: enabled
:delimiter: " "
Set to ``false`` to disable the AD/LDAP configuration.
If ``false``, applications cannot generate STS credentials or otherwise authenticate to MinIO using the configured provider.
Defaults to ``true`` or "enabled".
Group Search Filter
~~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: group_search_filter
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-group-search-filter
:end-before: end-minio-ad-ldap-group-search-filter
Group Search Base DN
~~~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: group_search_base_dn
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-group-search-base-dn
:end-before: end-minio-ad-ldap-group-search-base-dn
TLS Skip Verify
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: tls_skip_verify
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-tls-skip-verify
:end-before: end-minio-ad-ldap-tls-skip-verify
Server Insecure
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_SERVER_INSECURE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: server_insecure
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-server-insecure
:end-before: end-minio-ad-ldap-server-insecure
Server Start TLS
~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_SERVER_STARTTLS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: server_starttls
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-server-starttls
:end-before: end-minio-ad-ldap-server-starttls
SRV Record Name
~~~~~~~~~~~~~~~
*Optional*
.. versionadded:: RELEASE.2022-12-12T19-27-27Z
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_SRV_RECORD_NAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: srv_record_name
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-srv_record_name
:end-before: end-minio-ad-ldap-srv_record_name
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_LDAP_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_ldap comment
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-ad-ldap-comment
:end-before: end-minio-ad-ldap-comment

180
source/reference/minio-server/settings/iam/minio-identity-plugin.rst Normal file
View File

@ -0,0 +1,180 @@
.. _minio-server-envvar-external-identity-management-plugin:
=========================================
MinIO Identity Management Plugin Settings
=========================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for enabling external identity management using the MinIO Identity Management Plugin.
See :ref:`minio-external-identity-management-plugin` for a tutorial on using these settings.
Examples
--------
When setting up the MinIO Identity Management Plugin, you must define at a minimum all of the *required* settings.
The examples here represent the minimum required settings.
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
MINIO_IDENTITY_PLUGIN_URL="https://authservice.example.net:8080/auth"
MINIO_IDENTITY_PLUGIN_ROLE_POLICY="ConsoleUser"
.. tab-item:: Configuration Settings
:sync: config
Use :mc:`mc admin config set` to create or update the OpenID configuration.
The :mc-conf:`identity_plugin url` argument is required.
Specify additional optional arguments as a whitespace (" ")-delimited list.
.. code-block:: shell
mc admin config set identity_plugin \
url="https://external-auth.example.net:8080/auth" \
role_policy="consoleAdmin" \
[ARGUMENT=VALUE] ...
Settings
--------
URL
~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_PLUGIN_URL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_plugin url
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-plugin-url
:end-before: end-minio-identity-management-plugin-url
Role Policy
~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_PLUGIN_ROLE_POLICY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_plugin role_policy
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-role-policy
:end-before: end-minio-identity-management-role-policy
Enable
~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
This setting does not have an environment variable option.
.. tab-item:: Configuration Setting
:selected:
.. mc-conf:: identity_plugin enabled
:delimiter: " "
Set to ``false`` to disable the identity provider configuration.
Applications cannot generate STS credentials or otherwise authenticate to MinIO using the configured provider if set to ``false``.
Defaults to ``true`` or "enabled".
Token
~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_PLUGIN_TOKEN
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_plugin token
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-auth-token
:end-before: end-minio-identity-management-auth-token
Role ID
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_PLUGIN_ROLE_ID
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_plugin role_id
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-role-id
:end-before: end-minio-identity-management-role-id
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_PLUGIN_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_plugin comment
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-comment
:end-before: end-minio-identity-management-comment

407
source/reference/minio-server/settings/iam/openid.rst Normal file
View File

@ -0,0 +1,407 @@
.. _minio-server-envvar-external-identity-management-openid:
.. _minio-open-id-config-settings:
===================================
OpenID Identity Management Settings
===================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for enabling external identity management using an OpenID Connect (OIDC)-compatible provider.
See :ref:`minio-external-identity-management-openid` for a tutorial on using these settings.
Examples
--------
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration"
.. tab-item:: Configuration Settings
:sync: config
Use :mc-cmd:`mc admin config set` to set or update the OpenID configuration.
The :mc-conf:`~identity_openid.config_url` argument is *required*.
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set identity_openid \
config_url="https://openid-provider.example.net/.well-known/openid-configuration" \
[ARGUMENT="VALUE"] ...
Settings
--------
Config URL
~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_CONFIG_URL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid config_url
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-config-url
:end-before: end-minio-openid-config-url
Enabled
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
This setting does not have an environment variable option.
Use the Configuration Setting instead.
.. tab-item:: Configuration Setting
:selected:
.. mc-conf:: identity_openid enabled
:delimiter: " "
Set to ``false`` to disable the OpenID configuration.
Applications cannot generate STS credentials or otherwise authenticate to MinIO using the configured provider if set to ``false``.
Defaults to ``true`` or "enabled".
Client ID
~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_CLIENT_ID
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid client_id
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-client-id
:end-before: end-minio-openid-client-id
Client Secret
~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_CLIENT_SECRET
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid client_secret
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-client-secret
:end-before: end-minio-openid-client-secret
Role Policy
~~~~~~~~~~~
*Optional*
This setting is mutually exclusive with the ``Claim Name`` setting.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_ROLE_POLICY
.. tab-item:: Configuration Setting
.. mc-conf:: identity_openid role_policy
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-role-policy
:end-before: end-minio-openid-role-policy
Claim Name
~~~~~~~~~~
*Optional*
This setting is mutually exclusive with the ``Role Policy`` setting.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_NAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid claim_name
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-name
:end-before: end-minio-openid-claim-name
Claim Prefix
~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_PREFIX
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid claim_prefix
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-prefix
:end-before: end-minio-openid-claim-prefix
Display Name
~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_DISPLAY_NAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid display_name
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-display-name
:end-before: end-minio-openid-display-name
Scopes
~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_SCOPES
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid scopes
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-scopes
:end-before: end-minio-openid-scopes
Redirect URI
~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_REDIRECT_URI
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid redirect_uri
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-redirect-uri
:end-before: end-minio-openid-redirect-uri
Dynamic URI Redirect
~~~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid redirect_uri_dynamic
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-redirect-uri-dynamic
:end-before: end-minio-openid-redirect-uri-dynamic
User Info
~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_USERINFO
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid claim_userinfo
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-userinfo
:end-before: end-minio-openid-claim-userinfo
Vendor
~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_VENDOR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid vendor
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-vendor
:end-before: end-minio-openid-vendor
Keycloak Realm
~~~~~~~~~~~~~~
*Optional*
This setting requires that the ``OpenID Vendor`` setting be defined as ``keycloak``.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_KEYCLOAK_REALM
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid keycloak_realm
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-keycloak-realm
:end-before: end-minio-openid-keycloak-realm
Keycloak Admin URL
~~~~~~~~~~~~~~~~~~
*Optional*
This setting requires that the ``OpenID Vendor`` setting be defined as ``keycloak``.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid keycloak_admin_url
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-keycloak-admin-url
:end-before: end-minio-openid-keycloak-admin-url
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_IDENTITY_OPENID_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: identity_openid comment
:delimiter: " "
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-comment
:end-before: end-minio-openid-comm

60
source/reference/minio-server/settings/kes.rst Normal file
View File

@ -0,0 +1,60 @@
.. _minio-server-envvar-kes:
===============================
Key Encryption Service Settings
===============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
The following environment variables control how the MinIO Server interacts with the Key Encryption Service (KES) when managing encryption and keys.
.. note::
These settings do not have configuration setting options for use with :mc:`mc admin config set`.
Define any of these environment variables in the host system prior to starting or restarting the MinIO process.
Refer to your operating system's documentation for how to define an environment variable.
.. envvar:: MINIO_KMS_KES_ENDPOINT
The endpoint for the MinIO Key Encryption Service (KES) process to use for supporting SSE-S3 and MinIO backend encryption operations.
.. envvar:: MINIO_KMS_KES_KEY_FILE
The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE` x.509 certificate to use when authenticating to the KES server.
The KES server requires clients to present their certificate for performing mutual TLS (mTLS).
See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>` for more complete documentation on KES access control.
.. envvar:: MINIO_KMS_KES_CERT_FILE
The x.509 certificate to present to the KES server.
The KES server requires clients to present their certificate for performing mutual TLS (mTLS).
The KES server computes an :minio-git:`identity <kes/wiki/Configuration#policy-configuration>` from the certificate and compares it to its configured policies.
The KES server grants the :mc:`minio` server access to only those operations explicitly granted by the policy.
See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>` for more complete documentation on KES access control.
.. envvar:: MINIO_KMS_KES_KEY_NAME
The name of an external key on the Key Management system (KMS) configured on the KES server and used for performing en/decryption operations.
MinIO uses this key for the following:
- Encrypting backend data (:ref:`IAM <minio-authentication-and-identity-management>`, server configuration).
- The default encryption key for Server-Side Encryption with :ref:`SSE-KMS <minio-encryption-sse-kms>`.
- The encryption key for Server-Side Encryption with :ref:`SSE-S3 <minio-encryption-sse-s3>`.
.. envvar:: MINIO_KMS_KES_ENCLAVE
Use this optional environment variable to define the name of a KES enclave.
A KES enclave provides an isolated space for its associated keys separate from other enclaves on a stateful KES server.
If not set, MinIO does not send enclave information.
For a stateful KES server, this results in using the default enclave.

988
source/reference/minio-server/settings/metrics-and-logging.rst Normal file
View File

@ -0,0 +1,988 @@
.. _minio-server-envvar-metrics-logging:
============================
Metrics and Logging Settings
============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings that control behavior related to MinIO metrics and logging.
See :ref:`minio-metrics-and-alerts` for more information.
These settings configure publishing regular :mc:`minio server` logs and audit logs to an HTTP webhook.
See :ref:`minio-logging` for more complete documentation.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
- :ref:`minio-server-envvar-logging-regular`
- :ref:`minio-server-envvar-logging-audit`
- :ref:`minio-server-envvar-logging-audit-kafka`
Prometheus Authentication
-------------------------
This setting controls how MinIO authenticates to Prometheus.
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_PROMETHEUS_AUTH_TYPE
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Specifies the authentication mode for the Prometheus :ref:`scraping endpoints <minio-metrics-and-alerts>`.
- ``jwt`` - *Default* MinIO requires that the scraping client specify a JWT token for authenticating requests.
Use :mc-cmd:`mc admin prometheus generate` to generate the necessary JWT bearer tokens.
- ``public`` MinIO does not require that scraping clients authenticate their requests.
.. _minio-server-envvar-logging-regular:
.. _minio-server-config-logging-regular:
Server Logs
-----------
The following section documents settings for configuring MinIO to publish :mc:`minio server` logs to an HTTP webhook endpoint.
See :ref:`minio-logging-publish-server-logs` 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:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
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"
.. tab-item:: Configuration Setting
:sync: config
.. code-block:: shell
:class: copyable
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
++++++
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_LOGGER_WEBHOOK_ENABLE
Specify ``"on"`` to enable publishing :mc:`minio server` logs to the HTTP webhook endpoint.
Requires specifying :envvar:`MINIO_LOGGER_WEBHOOK_ENDPOINT`.
.. tab-item:: Configuration Setting
There is no configuration setting for this value.
Use the environment variable instead.
Endpoint
++++++++
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_LOGGER_WEBHOOK_ENDPOINT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook endpoint
:delimiter: " "
The HTTP endpoint of the webhook.
Auth Token
++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: 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``:
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
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 :mc-conf:`logger_webhook auth_token <logger_webhook.auth_token>` configuration setting.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook auth_token
:delimiter: " "
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``:
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
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*.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_LOGGER_WEBHOOK_CLIENT_CERT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook client_cert
:delimiter: " "
The path to the mTLS certificate to use for authenticating to the webhook logger.
Client Key
++++++++++
*Optional*
Required if you define the *Client Certificate*.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_LOGGER_WEBHOOK_CLIENT_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook client_key
:delimiter: " "
The path to the mTLS certificate key to use to authenticate with the webhook logger service.
Proxy
+++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_LOGGER_WEBHOOK_PROXY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook proxy
:delimiter: " "
.. versionadded:: 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*
.. versionadded:: RELEASE.2023-05-18T00-05-36Z
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_LOGGER_WEBHOOK_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook queue_dir
:delimiter: " "
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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_LOGGER_WEBHOOK_QUEUE_SIZE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: logger_webhook queue_size
:delimiter: " "
An integer value to use for the queue size for logger webhook targets.
.. _minio-server-envvar-logging-audit:
.. _minio-server-config-logging-audit:
Webhook Audit Logs
------------------
The following section documents environment variables for configuring MinIO to publish audit logs to an HTTP webhook endpoint.
See :ref:`minio-logging-publish-audit-logs` 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:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
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"
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook
The top-level configuration key for defining an HTTP webhook target for
publishing :ref:`MinIO audit logs <minio-logging>`.
Use :mc-cmd:`mc admin config set` to set or update an HTTP webhook target.
Specify additional optional arguments as a whitespace (``" "``)-delimited
list.
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
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
++++++
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_AUDIT_WEBHOOK_ENABLE
Specify ``"on"`` to enable publishing audit logs to the HTTP webhook endpoint.
Requires specifying :envvar:`MINIO_AUDIT_WEBHOOK_ENDPOINT`.
.. tab-item:: Configuration Setting
Configure an audit webhook to enable it.
There is *not* a separate ``enable`` configuration setting.
Endpoint
++++++++
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_WEBHOOK_ENDPOINT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook endpoint
:delimiter: " "
The HTTP endpoint of the webhook.
Auth Token
++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_WEBHOOK_AUTH_TOKEN
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook auth_token
:delimiter: " "
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.
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
For example, for a Bearer token, prepend ``Bearer``:
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
.. tab-item:: Configuration Setting
:sync: config
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_WEBHOOK_CLIENT_CERT
Requires also specifying :envvar:`MINIO_AUDIT_WEBHOOK_CLIENT_KEY`.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook client_cert
:delimiter: " "
Requires also specifying :mc-conf:`~audit_webhook.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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_WEBHOOK_CLIENT_KEY
Requires also specifying :envvar:`MINIO_AUDIT_WEBHOOK_CLIENT_CERT`.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook client_key
:delimiter: " "
Requires specifying :mc-conf:`~audit_webhook.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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_WEBHOOK_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook queue_dir
:delimiter: " "
.. versionadded:: 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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_WEBHOOK_QUEUE_SIZE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_webhook queue_size
:delimiter: " "
An integer value to use for the queue size for audit webhook targets.
The default is ``100000`` events.
.. _minio-server-envvar-logging-audit-kafka:
.. _minio-server-config-logging-kafka-audit:
Kafka Audit Logs
----------------
The following section documents environment variables for configuring MinIO to publish audit logs to a Kafka broker.
.. mc-conf:: audit_kafka
The top-level configuration key for defining a Kafka broker target for publishing :ref:`MinIO audit logs <minio-logging>`.
Use :mc-cmd:`mc admin config set` to set or update a Kafka audit target.
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set audit_kafka \
brokers="https://kafka-endpoint.example.net:9092" [ARGUMENTS=VALUE ...]
Settings
~~~~~~~~
Enable
++++++
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_AUDIT_KAFKA_ENABLE
Set to ``"on"`` to enable the target.
Set to ``"off"`` to disable the target.
.. tab-item:: Configuration Setting
There is not a configuration setting for this value.
Use the environment variable to disable a configured audit webhook target.
Brokers
+++++++
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_BROKERS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka brokers
:delimiter: " "
A comma-separated list of Kafka broker addresses:
.. code-block:: shell
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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_TOPIC
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka topic
:delimiter: " "
The name of the Kafka topic to associate to MinIO audit log events.
TLS
+++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_TLS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka tls
:delimiter: " "
Set to ``"on"`` to enable TLS connectivity to the specified Kafka brokers.
Defaults to ``"off"``.
TLS Skip Verify
+++++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_TLS_SKIP_VERIFY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka tls_skip_verify
:delimiter: " "
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 :ref:`CA directory <minio-tls>` for verifying remote client TLS certificates.
Defaults to ``"off"`` for strict verification of TLS certificates.
SASL
++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_SASL
Requires specifying :envvar:`MINIO_AUDIT_KAFKA_SASL_USERNAME` and :envvar:`MINIO_AUDIT_KAFKA_SASL_PASSWORD`.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka sasl
:delimiter: " "
Requires specifying :mc-conf:`~audit_kafka.sasl_username` and :mc-conf:`~audit_kafka.sasl_password`.
Set to ``"on"`` to direct MinIO to use SASL to authenticate against the Kafka brokers.
SASL Username
+++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_SASL_USERNAME
Requires specifying :envvar:`MINIO_AUDIT_KAFKA_SASL` and :envvar:`MINIO_AUDIT_KAFKA_SASL_PASSWORD`.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka sasl_username
:delimiter: " "
Requires specifying :mc-conf:`~audit_kafka.sasl` and :mc-conf:`~audit_kafka.sasl_password`.
The SASL username MinIO uses for authentication against the Kafka brokers.
SASL Password
+++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_SASL_PASSWORD
Requires specifying :envvar:`MINIO_AUDIT_KAFKA_SASL` and :envvar:`MINIO_AUDIT_KAFKA_SASL_USERNAME`.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka sasl_password
:delimiter: " "
Requires specifying :mc-conf:`~audit_kafka.sasl` and :mc-conf:`~audit_kafka.sasl_username`.
The SASL password MinIO uses for authentication against the Kafka brokers.
SASL Mechanism
++++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_SASL_MECHANISM
.. important::
The ``PLAIN`` authentication mechanism sends credentials in plain text over the network.
Use :envvar:`MINIO_AUDIT_KAFKA_TLS` or to enable TLS connectivity to the Kafka brokers and ensure secure transmission of SASL credentials.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka sasl_mechanism
:delimiter: " "
.. important::
The ``PLAIN`` authentication mechanism sends credentials in plain text over the network.
Use :mc-conf:`~audit_kafka.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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_TLS_CLIENT_AUTH
Requires specifying :envvar:`MINIO_AUDIT_KAFKA_CLIENT_TLS_CERT` and :envvar:`MINIO_AUDIT_KAFKA_CLIENT_TLS_KEY`.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka tls_client_auth
:delimiter: " "
Requires specifying :mc-conf:`~audit_kafka.client_tls_cert` and :mc-conf:`~audit_kafka.client_tls_key`.
Set to ``"on"`` to direct MinIO to use mTLS to authenticate against the Kafka brokers.
Client TLS Certificate
++++++++++++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_CLIENT_TLS_CERT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka client_tls_cert
:delimiter: " "
The path to the TLS client certificate to use for mTLS authentication.
Client TLS Key
++++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_CLIENT_TLS_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka client_tls_key
:delimiter: " "
The path to the TLS client private key to use for mTLS authentication.
Version
+++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_VERSION
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka version
:delimiter: " "
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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka comment
:delimiter: " "
A comment to associate with the configuration.
Queue Directory
+++++++++++++++
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka queue_dir
:delimiter: " "
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*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_AUDIT_KAFKA_QUEUE_SIZE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: audit_kafka queue_size
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.

74
source/reference/minio-server/settings/notifications.rst Normal file
View File

@ -0,0 +1,74 @@
.. _minio-server-envvar-notifications:
.. _minio-server-config-logging-logs:
=============================
Bucket Notifications Settings
=============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings that control behavior related to :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Sync Events
-----------
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_API_SYNC_EVENTS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: sync_events
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-api-sync-events
:end-before: end-minio-api-sync-events
Supported Notification Targets
------------------------------
Notifications require a target to receive the events.
MinIO supports a variety of possible targets.
Settings for each target type have their own pages.
Select the appropriate link below for the type of target you use for notifications.
- :ref:`minio-server-envvar-bucket-notification-amqp`
- :ref:`minio-server-envvar-bucket-notification-elasticsearch`
- :ref:`minio-server-envvar-bucket-notification-kafka`
- :ref:`minio-server-envvar-bucket-notification-mqtt`
- :ref:`minio-server-envvar-bucket-notification-mysql`
- :ref:`minio-server-envvar-bucket-notification-nats`
- :ref:`minio-server-envvar-bucket-notification-nsq`
- :ref:`minio-server-envvar-bucket-notification-postgresql`
- :ref:`minio-server-envvar-bucket-notification-redis`
- :ref:`minio-server-envvar-bucket-notification-webhook`
.. toctree::
:titlesonly:
:hidden:
/reference/minio-server/settings/notifications/amqp
/reference/minio-server/settings/notifications/elasticsearch
/reference/minio-server/settings/notifications/kafka
/reference/minio-server/settings/notifications/mqtt
/reference/minio-server/settings/notifications/mysql
/reference/minio-server/settings/notifications/nats
/reference/minio-server/settings/notifications/nsq
/reference/minio-server/settings/notifications/postgresql
/reference/minio-server/settings/notifications/redis
/reference/minio-server/settings/notifications/webhook-service

365
source/reference/minio-server/settings/notifications/amqp.rst Normal file
View File

@ -0,0 +1,365 @@
.. _minio-server-envvar-bucket-notification-amqp:
.. _minio-server-config-bucket-notification-amqp:
==========================
AMQP Notification Settings
==========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an AMQP service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-amqp` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple AMQP Targets
---------------------
You can specify multiple AMQP service endpoints by appending a unique identifier ``_ID`` for each set of related AMQP settings to the top level key.
Examples
~~~~~~~~
For example, the following commands set two distinct AMQP service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_AMQP_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_AMQP_URL_PRIMARY="amqp://user:password@amqp-endpoint.example.net:5672"
set MINIO_NOTIFY_AMQP_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_AMQP_URL_SECONDARY="amqp://user:password@amqp-endpoint.example.net:5672"
For example, :envvar:`MINIO_NOTIFY_AMQP_ENABLE_PRIMARY <MINIO_NOTIFY_AMQP_ENABLE>` indicates the environment variable is associated to an AMQP service endpoint with ID of ``PRIMARY``.
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_amqp:primary \
url="user:password@amqp://amqp-endpoint.example.net:5672" [ARGUMENT=VALUE ...]
mc admin config set notify_amqp:secondary \
url="user:password@amqp://amqp-endpoint.example.net:5672" [ARGUMENT=VALUE ...]
Notice that for configuration settings, the unique identifier appends to ``amqp`` only, not to each individual argument.
Settings
--------
Enable
~~~~~~
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_NOTIFY_AMQP_ENABLE
Requires specifying :envvar:`MINIO_NOTIFY_AMQP_URL` if set to ``on``.
.. tab-item:: Configuration Setting
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-no-config-option
:end-before: end-minio-settings-no-config-option
Configure an AMQP target with desired options to enable a setting.
Specify ``on`` to enable publishing bucket notifications to an AMQP endpoint.
Defaults to ``off``.
URL
~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_URL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp url
:delimiter: " "
Specify the AMQP server endpoint to which MinIO publishes bucket events.
For example, ``amqp://myuser:mypassword@localhost:5672``.
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Exchange
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_EXCHANGE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp exchange
:delimiter: " "
Specify the name of the AMQP exchange to use.
Exchange Type
~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_EXCHANGE_TYPE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp exchange_type
:delimiter: " "
Specify the type of the AMQP exchange.
Routing Key
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_ROUTING_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp routing_key
:delimiter: " "
Specify the routing key for publishing events.
Mandatory
~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_MANDATORY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp mandatory
:delimiter: " "
Specify ``off`` to ignore undelivered messages errors.
Defaults to ``on``.
Durable
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_DURABLE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp durable
:delimiter: " "
Specify ``on`` to persist the message queue across broker restarts.
Defaults to ``off``.
No Wait
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_NO_WAIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp no_wait
:delimiter: " "
Specify ``on`` to enable non-blocking message delivery.
Defaults to ``off``.
Internal
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_INTERNAL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp internal
:delimiter: " "
.. explanation is very unclear. Need to revisit this.
Specify ``on`` to use the exchange only if it is bound to other exchanges.
See the RabbitMQ documentation on `Exchange to Exchange Bindings
<https://www.rabbitmq.com/e2e.html>`__ for more information on AMQP exchange binding.
Auto Deleted
~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_AUTO_DELETED
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp auto_deleted
:delimiter: " "
Specify ``on`` to automatically delete the message queue if there are no consumers.
Defaults to ``off``.
Delivery Mode
~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_DELIVERY_MODE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp delivery_mode
:delimiter: " "
Specify ``1`` for set the delivery mode to non-persistent queue.
Specify ``2`` to set the delivery mode to persistent queue.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp queue_dir
:delimiter: " "
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 AMQP service is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_AMQP_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_amqp comment
:delimiter: " "
Specify a comment for the AMQP configuration.

296
source/reference/minio-server/settings/notifications/elasticsearch.rst Normal file
View File

@ -0,0 +1,296 @@
.. _minio-server-envvar-bucket-notification-elasticsearch:
.. _minio-server-config-bucket-notification-elasticsearch:
===================================
Elasticsearch Notification Settings
===================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an Elasticsearch service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-elasticsearch` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple Elasticsearch Targets
------------------------------
You can specify multiple Elasticsearch service endpoints by appending a unique identifier ``_ID`` for each set of related settings.
For example, the following commands set two distinct Elasticsearch service endpoints as ``PRIMARY`` and ``SECONDARY``, respectively:
Examples
~~~~~~~~
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_ELASTICSEARCH_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_ELASTICSEARCH_URL_PRIMARY="https://user:password@elasticsearch-endpoint.example.net:9200"
set MINIO_NOTIFY_ELASTICSEARCH_INDEX_PRIMARY="bucketevents"
set MINIO_NOTIFY_ELASTICSEARCH_FORMAT_PRIMARY="namespace"
set MINIO_NOTIFY_ELASTICSEARCH_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_ELASTICSEARCH_URL_SECONDARY="https://user:password@elasticsearch-endpoint.example.net:9200"
set MINIO_NOTIFY_ELASTICSEARCH_INDEX_SECONDARY="bucketevents"
set MINIO_NOTIFY_ELASTICSEARCH_FORMAT_SECONDARY="namespace"
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_elasticsearch:primary \
url="user:password@https://elasticsearch-endpoint.example.net:9200" \
index="bucketevents" \
format="namespace" \
[ARGUMENT=VALUE ...]
mc admin config set notify_elasticsearch:secondary \
url="user:password@https://elasticsearch-endpoint.example.net:9200" \
index="bucketevents" \
format="namespace" \
[ARGUMENT=VALUE ...]
Notice that for configuration settings, the unique identifier appends to ``notify_elasticsearch`` only, not to each individual argument.
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_ENABLE
Specify ``on`` to enable publishing bucket notifications to an Elasticsearch service endpoint.
Defaults to ``off``.
Requires specifying the following additional environment variables if set to ``on``:
- :envvar:`MINIO_NOTIFY_ELASTICSEARCH_URL`
- :envvar:`MINIO_NOTIFY_ELASTICSEARCH_INDEX`
- :envvar:`MINIO_NOTIFY_ELASTICSEARCH_FORMAT`
.. tab-item:: Configuration Setting
.. mc-conf:: notify_elasticsearch
The top-level configuration key for defining an Elasticsearch service endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an Elasticsearch service endpoint.
The following arguments are *required* for each target:
- :mc-conf:`~notify_elasticsearch.url`
- :mc-conf:`~notify_elasticsearch.index`
- :mc-conf:`~notify_elasticsearch.format`
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_elasticsearch \
url="https://user:password@elasticsearch.example.com:9200" \
[ARGUMENT="VALUE"] ... \
URL
~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_URL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch url
:delimiter: " "
Specify the Elasticsearch service endpoint to which MinIO publishes bucket events.
For example, ``https://elasticsearch.example.com:9200``.
MinIO supports passing authentication information using as URL parameters using the format ``PROTOCOL://USERNAME:PASSWORD@HOSTNAME:PORT``.
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Index
~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_INDEX
.. tab-item:: Configuration Setting
.. mc-conf:: notify_elasticsearch index
:delimiter: " "
Specify the name of the Elasticsearch index in which to store or update MinIO bucket events.
Elasticsearch automatically creates the index if it does not exist.
Format
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_FORMAT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch format
:delimiter: " "
Specify the format of event data written to the Elasticsearch index.
MinIO supports the following values:
``namespace``
For each bucket event, MinIO creates a JSON document with the bucket and object name from the event as the document ID and the actual event as part of the document body.
Additional updates to that object modify the existing index entry for that object.
Similarly, deleting the object also deletes the corresponding index entry.
``access``
For each bucket event, MinIO creates a JSON document with the event details and appends it to the index with an Elasticsearch-generated random ID.
Additional updates to an object result in new index entries, and existing entries remain unmodified.
Username
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_USERNAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch username
:delimiter: " "
The username for connecting to an Elasticsearch service endpoint which enforces authentication.
Password
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_PASSWORD
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch password
:delimiter: " "
The password for connecting to an Elasticsearch service endpoint which enforces authentication.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch queue_dir
:delimiter: " "
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 Elasticsearch service is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_ELASTICSEARCH_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_elasticsearch comment
:delimiter: " "
Specify a comment to associate with the Elasticsearch configuration.

444
source/reference/minio-server/settings/notifications/kafka.rst Normal file
View File

@ -0,0 +1,444 @@
.. _minio-server-envvar-bucket-notification-kafka:
.. _minio-server-config-bucket-notification-kafka:
===========================
Kafka Notification Settings
===========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an Kafka service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-kafka` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple Kafka Targets
----------------------
You can specify multiple Kafka service endpoints by appending a unique identifier ``_ID`` for each set of related Kafka settings on to the top level key.
Examples
~~~~~~~~
For example, the following commands set two distinct Kafka service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_KAFKA_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_KAFKA_BROKERS_PRIMARY="https://kafka1.example.net:9200, https://kafka2.example.net:9200"
set MINIO_NOTIFY_KAFKA_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_KAFKA_BROKERS_SECONDARY="https://kafka1.example.net:9200, https://kafka2.example.net:9200"
.. tab-item:: Configuration Setting
:sync: config
.. code-block:: shell
mc admin config set notify_kafka:primary \
brokers="https://kafka1.example.net:9200, https://kafka2.example.net:9200"
[ARGUMENT=VALUE ...]
mc admin config set notify_kafka:secondary \
brokers="https://kafka1.example.net:9200, https://kafka2.example.net:9200"
[ARGUMENT=VALUE ...]
Notice that for configuration settings, the unique identifier appends to ``notify_kafka`` only, not to each individual argument.
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_ENABLE
Specify ``on`` to enable publishing bucket notifications to a Kafka service endpoint.
Defaults to ``off``.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka
The top-level configuration key for defining an Kafka service endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an Kafka service endpoint.
The :mc-conf:`~notify_kafka.brokers` argument is *required* for each target.
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_kafka \
brokers="https://kafka1.example.net:9200, https://kafka2.example.net:9200"
[ARGUMENT="VALUE"] ... \
Brokers
~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_BROKERS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka brokers
:delimiter: " "
Specify a comma-separated list of Kafka broker addresses.
For example:
``"kafka1.example.com:2021,kafka2.example.com:2021"``
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Topic
~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_TOPIC
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka topic
:delimiter: " "
Specify the name of the Kafka topic to which MinIO publishes bucket events.
SASL
~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_SASL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka sasl
:delimiter: " "
Specify ``on`` to enable SASL authentication.
SASL Username
~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_SASL_USERNAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka sasl_username
:delimiter: " "
Specify the username for performing SASL/PLAIN or SASL/SCRAM authentication to the Kafka broker(s).
SASL Password
~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_SASL_PASSWORD
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka sasl_password
:delimiter: " "
Specify the password for performing SASL/PLAIN or SASL/SCRAM authentication to the Kafka broker(s).
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
SASL Mechanism
~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_SASL_MECHANISM
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka sasl_mechanism
:delimiter: " "
Specify the SASL mechanism to use for authenticating to the Kafka broker(s).
MinIO supports the following mechanisms:
- ``PLAIN`` (Default)
- ``SHA256``
- ``SHA512``
TLS Client Auth
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_TLS_CLIENT_AUTH
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka tls_client_auth
:delimiter: " "
Specify the client authentication type of the Kafka broker(s).
The following table lists the supported values and their mappings
.. list-table::
:header-rows: 1
:widths: 20 80
:width: 100%
* - Value
- Authentication Type
* - 0
- ``NoClientCert``
* - 1
- ``RequestClientCert``
* - 2
- ``RequireAnyClientCert``
* - 3
- ``VerifyClientCertIfGiven``
* - 4
- ``RequireAndVerifyClientCert``
See `ClientAuthType <https://golang.org/pkg/crypto/tls/#ClientAuthType>`__ for more information on each client auth type.
TLS
~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_TLS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka tls
:delimiter: " "
Specify ``on`` to enable TLS connectivity to the Kafka broker(s).
TLS Skip Verify
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_TLS_SKIP_VERIFY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka tls_skip_verify
:delimiter: " "
Enables or disables TLS verification of the NATS service endpoint TLS certificates.
- Specify ``on`` to disable TLS verification *(Default)*.
- Specify ``off`` to enable TLS verification.
Client TLS Cert
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_CLIENT_TLS_CERT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka client_tls_cert
:delimiter: " "
Specify the path to the client certificate to use for performing mTLS authentication to the Kafka broker(s).
Client TLS Key
~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_CLIENT_TLS_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka client_tls_key
:delimiter: " "
Specify the path to the client private key to use for performing mTLS authentication to the Kafka broker(s).
Version
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_VERSION
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka version
:delimiter: " "
Specify the version of the Kafka cluster to assume when performing operations against that cluster.
See the `sarama reference documentation <https://github.com/shopify/sarama/blob/v1.20.1/config.go#L327>`__ for more information on this field's behavior.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka queue_dir
:delimiter: " "
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 server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_KAFKA_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_kafka comment
:delimiter: " "
Specify a comment to associate with the Kafka configuration.

337
source/reference/minio-server/settings/notifications/mqtt.rst Normal file
View File

@ -0,0 +1,337 @@
.. _minio-server-envvar-bucket-notification-mqtt:
.. _minio-server-config-bucket-notification-mqtt:
==========================
MQTT Notification Settings
==========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an MQTT service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-mqtt` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple MQTT Targets
---------------------
You can specify multiple MQTT service endpoints by appending a unique identifier ``_ID`` for each set of related MQTT settings to the top level key.
For example, the following commands set two distinct MQTT service endpoints as ``PRIMARY`` and ``SECONDARY``, respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_MQTT_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_MQTT_BROKER_PRIMARY="tcp://user:password@mqtt-endpoint.example.net:1883"
set MINIO_NOTIFY_MQTT_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_MQTT_BROKER_SECONDARY="tcp://user:password@mqtt-endpoint.example.net:1883"
.. tab-item:: Configuration Setting
:sync: config
.. code-block:: shell
mc admin config set notify_mqtt:primary \
broker="tcp://endpoint:port" \
topic="minio/bucket-name/events/" \
username="username" \
password="password" \
[ARGUMENT="VALUE"] ... \
mc admin config set notify_mqtt:secondary \
broker="tcp://endpoint:port" \
topic="minio/bucket-name/events/" \
username="username" \
password="password" \
[ARGUMENT="VALUE"] ... \
With these settings, :envvar:`MINIO_NOTIFY_MQTT_ENABLE_PRIMARY <MINIO_NOTIFY_MQTT_ENABLE>` indicates the environment variable is associated to an MQTT service endpoint with an ID of ``PRIMARY``.
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_ENABLE
Specify ``on`` to enable publishing bucket notifications to an MQTT endpoint.
Defaults to ``off``.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt
The top-level configuration key for defining an MQTT server/broker endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an MQTT server/broker endpoint.
The following arguments are *required* for each endpoint:
- :mc-conf:`~notify_mqtt.broker`
- :mc-conf:`~notify_mqtt.topic`
- :mc-conf:`~notify_mqtt.username` *Optional if MQTT server/broker does not enforce authentication/authorization*
- :mc-conf:`~notify_mqtt.password` *Optional if MQTT server/broker does not enforce authentication/authorization*
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_mqtt \
broker="tcp://endpoint:port" \
topic="minio/bucket-name/events/" \
username="username" \
password="password" \
[ARGUMENT="VALUE"] ... \
Broker
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_BROKER
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt broker
:delimiter: " "
Specify the MQTT server/broker endpoint.
MinIO supports TCP, TLS, or Websocket connections to the server/broker URL.
For example:
- ``tcp://mqtt.example.net:1883``
- ``tls://mqtt.example.net:1883``
- ``ws://mqtt.example.net:1883``
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Topic
~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_TOPIC
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt topic
:delimiter: " "
Specify the name of the MQTT topic to associate with events published by MinIO to the MQTT endpoint.
Username
~~~~~~~~
*Required if the MQTT server/broker enforces authentication/authorization*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_USERNAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt username
:delimiter: " "
Specify the MQTT username MinIO should use to authenticate to the MQTT server/broker.
Password
~~~~~~~~
*Required if the MQTT server/broker enforces authentication/authorization*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_PASSWORD
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt password
:delimiter: " "
Specify the password for the MQTT username MinIO uses to authenticate to the MQTT server/broker.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
Quality of Service
~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_QOS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt qos
:delimiter: " "
Specify the Quality of Service priority for the published events.
Defaults to ``0``.
Keep Alive Interval
~~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_KEEP_ALIVE_INTERVAL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt keep_alive_interval
:delimiter: " "
Specify the keep-alive interval for the MQTT connections. MinIO
supports the following units of time measurement:
- ``s`` - seconds, "60s"
- ``m`` - minutes, "60m"
- ``h`` - hours, "24h"
- ``d`` - days, "7d"
Reconnect Interval
~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_RECONNECT_INTERVAL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt reconnect_interval
:delimiter: " "
Specify the reconnect interval for the MQTT connections. MinIO
supports the following units of time measurement:
- ``s`` - seconds, "60s"
- ``m`` - minutes, "60m"
- ``h`` - hours, "24h"
- ``d`` - days, "7d"
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt queue_dir
:delimiter: " "
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 MQTT server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MQTT_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mqtt comment
:delimiter: " "
Specify a comment to associate with the MQTT configuration.

282
source/reference/minio-server/settings/notifications/mysql.rst Normal file
View File

@ -0,0 +1,282 @@
.. _minio-server-envvar-bucket-notification-mysql:
.. _minio-server-config-bucket-notification-mysql:
===========================
MySQL Notification Settings
===========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring a MYSQL service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-mysql` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple MYSQL Targets
----------------------
You can specify multiple MySQL service endpoints by appending a unique identifier ``_ID`` for each set of related MySQL settings on to the top level key.
Examples
~~~~~~~~
The following commands set two distinct MySQL service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_MYSQL_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_MYSQL_DSN_STRING_PRIMARY="username:password@tcp(mysql.example.com:3306)/miniodb"
set MINIO_NOTIFY_MYSQL_TABLE_PRIMARY="minioevents"
set MINIO_NOTIFY_MYSQL_FORMAT_PRIMARY="namespace"
set MINIO_NOTIFY_MYSQL_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_MYSQL_DSN_STRING_SECONDARY="username:password@tcp(mysql.example.com:3306)/miniodb"
set MINIO_NOTIFY_MYSQL_TABLE_SECONDARY="minioevents"
set MINIO_NOTIFY_MYSQL_FORMAT_SECONDARY="namespace"
With these settings, :envvar:`MINIO_NOTIFY_MYSQL_ENABLE_PRIMARY <MINIO_NOTIFY_MYSQL_ENABLE>` indicates the environment variable is associated to a MySQL service endpoint with ID of ``PRIMARY``.
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_mysql:primary \
dsn_string="username:password@tcp(mysql.example.com:3306)/miniodb"
table="minioevents" \
format="namespace" \
[ARGUMENT=VALUE ...]
mc admin config set notify_mysql:secondary \
dsn_string="username:password@tcp(mysql.example.com:3306)/miniodb"
table="minioevents" \
format="namespace" \
[ARGUMENT=VALUE ...]
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_ENABLE
Specify ``on`` to enable publishing bucket notifications to a MySQL service endpoint.
Defaults to ``off``.
Requires specifying the following additional environment variables if set to ``on``:
- :envvar:`MINIO_NOTIFY_MYSQL_DSN_STRING`
- :envvar:`MINIO_NOTIFY_MYSQL_TABLE`
- :envvar:`MINIO_NOTIFY_MYSQL_FORMAT`
.. tab-item:: Configuration Settings
:sync: config
.. mc-conf:: notify_mysql
The top-level configuration key for defining an MySQL service endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an MySQL service endpoint.
The following arguments are *required* for each target:
- :mc-conf:`~notify_mysql.dsn_string`
- :mc-conf:`~notify_mysql.table`
- :mc-conf:`~notify_mysql.format`
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_mysql \
dsn_string="username:password@tcp(mysql.example.com:3306)/miniodb"
table="minioevents" \
format="namespace" \
[ARGUMENT="VALUE"] ... \
Data Source Name (DSN) String
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_DSN_STRING
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql dsn_string
:delimiter: " "
Specify the data source name (DSN) of the MySQL service endpoint. MinIO expects the following format:
``<user>:<password>@tcp(<host>:<port>)/<database>``
For example:
``"username:password@tcp(mysql.example.com:3306)/miniodb"``
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Table
~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_TABLE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql table
:delimiter: " "
Specify the name of the MySQL table to which MinIO publishes event notifications.
Format
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_FORMAT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql format
:delimiter: " "
Specify the format of event data written to the MySQL service endpoint.
MinIO supports the following values:
``namespace``
For each bucket event, MinIO creates a JSON document with the bucket and object name from the event as the document ID and the actual event as part of the document body.
Additional updates to that object modify the existing table entry for that object.
Similarly, deleting the object also deletes the corresponding table entry.
``access``
For each bucket event, MinIO creates a JSON document with the event details and appends it to the table with a MySQL-generated random ID.
Additional updates to an object result in new index entries, and existing entries remain unmodified.
Max Open Connections
~~~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_MAX_OPEN_CONNECTIONS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql max_open_connections
:delimiter: " "
Specify the maximum number of open connections to the MySQL database.
Defaults to ``2``.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql queue_dir
:delimiter: " "
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 MySQL server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages. Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_MYSQL_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_mysql comment
:delimiter: " "
Specify a comment to associate with the MySQL configuration.

519
source/reference/minio-server/settings/notifications/nats.rst Normal file
View File

@ -0,0 +1,519 @@
.. _minio-server-envvar-bucket-notification-nats:
.. _minio-server-config-bucket-notification-nats:
==========================
NATS Notification Settings
==========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. admonition:: NATS Streaming Deprecated
:class: important
NATS Streaming is deprecated.
Migrate to `JetStream <https://docs.nats.io/nats-concepts/jetstream>`__ instead.
The related MinIO configuration options and environment variables are deprecated.
This page documents settings for configuring an NATS service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-nats` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple NATS Targets
---------------------
You can specify multiple NATS service endpoints by appending a unique identifier ``_ID`` for each set of related NATS settings on to the top level key.
Example
~~~~~~~
For example, the following commands set two distinct NATS service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_NATS_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_NATS_ADDRESS_PRIMARY="https://nats-endpoint.example.net:4222"
set MINIO_NOTIFY_NATS_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_NATS_ADDRESS_SECONDARY="https://nats-endpoint.example.net:4222"
With these settings, :envvar:`MINIO_NOTIFY_NATS_ENABLE_PRIMARY <MINIO_NOTIFY_NATS_ENABLE>` indicates the environment variable is associated to an NATS service endpoint with ID of ``PRIMARY``.
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_nats:primary \
address="https://nats-endpoint.example.com:4222" \
subject="minioevents" \
[ARGUMENT=VALUE ...]
mc admin config set notify_nats:secondary \
address="https://nats-endpoint.example.com:4222" \
subject="minioevents" \
[ARGUMENT=VALUE ...]
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_ENABLE
Specify ``on`` to enable publishing bucket notifications to an NATS service endpoint.
Defaults to ``off``.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats
The top-level configuration key for defining an NATS service endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an NATS service endpoint.
The :mc-conf:`~notify_nats.address` and :mc-conf:`~notify_nats.subject` arguments are *required* for each target.
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_nats \
address="https://nats-endpoint.example.com:4222" \
subject="minioevents" \
[ARGUMENT="VALUE"] ... \
Address
~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_ADDRESS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats address
:delimiter: " "
Specify the NATS service endpoint to which MinIO publishes bucket events.
For example, ``https://nats-endpoint.example.com:4222``.
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Subject
~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_SUBJECT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats subject
:delimiter: " "
Specify the subscription to which MinIO associates events published to the NATS endpoint.
Username
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_USERNAME
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats username
:delimiter: " "
Specify the username for connecting to the NATS service endpoint.
Password
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_PASSWORD
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats password
:delimiter: " "
Specify the passport for connecting to the NATS service endpoint.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
Token
~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_TOKEN
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats token
:delimiter: " "
Specify the token for connecting to the NATS service endpoint.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
TLS
~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_TLS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats tls
:delimiter: "
Specify ``on`` to enable TLS connectivity to the NATS service endpoint.
TLS Skip Verify
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_TLS_SKIP_VERIFY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats tls_skip_verify
:delimiter: " "
Enables or disables TLS verification of the NATS service endpoint TLS certificates.
- Specify ``on`` to disable TLS verification (Default).
- Specify ``off`` to enable TLS verification.
Ping Interval
~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_PING_INTERVAL
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats ping_interval
:delimiter: " "
Specify the duration interval for client pings to the NATS server.
MinIO supports the following time units:
- ``s`` - seconds, ``"60s"``
- ``m`` - minutes, ``"5m"``
- ``h`` - hours, ``"1h"``
- ``d`` - days, ``"1d"``
Jetstream
~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_JETSTREAM
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats jetstream
:delimiter: " "
Specify ``on`` to enable JetStream support for streaming events to a NATS JetStream service endpoint.
Streaming
~~~~~~~~~
*Deprecated*
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_STREAMING
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats streaming
:delimiter: " "
Specify ``on`` to enable asynchronous publishing of events to the NATS service endpoint.
Streaming Async
~~~~~~~~~~~~~~~
*Deprecated*
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_STREAMING_ASYNC
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats streaming_async
:delimiter: " "
Specify ``on`` to enable asynchronous publishing of events to the NATS service endpoint.
Max ACK Responses In Flight
~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Deprecated*
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_STREAMING_MAX_PUB_ACKS_IN_FLIGHT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats streaming_max_pub_acks_in_flight
:delimiter: " "
Specify the number of messages to publish without waiting for an ACK response from the NATS service endpoint.
Streaming Cluster ID
~~~~~~~~~~~~~~~~~~~~
*Deprecated*
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_STREAMING_CLUSTER_ID
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats streaming_cluster_id
:delimiter: " "
Specify the unique ID for the NATS streaming cluster.
Cert Authority
~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_CERT_AUTHORITY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats cert_authority
:delimiter: " "
Specify the path to the Certificate Authority chain used to sign the NATS service endpoint TLS certificates.
Client Cert
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_CLIENT_CERT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats client_cert
:delimiter: " "
Specify the path to the client certificate to use for performing mTLS authentication to the NATS service endpoint.
Client Key
~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_CLIENT_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats client_key
:delimiter: " "
Specify the path to the client private key to use for performing mTLS authentication to the NATS service endpoint.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats queue_dir
:delimiter: " "
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 NATS server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NATS_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nats comment
:delimiter: " "
Specify a comment to associate with the NATS configuration.

250
source/reference/minio-server/settings/notifications/nsq.rst Normal file
View File

@ -0,0 +1,250 @@
.. _minio-server-envvar-bucket-notification-nsq:
.. _minio-server-config-bucket-notification-nsq:
=========================
NSQ Notification Settings
=========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an NSQ service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-nsq` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple NSQ Targets
--------------------
You can specify multiple NSQ service endpoints by appending a unique identifier ``_ID`` to the end of the top level key for each set of related NSQ settings.
For example, the following commands set two distinct NSQ service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_NSQ_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_NSQ_NSQD_ADDRESS_PRIMARY="https://user:password@nsq-endpoint.example.net:9200"
set MINIO_NOTIFY_NSQ_TOPIC_PRIMARY="bucketevents"
set MINIO_NOTIFY_NSQ_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_NSQ_NSQD_ADDRESS_SECONDARY="https://user:password@nsq-endpoint.example.net:9200"
set MINIO_NOTIFY_NSQ_TOPIC_SECONDARY="bucketevents"
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_nsq:primary \
nsqd_address="ENDPOINT" \
topic="<string>" \
[ARGUMENT="VALUE"] ... \
mc admin config set notify_nsq:secondary \
nsqd_address="ENDPOINT" \
topic="<string>" \
[ARGUMENT="VALUE"] ... \
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_ENABLE
Specify ``on`` to enable publishing bucket notifications to an NSQ endpoint.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq
The top-level configuration key for defining an NSQ server/broker endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an NSQ server/broker endpoint.
The following arguments are *required* for each endpoint:
- :mc-conf:`~notify_nsq.nsqd_address`
- :mc-conf:`~notify_nsq.topic`
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_nsq \
nsqd_address="https://nsq-endpoint.example.net:4150" \
topic="<string>" \
[ARGUMENT="VALUE"] ...
NSQ Daemon Server Address
~~~~~~~~~~~~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_NSQD_ADDRESS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq nsqd_address
:delimiter: " "
Specify the NSQ server address where the NSQ Daemon runs.
For example:
``https://nsq-endpoint.example.net:4150``
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Topic
~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_TOPIC
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq topic
:delimiter: " "
Specify the name of the NSQ topic MinIO uses when publishing events to the broker.
TLS
~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_TLS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq tls
:delimiter: " "
Specify ``on`` to enable TLS connectivity to the NSQ service broker.
TLS Skip Verify
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_TLS_SKIP_VERIFY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq tls_skip_verify
:delimiter: " "
Enables or disables TLS verification of the NSQ service broker TLS certificates.
- Specify ``on`` to disable TLS verification (Default).
- Specify ``off`` to enable TLS verification.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq queue_dir
:delimiter: " "
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 NSQ server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_NSQ_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_nsq comment
:delimiter: " "
Specify a comment to associate with the NSQ configuration.

277
source/reference/minio-server/settings/notifications/postgresql.rst Normal file
View File

@ -0,0 +1,277 @@
.. _minio-server-envvar-bucket-notification-postgresql:
.. _minio-server-config-bucket-notification-postgresql:
================================
PostgreSQL Notification Settings
================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an POSTGRES service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-postgresql` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple PostgreSQL Targets
---------------------------
You can specify multiple PostgreSQL service endpoints by appending a unique identifier ``_ID`` for each set of related PostgreSQL settings on to the top level key.
For example, the following commands set two distinct PostgreSQL service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_POSTGRES_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_POSTGRES_CONNECTION_STRING_PRIMARY="host=postgresql-endpoint.example.net port=4222..."
set MINIO_NOTIFY_POSTGRES_TABLE_PRIMARY="minioevents"
set MINIO_NOTIFY_POSTGRES_FORMAT_PRIMARY="namespace"
set MINIO_NOTIFY_POSTGRES_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_POSTGRES_CONNECTION_STRING_SECONDARY="host=postgresql-endpoint.example.net port=4222..."
set MINIO_NOTIFY_POSTGRES_TABLE_SECONDARY="minioevents"
set MINIO_NOTIFY_POSTGRES_FORMAT_SECONDARY="namespace"
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_postgres:primary \
connection_string="host=postgresql.example.com port=5432..."
table="minioevents" \
format="namespace" \
[ARGUMENT=VALUE ...]
mc admin config set notify_postgres:secondary \
connection_string="host=postgresql.example.com port=5432..."
table="minioevents" \
format="namespace" \
[ARGUMENT=VALUE ...]
With these settings, :envvar:`MINIO_NOTIFY_POSTGRES_ENABLE_PRIMARY <MINIO_NOTIFY_POSTGRES_ENABLE>` indicates the environment variable is associated to an PostgreSQL service endpoint with ID of ``PRIMARY``.
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_ENABLE
Specify ``on`` to enable publishing bucket notifications to a PostgreSQL service endpoint.
Defaults to ``off``.
Requires specifying the following additional environment variables if set to ``on``:
- :envvar:`MINIO_NOTIFY_POSTGRES_CONNECTION_STRING`
- :envvar:`MINIO_NOTIFY_POSTGRES_TABLE`
- :envvar:`MINIO_NOTIFY_POSTGRES_FORMAT`
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres
The top-level configuration key for defining an PostgreSQL service endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an PostgreSQL service endpoint.
The following arguments are *required* for each target:
- :mc-conf:`~notify_postgres.connection_string`
- :mc-conf:`~notify_postgres.table`
- :mc-conf:`~notify_postgres.format`
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_postgres \
connection_string="host=postgresql.example.com port=5432..." \
table="minioevents" \
format="namespace" \
[ARGUMENT="VALUE"] ...
Connection String
~~~~~~~~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_CONNECTION_STRING
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres connection_string
:delimiter: " "
Specify the `URI connection string <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`__ of the PostgreSQL service endpoint.
MinIO supports ``key=value`` format for the PostgreSQL connection string.
For example:
``"host=https://postgresql.example.com port=5432 ..."``
For more complete documentation on supported PostgreSQL connection string parameters, see the `PostgreSQL Connection Strings documentation <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`__.
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Table
~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_TABLE
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres table
:delimiter: " "
Specify the name of the PostgreSQL table to which MinIO publishes event notifications.
Format
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_FORMAT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres format
:delimiter: " "
Specify the format of event data written to the PostgreSQL service endpoint.
MinIO supports the following values:
``namespace``
For each bucket event, MinIO creates a JSON document with the bucket and object name from the event as the document ID and the actual event as part of the document body.
Additional updates to that object modify the existing table entry for that object.
Similarly, deleting the object also deletes the corresponding table entry.
``access``
For each bucket event, MinIO creates a JSON document with the event details and appends it to the table with a PostgreSQL-generated random ID.
Additional updates to an object result in new index entries, and existing entries remain unmodified.
Max Open Connections
~~~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_MAX_OPEN_CONNECTIONS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres max_open_connections
:delimiter: " "
Specify the maximum number of open connections to the PostgreSQL database.
Defaults to ``2``.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres queue_dir
:delimiter: " "
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 PostgreSQL server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_POSTGRES_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_postgres comment
:delimiter: " "
Specify a comment to associate with the PostgreSQL configuration.

274
source/reference/minio-server/settings/notifications/redis.rst Normal file
View File

@ -0,0 +1,274 @@
.. _minio-server-envvar-bucket-notification-redis:
.. _minio-server-config-bucket-notification-redis:
===========================
Redis Notification Settings
===========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring a Redis service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-redis` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple Redis Targets
----------------------
You can specify multiple Redis service endpoints by appending a unique identifier ``_ID`` to the end of the top level key for each set of related Redis settings.
For example, the following commands set two distinct Redis service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_REDIS_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_REDIS_REDIS_ADDRESS_PRIMARY="https://user:password@redis-endpoint.example.net:9200"
set MINIO_NOTIFY_REDIS_KEY_PRIMARY="bucketevents"
set MINIO_NOTIFY_REDIS_FORMAT_PRIMARY="namespace"
set MINIO_NOTIFY_REDIS_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_REDIS_REDIS_ADDRESS_SECONDARY="https://user:password@redis-endpoint2.example.net:9200"
set MINIO_NOTIFY_REDIS_KEY_SECONDARY="bucketevents"
set MINIO_NOTIFY_REDIS_FORMAT_SECONDARY="namespace"
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_redis:primary \
address="https://redis-endpoint.example.net:9200" \
key="bucketevents" \
format="namespace" \
[ARGUMENT="VALUE"] ... \
mc admin config set notify_redis:secondary \
address="https://redis-endpoint2.example.net:9200" \
key="bucketevents" \
format="namespace" \
[ARGUMENT="VALUE"] ...
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_ENABLE
Specify ``on`` to enable publishing bucket notifications to a Redis service endpoint.
Defaults to ``off``.
Requires specifying the following additional environment variables if set to ``on``:
- :envvar:`MINIO_NOTIFY_REDIS_ADDRESS`
- :envvar:`MINIO_NOTIFY_REDIS_KEY`
- :envvar:`MINIO_NOTIFY_REDIS_FORMAT`
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis
The top-level configuration key for defining an Redis server/broker endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an Redis server/broker endpoint.
The following arguments are *required* for each endpoint:
- :mc-conf:`~notify_redis.address`
- :mc-conf:`~notify_redis.key`
- :mc-conf:`~notify_redis.format`
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_redis \
address="ENDPOINT" \
key="<string>" \
format="<string>" \
[ARGUMENT="VALUE"] ... \
Address
~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_ADDRESS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis address
:delimiter: " "
Specify the Redis service endpoint to which MinIO publishes bucket events.
For example, ``https://redis.example.com:6369``.
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Key
~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis key
:delimiter: " "
Specify the Redis key to use for storing and updating events.
Redis auto-creates the key if it does not exist.
Format
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_FORMAT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis format
:delimiter: " "
Specify the format of event data written to the Redis service endpoint.
MinIO supports the following values:
``namespace``
For each bucket event, MinIO creates a JSON document with the bucket and object name from the event as the document ID and the actual event as part of the document body.
Additional updates to that object modify the existing index entry for that object.
Similarly, deleting the object also deletes the corresponding index entry.
``access``
For each bucket event, MinIO creates a JSON document with the event details and appends it to the key with a Redis-generated random ID.
Additional updates to an object result in new index entries, and existing entries remain unmodified.
Password
~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_PASSWORD
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis password
:delimiter: " "
Specify the password for the Redis server.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis queue_dir
:delimiter: " "
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 Redis server/broker is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_REDIS_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_redis comment
:delimiter: " "
Specify a comment to associate with the Redis configuration.

289
source/reference/minio-server/settings/notifications/webhook-service.rst Normal file
View File

@ -0,0 +1,289 @@
.. _minio-server-envvar-bucket-notification-webhook-service:
.. _minio-server-envvar-bucket-notification-webhook:
.. _minio-server-config-bucket-notification-webhook:
=====================================
Webhook Service Notification Settings
=====================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents settings for configuring an Webhook service as a target for :ref:`Bucket Notifications <minio-bucket-notifications>`.
See :ref:`minio-bucket-notifications-publish-webhook` for a tutorial on using these settings.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Multiple Webhook Service Targets
--------------------------------
You can specify multiple Webhook service endpoints by appending a unique identifier ``_ID`` for each set of related Webhook settings on to the top level key.
For example, the following commands set two distinct Webhook service endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
.. tab-set::
.. tab-item:: Environment Variables
:sync: envvar
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_WEBHOOK_ENABLE_PRIMARY="on"
set MINIO_NOTIFY_WEBHOOK_ENDPOINT_PRIMARY="https://webhook1.example.net"
set MINIO_NOTIFY_WEBHOOK_ENABLE_SECONDARY="on"
set MINIO_NOTIFY_WEBHOOK_ENDPOINT_SECONDARY="https://webhook1.example.net"
.. tab-item:: Configuration Settings
:sync: config
.. code-block:: shell
mc admin config set notify_webhook:primary \
endpoint="https://webhook1.example.net"
[ARGUMENT=VALUE ...]
mc admin config set notify_webhook:secondary \
endpoint="https://webhook2.example.net
[ARGUMENT=VALUE ...]
Settings
--------
Enable
~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_ENABLE
Specify ``on`` to enable publishing bucket notifications to a Webhook service endpoint.
Defaults to ``off``.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook
The top-level configuration key for defining an Webhook service endpoint for use with :ref:`MinIO bucket notifications <minio-bucket-notifications>`.
Use :mc-cmd:`mc admin config set` to set or update an Webhook service endpoint.
The :mc-conf:`~notify_webhook.endpoint` argument is *required* for each target.
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set notify_webhook \
endpoint="https://webhook.example.net"
[ARGUMENT="VALUE"] ... \
Endpoint
~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_ENDPOINT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook endpoint
:delimiter: " "
Specify the URL for the webhook service.
.. include:: /includes/linux/minio-server.rst
:start-after: start-notify-target-online-desc
:end-before: end-notify-target-online-desc
Auth Token
~~~~~~~~~~
*Required*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_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``:
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"
Modify the value according to the endpoint requirements.
A custom authentication format could resemble the following:
.. code-block:: shell
:class: copyable
set MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
Consult the documentation for the desired service for more details.
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook auth_token
:delimiter: " "
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``:
.. code-block:: shell
:class: copyable
mc admin config set myminio notify_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:
.. code-block:: shell
:class: copyable
mc admin config set myminio notify_webhook \
endpoint="https://webhook-1.example.net" \
auth_token="ServiceXYZ 1a2b3c4f5e"
Consult the documentation for the desired service for more details.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
Queue Directory
~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_QUEUE_DIR
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook queue_dir
:delimiter: " "
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 webhook service is offline and replays the stored events when connectivity resumes.
Queue Limit
~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_QUEUE_LIMIT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook queue_limit
:delimiter: " "
Specify the maximum limit for undelivered messages.
Defaults to ``100000``.
Client Certificate
~~~~~~~~~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_CLIENT_CERT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook client_cert
:delimiter: " "
Specify the path to the client certificate to use for performing mTLS authentication to the webhook service.
Client Key
~~~~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_CLIENT_KEY
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook client_key
:delimiter: " "
Specify the path to the client private key to use for performing mTLS authentication to the webhook service.
Comment
~~~~~~~
*Optional*
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_NOTIFY_WEBHOOK_COMMENT
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: notify_webhook comment
:delimiter: " "
Specify a comment to associate with the Webhook configuration.

54
source/reference/minio-server/settings/object-lambda.rst Normal file
View File

@ -0,0 +1,54 @@
.. _minio-server-envvar-object-lambda-webhook:
===============================
Object Lambda Function Settings
===============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page documents environment variables for configuring MinIO to publish data to an HTTP webhook endpoint and trigger an Object Lambda function.
See :ref:`developers-object-lambda` for more complete documentation and tutorials on using these environment variables.
You can specify multiple webhook endpoints as Lambda targets by appending a unique identifier ``_FUNCTIONNAME`` for each Object Lambda function.
For example, the following command sets two distinct Object Lambda webhook endpoints:
.. code-block:: shell
:class: copyable
export MINIO_LAMBDA_WEBHOOK_ENABLE_myfunction="on"
export MINIO_LAMBDA_WEBHOOK_ENDPOINT_myfunction="http://webhook-1.example.net"
export MINIO_LAMBDA_WEBHOOK_ENABLE_yourfunction="on"
export MINIO_LAMBDA_WEBHOOK_ENDPOINT_yourfunction="http://webhook-2.example.net"
Environment Variables
---------------------
.. envvar:: MINIO_LAMBDA_WEBHOOK_ENABLE
Specify ``"on"`` to enable the Object Lambda webhook endpoint for a handler function.
Requires specifying :envvar:`MINIO_LAMBDA_WEBHOOK_ENDPOINT`.
.. envvar:: MINIO_LAMBDA_WEBHOOK_ENDPOINT
The HTTP endpoint of the lambda webhook for the handler function.
.. envvar:: MINIO_LAMBDA_WEBHOOK_AUTH_TOKEN
Specify the opaque string or JWT authorization token to use for authenticating to the lambda webhook service.
.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
.. envvar:: MINIO_LAMBDA_WEBHOOK_CLIENT_CERT
Specify the path to the client certificate to use for performing mTLS authentication to the lambda webhook service.
.. envvar:: MINIO_LAMBDA_WEBHOOK_CLIENT_KEY
Specify the path to the private key to use for performing mTLS authentication to the lambda webhook service.

97
source/reference/minio-server/settings/root-credentials.rst Normal file
View File

@ -0,0 +1,97 @@
.. _minio-server-envvar-root:
====================
Root Access Settings
====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings that control root (superuser) access for the MinIO process.
The root user has complete access and permissions to perform operations on the MinIO deployment.
.. include:: /includes/common-mc-admin-config.rst
:start-after: start-minio-settings-defined
:end-before: end-minio-settings-defined
Root User
---------
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_ROOT_USER
The access key for the :ref:`root <minio-users-root>` user.
.. warning::
If :envvar:`MINIO_ROOT_USER` is unset, :mc:`minio` defaults to ``minioadmin``.
**NEVER** use the default credentials in production environments.
MinIO strongly recommends specifying a unique, long, and random :envvar:`MINIO_ROOT_USER` value for all environments.
.. tab-item:: Configuration Setting
:sync: config
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Root Password
-------------
.. tab-set::
.. tab-item:: Environment Variable
:selected:
.. envvar:: MINIO_ROOT_PASSWORD
The secret key for the :ref:`root <minio-users-root>` user.
.. warning::
If :envvar:`MINIO_ROOT_PASSWORD` is unset, :mc:`minio` defaults to ``minioadmin``.
**NEVER** use the default credentials in production environments.
MinIO strongly recommends specifying a unique, long, and random :envvar:`MINIO_ROOT_PASSWORD` value for all environments.
.. tab-item:: Configuration Setting
This setting does not have a configuration variable setting.
Use the Environment Variable instead.
Root Access
-----------
.. tab-set::
.. tab-item:: Environment Variable
:sync: envvar
.. envvar:: MINIO_API_ROOT_ACCESS
.. tab-item:: Configuration Setting
:sync: config
.. mc-conf:: api root-access
:delimiter: " "
.. versionadded:: MinIO Server RELEASE.2023-05-04T21-44-30Z
Specify ``on`` to enable and ``off`` to disable the :ref:`root <minio-users-root>` user account.
Disabling the root service account also disables all service accounts associated with root, excluding those used by site replication.
Defaults to ``on``.
Ensure you have at least one other admin user, such as one with the :userpolicy:`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 reset after an unintentional lock, set :envvar:`MINIO_API_ROOT_ACCESS` ``on`` to override this setting and temporarily re-enable the root account.
You can then change this setting to ``on`` *or* make the necessary user/policy changes to ensure normal administrative access through other non-root accounts.

91
source/reference/minio-server/settings/storage-class.rst Normal file
View File

@ -0,0 +1,91 @@
.. _minio-server-envvar-storage-class:
.. _minio-ec-storage-class:
=====================
Erasure Code Settings
=====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
This page covers settings that configure the :ref:`Erasure Code <minio-erasure-coding>` :ref:`parity <minio-ec-parity>` to use for objects written to the MinIO cluster.
This impacts how MinIO uses the space on the drive(s) and how MinIO can recover objects stored on lost drives or similar issues.
.. note::
*MinIO Storage Classes* are distinct from *AWS Storage Classes*.
AWS Storage Classes refer to the specific storage tier on which to store a given object, such as ``hot`` or ``glacier`` storage.
MinIO Storage Classes affect the erasure code parity setting used and relate to :ref:`minio-availability-resiliency` of objects.
For tiering from one type of storage to another, such as for cost management purposes, see :ref:`minio-lifecycle-management-tiering`.
Define any of these environment variables in the host system prior to starting or restarting the MinIO process.
Refer to your operating system's documentation for how to define an environment variable.
Environment Variables
---------------------
.. note::
These settings do not have configuration setting options for use with :mc:`mc admin config set`.
.. envvar:: MINIO_STORAGE_CLASS_STANDARD
The :ref:`parity level <minio-ec-parity>` for the deployment.
MinIO shards objects written with the default ``STANDARD`` storage class using this parity value.
MinIO references the ``x-amz-storage-class`` header in request metadata for determining which storage class to assign an object.
The specific syntax or method for setting headers depends on your preferred method for interfacing with the MinIO server.
Specify the value using ``EC:M`` notation, where ``M`` refers to the number of parity blocks to create for the object.
The following table lists the default values based on the :ref:`erasure set size <minio-ec-erasure-set>` of the initial server pool in the deployment:
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Erasure Set Size
- Default Parity (EC:N)
* - 4-5
- EC:2
* - 6 - 7
- EC:3
* - 8 - 16
- EC:4
The minimum supported value is ``0``, which indicates no erasure coding protections.
These deployments rely entirely on the storage controller or resource for availability / resiliency.
The maximum value depends on the erasure set size of the initial server pool in the deployment, where the upper bound is :math:`\frac{\text{ERASURE_SET_SIZE}}{\text{2}}`.
For example, a deployment with erasure set stripe size of 16 has a maximum standard parity of 8.
You can change this value after startup to any value between ``0`` and the upper bound for the erasure set size.
MinIO only applies the changed parity to newly written objects.
Existing objects retain the parity value in place at the time of their creation.
.. envvar:: MINIO_STORAGE_CLASS_RRS
The :ref:`parity level <minio-ec-parity>` for objects written with the ``REDUCED`` storage class.
MinIO references the ``x-amz-storage-class`` header in request metadata for determining which storage class to assign an object.
The specific syntax or method for setting headers depends on your preferred method for interfacing with the MinIO server.
Specify the value using ``EC:M`` notation, where ``M`` refers to the number of parity blocks to create for the object.
This value **must be** less than or equal to :envvar:`MINIO_STORAGE_CLASS_STANDARD`.
You cannot set this value for deployments with an erasure set size less than 5.
Defaults to ``EC:2``.
.. envvar:: MINIO_STORAGE_CLASS_COMMENT
Adds a comment to the storage class settings.