github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/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 MinIO stores all its config as part of the server deployment, config is erasure coded on MinIO. On a fresh deployment MinIO automatically generates a new `config` and this config is available to be configured via `mc admin config` command. MinIO also encrypts all the config, IAM and policies content if KMS is configured. Please refer to how to encrypt your config and IAM credentials [here](https://github.com/minio/minio/blob/master/docs/kms/IAM.md). 6 7 ### Certificate Directory 8 9 TLS certificates by default are expected to be 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://min.io/docs/minio/linux/operations/network-encryption.html). 10 11 Following is a sample directory structure for MinIO server with TLS certificates. 12 13 ```sh 14 $ mc tree --files ~/.minio 15 /home/user1/.minio 16 └─ certs 17 ├─ CAs 18 ├─ private.key 19 └─ public.crt 20 ``` 21 22 You can provide a custom certs directory using `--certs-dir` command line option. 23 24 #### Credentials 25 26 On MinIO admin credentials or root credentials are only allowed to be changed using ENVs namely `MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD`. 27 28 ```sh 29 export MINIO_ROOT_USER=minio 30 export MINIO_ROOT_PASSWORD=minio13 31 minio server /data 32 ``` 33 34 #### Site 35 36 ``` 37 KEY: 38 site label the server and its location 39 40 ARGS: 41 name (string) name for the site e.g. "cal-rack0" 42 region (string) name of the location of the server e.g. "us-west-1" 43 comment (sentence) optionally add a comment to this setting 44 ``` 45 46 or environment variables 47 48 ``` 49 KEY: 50 site label the server and its location 51 52 ARGS: 53 MINIO_SITE_NAME (string) name for the site e.g. "cal-rack0" 54 MINIO_SITE_REGION (string) name of the location of the server e.g. "us-west-1" 55 MINIO_SITE_COMMENT (sentence) optionally add a comment to this setting 56 ``` 57 58 Example: 59 60 ```sh 61 export MINIO_SITE_REGION="us-west-0" 62 export MINIO_SITE_NAME="sfo-rack-1" 63 minio server /data 64 ``` 65 66 ### Storage Class 67 68 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). 69 70 ``` 71 KEY: 72 storage_class define object level redundancy 73 74 ARGS: 75 standard (string) set the parity count for default standard storage class e.g. "EC:4" 76 rrs (string) set the parity count for reduced redundancy storage class e.g. "EC:2" 77 comment (sentence) optionally add a comment to this setting 78 ``` 79 80 or environment variables 81 82 ``` 83 KEY: 84 storage_class define object level redundancy 85 86 ARGS: 87 MINIO_STORAGE_CLASS_STANDARD (string) set the parity count for default standard storage class e.g. "EC:4" 88 MINIO_STORAGE_CLASS_RRS (string) set the parity count for reduced redundancy storage class e.g. "EC:2" 89 MINIO_STORAGE_CLASS_COMMENT (sentence) optionally add a comment to this setting 90 ``` 91 92 #### Etcd 93 94 MinIO supports storing encrypted IAM assets in etcd, if KMS is configured. Please refer to how to encrypt your config and IAM credentials [here](https://github.com/minio/minio/blob/master/docs/kms/IAM.md). 95 96 > 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*. 97 98 ``` 99 KEY: 100 etcd federate multiple clusters for IAM and Bucket DNS 101 102 ARGS: 103 endpoints* (csv) comma separated list of etcd endpoints e.g. "http://localhost:2379" 104 path_prefix (path) namespace prefix to isolate tenants e.g. "customer1/" 105 coredns_path (path) shared bucket DNS records, default is "/skydns" 106 client_cert (path) client cert for mTLS authentication 107 client_cert_key (path) client cert key for mTLS authentication 108 comment (sentence) optionally add a comment to this setting 109 ``` 110 111 or environment variables 112 113 ``` 114 KEY: 115 etcd federate multiple clusters for IAM and Bucket DNS 116 117 ARGS: 118 MINIO_ETCD_ENDPOINTS* (csv) comma separated list of etcd endpoints e.g. "http://localhost:2379" 119 MINIO_ETCD_PATH_PREFIX (path) namespace prefix to isolate tenants e.g. "customer1/" 120 MINIO_ETCD_COREDNS_PATH (path) shared bucket DNS records, default is "/skydns" 121 MINIO_ETCD_CLIENT_CERT (path) client cert for mTLS authentication 122 MINIO_ETCD_CLIENT_CERT_KEY (path) client cert key for mTLS authentication 123 MINIO_ETCD_COMMENT (sentence) optionally add a comment to this setting 124 ``` 125 126 ### API 127 128 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). 129 130 ``` 131 KEY: 132 api manage global HTTP API call specific features, such as throttling, authentication types, etc. 133 134 ARGS: 135 requests_max (number) set the maximum number of concurrent requests (default: '0') 136 requests_deadline (duration) set the deadline for API requests waiting to be processed (default: '10s') 137 cluster_deadline (duration) set the deadline for cluster readiness check (default: '10s') 138 cors_allow_origin (csv) set comma separated list of origins allowed for CORS requests (default: '*') 139 remote_transport_deadline (duration) set the deadline for API requests on remote transports while proxying between federated instances e.g. "2h" (default: '2h') 140 list_quorum (string) set the acceptable quorum expected for list operations e.g. "optimal", "reduced", "disk", "strict" (default: 'strict') 141 replication_priority (string) set replication priority (default: 'auto') 142 transition_workers (number) set the number of transition workers (default: '100') 143 stale_uploads_expiry (duration) set to expire stale multipart uploads older than this values (default: '24h') 144 stale_uploads_cleanup_interval (duration) set to change intervals when stale multipart uploads are expired (default: '6h') 145 delete_cleanup_interval (duration) set to change intervals when deleted objects are permanently deleted from ".trash" folder (default: '5m') 146 odirect (boolean) set to enable or disable O_DIRECT for read and writes under special conditions. NOTE: do not disable O_DIRECT without prior testing (default: 'on') 147 root_access (boolean) turn 'off' root credential access for all API calls including s3, admin operations (default: 'on') 148 sync_events (boolean) set to enable synchronous bucket notifications (default: 'off') 149 ``` 150 151 or environment variables 152 153 ``` 154 MINIO_API_REQUESTS_MAX (number) set the maximum number of concurrent requests (default: '0') 155 MINIO_API_REQUESTS_DEADLINE (duration) set the deadline for API requests waiting to be processed (default: '10s') 156 MINIO_API_CLUSTER_DEADLINE (duration) set the deadline for cluster readiness check (default: '10s') 157 MINIO_API_CORS_ALLOW_ORIGIN (csv) set comma separated list of origins allowed for CORS requests (default: '*') 158 MINIO_API_REMOTE_TRANSPORT_DEADLINE (duration) set the deadline for API requests on remote transports while proxying between federated instances e.g. "2h" (default: '2h') 159 MINIO_API_LIST_QUORUM (string) set the acceptable quorum expected for list operations e.g. "optimal", "reduced", "disk", "strict" (default: 'strict') 160 MINIO_API_REPLICATION_PRIORITY (string) set replication priority (default: 'auto') 161 MINIO_API_TRANSITION_WORKERS (number) set the number of transition workers (default: '100') 162 MINIO_API_STALE_UPLOADS_EXPIRY (duration) set to expire stale multipart uploads older than this values (default: '24h') 163 MINIO_API_STALE_UPLOADS_CLEANUP_INTERVAL (duration) set to change intervals when stale multipart uploads are expired (default: '6h') 164 MINIO_API_DELETE_CLEANUP_INTERVAL (duration) set to change intervals when deleted objects are permanently deleted from ".trash" folder (default: '5m') 165 MINIO_API_ODIRECT (boolean) set to enable or disable O_DIRECT for read and writes under special conditions. NOTE: do not disable O_DIRECT without prior testing (default: 'on') 166 MINIO_API_ROOT_ACCESS (boolean) turn 'off' root credential access for all API calls including s3, admin operations (default: 'on') 167 MINIO_API_SYNC_EVENTS (boolean) set to enable synchronous bucket notifications (default: 'off') 168 ``` 169 170 #### Notifications 171 172 Notification targets supported by MinIO are in the following list. To configure individual targets please refer to more detailed documentation [here](https://min.io/docs/minio/linux/administration/monitoring.html#bucket-notifications). 173 174 ``` 175 notify_webhook publish bucket notifications to webhook endpoints 176 notify_amqp publish bucket notifications to AMQP endpoints 177 notify_kafka publish bucket notifications to Kafka endpoints 178 notify_mqtt publish bucket notifications to MQTT endpoints 179 notify_nats publish bucket notifications to NATS endpoints 180 notify_nsq publish bucket notifications to NSQ endpoints 181 notify_mysql publish bucket notifications to MySQL databases 182 notify_postgres publish bucket notifications to Postgres databases 183 notify_elasticsearch publish bucket notifications to Elasticsearch endpoints 184 notify_redis publish bucket notifications to Redis datastores 185 ``` 186 187 ### Accessing configuration 188 189 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). 190 191 #### List all config keys available 192 193 ``` 194 ~ mc admin config set myminio/ 195 ``` 196 197 #### Obtain help for each key 198 199 ``` 200 ~ mc admin config set myminio/ <key> 201 ``` 202 203 e.g: `mc admin config set myminio/ etcd` returns available `etcd` config args 204 205 ``` 206 ~ mc admin config set play/ etcd 207 KEY: 208 etcd federate multiple clusters for IAM and Bucket DNS 209 210 ARGS: 211 endpoints* (csv) comma separated list of etcd endpoints e.g. "http://localhost:2379" 212 path_prefix (path) namespace prefix to isolate tenants e.g. "customer1/" 213 coredns_path (path) shared bucket DNS records, default is "/skydns" 214 client_cert (path) client cert for mTLS authentication 215 client_cert_key (path) client cert key for mTLS authentication 216 comment (sentence) optionally add a comment to this setting 217 ``` 218 219 To get ENV equivalent for each config args use `--env` flag 220 221 ``` 222 ~ mc admin config set play/ etcd --env 223 KEY: 224 etcd federate multiple clusters for IAM and Bucket DNS 225 226 ARGS: 227 MINIO_ETCD_ENDPOINTS* (csv) comma separated list of etcd endpoints e.g. "http://localhost:2379" 228 MINIO_ETCD_PATH_PREFIX (path) namespace prefix to isolate tenants e.g. "customer1/" 229 MINIO_ETCD_COREDNS_PATH (path) shared bucket DNS records, default is "/skydns" 230 MINIO_ETCD_CLIENT_CERT (path) client cert for mTLS authentication 231 MINIO_ETCD_CLIENT_CERT_KEY (path) client cert key for mTLS authentication 232 MINIO_ETCD_COMMENT (sentence) optionally add a comment to this setting 233 ``` 234 235 This behavior is consistent across all keys; each key self-documents itself with valid examples. 236 237 ## Dynamic systems without restarting server 238 239 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. 240 241 ``` 242 api manage global HTTP API call specific features, such as throttling, authentication types, etc. 243 heal manage object healing frequency and bitrot verification checks 244 scanner manage namespace scanning for usage calculation, lifecycle, healing and more 245 ``` 246 247 > NOTE: if you set any of the following sub-system configuration using ENVs, dynamic behavior is not supported. 248 249 ### Usage scanner 250 251 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. 252 253 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. 254 255 ``` 256 ~ mc admin config set alias/ scanner 257 KEY: 258 scanner manage namespace scanning for usage calculation, lifecycle, healing and more 259 260 ARGS: 261 delay (float) scanner delay multiplier, defaults to '10.0' 262 max_wait (duration) maximum wait time between operations, defaults to '15s' 263 cycle (duration) time duration between scanner cycles 264 ``` 265 266 Example: the 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. 267 268 ```sh 269 ~ mc admin config set alias/ scanner delay=30.0 270 ``` 271 272 Once set the scanner settings are automatically applied without the need for server restarts. 273 274 ### Healing 275 276 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 '250ms' per object when the system has `max_io` number of concurrent requests. It is possible to adjust the `max_sleep` 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/ heal max_sleep=1s` and maximum concurrent requests allowed before we start slowing things down can be configured with `mc admin config set alias/ heal max_io=30` . By default the wait delay is `250ms` beyond 100 concurrent operations. This means the healer will sleep *250 milliseconds* at max for each heal operation if there are more than *100* concurrent client requests. 277 278 In most setups this is sufficient to heal the content after drive replacements. Setting `max_sleep` to a *lower* value and setting `max_io` to a *higher* value would make heal go faster. 279 280 Each node is responsible of healing its local drives; Each drive will have multiple heal workers which is the quarter of the number of CPU cores of the node or the quarter of the configured nr_requests of the drive (https://www.kernel.org/doc/Documentation/block/queue-sysfs.txt). It is also possible to provide a custom number of workers by using this command: `mc admin config set alias/ heal drive_workers=100` . 281 282 283 ``` 284 ~ mc admin config set alias/ heal 285 KEY: 286 heal manage object healing frequency and bitrot verification checks 287 288 ARGS: 289 bitrotscan (on|off) perform bitrot scan on drives when checking objects during scanner 290 max_sleep (duration) maximum sleep duration between objects to slow down heal operation. eg. 2s 291 max_io (int) maximum IO requests allowed between objects to slow down heal operation. eg. 3 292 drive_workers (int) the number of workers per drive to heal a new disk replacement. 293 ``` 294 295 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`. 296 297 ```sh 298 ~ mc admin config set alias/ heal max_sleep=300ms max_io=100 299 ``` 300 301 Once set the healer settings are automatically applied without the need for server restarts. 302 303 ## Environment only settings (not in config) 304 305 ### Browser 306 307 Enable or disable access to console web UI. By default it is set to `on`. You may override this field with `MINIO_BROWSER` environment variable. 308 309 Example: 310 311 ```sh 312 export MINIO_BROWSER=off 313 minio server /data 314 ``` 315 316 ### Domain 317 318 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. Read more about path-style and virtual-host-style [here](http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAPI.html). 319 320 Example: 321 322 ```sh 323 export MINIO_DOMAIN=mydomain.com 324 minio server /data 325 ``` 326 327 For advanced use cases `MINIO_DOMAIN` environment variable supports multiple-domains with comma separated values. 328 329 ```sh 330 export MINIO_DOMAIN=sub1.mydomain.com,sub2.mydomain.com 331 minio server /data 332 ``` 333 334 ## Explore Further 335 336 * [MinIO Quickstart Guide](https://min.io/docs/minio/linux/index.html#quickstart-for-linux) 337 * [Configure MinIO Server with TLS](https://min.io/docs/minio/linux/operations/network-encryption.html)