133 lines
3.3 KiB
Plaintext
133 lines
3.3 KiB
Plaintext
Introduction
|
|
============
|
|
|
|
A suite of tools for manipulating the metadata of the dm-thin
|
|
device-mapper target.
|
|
|
|
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).
|
|
make, autoconf etc.
|
|
|
|
There are more requirements for testing, detailed below.
|
|
|
|
Building
|
|
========
|
|
|
|
./configure
|
|
make
|
|
sudo make install
|
|
|
|
|
|
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`
|
|
|
|
To convert xml back to the binary form use _thin\_restore_.
|
|
|
|
`thin_restore -i my_xml -o /dev/mapper/my_thinp_metadata`
|
|
|
|
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`
|
|
|
|
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`
|
|
|
|
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`
|
|
|
|
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`
|
|
`thinp_restore -i repaired.xml -o /dev/mapper/my_metadata`
|
|
|
|
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:
|
|
|
|
`autoreconf`
|
|
|
|
Enable tests
|
|
------------
|
|
|
|
You will need to enable tests when you configure.
|
|
|
|
`./configure --enable-testing`
|
|
|
|
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`
|
|
|
|
All tests can be run via:
|
|
|
|
`make unit-test`
|
|
|
|
Alternatively you may want to run a subset of the tests:
|
|
|
|
`make unit-tests/unit_tests`
|
|
`unit-tests/unit_tests --gtest_filter=BtreeTests.*`
|
|
|
|
Functional tests
|
|
----------------
|
|
|
|
These top level tests are implemented using the
|
|
[cucumber](http://cukes.info/) tool. They check the user interface of
|
|
the tools (eg, command line switches are accepted and effective).
|
|
|
|
I've provided a Gemfile, so installing this should be easy:
|
|
|
|
i) Install Ruby 1.9.x. I recommend doing this via RVM.
|
|
ii) Make sure _bundler_ is installed:
|
|
|
|
`gem install bundler`
|
|
|
|
iii) Install dependencies (including _cucumber_ and _thinp\_xml_)
|
|
|
|
`bundle`
|
|
|
|
Once you've done this you can run the tests with a simple:
|
|
|
|
`rake features`
|
|
|
|
Or specific tests with:
|
|
|
|
`cucumber features/thin_restore -n 'print help'`
|