diff --git a/source/conf.py b/source/conf.py index 902fda55..5611e38c 100644 --- a/source/conf.py +++ b/source/conf.py @@ -138,11 +138,11 @@ rst_prolog = """ .. |podman| replace:: `Podman `__ .. |kes-stable| replace:: 0.16.1 - .. |minio-tag| replace:: `RELEASE.2022-05-08T23-50-31Z `__ .. |minio-latest| replace:: RELEASE.2022-05-08T23-50-31Z .. |minio-rpm| replace:: https://dl.min.io/server/minio/release/linux-amd64/minio-20220508235031.0.0.x86_64.rpm .. |minio-deb| replace:: https://dl.min.io/server/minio/release/linux-amd64/minio_20220508235031.0.0_amd64.deb -.. |subnet| replace:: `MinIO SUBNET ` +.. |subnet| replace:: `MinIO SUBNET `__ +.. |subnet-short| replace:: `SUBNET `__ """ \ No newline at end of file diff --git a/source/default-conf.py b/source/default-conf.py index c70e69c7..19525c3e 100644 --- a/source/default-conf.py +++ b/source/default-conf.py @@ -144,5 +144,6 @@ rst_prolog = """ .. |minio-rpm| replace:: RPMURL .. |minio-deb| replace:: DEBURL .. |subnet| replace:: `MinIO SUBNET `__ +.. |subnet-short| replace:: `SUBNET `__ """ \ No newline at end of file diff --git a/source/images/subnet/SUBNET-deployment-health-summary.png b/source/images/subnet/SUBNET-deployment-health-summary.png new file mode 100644 index 00000000..03f39b4d Binary files /dev/null and b/source/images/subnet/SUBNET-deployment-health-summary.png differ diff --git a/source/images/subnet/deployment-health-tls-config-fail.png b/source/images/subnet/deployment-health-tls-config-fail.png new file mode 100644 index 00000000..b862e653 Binary files /dev/null and b/source/images/subnet/deployment-health-tls-config-fail.png differ diff --git a/source/images/subnet/deployments-overview.png b/source/images/subnet/deployments-overview.png new file mode 100644 index 00000000..fff76588 Binary files /dev/null and b/source/images/subnet/deployments-overview.png differ diff --git a/source/images/subnet/issue-expanded.png b/source/images/subnet/issue-expanded.png new file mode 100644 index 00000000..f44b84d8 Binary files /dev/null and b/source/images/subnet/issue-expanded.png differ diff --git a/source/images/subnet/issues-section.png b/source/images/subnet/issues-section.png new file mode 100644 index 00000000..70451c83 Binary files /dev/null and b/source/images/subnet/issues-section.png differ diff --git a/source/includes/common-mc-support.rst b/source/includes/common-mc-support.rst new file mode 100644 index 00000000..1305259a --- /dev/null +++ b/source/includes/common-mc-support.rst @@ -0,0 +1,8 @@ +.. start-minio-only + +.. note:: + + The ``mc support`` commands were designed for MinIO deployments registered with |subnet| to ensure optimal outcome of diagnostics and performance testing. + MinIO does not guarantee any functionality if used against non-MinIO deployments or if used independently of MinIO engineering and support. + +.. end-minio-only \ No newline at end of file diff --git a/source/includes/facts-mc-admin.rst b/source/includes/facts-mc-admin.rst index 253e2ea0..cfbab88d 100644 --- a/source/includes/facts-mc-admin.rst +++ b/source/includes/facts-mc-admin.rst @@ -1,7 +1,7 @@ -start-minio-only +.. start-minio-only MinIO does not support using :mc-cmd:`mc admin` commands with other S3-compatible services, regardless of their claimed compatibility with MinIO deployments. -end-minio-only \ No newline at end of file +.. end-minio-only \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 49cf1277..a718d660 100644 --- a/source/index.rst +++ b/source/index.rst @@ -139,6 +139,7 @@ without validating their usage do so at their own risk. /lifecycle-management/lifecycle-management-overview /replication/replication-overview /monitoring/monitoring-overview + /support/support-overview /reference/minio-mc /reference/minio-mc-admin /reference/minio-server/minio-server diff --git a/source/installation/deploy-minio-distributed.rst b/source/installation/deploy-minio-distributed.rst index 9032fbc8..033cf9f9 100644 --- a/source/installation/deploy-minio-distributed.rst +++ b/source/installation/deploy-minio-distributed.rst @@ -498,4 +498,53 @@ host: * - More than 1 Pebibyte (Pi) - 128GiB - + +.. _minio-requests-per-node: + +Requests Per Node +~~~~~~~~~~~~~~~~~ + +You can calculate the maximum number of concurrent requests per host with this formula: + + :math:`totalRam / ramPerRequest` + +To calculate the amount of RAM used for each request, use this formula: + + :math:`((2MiB + 128KiB) * driveCount) + (2 * 10MiB) + (2 * 1 MiB)` + + 10MiB is the default erasure block size v1. + 1 MiB is the default erasure block size v2. + +The following table lists the maximum concurrent requests on a node based on the number of host drives and the *free* system RAM: + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Number of Drives + - 32 GiB of RAM + - 64 GiB of RAM + - 128 GiB of RAM + - 256 GiB of RAM + - 512 GiB of RAM + + * - 4 Drives + - 1,074 + - 2,149 + - 4,297 + - 8,595 + - 17,190 + + * - 8 Drives + - 840 + - 1,680 + - 3,361 + - 6,722 + - 13,443 + + * - 16 Drives + - 585 + - 1,170 + - 2.341 + - 4,681 + - 9,362 diff --git a/source/reference/minio-mc.rst b/source/reference/minio-mc.rst index e3e86472..a7808fc5 100644 --- a/source/reference/minio-mc.rst +++ b/source/reference/minio-mc.rst @@ -311,6 +311,14 @@ The following table lists :mc-cmd:`mc` commands: :start-after: start-mc-stat-desc :end-before: end-mc-stat-desc + * - | :mc:`mc support diagnostics` + | :mc:`mc support inspect` + | :mc:`mc support perf` + | :mc:`mc support profile` + | :mc:`mc support register` + - The MinIO Client ``mc support`` commands provides tools for analyzing deployment health or performance and for running diagnostics. + You can also register your deployment with |SUBNET| and upload generated health reports for further analysis by MinIO engineering. + * - | :mc:`mc tag set` | :mc:`mc tag remove` | :mc:`mc tag list` @@ -481,6 +489,11 @@ All :ref:`commands ` support the following global options: /reference/minio-mc/mc-share-list /reference/minio-mc/mc-sql /reference/minio-mc/mc-stat + /reference/minio-mc/mc-support-diagnostics + /reference/minio-mc/mc-support-inspect + /reference/minio-mc/mc-support-perf + /reference/minio-mc/mc-support-profile + /reference/minio-mc/mc-support-register /reference/minio-mc/mc-tag-set /reference/minio-mc/mc-tag-list /reference/minio-mc/mc-tag-remove diff --git a/source/reference/minio-mc/mc-support-diagnostics.rst b/source/reference/minio-mc/mc-support-diagnostics.rst new file mode 100644 index 00000000..5b51abe3 --- /dev/null +++ b/source/reference/minio-mc/mc-support-diagnostics.rst @@ -0,0 +1,134 @@ +========================== +``mc support diagnostics`` +========================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +.. mc:: mc support diagnostics + +.. mc:: mc support diag + +Description +----------- + +The :mc-cmd:`mc support diagnostics` command generates a health report for a MinIO deployment. +For deployments registered with the MinIO subscription network (|subnet-short|), the command can automatically upload the health report for analysis. + +The resulting health report is intended for use by MinIO Engineering via SUBNET and may contain internal or private data points. +Exercise caution before sending a health report to a third party or posting the health report in a public forum. + +MinIO recommends that you run the health diagnostics when first provisioning the cluster and again at any failure scenario. + +This diagnostic test runs as a one-shot test and can run for as long as 5 minutes. +During the test, MinIO freezes all S3 calls and queues read or write operations until the test completes. +The queue is limited based on the supported maximum concurrent :ref:`requests per host `. +Requests that exceed this limit on a given host return a ``503`` error after ~10 seconds. + +Use the :mc-cmd:`mc support diagnostics` command to trigger the diagnostic test. +For clusters registered with SUBNET, the command uploads the results as part of SUBNET Health reports. + +For airgapped or firewalled environments, or other environments that prevent direct network access from the deployment, you can save the report locally with the :mc-cmd:`~mc support diag --airgap` flag. +After saving, you can then upload the results of the test to SUBNET manually. + +.. include:: /includes/common-mc-support.rst + :start-after: start-minio-only + :end-before: end-minio-only + +Sample Output +~~~~~~~~~~~~~ + +.. code-block:: shell + + ● Admin Info ... ✔ + ● CPU ... ✔ + ● Disk Hardware ... ✔ + ● Os Info ... ✔ + ● Mem Info ... ✔ + ● Process Info ... ✔ + ● Config ... ✔ + ● Drive ... ✔ + ● Net ... ✔ + ********************************************************************************* + WARNING!! + ** THIS FILE MAY CONTAIN SENSITIVE INFORMATION ABOUT YOUR ENVIRONMENT ** + ** PLEASE INSPECT CONTENTS BEFORE SHARING IT ON ANY PUBLIC FORUM ** + ********************************************************************************* + mc: Health data saved to dc-11-health_20220511053323.json.gz + +The gzipped output contains the requested health information. + + +Examples +-------- + +Generate Health Data for a Cluster and Automatically Upload to SUBNET +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generate health data for a MinIO cluster and automatically for a MinIO cluster at alias ``minio1`` for transmission to SUBNET. + +.. code-block:: shell + :class: copyable + + mc support diag minio1 + +The automatic upload of data only occurs for deployments registered with SUBNET using :mc-cmd:`mc support register`. + +.. _minio-support-diagnostics-airgap: + +Generate Health Data for a Cluster to Upload Manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generate a diagnostic report for a MinIO deployment at alias ``minio2`` and save it for manual upload to SUBNET: + +.. code-block:: shell + :class: copyable + + mc support diag minio2 --airgap + +#. Run the command to download the ``.gzip`` file +#. Login to https://subnet.min.io and select the :guilabel:`Deployments` section +#. Select the deployment for the report +#. Select the :guilabel:`Upload` button +#. Drag and drop the file or browse to the ``.gzip`` file location to upload it + + +Syntax +------ + +The command has the following syntax: + +.. code-block:: shell + + mc [GLOBALFLAGS] support diag \ + ALIAS \ + [--airgap] + + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment. + +.. mc-cmd:: --airgap + :optional: + + Use in environments without network access to SUBNET (for example, airgapped, firewalled, or similar configuration). + Generates the diagnostic report and saves it to the location where you ran the command. + + You must manually upload the report to SUBNET. + + For instructions, see the :ref:`airgap example `. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals diff --git a/source/reference/minio-mc/mc-support-inspect.rst b/source/reference/minio-mc/mc-support-inspect.rst new file mode 100644 index 00000000..4e478c3c --- /dev/null +++ b/source/reference/minio-mc/mc-support-inspect.rst @@ -0,0 +1,140 @@ +====================== +``mc support inspect`` +====================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +.. mc:: mc support inspect + +Description +----------- + +The :mc-cmd:`mc support inspect` command collects the data and metadata associated to objects at the specified path. +MinIO assembles this data from each backend drive storing an :ref:`erasure shard ` for each specified object. + +The command produces a zip file that includes all matching files with their respective *host+drive+path*. + +You can export the contents to a JSON output for further analysis. + +The resulting report is intended for use by MinIO Engineering via |SUBNET| and may contain internal or private data points associated to the object. +Exercise caution before sending a report to a third party or posting the report in a public forum. + +.. important:: + + :mc-cmd:`mc support inspect` requires a MinIO deployment server from October 2021 or later. + +.. include:: /includes/common-mc-support.rst + :start-after: start-minio-only + :end-before: end-minio-only + +Wildcards +--------- + +The command suports wildcard ``*`` pattern matching for prefixes or objects. + +.. code-block:: shell + :class: copyable + + mc support inspect ALIAS/bucket/path/**/xl.meta + +This command collects all ``xl.meta`` associated to objects at ``ALIAS/bucket/path/``. + + +Examples +-------- + +Download Metadata for an Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can download the metadata for an object. +Metadata stores in an ``xl.meta`` binary file. + +The folloing command downloads the ``xl.meta`` from ``mybucket/myobject`` on the ``minio1`` deployment. + +The file downloads from all drives as a zip archive file. + +.. code-block:: shell + :class: copyable + + mc support inspect minio1/mybucket/myobject/xl.meta + +The contents of the ``xl.meta`` file are not human readable. +You can convert the contents of an ``xl.meta`` file to JSON format. + +Download All Parts of an Object as an Encrypted Zip +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command downloads all of the constituent parts of an object with the following details: + +- MinIO deployment alias: ``minio1`` +- Bucket: ``mybucket`` +- Object: ``myobject`` + +The file downloads as an encrypted zip file. + +.. code-block:: shell + :class: copyable + + mc support inspect --encrypt minio1/mybucket/myobject*/*/part.* + +You can decrypt the resulting zip file with the :ref:`decryption tool ` + +Download All Objects at a Prefix Recursively +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command downloads all objects recursively found at a prefix. + +.. caution:: + + This can be an expensive operation. + Proceed with caution. + +.. code-block:: shell + :class: copyable + + mc support inspect minio1/mybucket/myobject/** + + +Syntax +------ + +The command has the following syntax: + +.. code-block:: shell + + mc [GLOBALFLAGS] support inspect \ + [--encrypt] \ + [--export] \ + ALIAS + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: --encrypt + :optional: + + Encrypt contents with a one-time key for confidential data. + +.. mc-cmd:: --export + :optional: + + Export inspect data as JSON or data JSON from ``xl.meta``. + + Use ``--export ``, replacing ```` with either ``json`` or ``djson`` as the output type. + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment. + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals diff --git a/source/reference/minio-mc/mc-support-perf.rst b/source/reference/minio-mc/mc-support-perf.rst new file mode 100644 index 00000000..f9190025 --- /dev/null +++ b/source/reference/minio-mc/mc-support-perf.rst @@ -0,0 +1,228 @@ +=================== +``mc support perf`` +=================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +.. mc:: mc support perf + +Description +----------- + +Use the :mc-cmd:`mc support perf` command to review the performance of the S3 API (read/write), network IO, and storage (drive read/write). + +The resulting tests can provide general guidance of deployment performance under S3 ``GET`` and ``PUT`` requests and identify any potential bottlenecks. + +For more complete performance testing, consider using a combination of load-testing using your staging application environments and the MinIO `WARP `_ S3 benchmarking tool. + +:mc-cmd:`mc support perf` has three subcommands + +#. :mc-cmd:`~mc support perf drive` + + Measure the speed of drives in a MinIO deployment. + +#. :mc-cmd:`~mc support perf object` + + Measure the speed of reading and writing objects in a cluster. + +#. :mc-cmd:`~mc support perf net` + + Measure the network throughput of all nodes. + +.. include:: /includes/common-mc-support.rst + :start-after: start-minio-only + :end-before: end-minio-only + +Examples +-------- + +Measure Speed of an Object +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Measure the performance of S3 read/write of an object on the alias ``minio1``. +MinIO autotunes concurrency to obtain maximum throughput and IOPS (Input/Output Per Second). + +.. code-block:: shell + :class: copyable + + mc support perf object minio1 + +Measure Speed of an Object of a Specific Size for a Specific Duration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run object the S3 read/write performance of an object for 20 seconds with object size of 128MiB on alias ``minio1``. +MinIO autotunes concurrency to obtain maximum throughput. + +.. code-block:: shell + :class: copyable + + mc support perf object minio1 --duration 20s --size 128MiB + + +Test Speed of All Drives on All Nodes with Default Specifications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run drive read/write performance measurements on all drive on all nodes for a cluster with alias ``minio1``. +The command does not specify the blocksize, so the default of 4MiB is used. + +.. code-block:: shell + :class: copyable + + mc support perf drive minio1 + +Test Drive Speed Measurements with Custom Specifications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run drive read/write performance measurements on a cluster with alias ``minio1`` specificying a blocksize of 64KiB and data read/written from each drive of 2GiB. + +.. code-block:: shell + :class: copyable + + mc support perf drive minio1 --blocksize 64KiB --filesize 2GiB + +Test Network Throughput +~~~~~~~~~~~~~~~~~~~~~~~ + +Run a network throughput test on a cluster with alias ``minio1``. + +.. code-block:: shell + :class: copyable + + mc support perf net minio1 + +Syntax +------ + +.. mc-cmd:: drive + :fullpath: + +Measure the read/write speed of the drives in a cluster. + +.. code-block:: shell + + mc [GLOBAL FLAGS] support perf drive \ + [--concurrent] \ + [--verbose, -v] \ + [--filesize] \ + [--blocksize] \ + [--serial] \ + ALIAS + +.. mc-cmd:: object + :fullpath: + +Measure the S3 peformance of reading and writing objects in a cluster. + +.. code-block:: shell + + mc [GLOBAL FLAGS] support perf object \ + [--duration] \ + [--size] \ + [--concurrent] \ + [--verbose, -v] \ + ALIAS + +.. mc-cmd:: net + :fullpath: + +Measure the network throughput of all nodes in a cluster. + +.. code-block:: shell + + mc [GLOBAL FLAGS] support perf net \ + [--concurrent] \ + [--verbose, -v] \ + [--serial] \ + ALIAS + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: --duration + :optional: + + Applies to the :mc-cmd:`~mc support perf object` command. + + Specify the duration for the performance tests to run. + + If not specified, the default value is ``10s``. + + Use ``--duration `` where ```` is a number and a unit of ``s`` for seconds, ``m`` for minutes. + +.. mc-cmd:: --size + :optional: + + Applies to the :mc-cmd:`~mc support perf object` command. + + Specify the size of the object to use for upload and download performance test. + + If not specified, the default value is ``64MiB``. + + Use ``--size `` where ```` is a number and the storage unit, ``KiB``, ``MiB``, or ``GiB``. + +.. mc-cmd:: --concurrent + :optional: + + Applies to the :mc-cmd:`~mc support perf drive`, :mc-cmd:`~mc support perf object`, and :mc-cmd:`~mc support perf net` commands. + + Specify the number of concurrent requests to test per server. + + If not specified, the default value is ``32``. + + Use ``--concurrent `` where ```` is a number. + +.. mc-cmd:: --verbose + :optional: + :alias: -v + + Applies to the :mc-cmd:`~mc support perf drive`, :mc-cmd:`~mc support perf object`, and :mc-cmd:`~mc support perf net` commands. + + Show per-server stats in the output. + +.. mc-cmd:: --filesize + :optional: + + Applies to the :mc-cmd:`~mc support perf drive` command. + + Specify the total size of data to read or write to each drive. + + If not specified, the default value is ``1GiB``. + + Use ``--filesize `` where ```` is a number and storage unit, ``KiB``, ``MiB``, or ``GiB``. + +.. mc-cmd:: --blocksize + :optional: + + Applies to the :mc-cmd:`~mc support perf drive` command. + + Specify the read/write block size. + + If not specified, the default value is ``4MiB``. + + Use ``--filesize `` where ```` is a number and a storage unit, using standard storage unit abbreviations. + +.. mc-cmd:: --serial + :optional: + + Applies to the :mc-cmd:`~mc support perf drive` and :mc-cmd:`~mc support perf net` commands. + + Run performance tests on drive(s) one by one. + +.. mc-cmd:: ALIAS + :required: + + Applies to the :mc-cmd:`~mc support perf drive`, :mc-cmd:`~mc support perf object`, and :mc-cmd:`~mc support perf net` commands. + + The :ref:`alias ` of the MinIO deployment. + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals diff --git a/source/reference/minio-mc/mc-support-profile.rst b/source/reference/minio-mc/mc-support-profile.rst new file mode 100644 index 00000000..715440fe --- /dev/null +++ b/source/reference/minio-mc/mc-support-profile.rst @@ -0,0 +1,119 @@ +====================== +``mc support profile`` +====================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +.. mc:: mc support profile + +Description +----------- + +The :mc-cmd:`mc support profile` command runs a system profile for your deployment. +The results of the profile can provide insight into the MinIO server process running on a given node. + +The resulting report is intended for use by MinIO Engineering. +You can upload the report to |subnet|. +Independent or third-party use of these profiles for diagnostics and remediation is done at your own risk. + +.. include:: /includes/common-mc-support.rst + :start-after: start-minio-only + :end-before: end-minio-only + +Examples +-------- + +Fetch CPU Profiling +~~~~~~~~~~~~~~~~~~~ + +This command retrieves the CPU profile on a MinIO deployment with the alias ``minio1``. +The profile runs for the default of 10 seconds. + +.. code-block:: shell + :class: copyable + + mc support profile --type cpu minio1/ + + +Fetch CPU, Memory, and Block Profiling Concurrently +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command fetches the profile of the CPU, memory, and block usage on the alias ``minio2``. +The profile runs for the default of 10 seconds. + +.. code-block:: shell + :class: copyable + + mc support profile --type cpu,mem,block minio2/ + +Fetch CPU, Memory, and Block Profiling Concurrently for 10 Minutes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command fetches the profile of the CPU, memory, and block on the alias ``minio3``. +The profile runs for 10 minutes (600 seconds). + +.. code-block:: shell + :class: copyable + + mc support profile --type cpu,mem,block --duration 600 minio3/ + +Syntax +------ + +The :mc-cmd:`mc support profile` command has the following syntax: + +.. code-block:: shell + + mc [GLOBALFLAGS] support profile \ + COMMAND \ + [--type] \ + [--duration] + ALIAS + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: --duration + :optional: + + Run profiling for the specified duration in seconds. + + Use ``--type `` where ```` is the number of seconds for the profile to run. + + If not specified, the command collects data for 10 seconds. + +.. mc-cmd:: --type + :optional: + + Specify the profile(s) to gather data for. + + Use ``--type `` where ```` is one or more comma-separated types of data to collect. + + Valid types are: + + - ``cpu`` + - ``cpuio`` + - ``mem`` + - ``block`` + - ``mutex`` + - ``trace`` + - ``threads`` + - ``goroutines`` + + If not specified, the command collects data for CPU, memory, block, mutex, threads, and goroutines. + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals diff --git a/source/reference/minio-mc/mc-support-register.rst b/source/reference/minio-mc/mc-support-register.rst new file mode 100644 index 00000000..5e005636 --- /dev/null +++ b/source/reference/minio-mc/mc-support-register.rst @@ -0,0 +1,107 @@ +======================= +``mc support register`` +======================= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +.. mc:: mc support register + +Description +----------- + +The :mc-cmd:`mc support register` command connects your deployment with your |SUBNET| account. + +After registration, upload deployment health reports directly to SUBNET using :mc-cmd:`mc support diagnostics` command. + + +Examples +-------- + +Register a Deployment Using the Cluster's Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register the MinIO deployment at alias ``minio1`` on SUBNET, using ``minio1`` as the cluster name: + +.. code-block:: shell + :class: copyable + + mc support register minio1 + +Register a Deployment with a Different Cluster Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register a MinIO deployment at alias ``minio2`` on SUBNET, using ``second-cluster`` as the name: + +.. code-block:: shell + :class: copyable + + mc support register minio2 --name second-cluster + +.. _minio-support-register-airgap: + +Register a Deployment Without Direct Internet Access +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register a MinIO deployment at alias ``minio3`` on SUBNET that does not have direct Internet access due to a firewall, airgap, or the like. + +.. code-block:: shell + :class: copyable + + mc support register minio3 --airgap + +#. Run the command to return a registration token +#. Copy the registration token +#. In a web browser, go to https://subnet.min.io and log in with your |SUBNET| credentials +#. Select the :guilabel:`Register` button +#. Select :guilabel:`No` for the question :guilabel:`"Is the cluster connected to the internet?"` +#. Paste the copied token into the box for :guilabel:`Register using MinIO Client Utility` +#. Select :guilabel:`Register` +#. Copy the API token that displays +#. Back in the terminal, paste or enter the API token to complete the registration process + + +Syntax +------ + +The command has the following syntax: + +.. code-block:: shell + + mc [GLOBALFLAGS] support register \ + ALIAS \ + [--name value] \ + [--airgap] + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment. + +.. mc-cmd:: --name + :optional: + + Specify a name other than the alias to associate to the MinIO cluster in SUBNET. + + Use ``--name `` replacing ```` with the name you want to use for the cluster on SUBNET. + +.. mc-cmd:: --airgap + :optional: + + Use in environments without network access to SUBNET (for example, airgapped, firewalled, or similar configuration). + + For instructions, see the :ref:`airgap example `. + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals diff --git a/source/support/encrypting-files.rst b/source/support/encrypting-files.rst new file mode 100644 index 00000000..898552c2 --- /dev/null +++ b/source/support/encrypting-files.rst @@ -0,0 +1,66 @@ +.. _minio-support-encryption: + +================ +Encrypting Files +================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +Description +----------- + +You can encrypt the output of the :mc-cmd:`mc support inspect` command for enhanced security when transmitting the files to |SUBNET|. + +Encryption +---------- + +You can choose to encrypt the output zip file for enhanced security with the ``--encrypt`` flag. +MinIO provides a binary to decrypt the file. + +When the encryption flag, the output provides a decryption key. +The output resembles the following: + +.. code-block:: shell + + $ mc support inspect --encrypt play/test123/test*/*/part.* + mc: Encrypted file data successfully downloaded as inspect.ad2b43d8.enc + mc: Decryption key: ad2b43d847fdb14e54c5836200177f7158b3f745433525f5d23c0e0208e50c9948540b54 + + mc: The decryption key will ONLY be shown here. It cannot be recovered. + mc: The encrypted file can safely be shared without the decryption key. + mc: Even with the decryption key, data stored with encryption cannot be accessed. + +As the output says, MinIO only displays the encryption key this one time, and it cannot be displayed or recovered later. + +.. _minio-support-decryption: + +Decryption +---------- + +MinIO provides a decryption tool to use on the files generated by :mc-cmd:`mc support inspect`. + +To install the decryption tool, install `Go `_, then run + +.. code-block:: shell + :class: copyable + + go install github.com/minio/minio/docs/debugging/inspect@latest + +After installing the inspect decryption binary, decrypt the file with the following command: + +.. code-block:: shell + + inspect -key= + +Replace ```` with the decryption key provided when generating the diagnosit file. +Replace ```` with the downloaded file name, including a relative or absolute path. + +``-key`` flag is optional. If not provided, an interactive prompt asks for the key. +The file name includes a portion of the decryption key. +This helps verify which key to use for the file. + +The decryption process outputs an unencrypted ``.zip`` file. \ No newline at end of file diff --git a/source/support/support-overview.rst b/source/support/support-overview.rst new file mode 100644 index 00000000..8d407bf1 --- /dev/null +++ b/source/support/support-overview.rst @@ -0,0 +1,167 @@ +======= +Support +======= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +Overview +-------- + +MinIO users have two options for support. + +#. Community support from the `public Slack channel `_. + + Community support is best-effort only and has no :abbr:`SLA (Service Level Agreement)` or :abbr:`SLO (Service Level Objective)`. +#. The MinIO Subscription Network, |subnet-short|, provides either 24 hour or 1 hour :abbr:`SLA (Service Level Agreement)` depending on subscription level. + + For current licensing levels and pricing, refer to the |SUBNET| page. + + +.. _minio-docs-subnet: + +SUBNET +------ + +SUBNET delivers 24/7/365 Direct-to-engineer support through a MinIO-built portal that blends the best of Slack and Zendesk. + +Features of SUBNET include: + +- Security and architecture reviews (depending on :abbr:`SLA (Service Level Agreement)`) +- Access to Panic Button (depending on :abbr:`SLA (Service Level Agreement)`) +- Secure communication channel to exchange logs and software binaries +- Unlimited seats for your team +- Unlimited issues + +For more information, see details at the |SUBNET| page. + +Registering Your MinIO Deployment with SUBNET +--------------------------------------------- + +.. tab-set:: + + .. tab-item:: Console + + You can register for SUBNET from the MinIO Console. + + #. Go to your MinIO cluster's URL, then sign in + #. Select the :guilabel:`Support` option + #. Select :guilabel:`Register` + #. Enter your :guilabel:`Email` address and a unique :guilabel:`Password`, then select :guilabel:`Register` + + .. tab-item:: Console Airgapped + + You can register MinIO deployments for SUBNET even if they exists an airgap, firewall, or otherwise no direct Internet access. + From the Console: + + #. Go to your MinIO cluster's URL, then sign in + #. Select the :guilabel:`Support` option + #. Select :guilabel:`Register` + #. Select the :guilabel:`Offline Activation` link at the bottom of the screen + #. Copy the registration token for your cluster from item 1 + #. Go to https://subnet.min.io/cluster/register and enter the registration token when prompted + #. Copy the generated API key and paste it in item 3 of the **Offline Registration** window in the MinIO Console + #. Select :guilabel:`Register` + + .. tab-item:: Command Line + + You can register for SUBNET from the command line. + + Refer to :mc-cmd:`mc support register` for instructions. + + For clusters without direct Internet access, refer to the instructions in the :ref:`airgap example ` of the :mc-cmd:`mc support register` documentation. + + +SUBNET Issues +------------- + +Use SUBNET issues to engage support from MinIO engineering. + +#. Log in to https://subnet.min.io +#. Select the :guilabel:`Issues` section + +Use the search bar to locate an existing issue or add a new issue. + +.. image:: /images/subnet/issues-section.png + :width: 600px + :alt: MinIO SUBNET with the Issues section displaying a list of an organization's issues + :align: center + +Select an existing issue from the list to expand the converation or add a response. + +.. image:: /images/subnet/issue-expanded.png + :width: 600px + :alt: A example MinIO SUBNET issue conversation + :align: center + +Reviewing Health Data in SUBNET +------------------------------- + +SUBNET provides health data about the clusters registered to the organization from the :guilabel:`Deployments` section. + +The view shows the total size of the org's MinIO clusters with details for each cluster. + +.. image:: /images/subnet/deployments-overview.png + :width: 600px + :alt: MinIO SUBNET displaying the deployments overview + :align: center + +Each of the organization's clusters display below the summary data. +Select a deployment row to view additional health details. + +Deployment Health +~~~~~~~~~~~~~~~~~ + +The deployment's details include a summary of the deployment's configuration and the number of checks run and failed. +You can select :guilabel:`Upload` to add diagnostic health data obtained from the :mc-cmd:`mc support diagnostics` command or the MinIO Console's Support > Health page. + +If you need support from MinIO Engineering, you can create a :guilabel:`New Issue` for the deployment. + +.. image:: /images/subnet/SUBNET-deployment-health-summary.png + :width: 600px + :alt: MinIO SUBNET displaying health summary information for a myminio deployment + :align: center + +SUBNET displays health checks for data points such as CPU, drives, memory, network, and security. + +Failed checks display first. +Checks with warnings display after failed checks. +Checks that pass display last. + +Select any failed or warned checks to display the JSON output for additional details. +You can scroll vertically through the output for the selected check. + +.. image:: /images/subnet/deployment-health-tls-config-fail.png + :width: 600px + :alt: MinIO SUBNET's health report for a deployment showing a failed Health Report with details expanded + :align: center + +Uploading Data to SUBNET +------------------------ + +If you registered the cluster with SUBNET, Performance and Inspection files can automatically upload to SUBNET. + +For clusters with an airgap, firewall, or otherwise blocked from SUBNET directly, you can manually upload files to SUBNET after logging in. + +#. Generate the file(s) to upload from the command line with :mc-cmd:`mc support diagnostics` or :mc-cmd:`mc support inspect` +#. Sign in to `SUBNET `_ +#. Select :guilabel:`Deployments` +#. Select :guilabel:`Diagnostics` +#. Drag and drop the ``.gzip`` file(s) or browse to the file location to upload + + +Encrypting Data +~~~~~~~~~~~~~~~ + +Data from the Inspect tool in :ref:`Console ` or the :mc-cmd:`mc support inspect` command can be encrypted. +For more details about encrypting or decrypting such files, see :ref:`Encrypting Files `. + + +.. toctree:: + :titlesonly: + :hidden: + + /support/encrypting-files