{
    "content": [
        {
            "type": "text",
            "text": "# lvmcache (man)\n\n## NAME\n\nlvmcache — LVM caching\n\n## DESCRIPTION\n\nlvm(8) includes two kinds of caching that can be used to improve the performance of a Logical\nVolume (LV). When caching, varying subsets of an  LV's  data  are  temporarily  stored  on  a\nsmaller, faster device (e.g. an SSD) to improve the performance of the LV.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **USAGE** (7 subsections)\n- **OPTIONS** (15 subsections)\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "lvmcache",
        "section": "",
        "mode": "man",
        "summary": "lvmcache — LVM caching",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [
            {
                "name": "lvm.conf",
                "section": "5",
                "url": "https://www.chedong.com/phpMan.php/man/lvm.conf/5/json"
            },
            {
                "name": "lvchange",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvchange/8/json"
            },
            {
                "name": "lvcreate",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvcreate/8/json"
            },
            {
                "name": "lvdisplay",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvdisplay/8/json"
            },
            {
                "name": "lvextend",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvextend/8/json"
            },
            {
                "name": "lvremove",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvremove/8/json"
            },
            {
                "name": "lvrename",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvrename/8/json"
            },
            {
                "name": "lvresize",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvresize/8/json"
            },
            {
                "name": "lvs",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/lvs/8/json"
            },
            {
                "name": "vgchange",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/vgchange/8/json"
            },
            {
                "name": "vgmerge",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/vgmerge/8/json"
            },
            {
                "name": "vgreduce",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/vgreduce/8/json"
            },
            {
                "name": "vgsplit",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/vgsplit/8/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 25,
                "subsections": []
            },
            {
                "name": "USAGE",
                "lines": 1,
                "subsections": [
                    {
                        "name": "1. Identify main LV that needs caching",
                        "lines": 5
                    },
                    {
                        "name": "2. Identify fast LV to use as the cache",
                        "lines": 10
                    },
                    {
                        "name": "3. Start caching the main LV",
                        "lines": 15
                    },
                    {
                        "name": "4. Display LVs",
                        "lines": 31
                    },
                    {
                        "name": "5. Use the main LV",
                        "lines": 2
                    },
                    {
                        "name": "6. Stop caching",
                        "lines": 21
                    },
                    {
                        "name": "Create a new LV with caching.",
                        "lines": 13
                    }
                ]
            },
            {
                "name": "OPTIONS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "option args",
                        "lines": 28
                    },
                    {
                        "name": "dm-cache block size",
                        "lines": 11
                    },
                    {
                        "name": "dm-writecache block size",
                        "lines": 20
                    },
                    {
                        "name": "dm-writecache settings",
                        "lines": 59
                    },
                    {
                        "name": "dm-cache with separate data and metadata LVs",
                        "lines": 24
                    },
                    {
                        "name": "dm-cache cache modes",
                        "lines": 21
                    },
                    {
                        "name": "dm-cache chunk size",
                        "lines": 14
                    },
                    {
                        "name": "lvs -o+chunksize VG/LV",
                        "lines": 11
                    },
                    {
                        "name": "dm-cache migration threshold",
                        "lines": 14
                    },
                    {
                        "name": "lvs -o+chunksize VG/LV",
                        "lines": 1
                    },
                    {
                        "name": "dm-cache cache policy",
                        "lines": 28
                    },
                    {
                        "name": "dm-cache spare metadata LV",
                        "lines": 4
                    },
                    {
                        "name": "dm-cache metadata formats",
                        "lines": 7
                    },
                    {
                        "name": "RAID1 cache device",
                        "lines": 9
                    },
                    {
                        "name": "dm-cache command shortcut",
                        "lines": 20
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "lvmcache — LVM caching\n\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "lvm(8) includes two kinds of caching that can be used to improve the performance of a Logical\nVolume (LV). When caching, varying subsets of an  LV's  data  are  temporarily  stored  on  a\nsmaller, faster device (e.g. an SSD) to improve the performance of the LV.\n\nTo  do  this with lvm, a new special LV is first created from the faster device. This LV will\nhold the cache. Then, the new fast LV is attached to the main LV by way of an lvconvert  com‐\nmand. lvconvert inserts one of the device mapper caching targets into the main LV's i/o path.\nThe device mapper target combines the main LV and fast LV into a  hybrid  device  that  looks\nlike  the  main  LV, but has better performance. While the main LV is being used, portions of\nits data will be temporarily and transparently stored on the special fast LV.\n\nThe two kinds of caching are:\n\n\n• A read and write hot-spot cache, using the dm-cache kernel module.  This cache  tracks  ac‐\ncess  patterns and adjusts its content deliberately so that commonly used parts of the main\nLV are likely to be found on the fast storage. LVM refers to this using the LV type cache.\n\n\n• A write cache, using the dm-writecache kernel module.  This cache can be used with  SSD  or\nPMEM  devices  to  speed  up  all  writes to the main LV. Data read from the main LV is not\nstored in the cache, only newly written data.  LVM refers to this using the LV type  write‐‐\ncache.\n\n",
                "subsections": []
            },
            "USAGE": {
                "content": "",
                "subsections": [
                    {
                        "name": "1. Identify main LV that needs caching",
                        "content": "The  main LV may already exist, and is located on larger, slower devices.  A main LV would be\ncreated with a command like:\n\n$ lvcreate -n main -L Size vg /dev/slowhhd\n"
                    },
                    {
                        "name": "2. Identify fast LV to use as the cache",
                        "content": "A fast LV is created using one or more fast devices, like an SSD.  This special  LV  will  be\nused to hold the cache:\n\n$ lvcreate -n fast -L Size vg /dev/fastssd\n\n$ lvs -a\nLV   Attr       Type   Devices\nfast -wi------- linear /dev/fastssd\nmain -wi------- linear /dev/slowhhd\n"
                    },
                    {
                        "name": "3. Start caching the main LV",
                        "content": "To  start  caching  the main LV, convert the main LV to the desired caching type, and specify\nthe fast LV to use as the cache:\n\nusing dm-cache:\n\n$ lvconvert --type cache --cachevol fast vg/main\n\nusing dm-writecache:\n\n$ lvconvert --type writecache --cachevol fast vg/main\n\nusing dm-cache (with cachepool):\n\n$ lvconvert --type cache --cachepool fast vg/main\n"
                    },
                    {
                        "name": "4. Display LVs",
                        "content": "Once the fast LV has been attached to the main LV, lvm reports the main  LV  type  as  either\ncache  or  writecache depending on the type used.  While attached, the fast LV is hidden, and\nrenamed with a cvol or cpool suffix.  It is displayed by lvs -a.  The corig or wcorig  LV\nrepresents the original LV without the cache.\n\nusing dm-cache:\n\n$ lvs -a\nLV           Pool        Type   Devices\nmain         [fastcvol] cache  maincorig(0)\n[fastcvol]              linear /dev/fastssd\n[maincorig]             linear /dev/slowhhd\n\nusing dm-writecache:\n\n$ lvs -a\nLV            Pool        Type       Devices\nmain          [fastcvol] writecache mainwcorig(0)\n[fastcvol]               linear     /dev/fastssd\n[mainwcorig]             linear     /dev/slowhhd\n\nusing dm-cache (with cachepool):\n\n$ lvs -a\nLV                 Pool         Type       Devices\nmain               [fastcpool] cache      maincorig(0)\n[fastcpool]                    cache-pool fastpoolcdata(0)\n[fastcpoolcdata]              linear     /dev/fastssd\n[fastcpoolcmeta]              linear     /dev/fastssd\n[maincorig]                    linear     /dev/slowhhd\n"
                    },
                    {
                        "name": "5. Use the main LV",
                        "content": "Use the LV until the cache is no longer wanted, or needs to be changed.\n"
                    },
                    {
                        "name": "6. Stop caching",
                        "content": "To stop caching the main LV, separate the fast LV from the main LV.  This changes the type of\nthe main LV back to what it was before the cache was attached.\n\n$ lvconvert --splitcache vg/main\n\n$ lvs -a\nLV   VG Attr       Type   Devices\nfast vg -wi------- linear /dev/fastssd\nmain vg -wi------- linear /dev/slowhhd\n\nTo stop caching the main LV and also remove unneeded cache pool,\nuse the --uncache:\n\n$ lvconvert --uncache vg/main\n\n$ lvs -a\nLV   VG Attr       Type   Devices\nmain vg -wi------- linear /dev/slowhhd\n\n\n"
                    },
                    {
                        "name": "Create a new LV with caching.",
                        "content": "A new LV can be created with caching attached at the time of  creation  using  the  following\ncommand:\n\n$ lvcreate --type cache|writecache -n Name -L Size\n--cachedevice /dev/fastssd vg /dev/slowhhd\n\nThe  main LV is created with the specified Name and Size from the slowhhd.  A hidden fast LV\nis created on the fastssd and is then attached to the new main LV.  If the fastssd  is  un‐\nused,  the  entire  disk  will  be used as the cache unless the --cachesize option is used to\nspecify a size for the fast LV.  The --cachedevice option can be  repeated  to  use  multiple\ndisks for the fast LV.\n\n"
                    }
                ]
            },
            "OPTIONS": {
                "content": "",
                "subsections": [
                    {
                        "name": "option args",
                        "content": "--cachevol LV\n\nPass  this  option  a  fast LV that should be used to hold the cache.  With a cachevol, cache\ndata and metadata are stored in different parts of the same fast LV.  This option can be used\nwith dm-writecache or dm-cache.\n\n--cachepool CachePoolLV|LV\n\nPass  this option a cachepool LV or a standard LV.  When using a cache pool, lvm places cache\ndata and cache metadata on different LVs.  The two LVs together  are  called  a  cache  pool.\nThis  has  a  bit  better performance for dm-cache and permits specific placement and segment\ntype selection for data and metadata volumes.  A cache pool is represented as a special  type\nof  LV  that  cannot be used directly.  If a standard LV is passed with this option, lvm will\nfirst convert it to a cache pool by combining it with another LV to use for  metadata.   This\noption can be used with dm-cache.\n\n--cachedevice PV\n\nThis  option  can be used in place of --cachevol, in which case a cachevol LV will be created\nusing the specified device.  This option can be repeated to create a cachevol using  multiple\ndevices,  or a tag name can be specified in which case the cachevol will be created using any\nof the devices with the given tag.  If a named cache device is unused, the entire device will\nbe  used  to create the cachevol.  To create a cachevol of a specific size from the cache de‐\nvices, include the --cachesize option.\n\n\n\n"
                    },
                    {
                        "name": "dm-cache block size",
                        "content": "A cache pool will have a logical block size of 4096 bytes if it is created on a device with a\nlogical block size of 4096 bytes.\n\nIf  a  main LV has logical block size 512 (with an existing xfs file system using that size),\nthen it cannot use a cache pool with a 4096 logical block size.  If the  cache  pool  is  at‐\ntached, the main LV will likely fail to mount.\n\nTo avoid this problem, use a mkfs option to specify a 4096 block size for the file system, or\nattach the cache pool before running mkfs.\n\n"
                    },
                    {
                        "name": "dm-writecache block size",
                        "content": "The dm-writecache block size can be 4096 bytes (the default), or 512 bytes.  The default 4096\nhas  better  performance  and  should be used except when 512 is necessary for compatibility.\nThe dm-writecache block size  is  specified  with  --cachesettings  blocksize=4096|512  when\ncaching is started.\n\nWhen a file system like xfs already exists on the main LV prior to caching, and the file sys‐\ntem is using a block size of 512, then the writecache block size should be set to 512.   (The\nfile system will likely fail to mount if writecache block size of 4096 is used in this case.)\n\nCheck the xfs sector size while the fs is mounted:\n\n$ xfsinfo /dev/vg/main\nLook for sectsz=512 or sectsz=4096\n\nThe writecache block size should be chosen to match the xfs sectsz value.\n\nIt  is also possible to specify a sector size of 4096 to mkfs.xfs when creating the file sys‐\ntem.  In this case the writecache block size of 4096 can be used.\n\n"
                    },
                    {
                        "name": "dm-writecache settings",
                        "content": "Tunable parameters can be passed to the dm-writecache kernel module using the --cachesettings\noption when caching is started, e.g.\n\n$ lvconvert --type writecache --cachevol fast \\\n--cachesettings 'highwatermark=N writebackjobs=N' vg/main\n\nTunable options are:\n\n\n• highwatermark = <percent>\n\nStart writeback when the writecache usage reaches this percent (0-100).\n\n\n• lowwatermark = <percent>\n\nStop writeback when the writecache usage reaches this percent (0-100).\n\n\n• writebackjobs = <count>\n\nLimit the number of blocks that are in flight during writeback.  Setting this value reduces\nwriteback throughput, but it may improve latency of read requests.\n\n\n• autocommitblocks = <count>\n\nWhen the application writes this amount of blocks without issuing the  FLUSH  request,  the\nblocks are automatically commited.\n\n\n• autocommittime = <milliseconds>\n\nThe data is automatically commited if this time passes and no FLUSH request is received.\n\n\n• fua = 0|1\n\nUse  the  FUA  flag when writing data from persistent memory back to the underlying device.\nApplicable only to persistent memory.\n\n\n• nofua = 0|1\n\nDon't use the FUA flag when writing back data and send the FLUSH request afterwards.   Some\nunderlying  devices  perform better with fua, some with nofua.  Testing is necessary to de‐\ntermine which.  Applicable only to persistent memory.\n\n\n• cleaner = 0|1\n\nSetting cleaner=1 enables the writecache cleaner mode in which data  is  gradually  flushed\nfrom  the  cache.   If  this is done prior to detaching the writecache, then the splitcache\ncommand will have little or no flushing to perform.  If not done beforehand, the splitcache\ncommand  enables  the  cleaner mode and waits for flushing to complete before detaching the\nwritecache.  Adding cleaner=0 to the splitcache command will skip the cleaner mode, and any\nrequired flushing is performed in device suspend.\n\n"
                    },
                    {
                        "name": "dm-cache with separate data and metadata LVs",
                        "content": "When  using dm-cache, the cache metadata and cache data can be stored on separate LVs.  To do\nthis, a \"cache pool\" is created, which is a special LV that references two sub LVs,  one  for\ndata and one for metadata.\n\nTo create a cache pool from two separate LVs:\n\n$ lvcreate -n fast -L DataSize vg /dev/fastssd1\n$ lvcreate -n fastmeta -L MetadataSize vg /dev/fastssd2\n$ lvconvert --type cache-pool --poolmetadata fastmeta vg/fast\n\nThen use the cache pool LV to start caching the main LV:\n\n$ lvconvert --type cache --cachepool fast vg/main\n\nA variation of the same procedure automatically creates a cache pool when caching is started.\nTo do this, use a standard LV as the --cachepool (this will hold cache data), and use another\nstandard  LV  as the --poolmetadata (this will hold cache metadata).  LVM will create a cache\npool LV from the two specified LVs, and use the cache pool to start caching the main LV.\n\n$ lvcreate -n fast -L DataSize vg /dev/fastssd1\n$ lvcreate -n fastmeta -L MetadataSize vg /dev/fastssd2\n$ lvconvert --type cache --cachepool fast --poolmetadata fastmeta vg/main\n\n"
                    },
                    {
                        "name": "dm-cache cache modes",
                        "content": "The default dm-cache cache mode is \"writethrough\".  Writethrough ensures that any data  writ‐\nten  will  be stored both in the cache and on the origin LV.  The loss of a device associated\nwith the cache in this case would not mean the loss of any data.\n\nA second cache mode is \"writeback\".  Writeback delays writing data blocks from the cache back\nto  the  origin  LV.  This mode will increase performance, but the loss of a cache device can\nresult in lost data.\n\nWith the --cachemode option, the cache mode can be set when caching is started, or changed on\nan  LV  that  is already cached.  The current cache mode can be displayed with the cachemode\nreporting option:\n\nlvs -o+cachemode VG/LV\n\nlvm.conf(5) allocation/cachemode\ndefines the default cache mode.\n\n$ lvconvert --type cache --cachevol fast \\\n--cachemode writethrough vg/main\n\n"
                    },
                    {
                        "name": "dm-cache chunk size",
                        "content": "The size of data blocks managed by dm-cache can be specified with the --chunksize option when\ncaching  is started.  The default unit is KiB.  The value must be a multiple of 32KiB between\n32KiB and 1GiB. Cache chunks bigger then 512KiB shall be only used when necessary.\n\nUsing a chunk size that is too large can result in wasteful use of the cache, in which  small\nreads and writes cause large sections of an LV to be stored in the cache. It can also require\nincreasing migration threshold which defaults to 2048 sectors (1 MiB). Lvm2 ensures migration\nthreshold  is at least 8 chunks in size. This may in some cases result in very high bandwidth\nload of transfering data between the cache LV and its cache origin LV.  However,  choosing  a\nchunk size that is too small can result in more overhead trying to manage the numerous chunks\nthat become mapped into the cache.  Overhead can include both excessive  CPU  time  searching\nfor chunks, and excessive memory tracking chunks.\n\nCommand to display the chunk size:"
                    },
                    {
                        "name": "lvs -o+chunksize VG/LV",
                        "content": "lvm.conf(5) cachepoolchunksize\ncontrols the default chunk size.\n\nThe default value is shown by:\nlvmconfig --type default allocation/cachepoolchunksize\n\nChecking migration threshold (in sectors) of running cached LV:\nlvs -o+kernelcachesettings VG/LV\n\n\n"
                    },
                    {
                        "name": "dm-cache migration threshold",
                        "content": "Migrating  data  between the origin and cache LV uses bandwidth.  The user can set a throttle\nto prevent more than a certain amount of migration occurring at any one time.  Currently  dm-\ncache is not taking any account of normal io traffic going to the devices.\n\nUser  can  set  migration  threshold via cache policy settings as \"migrationthreshold=<#sec‐\ntors>\" to set the maximum number of sectors being migrated, the default  being  2048  sectors\n(1MiB).\n\nCommand to set migration threshold to 2MiB (4096 sectors):\nlvcreate --cachepolicy 'migrationthreshold=4096' VG/LV\n\n\nCommand to display the migration threshold:\nlvs -o+kernelcachesettings,cachesettings VG/LV"
                    },
                    {
                        "name": "lvs -o+chunksize VG/LV",
                        "content": ""
                    },
                    {
                        "name": "dm-cache cache policy",
                        "content": "The  dm-cache subsystem has additional per-LV parameters: the cache policy to use, and possi‐\nbly tunable parameters for the cache policy.  Three policies are currently  available:  \"smq\"\nis  the  default  policy, \"mq\" is an older implementation, and \"cleaner\" is used to force the\ncache to write back (flush) all cached writes to the origin LV.\n\nThe older \"mq\" policy has a number of tunable parameters. The defaults are chosen to be suit‐\nable for the majority of systems, but in special circumstances, changing the settings can im‐\nprove performance.\n\nWith the --cachepolicy and --cachesettings options, the cache policy and settings can be  set\nwhen  caching  is  started, or changed on an existing cached LV (both options can be used to‐\ngether).  The current cache policy and settings can be displayed with  the  cachepolicy  and\ncachesettings reporting options:\n\nlvs -o+cachepolicy,cachesettings VG/LV\n\nChange the cache policy and settings of an existing LV.\n\n$ lvchange --cachepolicy mq --cachesettings \\\n'migrationthreshold=2048 randomthreshold=4' vg/main\n\nlvm.conf(5) allocation/cachepolicy\ndefines the default cache policy.\n\nlvm.conf(5) allocation/cachesettings\ndefines the default cache settings.\n\n"
                    },
                    {
                        "name": "dm-cache spare metadata LV",
                        "content": "See  lvmthin(7)  for a description of the \"pool metadata spare\" LV.  The same concept is used\nfor cache pools.\n\n"
                    },
                    {
                        "name": "dm-cache metadata formats",
                        "content": "There are two disk formats for dm-cache metadata.  The metadata format can be specified  with\n--cachemetadataformat  when  caching  is started, and cannot be changed.  Format 2 has better\nperformance; it is more compact, and stores dirty bits in a separate  btree,  which  improves\nthe speed of shutting down the cache.  With auto, lvm selects the best option provided by the\ncurrent dm-cache kernel module.\n\n"
                    },
                    {
                        "name": "RAID1 cache device",
                        "content": "RAID1 can be used to create the fast LV holding the cache so that it can  tolerate  a  device\nfailure.   (When  using dm-cache with separate data and metadata LVs, each of the sub-LVs can\nuse RAID1.)\n\n$ lvcreate -n main -L Size vg /dev/slow\n$ lvcreate --type raid1 -m 1 -n fast -L Size vg /dev/ssd1 /dev/ssd2\n$ lvconvert --type cache --cachevol fast vg/main\n\n"
                    },
                    {
                        "name": "dm-cache command shortcut",
                        "content": "A single command can be used to create a cache pool and attach that new cache pool to a  main\nLV:\n\n$ lvcreate --type cache --name Name --size Size VG/LV [PV]\n\nIn  this command, the specified LV already exists, and is the main LV to be cached.  The com‐\nmand creates a new cache pool with the given name and size, using the optionally specified PV\n(typically  an  ssd).   Then  it attaches the new cache pool to the existing main LV to begin\ncaching.\n\n(Note: ensure that the specified main LV is a standard LV.  If a cache pool LV is  mistakenly\nspecified, then the command does something different.)\n\n(Note:  the  type  option  is interpreted differently by this command than by normal lvcreate\ncommands in which --type specifies the type of the newly created LV.  In  this  case,  an  LV\nwith  type  cache-pool  is being created, and the existing main LV is being converted to type\ncache.)\n\n\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "lvm.conf(5), lvchange(8), lvcreate(8), lvdisplay(8), lvextend(8),  lvremove(8),  lvrename(8),\nlvresize(8), lvs(8), vgchange(8), vgmerge(8), vgreduce(8), vgsplit(8)\n\n\n\nRed Hat, Inc                      LVM TOOLS 2.03.11(2) (2021-01-08)                      LVMCACHE(7)",
                "subsections": []
            }
        }
    }
}