From 4b4cc62e7ddfa4cfff6be16f3e09c48a95fa539a Mon Sep 17 00:00:00 2001 From: Bjorn Neergaard Date: Wed, 2 Nov 2022 14:49:49 -0600 Subject: [PATCH] layer: clarify attributes for implied directories The image specification currently does not describe how conformant implementations should handle the case of a layer that contains "implied directories" -- entries that imply parent directories exist through their path, without those parent directories having their own entires in the archive. As such, this behavior is currently implementation-defined and may not be consistent, even in the same implementation (e.g. moby/moby#44106). To resolve this, we explicitly define what behavior is expected in this situation, selecting 'neutral' attributes (e.g. using the container `USER`'s UID/GID, and using `0755` for mode, as derived from the default `umask(2)` of 0022). Signed-off-by: Bjorn Neergaard --- layer.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/layer.md b/layer.md index 533a427cb..900d8aab9 100644 --- a/layer.md +++ b/layer.md @@ -61,6 +61,20 @@ Where supported, MUST include file attributes for Additions and Modifications in [Sparse files](https://en.wikipedia.org/wiki/Sparse_file) SHOULD NOT be used because they lack consistent support across tar implementations. +#### Implicit Directories + +As the tar format describes filesystem layouts using a flat datastructure, it is possible to have so-called "implicit directories" where not all parent directories implied an entries' path in the archive exist. + +When applying a layer, implementations MUST create any parent directories implied by an entries' path, even if it is otherwise absent from the archive. Attributes of the created parent directories MUST be set as follows: + +* `mtime` is set to the current `time(2)` +* `uid` is set to the container `USER`'s UID +* `gid` is set to the container `USER`'s GID +* `mode` is set to `0755` +* `xattrs` are empty + +Layer authors SHOULD ensure directory entries are fully present for all directory hierarchies in their layers, as previous versions of this specification did not specify this behavior and results may be implementation defined. + #### Hardlinks * Hardlinks are a [POSIX concept](https://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html) for having one or more directory entries for the same file on the same device.