dm-cache - cache target for device-mapper
==============================

dm-cache version 0.1 by
  Ming Zhao, dm-cache@googlegroups.com



Contents
===========
* Introduction
* Requirements
* Installation
* Setup
* Further information



Introduction
==============

  Dm-cache is a generic block-level disk cache for storage networking. It is
  built upon the Linux device-mapper, a generic block device virtualization
  infrastructure. It can be transparently plugged into a client of any storage
  system, including SAN, iSCSI and AoE, and supports dynamic customization for
  policy-guided optimizations.



Requirements
===============

  Dm-cache relies on the device-mapper kernel module (dm_mod.ko), which is
  available in the recent kernel versions. For older kernels, please refer to
  http://sources.redhat.com/dm/patches.html for device-mapper patches.

  In addition to dm-cache, device mapper also has other targets, including the
  popular Logical Volume Manager (LVM), but those are not necessary for the use
  of dm-cache.

  To set up dm-cache, you also need the device-mapper userspace library, which
  is available in your Linux distribution. For debian family, it is the dmsetup
  package; for Fedora Core and SUSE, it is the device-mapper package.



Installation
==============

* Download dm-cache:
  The latest dm-cache kernel patch can be found at: 
  http://github.com/mingzhao/dm-cache
  git://github.com/mingzhao/dm-cache.git

* Patch your kernel:
  Enter your kernel source's directory, and run:

  patch -p1 < path_to_the_patch

* Reconfigure kernel:
  Enable CONFIG_DM, and CONFIG_DM_CACHE.
  If you use GUI to configure kernel, enable "Device mapper support" and
  "Cache target support", under "Device Drivers->Multipe-device support (RAID
  and LVM)".

* Rebuild your kernel modules:

	make modules_install



Setup
========

* Load dm_mod and dm_cache modules:

  modprobe dm_mod
  modprobe dm_cache


* Use dmsetup to create a cache:

  Suppose the data you want to use is stored on /dev/sdc, e.g. a disk remotely 
  attached via iSCSI, and the local disk you want to use for caching the data 
  is /dev/sdb. Then issue a command in the following format to create a cache:

  echo 0 131072 cache /dev/sdc /dev/sdb 0 8 65536 256 1 | dmsetup create foo

  The first and second arguments after the "echo" command are the starting and 
  ending offsets of your source device (/dev/sdc). The third argument is always
  "cache", which is the name of the dm-cache target. The fourth and fifth 
  arguments are the paths to your source and cache device, respectively. The 
  rest of the arguments are the parameters for configuring your cache. If you do
  not specify these parameters, the default ones will be used.

  The first one is a flag to tell dm-cache whether to load cache metadata from
  the cache device. If it is set, the previously used cache configuration as
  well as the existing cached data are reused. Therefore you do not need to
  specify other parameters. Otherwise, a new cache is started from scratch.

  The second and third parameters specify the block size used by the cache (in
  number of sectors), and the capacity of the cache (in number of blocks). The
  fourth parameter specifies the cache associativity.

  The fifth parameter tells dm-cache whether to enable write back. If it is set,
  then writes are buffered in cache first, and committed to the source device
  later (before the cache is removed). Therefore, the performance of write
  operations can be improved. But it is not recommended if your cache device is
  not stable, which may cause data loss if it crashes.

  If the command succeeds, a virtual device with the given name ("foo") is
  created under /dev/mapper. You can mount it as a regular device, and it
  automatically caches the data blocks accessed from the source device.

  If it fails, please check /var/log/kern.log for detailed error information.

  Tip: You can find out your device's (e.g., /dev/sdc) using the following
  command: blockdev --getsize /dev/sdc

* Use a dmc-setup.pl to create a cache:

  Dmc-setup.pl is a helper program for managing disk caches. Your can perldoc
  for its help information: perldoc dmc-setup.pl


* Remove a cache:

  Assuming your cache is named "foo", run commands:

  umount /dev/mapper/foo
  dmsetup remove acache


Further information
=====================

  Dm-cache's discussion group: http://groups.google.com/group/dm-cache
  Dm-cache at github: http://github.com/mingzhao/dm-cache
  Device-mapper Resource Page: http://sources.redhat.com/dm