From 98315b8e60af1acd41aaeb1eba9216f929d2cd69 Mon Sep 17 00:00:00 2001 From: poornas Date: Sun, 1 Apr 2018 21:55:09 -0700 Subject: [PATCH] Update disk cache documentation (#5743) --- cmd/gateway/azure/gateway-azure.go | 4 ++-- cmd/gateway/b2/gateway-b2.go | 4 ++-- cmd/gateway/gcs/gateway-gcs.go | 4 ++-- cmd/gateway/manta/gateway-manta.go | 4 ++-- cmd/gateway/nas/gateway-nas.go | 4 ++-- cmd/gateway/oss/gateway-oss.go | 4 ++-- cmd/gateway/s3/gateway-s3.go | 4 ++-- cmd/gateway/sia/gateway-sia.go | 4 ++-- cmd/server-main.go | 4 ++-- docs/config/README.md | 4 ++-- docs/disk-caching/DESIGN.md | 11 +++++++---- docs/disk-caching/README.md | 9 +++++---- 12 files changed, 32 insertions(+), 28 deletions(-) diff --git a/cmd/gateway/azure/gateway-azure.go b/cmd/gateway/azure/gateway-azure.go index 22d090ac8..d7b48afe5 100644 --- a/cmd/gateway/azure/gateway-azure.go +++ b/cmd/gateway/azure/gateway-azure.go @@ -73,7 +73,7 @@ ENVIRONMENT VARIABLES: MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -97,7 +97,7 @@ EXAMPLES: 3. Start minio gateway server for Azure Blob Storage backend with edge caching enabled. $ export MINIO_ACCESS_KEY=azureaccountname $ export MINIO_SECRET_KEY=azureaccountkey - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} diff --git a/cmd/gateway/b2/gateway-b2.go b/cmd/gateway/b2/gateway-b2.go index 380442fd4..8fbcefb0c 100644 --- a/cmd/gateway/b2/gateway-b2.go +++ b/cmd/gateway/b2/gateway-b2.go @@ -64,7 +64,7 @@ ENVIRONMENT VARIABLES: MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -83,7 +83,7 @@ EXAMPLES: 2. Start minio gateway server for B2 backend with edge caching enabled. $ export MINIO_ACCESS_KEY=accountID $ export MINIO_SECRET_KEY=applicationKey - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} diff --git a/cmd/gateway/gcs/gateway-gcs.go b/cmd/gateway/gcs/gateway-gcs.go index 0beb50438..a5b803b9d 100644 --- a/cmd/gateway/gcs/gateway-gcs.go +++ b/cmd/gateway/gcs/gateway-gcs.go @@ -110,7 +110,7 @@ ENVIRONMENT VARIABLES: MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -135,7 +135,7 @@ EXAMPLES: $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json $ export MINIO_ACCESS_KEY=accesskey $ export MINIO_SECRET_KEY=secretkey - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} mygcsprojectid diff --git a/cmd/gateway/manta/gateway-manta.go b/cmd/gateway/manta/gateway-manta.go index e4cf38d00..131b9da8b 100644 --- a/cmd/gateway/manta/gateway-manta.go +++ b/cmd/gateway/manta/gateway-manta.go @@ -75,7 +75,7 @@ ENVIRONMENT VARIABLES: MINIO_DOMAIN: To enable virtual-host-style requests, set this value to Minio host domain name. CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -99,7 +99,7 @@ EXAMPLES: 4. Start minio gateway server for Manta Object Storage backend with edge caching enabled. $ export MINIO_ACCESS_KEY=manta_account_name $ export MINIO_SECRET_KEY=manta_key_id - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} diff --git a/cmd/gateway/nas/gateway-nas.go b/cmd/gateway/nas/gateway-nas.go index ef83dfe23..a3b5d72fe 100644 --- a/cmd/gateway/nas/gateway-nas.go +++ b/cmd/gateway/nas/gateway-nas.go @@ -51,7 +51,7 @@ ENVIRONMENT VARIABLES: MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -70,7 +70,7 @@ EXAMPLES: 2. Start minio gateway server for NAS with edge caching enabled. $ export MINIO_ACCESS_KEY=accesskey $ export MINIO_SECRET_KEY=secretkey - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} /shared/nasvol diff --git a/cmd/gateway/oss/gateway-oss.go b/cmd/gateway/oss/gateway-oss.go index f8ea8d271..e1433586d 100644 --- a/cmd/gateway/oss/gateway-oss.go +++ b/cmd/gateway/oss/gateway-oss.go @@ -72,7 +72,7 @@ ENVIRONMENT VARIABLES: MINIO_DOMAIN: To enable virtual-host-style requests, set this value to Minio host domain name. CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -90,7 +90,7 @@ EXAMPLES: 3. Start minio gateway server for Aliyun OSS backend with edge caching enabled. $ export MINIO_ACCESS_KEY=accesskey $ export MINIO_SECRET_KEY=secretkey - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} diff --git a/cmd/gateway/s3/gateway-s3.go b/cmd/gateway/s3/gateway-s3.go index 453fc6f3b..6fedb0e15 100644 --- a/cmd/gateway/s3/gateway-s3.go +++ b/cmd/gateway/s3/gateway-s3.go @@ -57,7 +57,7 @@ ENVIRONMENT VARIABLES: MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -81,7 +81,7 @@ EXAMPLES: 3. Start minio gateway server for AWS S3 backend with edge caching enabled. $ export MINIO_ACCESS_KEY=accesskey $ export MINIO_SECRET_KEY=secretkey - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} diff --git a/cmd/gateway/sia/gateway-sia.go b/cmd/gateway/sia/gateway-sia.go index 88d32389d..cf4c4fd08 100644 --- a/cmd/gateway/sia/gateway-sia.go +++ b/cmd/gateway/sia/gateway-sia.go @@ -74,7 +74,7 @@ ENVIRONMENT VARIABLES: (Default values in parenthesis) MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -92,7 +92,7 @@ EXAMPLES: $ {{.HelpName}} 2. Start minio gateway server for Sia backend with edge caching enabled. - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} diff --git a/cmd/server-main.go b/cmd/server-main.go index d3dfbdb33..668cc7035 100644 --- a/cmd/server-main.go +++ b/cmd/server-main.go @@ -68,7 +68,7 @@ ENVIRONMENT VARIABLES: MINIO_BROWSER: To disable web browser access, set this value to "off". CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";". + MINIO_CACHE_DRIVES: List of mounted drives or directories delimited by ";". MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";". MINIO_CACHE_EXPIRY: Cache expiry duration in days. @@ -115,7 +115,7 @@ EXAMPLES: $ {{.HelpName}} http://node{1...8}.example.com/mnt/export/{1...8} 7. Start minio server with edge caching enabled. - $ export MINIO_CACHE_DRIVES="/home/drive1;/home/drive2;/home/drive3;/home/drive4" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3;/mnt/drive4" $ export MINIO_CACHE_EXCLUDE="bucket1/*;*.png" $ export MINIO_CACHE_EXPIRY=40 $ {{.HelpName}} /home/shared diff --git a/docs/config/README.md b/docs/config/README.md index 3902a147f..fd2392367 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -1,4 +1,4 @@ -# Minio Server `config.json` (v22) Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) [![Go Report Card](https://goreportcard.com/badge/minio/minio)](https://goreportcard.com/report/minio/minio) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/) [![codecov](https://codecov.io/gh/minio/minio/branch/master/graph/badge.svg)](https://codecov.io/gh/minio/minio) +# Minio Server `config.json` (v23) Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) [![Go Report Card](https://goreportcard.com/badge/minio/minio)](https://goreportcard.com/report/minio/minio) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/) [![codecov](https://codecov.io/gh/minio/minio/branch/master/graph/badge.svg)](https://codecov.io/gh/minio/minio) Minio server stores all its configuration data in `${HOME}/.minio/config.json` file by default. Following sections provide detailed explanation of each fields and how to customize them. A complete example of `config.json` is available [here](https://raw.githubusercontent.com/minio/minio/master/docs/config/config.sample.json) @@ -95,7 +95,7 @@ By default, parity for objects with standard storage class is set to `N/2`, and ### Cache |Field|Type|Description| |:---|:---|:---| -|``drives``| _[]string_ | List of drives| +|``drives``| _[]string_ | List of mounted file system drives with [`atime`](http://kerolasa.github.io/filetimes.html) support enabled| |``exclude`` | _[]string_ | List of wildcard patterns for prefixes to exclude from cache | |``expiry`` | _int_ | Days to cache expiry | diff --git a/docs/disk-caching/DESIGN.md b/docs/disk-caching/DESIGN.md index 9a7b772cd..706cc56df 100644 --- a/docs/disk-caching/DESIGN.md +++ b/docs/disk-caching/DESIGN.md @@ -9,16 +9,16 @@ minio server -h ... ... CACHE: - MINIO_CACHE_DRIVES: List of cache drives delimited by ";" + MINIO_CACHE_DRIVES: List of mounted cache drives or directories delimited by ";" MINIO_CACHE_EXCLUDE: List of cache exclusion patterns delimited by ";" MINIO_CACHE_EXPIRY: Cache expiry duration in days ... ... - 7. Start minio server with edge caching enabled on '/drive1', '/drive2' and '/drive3', + 7. Start minio server with edge caching enabled on '/mnt/drive1', '/mnt/drive2' and '/mnt/drive3', exclude all objects under 'mybucket', exclude all objects with '.pdf' as extension with expiry upto 40 days. - $ export MINIO_CACHE_DRIVES="/drive1;/drive2;/drive3" + $ export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3" $ export MINIO_CACHE_EXCLUDE="mybucket/*;*.pdf" $ export MINIO_CACHE_EXPIRY=40 $ minio server /home/shared @@ -26,7 +26,7 @@ minio server -h ## Assumptions - Disk cache size defaults to 80% of your drive capacity. -- Disk caching requires [`atime`](http://kerolasa.github.io/filetimes.html) support to be enabled on the cache drive. +- The cache drives are required to be a filesystem mount point with [`atime`](http://kerolasa.github.io/filetimes.html) support to be enabled on the drive. Alternatively writable directories with atime support can be specified in MINIO_CACHE_DRIVES - Expiration of each cached entry takes user provided expiry as a hint, and defaults to 90 days if not provided. - Garbage collection sweep of the expired cache entries happens whenever cache usage is > 80% of drive capacity, GC continues until sufficient disk space is reclaimed. - An object is only cached when drive has sufficient disk space, upto 100 times the size of the object. @@ -42,6 +42,9 @@ Disk caching caches objects for both **uploaded** and **downloaded** objects i.e > NOTE: Expiration happens automatically based on the configured interval as explained above, frequently accessed objects stay alive in cache for a significantly longer time. +### Crash Recovery +Upon restart of minio server after a running minio process is killed or crashes, disk caching resumes automatically. The garbage collection cycle resumes and any previously cached entries are served from cache. + ## Limits - Bucket policies are not cached, so anonymous operations are not supported when backend is offline. - Objects are distributed using deterministic hashing among the list of configured cache drives. If one or more drives go offline, or cache drive configuration is altered in any way, performance may degrade to a linear lookup time depending on the number of disks in cache. diff --git a/docs/disk-caching/README.md b/docs/disk-caching/README.md index 8cddd039c..a7a287ba2 100644 --- a/docs/disk-caching/README.md +++ b/docs/disk-caching/README.md @@ -11,20 +11,20 @@ Disk caching feature here refers to the use of caching disks to store content cl Install Minio - [Minio Quickstart Guide](https://docs.minio.io/docs/minio). ### 2. Run Minio with cache -Disk caching can be enabled by updating the `cache` config settings for Minio server. Config `cache` settings takes the drive locations, cache expiry duration (in days) and any wildcard patterns to exclude from being cached. +Disk caching can be enabled by updating the `cache` config settings for Minio server. Config `cache` settings takes the mounted drive(s) or directory paths, cache expiry duration (in days) and any wildcard patterns to exclude from being cached. ```json "cache": { - "drives": ["/drive1", "/drive2", "/drive3"], + "drives": ["/mnt/drive1", "/mnt/drive2", "/mnt/drive3"], "expiry": 90, "exclude": ["*.pdf","mybucket/*"] }, ``` -The cache settings may also be set through environment variables. When set, environment variables override any `cache` config settings for Minio server. Following example uses `/drive1`, `/drive2` and `/drive3` for caching, with expiry upto 90 days while excluding all objects under bucket `mybucket` and all objects with '.pdf' as extension while starting a standalone erasure coded setup. +The cache settings may also be set through environment variables. When set, environment variables override any `cache` config settings for Minio server. Following example uses `/mnt/drive1`, `/mnt/drive2` and `/mnt/drive3` for caching, with expiry upto 90 days while excluding all objects under bucket `mybucket` and all objects with '.pdf' as extension while starting a standalone erasure coded setup. ```bash -export MINIO_CACHE_DRIVES="/drive1;/drive2;/drive3" +export MINIO_CACHE_DRIVES="/mnt/drive1;/mnt/drive2;/mnt/drive3" export MINIO_CACHE_EXPIRY=90 export MINIO_CACHE_EXCLUDE="*.pdf;mybucket/*" minio server /export{1...24} @@ -34,6 +34,7 @@ minio server /export{1...24} To test this setup, access the Minio server via browser or [`mc`](https://docs.minio.io/docs/minio-client-quickstart-guide). You’ll see the uploaded files are accessible from the all the Minio endpoints. # Explore Further +- [Disk cache design](https://github.com/minio/minio/blob/master/docs/disk-caching/DESIGN.md) - [Use `mc` with Minio Server](https://docs.minio.io/docs/minio-client-quickstart-guide) - [Use `aws-cli` with Minio Server](https://docs.minio.io/docs/aws-cli-with-minio) - [Use `s3cmd` with Minio Server](https://docs.minio.io/docs/s3cmd-with-minio)