storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/docs/config/README.md (about)

     1  # MinIO Server Config Guide [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/)
     2  
     3  ## Configuration Directory
     4  
     5  Till MinIO release `RELEASE.2018-08-02T23-11-36Z`, MinIO server configuration file (`config.json`) was stored in the configuration directory specified by `--config-dir` or defaulted to `${HOME}/.minio`. However from releases after `RELEASE.2018-08-18T03-49-57Z`, the configuration file (only), has been migrated to the storage backend (storage backend is the directory passed to MinIO server while starting the server).
     6  
     7  You can specify the location of your existing config using `--config-dir`, MinIO will migrate the `config.json` to your backend storage. Your current `config.json` will be renamed upon successful migration as `config.json.deprecated` in your current `--config-dir`. All your existing configurations are honored after this migration.
     8  
     9  Additionally `--config-dir` is now a legacy option which will is scheduled for removal in future, so please update your local startup, ansible scripts accordingly.
    10  
    11  ```sh
    12  minio server /data
    13  ```
    14  
    15  MinIO also encrypts all the config, IAM and policies content with admin credentials.
    16  
    17  ### Certificate Directory
    18  
    19  TLS certificates by default are stored under ``${HOME}/.minio/certs`` directory. You need to place certificates here to enable `HTTPS` based access. Read more about [How to secure access to MinIO server with TLS](https://docs.min.io/docs/how-to-secure-access-to-minio-server-with-tls).
    20  
    21  Following is the directory structure for MinIO server with TLS certificates.
    22  
    23  ```sh
    24  $ mc tree --files ~/.minio
    25  /home/user1/.minio
    26  └─ certs
    27     ├─ CAs
    28     ├─ private.key
    29     └─ public.crt
    30  ```
    31  
    32  You can provide a custom certs directory using `--certs-dir` command line option.
    33  
    34  #### Credentials
    35  On MinIO admin credentials or root credentials are only allowed to be changed using ENVs namely `MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD`. Using the combination of these two values MinIO encrypts the config stored at the backend.
    36  
    37  ```sh
    38  export MINIO_ROOT_USER=minio
    39  export MINIO_ROOT_PASSWORD=minio13
    40  minio server /data
    41  ```
    42  
    43  ##### Rotating encryption with new credentials
    44  
    45  Additionally if you wish to change the admin credentials, then MinIO will automatically detect this and re-encrypt with new credentials as shown below. For one time only special ENVs as shown below needs to be set for rotating the encryption config.
    46  
    47  > Old ENVs are never remembered in memory and are destroyed right after they are used to migrate your existing content with new credentials. You are safe to remove them after the server as successfully started, by restarting the services once again.
    48  
    49  ```sh
    50  export MINIO_ROOT_USER=newminio
    51  export MINIO_ROOT_PASSWORD=newminio123
    52  export MINIO_ROOT_USER_OLD=minio
    53  export MINIO_ROOT_PASSWORD_OLD=minio123
    54  minio server /data
    55  ```
    56  
    57  Once the migration is complete, server will automatically unset the `MINIO_ROOT_USER_OLD` and `MINIO_ROOT_PASSWORD_OLD` with in the process namespace.
    58  
    59  > **NOTE: Make sure to remove `MINIO_ROOT_USER_OLD` and `MINIO_ROOT_PASSWORD_OLD` in scripts or service files before next service restarts of the server to avoid double encryption of your existing contents.**
    60  
    61  #### Region
    62  ```
    63  KEY:
    64  region  label the location of the server
    65  
    66  ARGS:
    67  name     (string)    name of the location of the server e.g. "us-west-rack2"
    68  comment  (sentence)  optionally add a comment to this setting
    69  ```
    70  
    71  or environment variables
    72  ```
    73  KEY:
    74  region  label the location of the server
    75  
    76  ARGS:
    77  MINIO_REGION_NAME     (string)    name of the location of the server e.g. "us-west-rack2"
    78  MINIO_REGION_COMMENT  (sentence)  optionally add a comment to this setting
    79  ```
    80  
    81  Example:
    82  
    83  ```sh
    84  export MINIO_REGION_NAME="my_region"
    85  minio server /data
    86  ```
    87  
    88  ### Storage Class
    89  By default, parity for objects with standard storage class is set to `N/2`, and parity for objects with reduced redundancy storage class objects is set to `2`. Read more about storage class support in MinIO server [here](https://github.com/minio/minio/blob/master/docs/erasure/storage-class/README.md).
    90  
    91  ```
    92  KEY:
    93  storage_class  define object level redundancy
    94  
    95  ARGS:
    96  standard  (string)    set the parity count for default standard storage class e.g. "EC:4"
    97  rrs       (string)    set the parity count for reduced redundancy storage class e.g. "EC:2"
    98  comment   (sentence)  optionally add a comment to this setting
    99  ```
   100  
   101  or environment variables
   102  ```
   103  KEY:
   104  storage_class  define object level redundancy
   105  
   106  ARGS:
   107  MINIO_STORAGE_CLASS_STANDARD  (string)    set the parity count for default standard storage class e.g. "EC:4"
   108  MINIO_STORAGE_CLASS_RRS       (string)    set the parity count for reduced redundancy storage class e.g. "EC:2"
   109  MINIO_STORAGE_CLASS_COMMENT   (sentence)  optionally add a comment to this setting
   110  ```
   111  
   112  ### Cache
   113  MinIO provides caching storage tier for primarily gateway deployments, allowing you to cache content for faster reads, cost savings on repeated downloads from the cloud.
   114  
   115  ```
   116  KEY:
   117  cache  add caching storage tier
   118  
   119  ARGS:
   120  drives*  (csv)       comma separated mountpoints e.g. "/optane1,/optane2"
   121  expiry   (number)    cache expiry duration in days e.g. "90"
   122  quota    (number)    limit cache drive usage in percentage e.g. "90"
   123  exclude  (csv)       comma separated wildcard exclusion patterns e.g. "bucket/*.tmp,*.exe"
   124  after    (number)    minimum number of access before caching an object
   125  comment  (sentence)  optionally add a comment to this setting
   126  ```
   127  
   128  or environment variables
   129  ```
   130  KEY:
   131  cache  add caching storage tier
   132  
   133  ARGS:
   134  MINIO_CACHE_DRIVES*  (csv)       comma separated mountpoints e.g. "/optane1,/optane2"
   135  MINIO_CACHE_EXPIRY   (number)    cache expiry duration in days e.g. "90"
   136  MINIO_CACHE_QUOTA    (number)    limit cache drive usage in percentage e.g. "90"
   137  MINIO_CACHE_EXCLUDE  (csv)       comma separated wildcard exclusion patterns e.g. "bucket/*.tmp,*.exe"
   138  MINIO_CACHE_AFTER    (number)    minimum number of access before caching an object
   139  MINIO_CACHE_COMMENT  (sentence)  optionally add a comment to this setting
   140  ```
   141  
   142  #### Etcd
   143  MinIO supports storing encrypted IAM assets and bucket DNS records on etcd.
   144  
   145  > NOTE: if *path_prefix* is set then MinIO will not federate your buckets, namespaced IAM assets are assumed as isolated tenants, only buckets are considered globally unique but performing a lookup with a *bucket* which belongs to a different tenant will fail unlike federated setups where MinIO would port-forward and route the request to relevant cluster accordingly. This is a special feature, federated deployments should not need to set *path_prefix*.
   146  
   147  ```
   148  KEY:
   149  etcd  federate multiple clusters for IAM and Bucket DNS
   150  
   151  ARGS:
   152  endpoints*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
   153  path_prefix      (path)      namespace prefix to isolate tenants e.g. "customer1/"
   154  coredns_path     (path)      shared bucket DNS records, default is "/skydns"
   155  client_cert      (path)      client cert for mTLS authentication
   156  client_cert_key  (path)      client cert key for mTLS authentication
   157  comment          (sentence)  optionally add a comment to this setting
   158  ```
   159  
   160  or environment variables
   161  ```
   162  KEY:
   163  etcd  federate multiple clusters for IAM and Bucket DNS
   164  
   165  ARGS:
   166  MINIO_ETCD_ENDPOINTS*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
   167  MINIO_ETCD_PATH_PREFIX      (path)      namespace prefix to isolate tenants e.g. "customer1/"
   168  MINIO_ETCD_COREDNS_PATH     (path)      shared bucket DNS records, default is "/skydns"
   169  MINIO_ETCD_CLIENT_CERT      (path)      client cert for mTLS authentication
   170  MINIO_ETCD_CLIENT_CERT_KEY  (path)      client cert key for mTLS authentication
   171  MINIO_ETCD_COMMENT          (sentence)  optionally add a comment to this setting
   172  ```
   173  
   174  ### API
   175  By default, there is no limitation on the number of concurrent requests that a server/cluster processes at the same time. However, it is possible to impose such limitation using the API subsystem. Read more about throttling limitation in MinIO server [here](https://github.com/minio/minio/blob/master/docs/throttle/README.md).
   176  
   177  ```
   178  KEY:
   179  api  manage global HTTP API call specific features, such as throttling, authentication types, etc.
   180  
   181  ARGS:
   182  requests_max               (number)    set the maximum number of concurrent requests, e.g. "1600"
   183  requests_deadline          (duration)  set the deadline for API requests waiting to be processed e.g. "1m"
   184  cors_allow_origin          (csv)       set comma separated list of origins allowed for CORS requests e.g. "https://example1.com,https://example2.com"
   185  remote_transport_deadline  (duration)  set the deadline for API requests on remote transports while proxying between federated instances e.g. "2h"
   186  ```
   187  
   188  or environment variables
   189  
   190  ```
   191  MINIO_API_REQUESTS_MAX               (number)    set the maximum number of concurrent requests, e.g. "1600"
   192  MINIO_API_REQUESTS_DEADLINE          (duration)  set the deadline for API requests waiting to be processed e.g. "1m"
   193  MINIO_API_CORS_ALLOW_ORIGIN          (csv)       set comma separated list of origins allowed for CORS requests e.g. "https://example1.com,https://example2.com"
   194  MINIO_API_REMOTE_TRANSPORT_DEADLINE  (duration)  set the deadline for API requests on remote transports while proxying between federated instances e.g. "2h"
   195  ```
   196  
   197  #### Notifications
   198  Notification targets supported by MinIO are in the following list. To configure individual targets please refer to more detailed documentation [here](https://docs.min.io/docs/minio-bucket-notification-guide.html)
   199  
   200  ```
   201  notify_webhook        publish bucket notifications to webhook endpoints
   202  notify_amqp           publish bucket notifications to AMQP endpoints
   203  notify_kafka          publish bucket notifications to Kafka endpoints
   204  notify_mqtt           publish bucket notifications to MQTT endpoints
   205  notify_nats           publish bucket notifications to NATS endpoints
   206  notify_nsq            publish bucket notifications to NSQ endpoints
   207  notify_mysql          publish bucket notifications to MySQL databases
   208  notify_postgres       publish bucket notifications to Postgres databases
   209  notify_elasticsearch  publish bucket notifications to Elasticsearch endpoints
   210  notify_redis          publish bucket notifications to Redis datastores
   211  ```
   212  
   213  ### Accessing configuration
   214  All configuration changes can be made using [`mc admin config` get/set/reset/export/import commands](https://github.com/minio/mc/blob/master/docs/minio-admin-complete-guide.md).
   215  
   216  #### List all config keys available
   217  ```
   218  ~ mc admin config set myminio/
   219  ```
   220  
   221  #### Obtain help for each key
   222  ```
   223  ~ mc admin config set myminio/ <key>
   224  ```
   225  
   226  e.g: `mc admin config set myminio/ etcd` returns available `etcd` config args
   227  
   228  ```
   229  ~ mc admin config set play/ etcd
   230  KEY:
   231  etcd  federate multiple clusters for IAM and Bucket DNS
   232  
   233  ARGS:
   234  endpoints*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
   235  path_prefix      (path)      namespace prefix to isolate tenants e.g. "customer1/"
   236  coredns_path     (path)      shared bucket DNS records, default is "/skydns"
   237  client_cert      (path)      client cert for mTLS authentication
   238  client_cert_key  (path)      client cert key for mTLS authentication
   239  comment          (sentence)  optionally add a comment to this setting
   240  ```
   241  
   242  To get ENV equivalent for each config args use `--env` flag
   243  ```
   244  ~ mc admin config set play/ etcd --env
   245  KEY:
   246  etcd  federate multiple clusters for IAM and Bucket DNS
   247  
   248  ARGS:
   249  MINIO_ETCD_ENDPOINTS*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
   250  MINIO_ETCD_PATH_PREFIX      (path)      namespace prefix to isolate tenants e.g. "customer1/"
   251  MINIO_ETCD_COREDNS_PATH     (path)      shared bucket DNS records, default is "/skydns"
   252  MINIO_ETCD_CLIENT_CERT      (path)      client cert for mTLS authentication
   253  MINIO_ETCD_CLIENT_CERT_KEY  (path)      client cert key for mTLS authentication
   254  MINIO_ETCD_COMMENT          (sentence)  optionally add a comment to this setting
   255  ```
   256  
   257  This behavior is consistent across all keys, each key self documents itself with valid examples.
   258  
   259  ## Dynamic systems without restarting server
   260  
   261  The following sub-systems are dynamic i.e., configuration parameters for each sub-systems can be changed while the server is running without any restarts.
   262  
   263  ```
   264  api                   manage global HTTP API call specific features, such as throttling, authentication types, etc.
   265  heal                  manage object healing frequency and bitrot verification checks
   266  scanner               manage namespace scanning for usage calculation, lifecycle, healing and more
   267  ```
   268  
   269  > NOTE: if you set any of the following sub-system configuration using ENVs, dynamic behavior is not supported.
   270  
   271  ### Usage scanner
   272  
   273  Data usage scanner is enabled by default. The following configuration settings allow for more staggered delay in terms of usage calculation. The scanner adapts to the system speed and completely pauses when the system is under load. It is possible to adjust the speed of the scanner and thereby the latency of updates being reflected. The delays between each operation of the scanner can be adjusted by the `mc admin config set alias/ delay=15.0`. By default the value is `10.0`. This means the scanner will sleep *10x* the time each operation takes.
   274  
   275  In most setups this will keep the scanner slow enough to not impact overall system performance. Setting the `delay` key to a *lower* value will make the scanner faster and setting it to 0 will make the scanner run at full speed (not recommended in production). Setting it to a higher value will make the scanner slower, consuming less resources with the trade off of not collecting metrics for operations like healing and disk usage as fast.
   276  
   277  ```
   278  ~ mc admin config set alias/ scanner
   279  KEY:
   280  scanner  manage namespace scanning for usage calculation, lifecycle, healing and more
   281  
   282  ARGS:
   283  delay     (float)     scanner delay multiplier, defaults to '10.0'
   284  max_wait  (duration)  maximum wait time between operations, defaults to '15s'
   285  ```
   286  
   287  Example: Following setting will decrease the scanner speed by a factor of 3, reducing the system resource use, but increasing the latency of updates being reflected.
   288  
   289  ```sh
   290  ~ mc admin config set alias/ scanner delay=30.0
   291  ```
   292  
   293  Once set the scanner settings are automatically applied without the need for server restarts.
   294  
   295  > NOTE: Data usage scanner is not supported under Gateway deployments.
   296  
   297  ### Healing
   298  
   299  Healing is enabled by default. The following configuration settings allow for more staggered delay in terms of healing. The healing system by default adapts to the system speed and pauses up to '1sec' per object when the system has `max_io` number of concurrent requests. It is possible to adjust the `max_delay` and `max_io` values thereby increasing the healing speed. The delays between each operation of the healer can be adjusted by the `mc admin config set alias/ max_delay=1s` and maximum concurrent requests allowed before we start slowing things down can be configured with `mc admin config set alias/ max_io=30` . By default the wait delay is `1sec` beyond 10 concurrent operations. This means the healer will sleep *1 second* at max for each heal operation if there are more than *10* concurrent client requests.
   300  
   301  In most setups this is sufficient to heal the content after drive replacements. Setting `max_delay` to a *lower* value and setting `max_io` to a *higher* value would make heal go faster.
   302  
   303  ```
   304  ~ mc admin config set alias/ heal
   305  KEY:
   306  heal  manage object healing frequency and bitrot verification checks
   307  
   308  ARGS:
   309  bitrotscan  (on|off)    perform bitrot scan on disks when checking objects during scanner
   310  max_sleep   (duration)  maximum sleep duration between objects to slow down heal operation. eg. 2s
   311  max_io      (int)       maximum IO requests allowed between objects to slow down heal operation. eg. 3
   312  ```
   313  
   314  Example: The following settings will increase the heal operation speed by allowing healing operation to run without delay up to `100` concurrent requests, and the maximum delay between each heal operation is set to `300ms`.
   315  
   316  ```sh
   317  ~ mc admin config set alias/ heal max_delay=300ms max_io=100
   318  ```
   319  
   320  Once set the healer settings are automatically applied without the need for server restarts.
   321  
   322  > NOTE: Healing is not supported under Gateway deployments.
   323  
   324  
   325  ## Environment only settings (not in config)
   326  
   327  ### Browser
   328  
   329  Enable or disable access to web UI. By default it is set to `on`. You may override this field with `MINIO_BROWSER` environment variable.
   330  
   331  Example:
   332  
   333  ```sh
   334  export MINIO_BROWSER=off
   335  minio server /data
   336  ```
   337  
   338  ### Domain
   339  
   340  By default, MinIO supports path-style requests that are of the format http://mydomain.com/bucket/object. `MINIO_DOMAIN` environment variable is used to enable virtual-host-style requests. If the request `Host` header matches with `(.+).mydomain.com` then the matched pattern `$1` is used as bucket and the path is used as object. More information on path-style and virtual-host-style [here](http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAPI.html)
   341  Example:
   342  
   343  ```sh
   344  export MINIO_DOMAIN=mydomain.com
   345  minio server /data
   346  ```
   347  
   348  For advanced use cases `MINIO_DOMAIN` environment variable supports multiple-domains with comma separated values.
   349  ```sh
   350  export MINIO_DOMAIN=sub1.mydomain.com,sub2.mydomain.com
   351  minio server /data
   352  ```
   353  
   354  ## Explore Further
   355  * [MinIO Quickstart Guide](https://docs.min.io/docs/minio-quickstart-guide)
   356  * [Configure MinIO Server with TLS](https://docs.min.io/docs/how-to-secure-access-to-minio-server-with-tls)