Skip to content

Commit

Permalink
layer: clarify attributes for implied directories
Browse files Browse the repository at this point in the history
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 <bneergaard@mirantis.com>
  • Loading branch information
neersighted committed Nov 8, 2022
1 parent 4df8887 commit 33d07f3
Showing 1 changed file with 14 additions and 0 deletions.
14 changes: 14 additions & 0 deletions layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

#### Implied Directories

As the tar format describes directory hierarchies using a flat datastructure, it is possible to have so-called "implied directories" where not all parent directories implied by an entries' path in the archive have their own entry.

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 Unix epoch (`0`)
* `uid` is set to the `0`
* `gid` is set to the `0`
* `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.
Expand Down

0 comments on commit 33d07f3

Please sign in to comment.