diff options
Diffstat (limited to 'package/aufs2-util/src/aufs.in.5')
| -rw-r--r-- | package/aufs2-util/src/aufs.in.5 | 1684 |
1 files changed, 0 insertions, 1684 deletions
diff --git a/package/aufs2-util/src/aufs.in.5 b/package/aufs2-util/src/aufs.in.5 deleted file mode 100644 index 0cbb14487..000000000 --- a/package/aufs2-util/src/aufs.in.5 +++ /dev/null @@ -1,1684 +0,0 @@ -.\".so aufs.tmac -. -.eo -.de TQ -.br -.ns -.TP \$1 -.. -.de Bu -.IP \(bu 4 -.. -.ec -.\" end of macro definitions -. -.\" ---------------------------------------------------------------------- -.TH aufs 5 \*[AUFS_VERSION] Linux "Linux Aufs User's Manual" -.SH NAME -aufs \- advanced multi layered unification filesystem. version \*[AUFS_VERSION] - -.\" ---------------------------------------------------------------------- -.SH DESCRIPTION -Aufs is a stackable unification filesystem such as Unionfs, which unifies -several directories and provides a merged single directory. -In the early days, aufs was entirely re-designed and re-implemented -Unionfs Version 1.x series. After -many original ideas, approaches and improvements, it -becomes totally different from Unionfs while keeping the basic features. -See Unionfs Version 1.x series for the basic features. -Recently, Unionfs Version 2.x series begin taking some of same -approaches to aufs's. - -.\" ---------------------------------------------------------------------- -.SH MOUNT OPTIONS -At mount-time, the order of interpreting options is, -.RS -.Bu -simple flags, except xino/noxino and udba=inotify -.Bu -branches -.Bu -xino/noxino -.Bu -udba=inotify -.RE - -At remount-time, -the options are interpreted in the given order, -e.g. left to right. -.RS -.Bu -create or remove -whiteout-base(\*[AUFS_WH_BASE]) and -whplink-dir(\*[AUFS_WH_PLINKDIR]) if necessary -.RE -. -.TP -.B br:BRANCH[:BRANCH ...] (dirs=BRANCH[:BRANCH ...]) -Adds new branches. -(cf. Branch Syntax). - -Aufs rejects the branch which is an ancestor or a descendant of another -branch. It is called overlapped. When the branch is loopback-mounted -directory, aufs also checks the source fs-image file of loopback -device. If the source file is a descendant of another branch, it will -be rejected too. - -After mounting aufs or adding a branch, if you move a branch under -another branch and make it descendant of another branch, aufs will not -work correctly. -. -.TP -.B [ add | ins ]:index:BRANCH -Adds a new branch. -The index begins with 0. -Aufs creates -whiteout-base(\*[AUFS_WH_BASE]) and -whplink-dir(\*[AUFS_WH_PLINKDIR]) if necessary. - -If there is the same named file on the lower branch (larger index), -aufs will hide the lower file. -You can only see the highest file. -You will be confused if the added branch has whiteouts (including -diropq), they may or may not hide the lower entries. -.\" It is recommended to make sure that the added branch has no whiteout. - -Even if a process have once mapped a file by mmap(2) with MAP_SHARED -and the same named file exists on the lower branch, -the process still refers the file on the lower(hidden) -branch after adding the branch. -If you want to update the contents of a process address space after -adding, you need to restart your process or open/mmap the file again. -.\" Usually, such files are executables or shared libraries. -(cf. Branch Syntax). -. -.TP -.B del:dir -Removes a branch. -Aufs does not remove -whiteout-base(\*[AUFS_WH_BASE]) and -whplink-dir(\*[AUFS_WH_PLINKDIR]) automatically. -For example, when you add a RO branch which was unified as RW, you -will see whiteout-base or whplink-dir on the added RO branch. - -If a process is referencing the file/directory on the deleting branch -(by open, mmap, current working directory, etc.), aufs will return an -error EBUSY. -. -.TP -.B mod:BRANCH -Modifies the permission flags of the branch. -Aufs creates or removes -whiteout-base(\*[AUFS_WH_BASE]) and/or -whplink-dir(\*[AUFS_WH_PLINKDIR]) if necessary. - -If the branch permission is been changing `rw' to `ro', and a process -is mapping a file by mmap(2) -.\" with MAP_SHARED -on the branch, the process may or may not -be able to modify its mapped memory region after modifying branch -permission flags. -Additioanlly when you enable CONFIG_IMA (in linux-2.6.30 and later), IMA -may produce some wrong messages. But this is equivalent when the -filesystem is changed `ro' in emergency. -(cf. Branch Syntax). -. -.TP -.B append:BRANCH -equivalent to `add:(last index + 1):BRANCH'. -(cf. Branch Syntax). -. -.TP -.B prepend:BRANCH -equivalent to `add:0:BRANCH.' -(cf. Branch Syntax). -. -.TP -.B xino=filename -Use external inode number bitmap and translation table. -When CONFIG_AUFS_EXPORT is enabled, external inode generation table too. -It is set to -<FirstWritableBranch>/\*[AUFS_XINO_FNAME] by default, or -\*[AUFS_XINO_DEFPATH]. -Comma character in filename is not allowed. - -The files are created per an aufs and per a branch filesystem, and -unlinked. So you -cannot find this file, but it exists and is read/written frequently by -aufs. -(cf. External Inode Number Bitmap, Translation Table and Generation Table). - -If you enable CONFIG_SYSFS, the path of xino files are not shown in -/proc/mounts (and /etc/mtab), instead it is shown in -<sysfs>/fs/aufs/si_<id>/xi_path. -Otherwise, it is shown in /proc/mounts unless it is not the default -path. -. -.TP -.B noxino -Stop using external inode number bitmap and translation table. - -If you use this option, -Some applications will not work correctly. -.\" And pseudo link feature will not work after the inode cache is -.\" shrunk. -(cf. External Inode Number Bitmap, Translation Table and Generation Table). -. -.TP -.B trunc_xib -Truncate the external inode number bitmap file. The truncation is done -automatically when you delete a branch unless you do not specify -`notrunc_xib' option. -(cf. External Inode Number Bitmap, Translation Table and Generation Table). -. -.TP -.B notrunc_xib -Stop truncating the external inode number bitmap file when you delete -a branch. -(cf. External Inode Number Bitmap, Translation Table and Generation Table). -. -.TP -.B create_policy | create=CREATE_POLICY -.TQ -.B copyup_policy | copyup | cpup=COPYUP_POLICY -Policies to select one among multiple writable branches. The default -values are `create=tdp' and `cpup=tdp'. -link(2) and rename(2) systemcalls have an exception. In aufs, they -try keeping their operations in the branch where the source exists. -(cf. Policies to Select One among Multiple Writable Branches). -. -.TP -.B verbose | v -Print some information. -Currently, it is only busy file (or inode) at deleting a branch. -. -.TP -.B noverbose | quiet | q | silent -Disable `verbose' option. -This is default value. -. -.TP -.B sum -df(1)/statfs(2) returns the total number of blocks and inodes of -all branches. -Note that there are cases that systemcalls may return ENOSPC, even if -df(1)/statfs(2) shows that aufs has some free space/inode. -. -.TP -.B nosum -Disable `sum' option. -This is default value. -. -.TP -.B dirwh=N -Watermark to remove a dir actually at rmdir(2) and rename(2). - -If the target dir which is being removed or renamed (destination dir) -has a huge number of whiteouts, i.e. the dir is empty logically but -physically, the cost to remove/rename the single -dir may be very high. -It is -required to unlink all of whiteouts internally before issuing -rmdir/rename to the branch. -To reduce the cost of single systemcall, -aufs renames the target dir to a whiteout-ed temporary name and -invokes a pre-created -kernel thread to remove whiteout-ed children and the target dir. -The rmdir/rename systemcall returns just after kicking the thread. - -When the number of whiteout-ed children is less than the value of -dirwh, aufs remove them in a single systemcall instead of passing -another thread. -This value is ignored when the branch is NFS. -The default value is \*[AUFS_DIRWH_DEF]. -.\" . -.\" .TP -.\" .B rdcache=N -. -.TP -.B rdblk=N -Specifies a size of internal VDIR block which is allocated at a time in -byte. -The VDIR block will be allocated several times when necessary. If your -directory has millions of files, you may want to expand this size. -The default value is defined as \*[AUFS_RDBLK_DEF]. -The size has to be lager than NAME_MAX (usually 255) and kmalloc\-able -(the maximum limit depends on your system. at least 128KB is available -for every system). -Whenever you can reset the value to default by specifying rdblk=def. -(cf. Virtual or Vertical Directory Block). -. -.TP -.B rdhash=N -Specifies a size of internal VDIR hash table which is used to compare -the file names under the same named directory on multiple branches. -The VDIR hash table will be allocated in readdir(3)/getdents(2), -rmdir(2) and rename(2) for the existing target directory. If your -directory has millions of files, you may want to expand this size. -The default value is defined as \*[AUFS_RDHASH_DEF]. -The size has to be lager than zero, and it will be multiplied by 4 or 8 -(for 32\-bit and 64\-bit respectively, currently). The result must be -kmalloc\-able -(the maximum limit depends on your system. at least 128KB is available -for every system). -Whenever you can reset the value to default by specifying rdhash=def. -(cf. Virtual or Vertical Directory Block). -. -.TP -.B plink -.TQ -.B noplink -Specifies to use `pseudo link' feature or not. -The default is `plink' which means use this feature. -(cf. Pseudo Link) -. -.TP -.B clean_plink -Removes all pseudo-links in memory. -In order to make pseudo-link permanent, use -`auplink' utility just before one of these operations, -unmounting aufs, -using `ro' or `noplink' mount option, -deleting a branch from aufs, -adding a branch into aufs, -or changing your writable branch as readonly. -If you installed both of /sbin/mount.aufs and /sbin/umount.aufs, and your -mount(8) and umount(8) support them, -`auplink' utility will be executed automatically and flush pseudo-links. -(cf. Pseudo Link) -. -.TP -.B udba=none | reval | inotify -Specifies the level of UDBA (User's Direct Branch Access) test. -(cf. User's Direct Branch Access and Inotify Limitation). -. -.TP -.B diropq=whiteouted | w | always | a -Specifies whether mkdir(2) and rename(2) dir case make the created directory -`opaque' or not. -In other words, to create `\*[AUFS_WH_DIROPQ]' under the created or renamed -directory, or not to create. -When you specify diropq=w or diropq=whiteouted, aufs will not create -it if the -directory was not whiteouted or opaqued. If the directory was whiteouted -or opaqued, the created or renamed directory will be opaque. -When you specify diropq=a or diropq==always, aufs will always create -it regardless -the directory was whiteouted/opaqued or not. -The default value is diropq=w, it means not to create when it is unnecessary. -If you define CONFIG_AUFS_COMPAT at aufs compiling time, the default will be -diropq=a. -You need to consider this option if you are planning to add a branch later -since `diropq' affects the same named directory on the added branch. -. -.TP -.B warn_perm -.TQ -.B nowarn_perm -Adding a branch, aufs will issue a warning about uid/gid/permission of -the adding branch directory, -when they differ from the existing branch's. This difference may or -may not impose a security risk. -If you are sure that there is no problem and want to stop the warning, -use `nowarn_perm' option. -The default is `warn_perm' (cf. DIAGNOSTICS). -. -.TP -.B shwh -.TQ -.B noshwh -By default (noshwh), aufs doesn't show the whiteouts and -they just hide the same named entries in the lower branches. The -whiteout itself also never be appeared. -If you enable CONFIG_AUFS_SHWH and specify `shwh' option, aufs -will show you the name of whiteouts -with keeping its feature to hide the lowers. -Honestly speaking, I am rather confused with this `visible whiteouts.' -But a user who originally requested this feature wrote a nice how-to -document about this feature. See Tips file in the aufs CVS tree. - -.\" ---------------------------------------------------------------------- -.SH Module Parameters -.TP -.B nwkq=N -The number of kernel thread named \*[AUFS_WKQ_NAME]. - -Those threads stay in the system while the aufs module is loaded, -and handle the special I/O requests from aufs. -The default value is \*[AUFS_NWKQ_DEF]. - -The special I/O requests from aufs include a part of copy-up, lookup, -directory handling, pseudo-link, xino file operations and the -delegated access to branches. -For example, Unix filesystems allow you to rmdir(2) which has no write -permission bit, if its parent directory has write permission bit. In aufs, the -removing directory may or may not have whiteout or `dir opaque' mark as its -child. And aufs needs to unlink(2) them before rmdir(2). -Therefore aufs delegates the actual unlink(2) and rmdir(2) to another kernel -thread which has been created already and has a superuser privilege. - -If you enable CONFIG_SYSFS, you can check this value through -<sysfs>/module/aufs/parameters/nwkq. - -. -.TP -.B brs=1 | 0 -Specifies to use the branch path data file under sysfs or not. - -If the number of your branches is large or their path is long -and you meet the limitation of mount(8) ro /etc/mtab, you need to -enable CONFIG_SYSFS and set aufs module parameter brs=1. - -When this parameter is set as 1, aufs does not show `br:' (or dirs=) -mount option through /proc/mounts (and /etc/mtab). So you can -keep yourself from the page limitation of -mount(8) or /etc/mtab. -Aufs shows branch paths through <sysfs>/fs/aufs/si_XXX/brNNN. -Actually the file under sysfs has also a size limitation, but I don't -think it is harmful. - -There is one more side effect in setting 1 to this parameter. -If you rename your branch, the branch path written in /etc/mtab will be -obsoleted and the future remount will meet some error due to the -unmatched parameters (Remember that mount(8) may take the options from -/etc/mtab and pass them to the systemcall). -If you set 1, /etc/mtab will not hold the branch path and you will not -meet such trouble. On the other hand, the entries for the -branch path under sysfs are generated dynamically. So it must not be obsoleted. -But I don't think users want to rename branches so often. - -If CONFIG_SYSFS is disable, this parameter is always set to 0. -. -.TP -.B sysrq=key -Specifies MagicSysRq key for debugging aufs. -You need to enable both of CONFIG_MAGIC_SYSRQ and CONFIG_AUFS_DEBUG. -Currently this is for developers only. -The default is `a'. -. -.TP -.B debug= 0 | 1 -Specifies disable(0) or enable(1) debug print in aufs. -This parameter can be changed dynamically. -You need to enable CONFIG_AUFS_DEBUG. -Currently this is for developers only. -The default is `0' (disable). - -.\" ---------------------------------------------------------------------- -.SH Entries under Sysfs and Debugfs -See linux/Documentation/ABI/*/{sys,debug}fs-aufs. - -.\" ---------------------------------------------------------------------- -.SH Branch Syntax -.TP -.B dir_path[ =permission [ + attribute ] ] -.TQ -.B permission := rw | ro | rr -.TQ -.B attribute := wh | nolwh -dir_path is a directory path. -The keyword after `dir_path=' is a -permission flags for that branch. -Comma, colon and the permission flags string (including `=')in the path -are not allowed. - -Any filesystem can be a branch, But some are not accepted such like -sysfs, procfs and unionfs. -If you specify such filesystems as an aufs branch, aufs will return an error -saying it is unsupported. - -Cramfs in linux stable release has strange inodes and it makes aufs -confused. For example, -.nf -$ mkdir -p w/d1 w/d2 -$ > w/z1 -$ > w/z2 -$ mkcramfs w cramfs -$ sudo mount -t cramfs -o ro,loop cramfs /mnt -$ find /mnt -ls - 76 1 drwxr-xr-x 1 jro 232 64 Jan 1 1970 /mnt - 1 1 drwxr-xr-x 1 jro 232 0 Jan 1 1970 /mnt/d1 - 1 1 drwxr-xr-x 1 jro 232 0 Jan 1 1970 /mnt/d2 - 1 1 -rw-r--r-- 1 jro 232 0 Jan 1 1970 /mnt/z1 - 1 1 -rw-r--r-- 1 jro 232 0 Jan 1 1970 /mnt/z2 -.fi - -All these two directories and two files have the same inode with one -as their link count. Aufs cannot handle such inode correctly. -Currently, aufs involves a tiny workaround for such inodes. But some -applications may not work correctly since aufs inode number for such -inode will change silently. -If you do not have any empty files, empty directories or special files, -inodes on cramfs will be all fine. - -A branch should not be shared as the writable branch between multiple -aufs. A readonly branch can be shared. - -The maximum number of branches is configurable at compile time (127 by -default). - -When an unknown permission or attribute is given, aufs sets ro to that -branch silently. - -.SS Permission -. -.TP -.B rw -Readable and writable branch. Set as default for the first branch. -If the branch filesystem is mounted as readonly, you cannot set it `rw.' -.\" A filesystem which does not support link(2) and i_op\->setattr(), for -.\" example FAT, will not be used as the writable branch. -. -.TP -.B ro -Readonly branch and it has no whiteouts on it. -Set as default for all branches except the first one. Aufs never issue -both of write operation and lookup operation for whiteout to this branch. -. -.TP -.B rr -Real readonly branch, special case of `ro', for natively readonly -branch. Assuming the branch is natively readonly, aufs can optimize -some internal operation. For example, if you specify `udba=inotify' -option, aufs does not set inotify for the things on rr branch. -Set by default for a branch whose fs-type is either `iso9660', -`cramfs' or `romfs' (and `squashfs' for linux\-2.6.29 and later). - -When your branch exists on slower device and you have some -capacity on your hdd, you may want to try ulobdev tool in ULOOP sample. -It can cache the contents of the real devices on another faster device, -so you will be able to get the better access performance. -The ulobdev tool is for a generic block device, and the ulohttp is for a -filesystem image on http server. -If you want to spin down your hdd to save the -battery life or something, then you may want to use ulobdev to save the -access to the hdd, too. -See $AufsCVS/sample/uloop in detail. - -.SS Attribute -. -.TP -.B wh -Readonly branch and it has/might have whiteouts on it. -Aufs never issue write operation to this branch, but lookup for whiteout. -Use this as `<branch_dir>=ro+wh'. -. -.TP -.B nolwh -Usually, aufs creates a whiteout as a hardlink on a writable -branch. This attributes prohibits aufs to create the hardlinked -whiteout, including the source file of all hardlinked whiteout -(\*[AUFS_WH_BASE].) -If you do not like a hardlink, or your writable branch does not support -link(2), then use this attribute. -But I am afraid a filesystem which does not support link(2) natively -will fail in other place such as copy-up. -Use this as `<branch_dir>=rw+nolwh'. -Also you may want to try `noplink' mount option, while it is not recommended. - -.\" .SS FUSE as a branch -.\" A FUSE branch needs special attention. -.\" The struct fuse_operations has a statfs operation. It is OK, but the -.\" parameter is struct statvfs* instead of struct statfs*. So almost -.\" all user\-space implementation will call statvfs(3)/fstatvfs(3) instead of -.\" statfs(2)/fstatfs(2). -.\" In glibc, [f]statvfs(3) issues [f]statfs(2), open(2)/read(2) for -.\" /proc/mounts, -.\" and stat(2) for the mountpoint. With this situation, a FUSE branch will -.\" cause a deadlock in creating something in aufs. Here is a sample -.\" scenario, -.\" .\" .RS -.\" .\" .IN -10 -.\" .Bu -.\" create/modify a file just under the aufs root dir. -.\" .Bu -.\" aufs acquires a write\-lock for the parent directory, ie. the root dir. -.\" .Bu -.\" A library function or fuse internal may call statfs for a fuse branch. -.\" The create=mfs mode in aufs will surely call statfs for each writable -.\" branches. -.\" .Bu -.\" FUSE in kernel\-space converts and redirects the statfs request to the -.\" user\-space. -.\" .Bu -.\" the user\-space statfs handler will call [f]statvfs(3). -.\" .Bu -.\" the [f]statvfs(3) in glibc will access /proc/mounts and issue -.\" stat(2) for the mountpoint. But those require a read\-lock for the aufs -.\" root directory. -.\" .Bu -.\" Then a deadlock occurs. -.\" .\" .RE 1 -.\" .\" .IN -.\" -.\" In order to avoid this deadlock, I would suggest not to call -.\" [f]statvfs(3) from fuse. Here is a sample code to do this. -.\" .nf -.\" struct statvfs stvfs; -.\" -.\" main() -.\" { -.\" statvfs(..., &stvfs) -.\" or -.\" fstatvfs(..., &stvfs) -.\" stvfs.f_fsid = 0 -.\" } -.\" -.\" statfs_handler(const char *path, struct statvfs *arg) -.\" { -.\" struct statfs stfs -.\" -.\" memcpy(arg, &stvfs, sizeof(stvfs)) -.\" -.\" statfs(..., &stfs) -.\" or -.\" fstatfs(..., &stfs) -.\" -.\" arg->f_bfree = stfs.f_bfree -.\" arg->f_bavail = stfs.f_bavail -.\" arg->f_ffree = stfs.f_ffree -.\" arg->f_favail = /* any value */ -.\" } -.\" .fi - -.\" ---------------------------------------------------------------------- -.SH External Inode Number Bitmap, Translation Table and Generation Table (xino) -Aufs uses one external bitmap file and one external inode number -translation table files per an aufs and per a branch -filesystem by default. -Additionally when CONFIG_AUFS_EXPORT is enabled, one external inode -generation table is added. -The bitmap (and the generation table) is for recycling aufs inode number -and the others -are a table for converting an inode number on a branch to -an aufs inode number. The default path -is `first writable branch'/\*[AUFS_XINO_FNAME]. -If there is no writable branch, the -default path -will be \*[AUFS_XINO_DEFPATH]. -.\" A user who executes mount(8) needs the privilege to create xino -.\" file. - -If you enable CONFIG_SYSFS, the path of xino files are not shown in -/proc/mounts (and /etc/mtab), instead it is shown in -<sysfs>/fs/aufs/si_<id>/xi_path. -Otherwise, it is shown in /proc/mounts unless it is not the default -path. - -Those files are always opened and read/write by aufs frequently. -If your writable branch is on flash memory device, it is recommended -to put xino files on other than flash memory by specifying `xino=' -mount option. - -The -maximum file size of the bitmap is, basically, the amount of the -number of all the files on all branches divided by 8 (the number of -bits in a byte). -For example, on a 4KB page size system, if you have 32,768 (or -2,599,968) files in aufs world, -then the maximum file size of the bitmap is 4KB (or 320KB). - -The -maximum file size of the table will -be `max inode number on the branch x size of an inode number'. -For example in 32bit environment, - -.nf -$ df -i /branch_fs -/dev/hda14 2599968 203127 2396841 8% /branch_fs -.fi - -and /branch_fs is an branch of the aufs. When the inode number is -assigned contiguously (without `hole'), the maximum xino file size for -/branch_fs will be 2,599,968 x 4 bytes = about 10 MB. But it might not be -allocated all of disk blocks. -When the inode number is assigned discontinuously, the maximum size of -xino file will be the largest inode number on a branch x 4 bytes. -Additionally, the file size is limited to LLONG_MAX or the s_maxbytes -in filesystem's superblock (s_maxbytes may be smaller than -LLONG_MAX). So the -support-able largest inode number on a branch is less than -2305843009213693950 (LLONG_MAX/4\-1). -This is the current limitation of aufs. -On 64bit environment, this limitation becomes more strict and the -supported largest inode number is less than LLONG_MAX/8\-1. - -The xino files are always hidden, i.e. removed. So you cannot -do `ls \-l xino_file'. -If you enable CONFIG_DEBUG_FS, you can check these information through -<debugfs>/aufs/<si_id>/{xib,xi[0-9]*,xigen}. xib is for the bitmap file, -xi0 ix for the first branch, and xi1 is for the next. xigen is for the -generation table. -xib and xigen are in the format of, - -.nf -<blocks>x<block size> <file size> -.fi - -Note that a filesystem usually has a -feature called pre-allocation, which means a number of -blocks are allocated automatically, and then deallocated -silently when the filesystem thinks they are unnecessary. -You do not have to be surprised the sudden changes of the number of -blocks, when your filesystem which xino files are placed supports the -pre-allocation feature. - -The rests are hidden xino file information in the format of, - -.nf -<file count>, <blocks>x<block size> <file size> -.fi - -If the file count is larger than 1, it means some of your branches are -on the same filesystem and the xino file is shared by them. -Note that the file size may not be equal to the actual consuming blocks -since xino file is a sparse file, i.e. a hole in a file which does not -consume any disk blocks. - -Once you unmount aufs, the xino files for that aufs are totally gone. -It means that the inode number is not permanent across umount or -shutdown. - -The xino files should be created on the filesystem except NFS. -If your first writable branch is NFS, you will need to specify xino -file path other than NFS. -Also if you are going to remove the branch where xino files exist or -change the branch permission to readonly, you need to use xino option -before del/mod the branch. - -The bitmap file can be truncated. -For example, if you delete a branch which has huge number of files, -many inode numbers will be recycled and the bitmap will be truncated -to smaller size. Aufs does this automatically when a branch is -deleted. -You can truncate it anytime you like if you specify `trunc_xib' mount -option. But when the accessed inode number was not deleted, nothing -will be truncated. -If you do not want to truncate it (it may be slow) when you delete a -branch, specify `notrunc_xib' after `del' mount option. - -If you do not want to use xino, use noxino mount option. Use this -option with care, since the inode number may be changed silently and -unexpectedly anytime. -For example, -rmdir failure, recursive chmod/chown/etc to a large and deep directory -or anything else. -And some applications will not work correctly. -.\" When the inode number has been changed, your system -.\" can be crazy. -If you want to change the xino default path, use xino mount option. - -After you add branches, the persistence of inode number may not be -guaranteed. -At remount time, cached but unused inodes are discarded. -And the newly appeared inode may have different inode number at the -next access time. The inodes in use have the persistent inode number. - -When aufs assigned an inode number to a file, and if you create the -same named file on the upper branch directly, then the next time you -access the file, aufs may assign another inode number to the file even -if you use xino option. -Some applications may treat the file whose inode number has been -changed as totally different file. - -.\" ---------------------------------------------------------------------- -.SH Pseudo Link (hardlink over branches) -Aufs supports `pseudo link' which is a logical hard-link over -branches (cf. ln(1) and link(2)). -In other words, a copied-up file by link(2) and a copied-up file which was -hard-linked on a readonly branch filesystem. - -When you have files named fileA and fileB which are -hardlinked on a readonly branch, if you write something into fileA, -aufs copies-up fileA to a writable branch, and write(2) the originally -requested thing to the copied-up fileA. On the writable branch, -fileA is not hardlinked. -But aufs remembers it was hardlinked, and handles fileB as if it existed -on the writable branch, by referencing fileA's inode on the writable -branch as fileB's inode. - -Once you unmount aufs, the plink info for that aufs kept in memory are totally -gone. -It means that the pseudo-link is not permanent. -If you want to make plink permanent, try `auplink' utility just before -one of these operations, -unmounting your aufs, -using `ro' or `noplink' mount option, -deleting a branch from aufs, -adding a branch into aufs, -or changing your writable branch to readonly. - -This utility will reproduces all real hardlinks on a writable branch by linking -them, and removes pseudo-link info in memory and temporary link on the -writable branch. -Since this utility access your branches directly, you cannot hide them by -`mount \-\-bind /tmp /branch' or something. - -If you are willing to rebuild your aufs with the same branches later, you -should use auplink utility before you umount your aufs. -If you installed both of /sbin/mount.aufs and /sbin/umount.aufs, and your -mount(8) and umount(8) support them, -`auplink' utility will be executed automatically and flush pseudo-links. - -.nf -# auplink /your/aufs/root flush -# umount /your/aufs/root -or -# auplink /your/aufs/root flush -# mount -o remount,mod:/your/writable/branch=ro /your/aufs/root -or -# auplink /your/aufs/root flush -# mount -o remount,noplink /your/aufs/root -or -# auplink /your/aufs/root flush -# mount -o remount,del:/your/aufs/branch /your/aufs/root -or -# auplink /your/aufs/root flush -# mount -o remount,append:/your/aufs/branch /your/aufs/root -.fi - -The plinks are kept both in memory and on disk. When they consumes too much -resources on your system, you can use the `auplink' utility at anytime and -throw away the unnecessary pseudo-links in safe. - -Additionally, the `auplink' utility is very useful for some security reasons. -For example, when you have a directory whose permission flags -are 0700, and a file who is 0644 under the 0700 directory. Usually, -all files under the 0700 directory are private and no one else can see -the file. But when the directory is 0711 and someone else knows the 0644 -filename, he can read the file. - -Basically, aufs pseudo-link feature creates a temporary link under the -directory whose owner is root and the permission flags are 0700. -But when the writable branch is NFS, aufs sets 0711 to the directory. -When the 0644 file is pseudo-linked, the temporary link, of course the -contents of the file is totally equivalent, will be created under the -0711 directory. The filename will be generated by its inode number. -While it is hard to know the generated filename, someone else may try peeping -the temporary pseudo-linked file by his software tool which may try the name -from one to MAX_INT or something. -In this case, the 0644 file will be read unexpectedly. -I am afraid that leaving the temporary pseudo-links can be a security hole. -It makes sense to execute `auplink /your/aufs/root flush' -periodically, when your writable branch is NFS. - -When your writable branch is not NFS, or all users are careful enough to set 0600 -to their private files, you do not have to worry about this issue. - -If you do not want this feature, use `noplink' mount option. - -.SS The behaviours of plink and noplink -This sample shows that the `f_src_linked2' with `noplink' option cannot follow -the link. - -.nf -none on /dev/shm/u type aufs (rw,xino=/dev/shm/rw/.aufs.xino,br:/dev/shm/rw=rw:/dev/shm/ro=ro) -$ ls -li ../r?/f_src_linked* ./f_src_linked* ./copied -ls: ./copied: No such file or directory -15 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked -15 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked2 -22 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ./f_src_linked -22 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ./f_src_linked2 -$ echo abc >> f_src_linked -$ cp f_src_linked copied -$ ls -li ../r?/f_src_linked* ./f_src_linked* ./copied -15 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked -15 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked2 -36 -rw-r--r-- 2 jro jro 6 Dec 22 11:03 ../rw/f_src_linked -53 -rw-r--r-- 1 jro jro 6 Dec 22 11:03 ./copied -22 -rw-r--r-- 2 jro jro 6 Dec 22 11:03 ./f_src_linked -22 -rw-r--r-- 2 jro jro 6 Dec 22 11:03 ./f_src_linked2 -$ cmp copied f_src_linked2 -$ - -none on /dev/shm/u type aufs (rw,xino=/dev/shm/rw/.aufs.xino,noplink,br:/dev/shm/rw=rw:/dev/shm/ro=ro) -$ ls -li ../r?/f_src_linked* ./f_src_linked* ./copied -ls: ./copied: No such file or directory -17 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked -17 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked2 -23 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ./f_src_linked -23 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ./f_src_linked2 -$ echo abc >> f_src_linked -$ cp f_src_linked copied -$ ls -li ../r?/f_src_linked* ./f_src_linked* ./copied -17 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked -17 -rw-r--r-- 2 jro jro 2 Dec 22 11:03 ../ro/f_src_linked2 -36 -rw-r--r-- 1 jro jro 6 Dec 22 11:03 ../rw/f_src_linked -53 -rw-r--r-- 1 jro jro 6 Dec 22 11:03 ./copied -23 -rw-r--r-- 2 jro jro 6 Dec 22 11:03 ./f_src_linked -23 -rw-r--r-- 2 jro jro 6 Dec 22 11:03 ./f_src_linked2 -$ cmp copied f_src_linked2 -cmp: EOF on f_src_linked2 -$ -.fi - -.\" -.\" If you add/del a branch, or link/unlink the pseudo-linked -.\" file on a branch -.\" directly, aufs cannot keep the correct link count, but the status of -.\" `pseudo-linked.' -.\" Those files may or may not keep the file data after you unlink the -.\" file on the branch directly, especially the case of your branch is -.\" NFS. - -If you add a branch which has fileA or fileB, aufs does not follow the -pseudo link. The file on the added branch has no relation to the same -named file(s) on the lower branch(es). -If you use noxino mount option, pseudo link will not work after the -kernel shrinks the inode cache. - -This feature will not work for squashfs before version 3.2 since its -inode is tricky. -When the inode is hardlinked, squashfs inodes has the same inode -number and correct link count, but the inode memory object is -different. Squashfs inodes (before v3.2) are generated for each, even -they are hardlinked. - -.\" ---------------------------------------------------------------------- -.SH User's Direct Branch Access (UDBA) -UDBA means a modification to a branch filesystem manually or directly, -e.g. bypassing aufs. -While aufs is designed and implemented to be safe after UDBA, -it can make yourself and your aufs confused. And some information like -aufs inode will be incorrect. -For example, if you rename a file on a branch directly, the file on -aufs may -or may not be accessible through both of old and new name. -Because aufs caches various information about the files on -branches. And the cache still remains after UDBA. - -Aufs has a mount option named `udba' which specifies the test level at -access time whether UDBA was happened or not. -. -.TP -.B udba=none -Aufs trusts the dentry and the inode cache on the system, and never -test about UDBA. With this option, aufs runs fastest, but it may show -you incorrect data. -Additionally, if you often modify a branch -directly, aufs will not be able to trace the changes of inodes on the -branch. It can be a cause of wrong behaviour, deadlock or anything else. - -It is recommended to use this option only when you are sure that -nobody access a file on a branch. -It might be difficult for you to achieve real `no UDBA' world when you -cannot stop your users doing `find / \-ls' or something. -If you really want to forbid all of your users to UDBA, here is a trick -for it. -With this trick, users cannot see the -branches directly and aufs runs with no problem, except `auplink' utility. -But if you are not familiar with aufs, this trick may make -yourself confused. - -.nf -# d=/tmp/.aufs.hide -# mkdir $d -# for i in $branches_you_want_to_hide -> do -> mount -n --bind $d $i -> done -.fi - -When you unmount the aufs, delete/modify the branch by remount, or you -want to show the hidden branches again, unmount the bound -/tmp/.aufs.hide. - -.nf -# umount -n $branches_you_want_to_unbound -.fi - -If you use FUSE filesystem as an aufs branch which supports hardlink, -you should not set this option, since FUSE makes inode objects for -each hardlinks (at least in linux\-2.6.23). When your FUSE filesystem -maintains them at link/unlinking, it is equivalent -to `direct branch access' for aufs. - -. -.TP -.B udba=reval -Aufs tests only the existence of the file which existed. If -the existed file was removed on the branch directly, aufs -discard the cache about the file and -re-lookup it. So the data will be updated. -This test is at minimum level to keep the performance and ensure the -existence of a file. -This is default and aufs runs still fast. - -This rule leads to some unexpected situation, but I hope it is -harmless. Those are totally depends upon cache. Here are just a few -examples. -. -.RS -.Bu -If the file is cached as negative or -not-existed, aufs does not test it. And the file is still handled as -negative after a user created the file on a branch directly. If the -file is not cached, aufs will lookup normally and find the file. -. -.Bu -When the file is cached as positive or existed, and a user created the -same named file directly on the upper branch. Aufs detects the cached -inode of the file is still existing and will show you the old (cached) -file which is on the lower branch. -. -.Bu -When the file is cached as positive or existed, and a user renamed the -file by rename(2) directly. Aufs detects the inode of the file is -still existing. You may or may not see both of the old and new files. -Todo: If aufs also tests the name, we can detect this case. -.RE - -If your outer modification (UDBA) is rare and you can ignore the -temporary and minor differences between virtual aufs world and real -branch filesystem, then try this mount option. -. -.TP -.B udba=inotify -Aufs sets `inotify' to all the accessed directories on its branches -and receives the event about the dir a |