storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/docs/config/README.md (about) 1 # MinIO Server Config Guide [](https://slack.min.io) [](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)