======================================
iostash - Flash cache driver for Linux
======================================

iostash version 0.1 by
	Nikolas Ioannou,   nio@zurich.ibm.com, http://researcher.ibm.com/researcher/view.php?person=zurich-nio
	Ioannis Koltsidas, iko@zurich.ibm.com, http://researcher.ibm.com/researcher/view.php?person=zurich-iko


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

A generic read-only block-level disk cache solution optimized for
Flash storage. It can transparently cache from any block device target
(typically HDD) to another block device that is used as a cache
(typically SSD). It dynamically hooks/unhooks into the target block
device, even if it is already mounted, and thus enables seamless
application acceleration. Also, it supports caching from one or more
targets to one or more cache devices (e.g., 3 HDDs caching to 1SSD). It
supports asynchronous write-through.

Details on the architecture of iostash can be found in the research
papers listed in the References section.


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

iostash is a Linux kernel module that depends on the device-mapper
Linux kernel framework (most mainstream Linux distros use a kernel
build that include this feature).

It should build for kernel version 2.6.28 and onwards, and has been
tested on RHEL6.4 (2.6.32-504.23.4.el6.x86_64) and Ubuntu 14.04.3 LTS
(3.16.0-46-generic).

Building requires having the kernel targets and the necessary
compilation tools:
CentOS/RHEL: https://wiki.centos.org/HowTos/BuildingKernelModules
Ubuntu: https://help.ubuntu.com/community/Kernel/Compile


Installation
======================================
1. Download:
The latest version of iostash can be found at github:
https://github.com/ibm-research/iostash
git://github.com/ibm-research/iostash.git

2. Build:
Make sure you have the kernel target and compilation tools. For Ubuntu
14.04.3, for example, these can be installed using:
sudo apt-get build-dep linux-image-`uname -r`

Enter the iostash directory and run:
$ ./build.sh

This will generate a bundle in the package/ directory. To install,
extract the content of the package in a directory and run the
'install.sh' script:

$ tar xvfz iostash-<kernel-version>.tar.gz
$ cd iostash-<kernel-version>
$ sudo ./install.sh

In case iostash is already running, the new binary will only be used
by the system the next time the module is loaded. To install and load
the new binary, invoke the installation script with '--force':

$ sudo ./install.sh --force

NOTE: This will purge the content of the caches, but it should not be
disruptive to on-going I/O. After the installation completes, the
existing cache devices and target will be added anew.

All the above instructions will build and install a kernel module for the
currently loaded kernel on the build system. One can build for a
specific kernel version by setting the KERNEL_DIR to the path for the
desired kernel.

A user-interface script will also be installed under /usr/bin/iostash.


Usage
======================================

1. Add a target device to start caching from (say /dev/sda):
$ sudo iostash target add /dev/sda

2. Add a new device to the cache (say /dev/nvme0n1):
$ sudo iostash cache add /dev/nvme0n1

3. List all target devices that we are caching from:
$ sudo iostash target list

4. List all devices that we are caching on:
$ sudo iostash cache list

5. Stop caching from a target device (say /dev/sda):
$ sudo iostash target remove /dev/sda

6. Remove a device from the pool of cache devices (say /dev/nvme0n1):
$ sudo iostash cache remove /dev/nvme0n1

7. View statistics per target device
$ sudo iostash target stat /dev/sda

8. View global statistics:
$ sudo iostash global stats


References
======================================

Flash-Conscious Cache Population for Enterprise Database Workloads
Hyojun Kim, Ioannis Koltsidas, Nikolas Ioannou, Sangeetha Seshadri,
Paul Muech, Clement Dickey, and Lawrence Chiu
International Workshop on Accelerating Data Management Systems Using
Modern Processor and Storage Architectures (ADMS), 2014
http://www.adms-conf.org/2014/adms14_kim.pdf

How Could a Flash Cache Degrade Database Performance Rather Than
Improve It? Lessons to be Learnt from Multi-Tiered Storage
Hyojun Kim, Ioannis Koltsidas and Nikolas Ioannou, Sangeetha Seshadri,
Paul Muench, Clement L. Dickey, and Lawrence Chiu
Workshop on Interactions of NVM/Flash with Operating Systems and
Workloads (INFLOW), 2014
https://www.usenix.org/system/files/conference/inflow14/inflow14-kim.pdf