[mirror_ubuntu-bionic-kernel.git] / Documentation / filesystems / aufs / design / 06dirren.txt


# Copyright (C) 2017 Junjiro R. Okajima
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

Special handling for renaming a directory (DIRREN)
----------------------------------------------------------------------
First, let's assume we have a simple usecase.

- /u = /rw + /ro
- /rw/dirA exists
- /ro/dirA and /ro/dirA/file exist too
- there is no dirB on both branches
- a user issues rename("dirA", "dirB")

Now, what should aufs behave against this rename(2)?
There are a few possible cases.

A. returns EROFS.
   since dirA exists on a readonly branch which cannot be renamed.
B. returns EXDEV.
   it is possible to copy-up dirA (only the dir itself), but the child
   entries ("file" in this case) should not be. it must be a bad
   approach to copy-up recursively.
C. returns a success.
   even the branch /ro is readonly, aufs tries renaming it. Obviously it
   is a violation of aufs' policy.
D. construct an extra information which indicates that /ro/dirA should
   be handled as the name of dirB.
   overlayfs has a similar feature called REDIRECT.

Until now, aufs implements the case B only which returns EXDEV, and
expects the userspace application behaves like mv(1) which tries
issueing rename(2) recursively.

A new aufs feature called DIRREN is introduced which implements the case
D. There are several "extra information" added.

1. detailed info per renamed directory
   path: /rw/dirB/$AUFS_WH_DR_INFO_PFX.<lower branch-id>
2. the inode-number list of directories on a branch
   path: /rw/dirB/$AUFS_WH_DR_BRHINO

The filename of "detailed info per directory" represents the lower
branch, and its format is
- a type of the branch id
  one of these.
  + uuid (not implemented yet)
  + fsid
  + dev
- the inode-number of the branch root dir

And it contains these info in a single regular file.
- magic number
- branch's inode-number of the logically renamed dir
- the name of the before-renamed dir

The "detailed info per directory" file is created in aufs rename(2), and
loaded in any lookup.
The info is considered in lookup for the matching case only. Here
"matching" means that the root of branch (in the info filename) is same
to the current looking-up branch. After looking-up the before-renamed
name, the inode-number is compared. And the matched dentry is used.

The "inode-number list of directories" is a regular file which contains
simply the inode-numbers on the branch. The file is created or updated
in removing the branch, and loaded in adding the branch. Its lifetime is
equal to the branch.
The list is refered in lookup, and when the current target inode is
found in the list, the aufs tries loading the "detailed info per
directory" and get the changed and valid name of the dir.

Theoretically these "extra informaiton" may be able to be put into XATTR
in the dir inode. But aufs doesn't choose this way because
1. XATTR may not be supported by the branch (or its configuration)
2. XATTR may have its size limit.
3. XATTR may be less easy to convert than a regular file, when the
   format of the info is changed in the future.
At the same time, I agree that the regular file approach is much slower
than XATTR approach. So, in the future, aufs may take the XATTR or other
better approach.

This DIRREN feature is enabled by aufs configuration, and is activated
by a new mount option.

