Go to file
Joe Thornber 9e20465fd1 [thin-repair, thin_dump] When repairing we now hunt for the best btree roots.
We've had a trickle of users who accidentally activate the same pool on a
VM and host at the same time.  Typically the host doesn't do any IO, but
the kernel will still rewrite the superblock on shutdown.  This leaves
the superblock pointing to very out of date btree roots and so we get
massive metadata loss.

This patch changes thin_repair, and thin_dump --repair.  They now hunt
for the most recent, undamaged and consistent roots of the device and
mapping trees, and use that as the starting point of the repair.
2019-04-17 12:17:13 +01:00
autoconf more build stuff 2011-12-09 12:54:51 +00:00
base [file_utils] Use aligned memory in zero_superblock 2018-04-17 11:42:43 +01:00
bin [thin_journal_check] Checks journal of block manager activity. 2018-09-24 14:51:46 +01:00
block-cache Revert "fix compile failed with libc musl (#103)" 2018-08-02 07:12:22 +01:00
caching [restore_emitter] squash a strncpy warning 2018-06-13 12:50:48 +01:00
contrib fix compilation for gcc 5.4.0 2016-09-07 13:49:36 +00:00
doc [thin_journal_check] Checks journal of block manager activity. 2018-09-24 14:51:46 +01:00
era [era/restore_emitter] remove a noop 2018-12-12 10:23:35 +00:00
features [functional-tests] era_check tests 2017-08-30 14:30:11 +01:00
ft-lib Update bcache.c (#115) 2018-11-12 08:18:48 +00:00
functional-tests [thin_repair] work in progress 2019-03-29 12:56:31 +00:00
lib gmock stub 2013-03-22 10:55:55 +00:00
man8 [man] Update manpage for thin_dump 2018-01-31 14:39:24 +00:00
persistent-data [thin_repair] work in progress 2019-03-29 12:56:31 +00:00
thin-provisioning [thin-repair, thin_dump] When repairing we now hunt for the best btree roots. 2019-04-17 12:17:13 +01:00
ui [thin_show_metadata] ncurses render 2016-02-26 12:50:17 +00:00
unit-tests [build] support separate build directories 2018-06-13 09:34:14 +01:00
xml_metadata add some example metadata dumps 2011-11-16 12:17:23 +00:00
.gitignore [manpages] Rewrite man pages in a simpler text format. 2017-09-20 11:15:00 +01:00
CHANGES update CHANGES 2017-11-13 14:18:07 +00:00
configure.ac [build] fix typo 2017-10-10 10:29:24 +01:00
COPYING Add copyright 2011-12-06 13:43:44 +00:00
get-gmock.sh update get-gmock script. 2016-06-07 11:15:35 +01:00
main.cc [base] introduce a command type that gets registered with the app 2016-01-08 12:51:52 +00:00
Makefile.in [thin_journal_check] first code drop 2018-08-28 13:12:20 +01:00
mk_release make mk_release executable 2012-03-05 11:46:20 +00:00
README.md [functional tests] Move test output from /tmp to . 2018-12-12 13:13:11 +00:00
TODO.org Add a TODO file 2013-04-23 11:18:21 +01:00
VERSION bump version 2018-04-23 10:41:48 +01:00
version.h.in version.h.in 2011-12-15 14:58:25 +01:00

Introduction

A suite of tools for manipulating the metadata of the dm-thin, dm-cache and dm-era device-mapper targets.

Requirements

A C++ compiler that supports the c++11 standard (eg, g++). The Boost C++ library. The expat xml parser library (version 1). The libaio library (note this is not the same as the aio library that you get by linking -lrt) make, autoconf etc.

There are more requirements for testing, detailed below.

Building

autoconf
./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.

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
thin_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

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/). In addition they make use of the thunderchez (https://github.com/ovenpasta/thunderchez) library.

Make sure the tools that you wish to test are in your PATH, and the thunderchez directory is in the CHEZSCHEMELIBDIRS environment variable.

Then,

cd funtional-tests
./run-tests run

Other command are help and list.

The test framework places temporary files under ./test-output/. By default the tests tidy up after themselves, just leaving a log file for each test. You 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