docs: convert docs to ReST and rename to *.rst

=============================

Guidance for writing policies

=============================

This policy is now an alias for smq (see below).

The following tunables are accepted, but have no effect:

The following tunables are accepted, but have no effect::

	'sequential_threshold <#nr_sequential_ios>'

	'random_threshold <#nr_random_ios>'

degrade slightly until smq recalculates the origin device's hotspots

that should be cached.

Memory usage:

Memory usage

^^^^^^^^^^^^

The mq policy used a lot of memory; 88 bytes per cache block on a 64

bit machine.

All this means smq uses ~25bytes per cache block.  Still a lot of

memory, but a substantial improvement nontheless.

Level balancing:

Level balancing

^^^^^^^^^^^^^^^

mq placed entries in different levels of the multiqueue structures

based on their hit count (~ln(hit count)).  This meant the bottom

levels generally had the most entries, and the top ones had very

performing badly then it starts moving entries more quickly between

levels.  This lets it adapt to new IO patterns very quickly.

Performance:

Performance

^^^^^^^^^^^

Testing smq shows substantially better performance than mq.

cleaner

Examples

========

The syntax for a table is:

The syntax for a table is::

	cache <metadata dev> <cache dev> <origin dev> <block size>

	<#feature_args> [<feature arg>]*

	<policy> <#policy_args> [<policy arg>]*

The syntax to send a message using the dmsetup command is:

The syntax to send a message using the dmsetup command is::

	dmsetup message <mapped device> 0 sequential_threshold 1024

	dmsetup message <mapped device> 0 random_threshold 8

Using dmsetup:

Using dmsetup::

	dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \

	    /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8"

	creates a 128GB large mapped device named 'blah' with the

=====

Cache

=====

Introduction

============

Glossary

========

  Migration -  Movement of the primary copy of a logical block from one

  Migration

	       Movement of the primary copy of a logical block from one

	       device to the other.

  Promotion -  Migration from slow device to fast device.

  Demotion  -  Migration from fast device to slow device.

  Promotion

	       Migration from slow device to fast device.

  Demotion

	       Migration from fast device to slow device.

The origin device always contains a copy of the logical block, which

may be out of date or kept in sync with the copy on the cache device

Constructor

-----------

  ::

   cache <metadata dev> <cache dev> <origin dev> <block size>

         <#feature args> [<feature arg>]*

         <policy> <#policy args> [policy args]*

 metadata dev    : fast device holding the persistent metadata

 cache dev	 : fast device holding cached data blocks

 origin dev	 : slow device holding original data blocks

 block size      : cache unit size in sectors

 ================ =======================================================

 metadata dev     fast device holding the persistent metadata

 cache dev	  fast device holding cached data blocks

 origin dev	  slow device holding original data blocks

 block size       cache unit size in sectors

 #feature args   : number of feature arguments passed

 feature args    : writethrough or passthrough (The default is writeback.)

 #feature args    number of feature arguments passed

 feature args     writethrough or passthrough (The default is writeback.)

 policy          : the replacement policy to use

 #policy args    : an even number of arguments corresponding to

 policy           the replacement policy to use

 #policy args     an even number of arguments corresponding to

                  key/value pairs passed to the policy

 policy args     : key/value pairs passed to the policy

 policy args      key/value pairs passed to the policy

		  E.g. 'sequential_threshold 1024'

		  See cache-policies.txt for details.

 ================ =======================================================

Optional feature arguments are:

   writethrough  : write through caching that prohibits cache block

   ==================== ========================================================

   writethrough		write through caching that prohibits cache block

			content from being different from origin block content.

			Without this argument, the default behaviour is to write

			back cache block contents later for performance reasons,

			so they may differ from the corresponding origin blocks.

   passthrough	 : a degraded mode useful for various cache coherency

   passthrough		a degraded mode useful for various cache coherency

			situations (e.g., rolling back snapshots of

			underlying storage).	 Reads and writes always go to

			the origin.	If a write goes to a cached origin

			block, then the cache block is invalidated.

			To enable passthrough mode the cache must be clean.

   metadata2	: use version 2 of the metadata.  This stores the dirty bits

                  in a separate btree, which improves speed of shutting

		  down the cache.

   metadata2		use version 2 of the metadata.  This stores the dirty

			bits in a separate btree, which improves speed of

			shutting down the cache.

   no_discard_passdown	: disable passing down discards from the cache

   no_discard_passdown	disable passing down discards from the cache

			to the origin's data device.

   ==================== ========================================================