For the more complicated case, there is a work with UDBA option, which
is to dected the direct access to the branches (by-passing aufs) and to
maintain the cashes in aufs. Since a single cached aufs dentry may
contains two names, before- and after-rename, the name comparision in
UDBA handler may not work correctly. In this case, the behaviour will be
equivalen to udba=reval case.
Commit	Line	Data
0006ebb4 SF	1
	2	# Copyright (C) 2017 Junjiro R. Okajima
	3	#
	4	# This program is free software; you can redistribute it and/or modify
	5	# it under the terms of the GNU General Public License as published by
	6	# the Free Software Foundation; either version 2 of the License, or
	7	# (at your option) any later version.
	8	#
	9	# This program is distributed in the hope that it will be useful,
	10	# but WITHOUT ANY WARRANTY; without even the implied warranty of
	11	# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	12	# GNU General Public License for more details.
	13	#
	14	# You should have received a copy of the GNU General Public License
	15	# along with this program. If not, see <http://www.gnu.org/licenses/>.
	16
	17	Special handling for renaming a directory (DIRREN)
	18	----------------------------------------------------------------------
	19	First, let's assume we have a simple usecase.
	20
	21	- /u = /rw + /ro
	22	- /rw/dirA exists
	23	- /ro/dirA and /ro/dirA/file exist too
	24	- there is no dirB on both branches
	25	- a user issues rename("dirA", "dirB")
	26
	27	Now, what should aufs behave against this rename(2)?
	28	There are a few possible cases.
	29
	30	A. returns EROFS.
	31	since dirA exists on a readonly branch which cannot be renamed.
	32	B. returns EXDEV.
	33	it is possible to copy-up dirA (only the dir itself), but the child
	34	entries ("file" in this case) should not be. it must be a bad
	35	approach to copy-up recursively.
	36	C. returns a success.
	37	even the branch /ro is readonly, aufs tries renaming it. Obviously it
	38	is a violation of aufs' policy.
	39	D. construct an extra information which indicates that /ro/dirA should
	40	be handled as the name of dirB.
	41	overlayfs has a similar feature called REDIRECT.
	42
	43	Until now, aufs implements the case B only which returns EXDEV, and
	44	expects the userspace application behaves like mv(1) which tries
	45	issueing rename(2) recursively.
	46
	47	A new aufs feature called DIRREN is introduced which implements the case
	48	D. There are several "extra information" added.
	49
	50	1. detailed info per renamed directory
	51	path: /rw/dirB/$AUFS_WH_DR_INFO_PFX.<lower branch-id>
	52	2. the inode-number list of directories on a branch
	53	path: /rw/dirB/$AUFS_WH_DR_BRHINO
	54
	55	The filename of "detailed info per directory" represents the lower
	56	branch, and its format is
	57	- a type of the branch id
	58	one of these.
	59	+ uuid (not implemented yet)
	60	+ fsid
	61	+ dev
	62	- the inode-number of the branch root dir
	63
	64	And it contains these info in a single regular file.
65	- magic number
66	- branch's inode-number of the logically renamed dir
67	- the name of the before-renamed dir
68
69	The "detailed info per directory" file is created in aufs rename(2), and
70	loaded in any lookup.
71	The info is considered in lookup for the matching case only. Here
72	"matching" means that the root of branch (in the info filename) is same
73	to the current looking-up branch. After looking-up the before-renamed
74	name, the inode-number is compared. And the matched dentry is used.
75
76	The "inode-number list of directories" is a regular file which contains
77	simply the inode-numbers on the branch. The file is created or updated
78	in removing the branch, and loaded in adding the branch. Its lifetime is
79	equal to the branch.
80	The list is refered in lookup, and when the current target inode is
81	found in the list, the aufs tries loading the "detailed info per
82	directory" and get the changed and valid name of the dir.
83
84	Theoretically these "extra informaiton" may be able to be put into XATTR
85	in the dir inode. But aufs doesn't choose this way because
86	1. XATTR may not be supported by the branch (or its configuration)
87	2. XATTR may have its size limit.
88	3. XATTR may be less easy to convert than a regular file, when the
89	format of the info is changed in the future.
90	At the same time, I agree that the regular file approach is much slower
91	than XATTR approach. So, in the future, aufs may take the XATTR or other
92	better approach.
93
94	This DIRREN feature is enabled by aufs configuration, and is activated
95	by a new mount option.
96
97	For the more complicated case, there is a work with UDBA option, which
98	is to dected the direct access to the branches (by-passing aufs) and to
99	maintain the cashes in aufs. Since a single cached aufs dentry may
100	contains two names, before- and after-rename, the name comparision in
101	UDBA handler may not work correctly. In this case, the behaviour will be
102	equivalen to udba=reval case.