# Copyright (C) 2005-2016 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/>.

Branch Manipulation

Since aufs supports dynamic branch manipulation, ie. add/remove a branch
and changing its permission/attribute, there are a lot of works to do.


Add a Branch
----------------------------------------------------------------------
o Confirm the adding dir exists outside of aufs, including loopback
  mount, and its various attributes.
o Initialize the xino file and whiteout bases if necessary.
  See struct.txt.

o Check the owner/group/mode of the directory
  When the owner/group/mode of the adding directory differs from the
  existing branch, aufs issues a warning because it may impose a
  security risk.
  For example, when a upper writable branch has a world writable empty
  top directory, a malicious user can create any files on the writable
  branch directly, like copy-up and modify manually. If something like
  /etc/{passwd,shadow} exists on the lower readonly branch but the upper
  writable branch, and the writable branch is world-writable, then a
  malicious guy may create /etc/passwd on the writable branch directly
  and the infected file will be valid in aufs.
  I am afraid it can be a security issue, but aufs can do nothing except
  producing a warning.


Delete a Branch
----------------------------------------------------------------------
o Confirm the deleting branch is not busy
  To be general, there is one merit to adopt "remount" interface to
  manipulate branches. It is to discard caches. At deleting a branch,
  aufs checks the still cached (and connected) dentries and inodes. If
  there are any, then they are all in-use. An inode without its
  corresponding dentry can be alive alone (for example, inotify/fsnotify case).

  For the cached one, aufs checks whether the same named entry exists on
  other branches.
  If the cached one is a directory, because aufs provides a merged view
  to users, as long as one dir is left on any branch aufs can show the
  dir to users. In this case, the branch can be removed from aufs.
  Otherwise aufs rejects deleting the branch.

  If any file on the deleting branch is opened by aufs, then aufs
  rejects deleting.


Modify the Permission of a Branch
----------------------------------------------------------------------
o Re-initialize or remove the xino file and whiteout bases if necessary.
  See struct.txt.

o rw --> ro: Confirm the modifying branch is not busy
  Aufs rejects the request if any of these conditions are true.
  - a file on the branch is mmap-ed.
  - a regular file on the branch is opened for write and there is no
    same named entry on the upper branch.