thin-provisioning-tools/README.md

165 lines
4.5 KiB
Markdown
Raw Permalink Normal View History

2013-06-27 16:10:08 +05:30
Introduction
============
2011-09-09 16:38:10 +05:30
2017-08-30 20:26:26 +05:30
A suite of tools for manipulating the metadata of the dm-thin, dm-cache and
dm-era device-mapper targets.
2013-06-27 16:10:08 +05:30
Requirements
============
A C++ compiler that supports the c++11 standard (eg, g++).
The [Boost C++ library](http://www.boost.org/).
The [expat](http://expat.sourceforge.net/) xml parser library (version 1).
2014-08-06 20:59:50 +05:30
The libaio library (note this is not the same as the aio library that you get by linking -lrt)
2013-06-27 16:10:08 +05:30
make, autoconf etc.
A couple of non-essential tools are written in rust, and will
require cargo and rustcc to be installed:
thin_metadata_pack
thin_metadata_unpack
2013-06-27 16:10:08 +05:30
There are more requirements for testing, detailed below.
Building
========
autoconf
./configure
make
sudo make install
2013-06-27 16:10:08 +05:30
Building Rust tools
===================
sudo make install-rust-tools
2013-06-27 16:10:08 +05:30
Quick examples
==============
These tools introduce an xml format for the metadata. This is useful
for making backups, or allowing scripting languages to generate or
manipulate metadata. A Ruby library for this available;
[thinp_xml](https://rubygems.org/gems/thinp_xml).
To convert the binary metadata format that the kernel uses to this xml
format use _thin\_dump_.
thin_dump --format xml /dev/mapper/my_thinp_metadata
2013-06-27 16:10:08 +05:30
To convert xml back to the binary form use _thin\_restore_.
thin_restore -i my_xml -o /dev/mapper/my_thinp_metadata
2013-06-27 16:10:08 +05:30
You should periodically check the health of your metadata, much as you
fsck a filesystem. Your volume manager (eg, LVM2) should be doing
this for you behind the scenes.
thin_check /dev/mapper/my_thinp_metadata
2013-06-27 16:10:08 +05:30
Checking all the mappings can take some time, you can omit this part
of the check if you wish.
thin_check --skip-mappings /dev/mapper/my_thinp_metadata
2013-06-27 16:10:08 +05:30
If your metadata has become corrupt for some reason (device failure,
user error, kernel bug), thin_check will tell you what the effects of
the corruption are (eg, which thin devices are effected, which
mappings).
There are two ways to repair metadata. The simplest is via the
_thin\_repair_ tool.
thin_repair -i /dev/mapper/broken_metadata_dev -o /dev/mapper/new_metadata_dev
2013-06-27 16:10:08 +05:30
This is a non-destructive operation that writes corrected metadata to
a new metadata device.
Alternatively you can go via the xml format (perhaps you want to
inspect the repaired metadata before restoring).
thin_dump --repair /dev/mapper/my_metadata > repaired.xml
thin_restore -i repaired.xml -o /dev/mapper/my_metadata
2013-06-27 16:10:08 +05:30
Development
===========
Autoconf
--------
If you've got the source from github you'll need to create the
configure script with autoconf. I do this by running:
2013-06-27 16:10:08 +05:30
autoreconf
2013-06-27 16:10:08 +05:30
Enable tests
------------
You will need to enable tests when you configure.
./configure --enable-testing
2013-06-27 16:10:08 +05:30
Unit tests
----------
Unit tests are implemented using the google mock framework. This is a
source library that you will have to download. A script is provided
to do this for you.
./get-gmock.sh
2013-06-27 16:10:08 +05:30
All tests can be run via:
make unit-test
2013-06-27 16:10:08 +05:30
Alternatively you may want to run a subset of the tests:
make unit-tests/unit_tests
unit-tests/unit_tests --gtest_filter=BtreeTests.*
2013-06-27 16:10:08 +05:30
Functional tests
----------------
2017-08-30 20:26:26 +05:30
A bunch of high level tests are implemented in the functional-tests directory.
These tests are written in Scheme. To run them you'll need to install
chezscheme (http://www.scheme.com/). There is no longer a dependency on
the ThunderChez library.
2013-06-27 16:10:08 +05:30
Make sure the tools that you wish to test are in your PATH.
2013-06-27 16:10:08 +05:30
2017-08-30 20:26:26 +05:30
Then,
2013-06-27 16:10:08 +05:30
2017-08-30 20:26:26 +05:30
cd funtional-tests
./run-tests run
2013-06-27 16:10:08 +05:30
2017-08-30 20:26:26 +05:30
Other command are help and list.
The test framework places temporary files under ./test-output/. By default
2017-08-30 20:44:45 +05:30
the tests tidy up after themselves, just leaving a log file for each test. You
2017-08-30 20:26:26 +05:30
can turn this off by using the --disable-unlink flag if you want all the
artifacts left.
Dump Metadata
=============
To dump the metadata of a live thin pool, you must first create a snapshot of
the metadata:
$ dmsetup message vg001-mythinpool-tpool 0 reserve_metadata_snap
Extract the metadata:
$ sudo bin/thin_dump -m /dev/mapper/vg001-mythinpool_tmeta
<superblock uuid="" time="1" transaction="2" data_block_size="128"nr_data_blocks="0">
<device dev_id="1" mapped_blocks="1" transaction="0" creation_time="0" snap_time="1">
<single_mapping origin_block="0" data_block="0" time="0"/>
</device>
<device dev_id="2" mapped_blocks="1" transaction="1" creation_time="1" snap_time="1">
<single_mapping origin_block="0" data_block="0" time="0"/>
</device>
</superblock>
Finally, release the root:
$ dmsetup message vg001-mythinpool-tpool 0 release_metadata_snap