xref: /external/ltp/testcases/kernel/fs/fs_bind

=================================================================
Test Suite for Bind Mount and Shared Subtree Features in the VFS:
=================================================================
Author: Avantika Mathur
Date: September 16, 2005
Last update: March 18th, 2008 (by Matt Helsley)

About:
------
These tests exercise the Linux Kernel's bind mount and shared subtree
capabilities. With it administrators may use clear semantics to manage
complex mount trees on a system.

Bind mount simply allows administrators to make a directory appear in
two places at once -- somewhat like hard links for files:

# mkdir mnt mnt2
# mount --bind mnt mnt2
# touch mnt/a
# ls mnt2
a

Note that bind mounts are not recursive. To get a recursive bind mount
use --rbind.

Another limitation of simple bind mounts is they cannot propagate future binds:

# mkdir mnt mnt2
# mount --bind mnt mnt2
# touch mnt/a
# mkdir mnt/foo
# ls mnt2
a foo
# mkdir sub
# touch sub/b
# mount --bind sub /mnt/foo
# ls mnt/foo
b
# ls mnt2/foo

mnt2/foo appears to be empty because the second bind mount did not propagate
to mnt2. Shared subtrees allow propagation whereas bind mounts do not.
To enable full administrator control of propagation there are several kinds of
subtrees:
	private		[default -- this is a "normal" mount]
	shared		[propagation goes both ways]
	slave		[propagation goes one way]
	unbindable	[cannot --bind and hence cannot share]

For further details on these types of subtrees please see your kernel source's
Documentation/filesystems/sharedsubtree.txt file.

Building:
---------
Uses GNU Make. In the root directory type:
make

Installing:
-----------
Type:
make install

Cleaning:
---------
Type:
make clean

Running:
--------
run LTPROOT/testscripts/test_fs_bind.sh


Testcases:
----------
There are multiple testcases testing in each of the following categories,
testing functionality of different types of mounts, different combinations,
etc:
-- bind
-- rbind
-- move
-- regression tests
-- clone namespace (currently not run)


Directory Structure:
--------------------
In the root directory of the suite there are scripts to execute the whole test suite. Logged results are stored in LTPROOT/results/fs_bind. PASS/FAIL
indications are passed to the LTP API and logged in the results directory too.

Basic tests of bind and move mounts are part of the test_fs_bind.sh test
script itself. These are prerequisites for the more the complicated tests.
The bind, rbind, and move directories contain tests for bind, rbind, move in
combination with the various kinds of subtrees. The regression and cloneNS
directories perform basic regression tests and combine some of the tests with
mount namespaces respectively.

The bin directory contains scripts used by each of the testcases for
common setup, creating, and comparing mounts.

Running the Test Suite:
-----------------------
To run the entire testsuite run:
test_fs_bind.sh

Log directories where the results are stored in LTPROOT/results/fs_bind

Reading the Test Suite Results:
-------------------------------
Test suite results are logged, by default, in the LTPROOT/results/fs_bind
directory. Its structure is:
fs_bind-\
	|-> errors		 (stderr of main test suite script itself)
	|-> summary		 (stdout of main test suite script itself)
	|-move--\
	|	|->test01-\	(logs of test01)
	|	|	  |-> log		(stdout)
	|	|	  |-> err		(stderr)
	|	|	  |-> mtab.before
	|	|	  |-> mtab.after
	|	|	  |-> proc_mounts.before
	|	|	  |-> proc_mounts.after
	|	|	  |-> files.before	(files  before running)
	|	|	  |-> dirs.before	(dirs   before running)
	|	|	  |-> files.after	(files  after  running)
	|	|	  \-> dirs.after	(dirs   after  running)
	|	|->test02-\
	|	|	  |
	|	...	  ...
	|-rbind--\
	|        |-->
	...       ...

An testXX/err file will only be left for those tests that had errors and
stderr was non-empty. mounts.*, files.*, and dirs.* files will be left for
tests that appear to have broken cleanup sections. The test_fs_bind.sh
script robustly handles cleanup so, unless the tests are run individually, this
is not an issue that prevents testing from completing successfully nor does it
interfere with test results.

These files make it easy to determine what happened during a given test.
It's easy to see which tests need to be debugged and which do not. It also
makes it easy to aggregate output or trace sandbox dirtying from test to test.

Running individual Tests:
-------------------------
Currently tests cannot be run individually because there are several important
LTP environment dependencies. Some of them are documented below:
	LTP test script environment variables:
		LTPROOT
		TCID
		TST_TOTAL
		TST_COUNT
	LTP commands/functions:
		tst_resm
		tst_brkm
		tst_exit
	LTP contents:
		LTPROOT/testcases/bin

It's important to note that the individual test scripts use the current working
directory extensively but never exit it. This may allow the tests to be run
individually once the above LTP environment dependencies are resolved.
Lastly none of the logging or debugging information will appear in the
LTPROOT/results/fs_bind directory when tests are invoked individually since
those are collected by the test_fs_bind.sh script.