xfs: Verify correctness of upgrading an fs to support large extent counters
[xfstests-dev.git] / README.overlay
1
2 To run xfstest on overlayfs, configure the variables of TEST and SCRATCH
3 partitions to be used as the "base fs" and run './check -overlay'.
4
5 For example, the following config file can be used to run tests on
6 xfs test/scratch partitions:
7
8  TEST_DEV=/dev/sda5
9  TEST_DIR=/mnt/test
10  SCRATCH_DEV=/dev/sda6
11  SCRATCH_MNT=/mnt/scratch
12  FSTYP=xfs
13
14 Using the same config file, but executing './check -overlay' will
15 use the same partitions as base fs for overlayfs directories
16 and set TEST_DIR/SCRATCH_MNT values to overlay mount points, i.e.:
17 /mnt/test/ovl-mnt and /mnt/scratch/ovl-mnt, for the context of
18 individual tests.
19
20 './check -overlay' does not support mkfs and fsck on the base fs, so
21 the base fs should be pre-formatted before starting the -overlay run.
22 An easy way to accomplish this is by running './check <some test>' once,
23 before running './check -overlay'.
24
25 './check -overlay' support check overlay test and scratch dirs,
26 OVERLAY_FSCK_OPTIONS should be set instead of FSCK_OPTIONS if fsck
27 options need to given directly.
28
29 Because of the lack of mkfs support, multi-section config files are only
30 partly supported with './check -overlay'. Only multi-section files that
31 do not change FSTYP and MKFS_OPTIONS can be safely used with -overlay.
32
33 For example, the following multi-section config file can be used to
34 run overlay tests on the same base fs, but with different mount options, and on
35 top of idmapped mounts:
36
37  [xfs]
38  TEST_DEV=/dev/sda5
39  TEST_DIR=/mnt/test
40  SCRATCH_DEV=/dev/sda6
41  SCRATCH_MNT=/mnt/scratch
42  FSTYP=xfs
43
44  [xfs_pquota]
45  MOUNT_OPTIONS="-o pquota"
46  TEST_FS_MOUNT_OPTS="-o noatime"
47  OVERLAY_MOUNT_OPTIONS="-o redirect_dir=off"
48  OVERLAY_FSCK_OPTIONS="-n -o redirect_dir=off"
49
50  [idmapped]
51  IDMAPPED_MOUNTS=true
52
53 In the example above, MOUNT_OPTIONS will be used to mount the base scratch fs,
54 TEST_FS_MOUNT_OPTS will be used to mount the base test fs,
55 OVERLAY_MOUNT_OPTIONS will be used to mount both test and scratch overlay and
56 OVERLAY_FSCK_OPTIONS will be used to check both test and scratch overlay.
57
58
59 Unionmount Testsuite
60 ====================
61
62 xfstests can be used as a test harness to run unionmount testsuite test cases
63 and provide extended test coverage for overlayfs.
64
65 To enable running unionmount testsuite, clone the git repository from:
66   https://github.com/amir73il/unionmount-testsuite.git
67 under the xfstests src directory, or set the environment variable
68 UNIONMOUNT_TESTSUITE to the local path where the repository was cloned.
69
70 Run './check -overlay -g overlay/union' to execute all the unionmount testsuite
71 test cases.