A policy called 'default' is always registered.  This is an alias for

the policy we currently think is giving best all round performance.

Status

------

::

  <metadata block size> <#used metadata blocks>/<#total metadata blocks>

  <cache block size> <#used cache blocks>/<#total cache blocks>

  <#read hits> <#read misses> <#write hits> <#write misses>

  <#core args> <core args>* <policy name> <#policy args> <policy args>*

  <cache metadata mode>

metadata block size	 : Fixed block size for each metadata block in

========================= =====================================================

metadata block size	  Fixed block size for each metadata block in

			  sectors

#used metadata blocks	 : Number of metadata blocks used

#total metadata blocks	 : Total number of metadata blocks

cache block size	 : Configurable block size for the cache device

#used metadata blocks	  Number of metadata blocks used

#total metadata blocks	  Total number of metadata blocks

cache block size	  Configurable block size for the cache device

			  in sectors

#used cache blocks	 : Number of blocks resident in the cache

#total cache blocks	 : Total number of cache blocks

#read hits		 : Number of times a READ bio has been mapped

#used cache blocks	  Number of blocks resident in the cache

#total cache blocks	  Total number of cache blocks

#read hits		  Number of times a READ bio has been mapped

			  to the cache

#read misses		 : Number of times a READ bio has been mapped

#read misses		  Number of times a READ bio has been mapped

			  to the origin

#write hits		 : Number of times a WRITE bio has been mapped

#write hits		  Number of times a WRITE bio has been mapped

			  to the cache

#write misses		 : Number of times a WRITE bio has been

#write misses		  Number of times a WRITE bio has been

			  mapped to the origin

#demotions		 : Number of times a block has been removed

#demotions		  Number of times a block has been removed

			  from the cache

#promotions		 : Number of times a block has been moved to

#promotions		  Number of times a block has been moved to

			  the cache

#dirty			 : Number of blocks in the cache that differ

#dirty			  Number of blocks in the cache that differ

			  from the origin

#feature args		 : Number of feature args to follow

feature args		 : 'writethrough' (optional)

#core args		 : Number of core arguments (must be even)

core args		 : Key/value pairs for tuning the core

#feature args		  Number of feature args to follow

feature args		  'writethrough' (optional)

#core args		  Number of core arguments (must be even)

core args		  Key/value pairs for tuning the core

			  e.g. migration_threshold

policy name		 : Name of the policy

#policy args		 : Number of policy arguments to follow (must be even)

policy args		 : Key/value pairs e.g. sequential_threshold

cache metadata mode      : ro if read-only, rw if read-write

	In serious cases where even a read-only mode is deemed unsafe

	no further I/O will be permitted and the status will just

	contain the string 'Fail'.  The userspace recovery tools

	should then be used.

needs_check		 : 'needs_check' if set, '-' if not set

	A metadata operation has failed, resulting in the needs_check

	flag being set in the metadata's superblock.  The metadata

	device must be deactivated and checked/repaired before the

	cache can be made fully operational again.  '-' indicates

	needs_check is not set.

policy name		  Name of the policy

#policy args		  Number of policy arguments to follow (must be even)

policy args		  Key/value pairs e.g. sequential_threshold

cache metadata mode       ro if read-only, rw if read-write

			  In serious cases where even a read-only mode is

			  deemed unsafe no further I/O will be permitted and

			  the status will just contain the string 'Fail'.

			  The userspace recovery tools should then be used.

needs_check		  'needs_check' if set, '-' if not set

			  A metadata operation has failed, resulting in the

			  needs_check flag being set in the metadata's

			  superblock.  The metadata device must be

			  deactivated and checked/repaired before the

			  cache can be made fully operational again.

			  '-' indicates	needs_check is not set.

========================= =====================================================

Messages

--------

need a generic way of getting and setting these.  Device-mapper

messages are used.  (A sysfs interface would also be possible.)

The message format is:

The message format is::

   <key> <value>

E.g.

E.g.::

   dmsetup message my_cache 0 sequential_threshold 1024

value, in the future a variant message that takes cblock ranges

expressed in hexadecimal may be needed to better support efficient

invalidation of larger caches.  The cache must be in passthrough mode

when invalidate_cblocks is used.

when invalidate_cblocks is used::

   invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]*

E.g.

