Measure and Warm the Linux File Cache with vmtouch

You will finish with a repeatable way to see how much of a file is resident in Linux's filesystem cache, read selected pages into that cache, and limit a crawl before it reaches the wrong data. The examples use vmtouch 1.3.1 from Debian package version 1.3.1-2 installed on this machine.

Allow about 15 minutes. You need a shell and a file or directory that you are allowed to inspect. The basic checks do not need elevated privileges. Cache state is temporary: warming a file does not write it, make it durable, or guarantee that the kernel will keep it resident.

1. Check the current cache residency

Start with one known file. The command opens the file read-only, maps it, and reports how many pages are resident. With no option, it does not read every page.

$ vmtouch /srv/example/data.db
           Files: 1
     Directories: 0
  Resident Pages: 512/4096  2M/16M  12.5%
         Elapsed: 0.0012 seconds

The exact counts and elapsed time depend on the file and the machine. In the summary, the first resident-page number is the useful cache count, the second is the total mapped-page count, and the sizes provide the same information in bytes. A directory is crawled recursively, so a broad path can inspect much more data than one file.

2. Warm pages into the cache

Use -t when you deliberately want vmtouch to read one byte from each page and fault non-resident pages into the filesystem cache:

$ vmtouch -t /srv/example/data.db
           Files: 1
     Directories: 0
   Touched Pages: 4096 (16M)
         Elapsed: 0.018 seconds

This changes cache state, not file contents. It can cause real disk I/O and consume memory that other workloads could use. The command guarantees that each page was brought into memory while it touched it, but a page can be evicted before the command exits. Use this on data you own and during a controlled test or maintenance window when the I/O matters.

Verify the result with a normal residency check:

$ vmtouch /srv/example/data.db
           Files: 1
     Directories: 0
  Resident Pages: 4096/4096  16M/16M  100%

The result can be lower than 100 percent on a busy host. That is expected and does not mean the touch command changed the file incorrectly.

3. Limit the amount and portion of data

Large files are skipped when they exceed the default maximum map size of 500M. Set a smaller or larger limit with -m, using values such as 4096, 4k, 100M or 1.5G:

$ vmtouch -v -m 100M /srv/example
/srv/example/index.db
[O] 1/1

           Files: 1
     Directories: 1
  Resident Pages: 1/1  4K/4K  100%

The verbose listing and final totals are illustrative: your paths and counts will differ. Skipped files are an easy source of confusion, so check the output before assuming that a directory was fully inspected.

To map only a portion of a file, use -p. A single size means the first part; a range gives a start and end; an omitted end means the rest of the file:

$ vmtouch -t -p 100M-200M /srv/example/archive.bin
           Files: 1
     Directories: 0
   Touched Pages: 25600 (100M)
         Elapsed: 0.11 seconds

Page boundaries and the file's actual length affect the final count. Check with vmtouch -v -p 100M-200M ... when the selected range matters.

4. Make a directory crawl predictable

Shell wildcards in an ignore or include pattern must be quoted, otherwise the shell may expand them before vmtouch sees them. This example ignores version-control metadata and backup files:

$ vmtouch -v -i .git -i '*.bak' /srv/example

-i stops the crawl at matching directories and ignores matching files. Use -I when you want to process only matching filenames, for example vmtouch -I '*.sqlite' /srv/example. These filters match names during the crawl, so inspect verbose output before using -t on an unfamiliar tree.

Symbolic links are not followed by default. Add -f only when that is intentional. If a directory contains mounted filesystems, -F prevents vmtouch from recursing into those separate filesystems. Both options are useful boundaries for a path such as /var, where an apparently small command can otherwise cross into unrelated data.

5. Use a file list for controlled batches

For a list produced by another command, use batch mode. Newline-delimited input is the default:

$ find /srv/example -type f -name '*.db' | vmtouch -v -b -

The hyphen tells -b to read the list from standard input. If filenames can contain newlines, produce NUL-delimited input and add -0:

$ find /srv/example -type f -print0 | vmtouch -v -0 -b -

Review the producer command independently. vmtouch will crawl every path it receives, so an overly broad find expression can turn a harmless diagnostic into a large I/O operation when combined with -t.

6. Evict or lock only with a clear operational reason

-e asks Linux to evict the mapped pages from the filesystem cache. It is useful for a controlled cold-cache test, but it can make the next access slower and may affect other users of the same files. Pages can also return before vmtouch exits. Treat it as a service-impacting test, not as routine housekeeping:

$ vmtouch -e /srv/example/data.db
           Files: 1
     Directories: 0
    Evicted Pages: 4096 (16M)
         Elapsed: 0.002 seconds

Linux supports this operation through posix_fadvise, but eviction is less portable across Unix systems. Do not use it on production data just to make a percentage look smaller.

-l and -L lock pages in physical memory and keep the vmtouch process running. They retain file descriptors and consume locked memory. Root privileges may be required to exceed the process limits for file descriptors or locked memory.

These modes can starve a host if used carelessly. Stop a foreground lock with Ctrl-C; a daemon started with -d must be stopped through its process, and a PID file can be requested with -P. Do not use locking as a substitute for capacity planning.

7. Avoid the common interpretation traps

Use -q only when silence is useful. It suppresses the normal summary and warnings, leaving only a fatal error on standard error. For troubleshooting, prefer the default output or -v. Use -h if hard-linked names should be counted separately; otherwise vmtouch avoids double-counting files that point to the same inode.

There is no undo command for a warm cache: normal memory pressure will reclaim pages, and a reboot clears the cache. There is also no durable state file for a residency check. If you need a repeatable test, record the command, the input paths, the file sizes and the host load, then run the same command again rather than relying on a previous percentage.