Skip to content

Commit f436a41

Browse files
AkihiroSudathaJeztah
AkihiroSuda
authored and
thaJeztah
committed
Add a note about the open(2) and rename(2) on AUFS and OverlayFS
Close moby#25409 Update moby#10180 Signed-off-by: Akihiro Suda <[email protected]> (cherry picked from commit aab101a) Signed-off-by: Sebastiaan van Stijn <[email protected]>
1 parent fc8a0f4 commit f436a41

2 files changed

Lines changed: 45 additions & 6 deletions

File tree

‎docs/userguide/storagedriver/aufs-driver.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,16 @@ a whiteout file in the container's top layer. This whiteout file effectively
9191
existence in the image's read-only layers. This works the same no matter which
9292
of the image's read-only layers the file exists in.
9393

94+
## Renaming directories with the AUFS storage driver
95+
96+
Calling `rename(2)` for a directory is not fully supported on AUFS. It returns
97+
`EXDEV` ("cross-device link not permitted"), even when both of the source and
98+
the destination path are on a same AUFS layer, unless the directory has no
99+
children.
100+
101+
So your application has to be designed so that it can handle `EXDEV` and fall
102+
back to a "copy and unlink" strategy.
103+
94104
## Configure Docker with AUFS
95105

96106
You can only use the AUFS storage driver on Linux systems with AUFS installed.
@@ -211,6 +221,13 @@ any of the potential overheads introduced by thin provisioning and
211221
copy-on-write. For this reason, you may want to place heavy write workloads on
212222
data volumes.
213223

224+
## AUFS compatibility
225+
226+
To summarize the AUFS's aspect which is incompatible with other filesystems:
227+
228+
- The AUFS does not fully support the `rename(2)` system call. Your application
229+
needs to detect its failure and fall back to a "copy and unlink" strategy.
230+
214231
## Related information
215232

216233
* [Understand images, containers, and storage drivers](imagesandcontainers.md)

‎docs/userguide/storagedriver/overlayfs-driver.md‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,13 @@ file in the image layer ("lowerdir") is not deleted. However, the whiteout file
301301
created in the "upperdir". This has the same effect as a whiteout file and
302302
effectively masks the existence of the directory in the image's "lowerdir".
303303

304+
- **Renaming directories**. Calling `rename(2)` for a directory is allowed only
305+
when both of the source and the destination path are on the top layer.
306+
Otherwise, it returns `EXDEV` ("cross-device link not permitted").
307+
308+
So your application has to be designed so that it can handle `EXDEV` and fall
309+
back to a "copy and unlink" strategy.
310+
304311
## Configure Docker with the `overlay`/`overlay2` storage driver
305312

306313
To configure Docker to use the `overlay` storage driver your Docker host must be
@@ -386,12 +393,6 @@ large. However, once the file has been copied up, all subsequent writes to that
386393
with AUFS. This is because AUFS supports more layers than OverlayFS and it is
387394
possible to incur far larger latencies if searching through many AUFS layers.
388395

389-
- **RPMs and Yum**. OverlayFS only implements a subset of the POSIX standards.
390-
This can result in certain OverlayFS operations breaking POSIX standards. One
391-
such operation is the *copy-up* operation. Therefore, using `yum` inside of a
392-
container on a Docker host using the `overlay`/`overlay2` storage drivers is
393-
unlikely to work without implementing workarounds.
394-
395396
- **Inode limits**. Use of the `overlay` storage driver can cause excessive
396397
inode consumption. This is especially so as the number of images and containers
397398
on the Docker host grows. A Docker host with a large number of images and lots
@@ -413,3 +414,24 @@ performance. This is because they bypass the storage driver and do not incur
413414
any of the potential overheads introduced by thin provisioning and
414415
copy-on-write. For this reason, you should place heavy write workloads on data
415416
volumes.
417+
418+
## OverlayFS compatibility
419+
To summarize the OverlayFS's aspect which is incompatible with other
420+
filesystems:
421+
422+
- **open(2)**. OverlayFS only implements a subset of the POSIX standards.
423+
This can result in certain OverlayFS operations breaking POSIX standards. One
424+
such operation is the *copy-up* operation. Suppose that your application calls
425+
`fd1=open("foo", O_RDONLY)` and then `fd2=open("foo", O_RDWR)`. In this case,
426+
your application expects `fd1` and `fd2` to refer to the same file. However, due
427+
to a copy-up operation that occurs after the first calling to `open(2)`, the
428+
descriptors refer to different files.
429+
430+
`yum` is known to be affected unless the `yum-plugin-ovl` package is installed.
431+
If the `yum-plugin-ovl` package is not available in your distribution (e.g.
432+
RHEL/CentOS prior to 6.8 or 7.2), you may need to run `touch /var/lib/rpm/*`
433+
before running `yum install`.
434+
435+
- **rename(2)**. OverlayFS does not fully support the `rename(2)` system call.
436+
Your application needs to detect its failure and fall back to a "copy and
437+
unlink" strategy.

0 commit comments

Comments
 (0)