E.g.::

   dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789

Examples

https://github.com/jthornber/device-mapper-test-suite

::

  dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \

	  /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0'

  dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \

========

dm-delay

========

Device-Mapper's "delay" target delays reads and/or writes

and maps them to different devices.

Parameters:

Parameters::

    <device> <offset> <delay> [<write_device> <write_offset> <write_delay>

			       [<flush_device> <flush_offset> <flush_delay>]]

Example scripts

===============

[[

::

	#!/bin/sh

	# Create device delaying rw operation for 500ms

	echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed

]]

[[

::

	#!/bin/sh

	# Create device delaying only write operation for 500ms and

	# splitting reads and writes to different devices $1 $2

	echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed

]]

========

dm-crypt

=========

========

Device-Mapper's "crypt" target provides transparent encryption of block devices

using the kernel crypto API.

For a more detailed description of supported parameters see:

https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt

Parameters: <cipher> <key> <iv_offset> <device path> \

Parameters::

	      <cipher> <key> <iv_offset> <device path> \

	      <offset> [<#opt_params> <opt_params>]

<cipher>

    Encryption cipher, encryption mode and Initial Vector (IV) generator.

    The cipher specifications format is:

    The cipher specifications format is::

       cipher[:keycount]-chainmode-ivmode[:ivopts]

    Examples:

    Examples::

       aes-cbc-essiv:sha256

       aes-xts-plain64

       serpent-xts-plain64

    as for the first format type.

    This format is mainly used for specification of authenticated modes.

    The crypto API cipher specifications format is:

    The crypto API cipher specifications format is::

        capi:cipher_api_spec-ivmode[:ivopts]

    Examples:

    Examples::

        capi:cbc(aes)-essiv:sha256

        capi:xts(aes)-plain64

    Examples of authenticated modes:

    Examples of authenticated modes::

        capi:gcm(aes)-random

        capi:authenc(hmac(sha256),xts(aes))-random

        capi:rfc7539(chacha20,poly1305)-random

encryption with dm-crypt using the 'cryptsetup' utility, see

https://gitlab.com/cryptsetup/cryptsetup

[[

::

	#!/bin/sh

	# Create a crypt device using dmsetup

	dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0"

]]

[[

::

	#!/bin/sh

	# Create a crypt device using dmsetup when encryption key is stored in keyring service

	dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0"

]]

[[

::

	#!/bin/sh

	# Create a crypt device using cryptsetup and LUKS header with default cipher

	cryptsetup luksFormat $1

	cryptsetup luksOpen $1 crypt1

]]

=========

dm-flakey

=========

Table parameters

----------------

::

  <dev path> <offset> <up interval> <down interval> \

    [<num_features> [<feature arguments>]]

Mandatory parameters:

    <dev path>: Full pathname to the underlying block-device, or a

    <dev path>:

        Full pathname to the underlying block-device, or a

        "major:minor" device-number.

    <offset>: Starting sector within the device.

    <up interval>: Number of seconds device is available.

    <down interval>: Number of seconds device returns errors.

    <offset>:

        Starting sector within the device.

    <up interval>:

        Number of seconds device is available.

    <down interval>:

        Number of seconds device returns errors.

Optional feature parameters:

  If no feature parameters are present, during the periods of

  unreliability, all I/O returns errors.

	During <down interval>, replace <Nth_byte> of the data of

	each matching bio with <value>.

    <Nth_byte>: The offset of the byte to replace.

    <Nth_byte>:

	The offset of the byte to replace.

	Counting starts at 1, to replace the first byte.

    <direction>: Either 'r' to corrupt reads or 'w' to corrupt writes.

    <direction>:

	Either 'r' to corrupt reads or 'w' to corrupt writes.

	'w' is incompatible with drop_writes.

    <value>: The value (from 0-255) to write.

    <flags>: Perform the replacement only if bio->bi_opf has all the

    <value>:

	The value (from 0-255) to write.

    <flags>:

	Perform the replacement only if bio->bi_opf has all the

	selected flags set.

Examples:

Replaces the 32nd byte of READ bios with the value 1::

  corrupt_bio_byte 32 r 1 0

	- replaces the 32nd byte of READ bios with the value 1

Replaces the 224th byte of REQ_META (=32) bios with the value 0::

  corrupt_bio_byte 224 w 0 32

	- replaces the 224th byte of REQ_META (=32) bios with the value 0