From 4edb3f7bae02ae49439f026acd2e2131417e28bd Mon Sep 17 00:00:00 2001 From: Ravind Kumar Date: Wed, 14 Feb 2024 17:16:58 -0500 Subject: [PATCH] Improve documentation on MINIO_DOMAIN (#1131) # Summary As per a recent customer issue, our guidance on `MINIO_DOMAIN` and path/virtual bucket lookups needs some attention. There are two main areas to address: 1. We need to guide users to avoid namespace collision within the `MINIO_DOMAIN` , as this causes bucket lookup issues with certain MinIO services/features 2. We need to generally improve docs on setting `MINIO_DOMAIN` correctly There is also a side objective from Engineering to ensure we have a simple admonition to direct users to test wherever possible changes to config settings before applying to production. --------- Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com> --- source/administration/object-management.rst | 31 +++++++++++++++++++ source/includes/common-mc-admin-config.rst | 11 ++++++- source/reference/minio-server/settings.rst | 15 +++++---- .../minio-server/settings/console.rst | 4 +++ .../reference/minio-server/settings/core.rst | 22 +++++++++++-- .../minio-server/settings/deprecated.rst | 4 +++ .../minio-server/settings/iam/ldap.rst | 8 +++++ .../settings/iam/minio-access-plugin.rst | 8 +++++ .../settings/iam/minio-identity-plugin.rst | 8 +++++ .../minio-server/settings/iam/openid.rst | 8 +++++ .../reference/minio-server/settings/kes.rst | 4 +++ .../settings/metrics-and-logging.rst | 4 +++ .../minio-server/settings/notifications.rst | 4 +++ .../settings/notifications/amqp.rst | 4 +++ .../settings/notifications/elasticsearch.rst | 4 +++ .../settings/notifications/kafka.rst | 4 +++ .../settings/notifications/mqtt.rst | 4 +++ .../settings/notifications/mysql.rst | 4 +++ .../settings/notifications/nats.rst | 4 +++ .../settings/notifications/nsq.rst | 4 +++ .../settings/notifications/postgresql.rst | 4 +++ .../settings/notifications/redis.rst | 4 +++ .../notifications/webhook-service.rst | 4 +++ .../minio-server/settings/object-lambda.rst | 4 +++ .../settings/root-credentials.rst | 4 +++ .../minio-server/settings/storage-class.rst | 4 +++ 26 files changed, 171 insertions(+), 12 deletions(-) diff --git a/source/administration/object-management.rst b/source/administration/object-management.rst index cadf3437..f3ddd827 100644 --- a/source/administration/object-management.rst +++ b/source/administration/object-management.rst @@ -55,6 +55,37 @@ Clients and administrators should not create these prefixes manually. Neither clients nor administrators would manually create the intermediate prefixes, as MinIO automatically infers them from the object name. +.. _minio-object-management-path-virtual-access: + +Path vs Virtual Host Bucket Access +---------------------------------- + +MinIO supports both :s3-docs:`path-style ` (default) or :s3-docs:`virtual-host bucket lookups `. + +For example, consider a MinIO deployment with an assigned Fully Qualified Domain Name (FQDN) of ``minio.example.net``: + +- With path-style lookups, applications specify the full path to a bucket, such as ``minio.example.net/mybucket``. +- With virtual-host lookups, applications specify the bucket as a subdomain, such as ``mybucket.minio.example.net/``. + +Some applications may require or expect virtual-host lookup support when performing S3 operations against MinIO. +To enable virtual-host bucket lookup, you must set the :envvar:`MINIO_DOMAIN` environment variable to a :abbr:`FQDN(Fully Qualified Domain Name)` that resolves to the MinIO Deployment. + +If you configure ``MINIO_DOMAIN``, you **must** consider all subdomains of the specified FQDN as exclusively assigned for use as bucket names. +Any MinIO services which conflict with those domains, such as replication targets, may exhibit unexpected or undesired behavior as a result of the collision. + +For example, if setting ``MINIO_DOMAIN=minio.example.net``, you **cannot** assign any subdomains of ``minio.example.net`` (in the form of ``*.minio.example.net``) to any MinIO service or target. +This includes hostnames for use with :ref:`bucket `, :ref:`batch `, or :ref:`site replication `. + +.. important:: + + For deployments with :ref:`TLS enabled `, you **must** ensure your TLS certificate SANs cover all subdomains of the leftmost domain specified to :envvar:`MINIO_DOMAIN`. + + For example, the example of ``MINIO_DOMAIN=minio.example.net`` requires a TLS SAN that covers the subdomains of ``minio.example.net``. + You can set an additional TLS SAN of ``*.minio.example.net`` to appropriately cover the subdomain namespace. + + TLS Wildcard rules prevent chaining to additional subdomain levels, such that a TLS certificate with a wildcard SAN of ``*.example.net`` would **not** cover the virtual host lookups at ``*.minio.example.net``. + + Object Organization and Planning -------------------------------- diff --git a/source/includes/common-mc-admin-config.rst b/source/includes/common-mc-admin-config.rst index d6dcbd6f..2b58b657 100644 --- a/source/includes/common-mc-admin-config.rst +++ b/source/includes/common-mc-admin-config.rst @@ -107,4 +107,13 @@ If you define both an environment variable and the similar configuration setting Some settings have only an environment variable or a configuration setting, but not both. -.. end-minio-settings-defined \ No newline at end of file +.. end-minio-settings-defined + +.. start-minio-settings-test-before-prod + +.. important:: + + Each configuration setting controls fundamental MinIO behavior and functionality. + MinIO **strongly recommends** testing configuration changes in a lower environment, such as DEV or QA, before applying to production. + +.. end-minio-settings-test-before-prod \ No newline at end of file diff --git a/source/reference/minio-server/settings.rst b/source/reference/minio-server/settings.rst index a21f8a72..a70ee64f 100644 --- a/source/reference/minio-server/settings.rst +++ b/source/reference/minio-server/settings.rst @@ -19,16 +19,15 @@ The :mc:`minio server` process stores its configuration in the storage backend : MinIO Settings -------------- -MinIO settings define runtime behavior of the MinIO :mc:`server ` process: +MinIO settings define runtime behavior of the MinIO :mc:`server ` process. -You can define many MinIO Server settings in one of two ways: +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-defined + :end-before: end-minio-settings-defined -1. Set :ref:`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 `. - -.. important:: - - Settings defined by an environment variable override similar settings defined as configurations with :mc:`mc admin config` or the MinIO Console. +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod Additional settings include those to customize: diff --git a/source/reference/minio-server/settings/console.rst b/source/reference/minio-server/settings/console.rst index 089071bd..9bce2fde 100644 --- a/source/reference/minio-server/settings/console.rst +++ b/source/reference/minio-server/settings/console.rst @@ -16,6 +16,10 @@ This page covers settings that manage access and behavior for the MinIO Console. :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Browser Settings ---------------- diff --git a/source/reference/minio-server/settings/core.rst b/source/reference/minio-server/settings/core.rst index 690a16f1..8a70d29b 100644 --- a/source/reference/minio-server/settings/core.rst +++ b/source/reference/minio-server/settings/core.rst @@ -16,6 +16,10 @@ This page covers settings that control core behavior of the MinIO process. :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Common Settings --------------- @@ -87,11 +91,23 @@ Domain .. envvar:: MINIO_DOMAIN - Set to the Fully Qualified Domain Name (FQDN) MinIO accepts Bucket DNS (Virtual Host)-style requests on. + Enables Virtual Host-style requests to the MinIO deployment. + Set the value to the Fully Qualified Domain Name (FQDN) for MinIO to accept incoming virtual host requests. - 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``. + Omitting this setting directs MinIO to only accept the default path-style requests. - If this setting is omitted, the default is to only accept path-style requests. For example, ``minio.example.net/data``. + For example, consider a MinIO deployment with an assigned FQDN of ``minio.example.net``. + + - With path-style lookups, applications can access the bucket using it's full path as ``minio.example.net/mybucket``. + - With virtual-host lookups, application can access the bucket as a virtual host as ``mybucket.minio.example.net/``. + + .. important:: + + If you configure ``MINIO_DOMAIN``, you **must** consider all subdomains of the specified FQDN as exclusively assigned for use as bucket names. + Any MinIO services which conflict with those domains, such as replication targets, may exhibit unexpected or undesired behavior as a result of the collision. + + For example, if setting ``MINIO_DOMAIN=minio.example.net``, you **cannot** assign any subdomains of ``minio.example.net`` (in the form of ``*.minio.example.net``) to any MinIO service or target. + This includes hostnames for use with :ref:`bucket `, :ref:`batch `, or :ref:`site replication `. .. tab-item:: Configuration Setting diff --git a/source/reference/minio-server/settings/deprecated.rst b/source/reference/minio-server/settings/deprecated.rst index 7d26328a..e48728dd 100644 --- a/source/reference/minio-server/settings/deprecated.rst +++ b/source/reference/minio-server/settings/deprecated.rst @@ -19,6 +19,10 @@ Users should migrate to the recommended replacement at the earliest opportunity. :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Environment Variables --------------------- diff --git a/source/reference/minio-server/settings/iam/ldap.rst b/source/reference/minio-server/settings/iam/ldap.rst index 86f208fe..2b847430 100644 --- a/source/reference/minio-server/settings/iam/ldap.rst +++ b/source/reference/minio-server/settings/iam/ldap.rst @@ -26,6 +26,14 @@ See :ref:`minio-authenticate-using-ad-ldap-generic` for a tutorial on using thes The ``identity_ldap`` configuration settings remains available for existing scripts and other tools. +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-defined + :end-before: end-minio-settings-defined + +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Examples -------- diff --git a/source/reference/minio-server/settings/iam/minio-access-plugin.rst b/source/reference/minio-server/settings/iam/minio-access-plugin.rst index 74890f94..2ffaff93 100644 --- a/source/reference/minio-server/settings/iam/minio-access-plugin.rst +++ b/source/reference/minio-server/settings/iam/minio-access-plugin.rst @@ -13,6 +13,14 @@ MinIO Access Management Plugin Settings This page documents settings for enabling external authorization management using the MinIO Access Management Plugin. See :ref:`minio-external-access-management-plugin` 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 + +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Examples -------- diff --git a/source/reference/minio-server/settings/iam/minio-identity-plugin.rst b/source/reference/minio-server/settings/iam/minio-identity-plugin.rst index b038db01..7a03a4ca 100644 --- a/source/reference/minio-server/settings/iam/minio-identity-plugin.rst +++ b/source/reference/minio-server/settings/iam/minio-identity-plugin.rst @@ -13,6 +13,14 @@ MinIO Identity Management Plugin Settings 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. +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-defined + :end-before: end-minio-settings-defined + +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Examples -------- diff --git a/source/reference/minio-server/settings/iam/openid.rst b/source/reference/minio-server/settings/iam/openid.rst index 2b33c790..90af58e5 100644 --- a/source/reference/minio-server/settings/iam/openid.rst +++ b/source/reference/minio-server/settings/iam/openid.rst @@ -14,6 +14,14 @@ OpenID Identity Management Settings 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. +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-defined + :end-before: end-minio-settings-defined + +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Examples -------- diff --git a/source/reference/minio-server/settings/kes.rst b/source/reference/minio-server/settings/kes.rst index dbda21f2..6dfb48ca 100644 --- a/source/reference/minio-server/settings/kes.rst +++ b/source/reference/minio-server/settings/kes.rst @@ -19,6 +19,10 @@ The following environment variables control how the MinIO Server interacts with 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. +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + .. 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. diff --git a/source/reference/minio-server/settings/metrics-and-logging.rst b/source/reference/minio-server/settings/metrics-and-logging.rst index 5034f50b..f00d4757 100644 --- a/source/reference/minio-server/settings/metrics-and-logging.rst +++ b/source/reference/minio-server/settings/metrics-and-logging.rst @@ -20,6 +20,10 @@ See :ref:`minio-logging` for more complete documentation. :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + - :ref:`minio-server-envvar-logging-regular` - :ref:`minio-server-envvar-logging-audit` - :ref:`minio-server-envvar-logging-audit-kafka` diff --git a/source/reference/minio-server/settings/notifications.rst b/source/reference/minio-server/settings/notifications.rst index 3114d556..6f40f066 100644 --- a/source/reference/minio-server/settings/notifications.rst +++ b/source/reference/minio-server/settings/notifications.rst @@ -17,6 +17,10 @@ This page covers settings that control behavior related to :ref:`MinIO bucket no :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Sync Events ----------- diff --git a/source/reference/minio-server/settings/notifications/amqp.rst b/source/reference/minio-server/settings/notifications/amqp.rst index 84c6244e..952cf2d8 100644 --- a/source/reference/minio-server/settings/notifications/amqp.rst +++ b/source/reference/minio-server/settings/notifications/amqp.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-amqp` for a tutorial on using these :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple AMQP Targets --------------------- diff --git a/source/reference/minio-server/settings/notifications/elasticsearch.rst b/source/reference/minio-server/settings/notifications/elasticsearch.rst index 80cd29bb..cc2c1c3d 100644 --- a/source/reference/minio-server/settings/notifications/elasticsearch.rst +++ b/source/reference/minio-server/settings/notifications/elasticsearch.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-elasticsearch` for a tutorial on us :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple Elasticsearch Targets ------------------------------ diff --git a/source/reference/minio-server/settings/notifications/kafka.rst b/source/reference/minio-server/settings/notifications/kafka.rst index 63d48b91..bc33e112 100644 --- a/source/reference/minio-server/settings/notifications/kafka.rst +++ b/source/reference/minio-server/settings/notifications/kafka.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-kafka` for a tutorial on using thes :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple Kafka Targets ---------------------- diff --git a/source/reference/minio-server/settings/notifications/mqtt.rst b/source/reference/minio-server/settings/notifications/mqtt.rst index ce39ea2d..3077f04a 100644 --- a/source/reference/minio-server/settings/notifications/mqtt.rst +++ b/source/reference/minio-server/settings/notifications/mqtt.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-mqtt` for a tutorial on using these :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple MQTT Targets --------------------- diff --git a/source/reference/minio-server/settings/notifications/mysql.rst b/source/reference/minio-server/settings/notifications/mysql.rst index 73bcf62d..a26b1106 100644 --- a/source/reference/minio-server/settings/notifications/mysql.rst +++ b/source/reference/minio-server/settings/notifications/mysql.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-mysql` for a tutorial on using thes :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple MYSQL Targets ---------------------- diff --git a/source/reference/minio-server/settings/notifications/nats.rst b/source/reference/minio-server/settings/notifications/nats.rst index f8d90992..137555d8 100644 --- a/source/reference/minio-server/settings/notifications/nats.rst +++ b/source/reference/minio-server/settings/notifications/nats.rst @@ -26,6 +26,10 @@ See :ref:`minio-bucket-notifications-publish-nats` for a tutorial on using these :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple NATS Targets --------------------- diff --git a/source/reference/minio-server/settings/notifications/nsq.rst b/source/reference/minio-server/settings/notifications/nsq.rst index e4f0a294..eec0e1ab 100644 --- a/source/reference/minio-server/settings/notifications/nsq.rst +++ b/source/reference/minio-server/settings/notifications/nsq.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-nsq` for a tutorial on using these :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple NSQ Targets -------------------- diff --git a/source/reference/minio-server/settings/notifications/postgresql.rst b/source/reference/minio-server/settings/notifications/postgresql.rst index bacce281..3a53c404 100644 --- a/source/reference/minio-server/settings/notifications/postgresql.rst +++ b/source/reference/minio-server/settings/notifications/postgresql.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-postgresql` for a tutorial on using :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple PostgreSQL Targets --------------------------- diff --git a/source/reference/minio-server/settings/notifications/redis.rst b/source/reference/minio-server/settings/notifications/redis.rst index 97b3b32f..b52bfeb3 100644 --- a/source/reference/minio-server/settings/notifications/redis.rst +++ b/source/reference/minio-server/settings/notifications/redis.rst @@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-redis` for a tutorial on using thes :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple Redis Targets ---------------------- diff --git a/source/reference/minio-server/settings/notifications/webhook-service.rst b/source/reference/minio-server/settings/notifications/webhook-service.rst index bf72950b..6fc1e961 100644 --- a/source/reference/minio-server/settings/notifications/webhook-service.rst +++ b/source/reference/minio-server/settings/notifications/webhook-service.rst @@ -19,6 +19,10 @@ See :ref:`minio-bucket-notifications-publish-webhook` for a tutorial on using th :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Multiple Webhook Service Targets -------------------------------- diff --git a/source/reference/minio-server/settings/object-lambda.rst b/source/reference/minio-server/settings/object-lambda.rst index 8c90d69e..85dfe65d 100644 --- a/source/reference/minio-server/settings/object-lambda.rst +++ b/source/reference/minio-server/settings/object-lambda.rst @@ -24,6 +24,10 @@ For example, the following command sets two distinct Object Lambda webhook endpo export MINIO_LAMBDA_WEBHOOK_ENABLE_yourfunction="on" export MINIO_LAMBDA_WEBHOOK_ENDPOINT_yourfunction="http://webhook-2.example.net" +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Environment Variables --------------------- diff --git a/source/reference/minio-server/settings/root-credentials.rst b/source/reference/minio-server/settings/root-credentials.rst index e52e0373..7f1e9afd 100644 --- a/source/reference/minio-server/settings/root-credentials.rst +++ b/source/reference/minio-server/settings/root-credentials.rst @@ -17,6 +17,10 @@ The root user has complete access and permissions to perform operations on the M :start-after: start-minio-settings-defined :end-before: end-minio-settings-defined +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Root User --------- diff --git a/source/reference/minio-server/settings/storage-class.rst b/source/reference/minio-server/settings/storage-class.rst index c32d70bc..536b50a1 100644 --- a/source/reference/minio-server/settings/storage-class.rst +++ b/source/reference/minio-server/settings/storage-class.rst @@ -26,6 +26,10 @@ This impacts how MinIO uses the space on the drive(s) and how MinIO can recover 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. +.. include:: /includes/common-mc-admin-config.rst + :start-after: start-minio-settings-test-before-prod + :end-before: end-minio-settings-test-before-prod + Environment Variables ---------------------