5.11 Determinism

3 min read

To make a package byte-reproducible (§5.10), the tar archive MUST obey every rule below. A consumer MUST reject a package that violates any of them.

  1. Tar entries MUST be ordered lexicographically by the entry name as written into the tar header, compared byte-for-byte over its UTF-8 bytes. A directory's entry name carries a trailing /, and that slash participates in the comparison.
  2. Every entry's modification time MUST equal the value of build.timestamp in the manifest (§5.18), which MUST NOT carry sub-second precision.
  3. Every entry's owner numeric ID and group numeric ID MUST be 0.
  4. Every entry's owner name and group name MUST be the string root.
  5. Entries MUST NOT carry extended attributes. Security descriptors are applied at file-creation time (§5.20), never through tar attributes; other install-time attributes are applied through side-effect declarations (§5.24) or by higher-level mechanisms outside this specification.
  6. Entry permission bits MUST be 0777 for every entry, with the setuid and setgid bits cleared (§5.16).
  7. PAX extended header records, when present, MUST appear in a fixed canonical order: path first, then linkpath if present, then any other record sorted by record name lexicographically.
  8. The tar header magic MUST be ustar\0 and the version MUST be 00.
  9. The devmajor and devminor header fields MUST be 0 for every entry type this specification permits — none of which is a device entry.
  10. Header padding bytes MUST be NUL (0x00).
  11. PAX global header records (typeflag g) MUST NOT appear.
  12. PAX extended header records (typeflag x) MUST appear only when an entry's path exceeds the ustar 100-byte limit, in which case a path record is emitted, or its linkname exceeds that limit, in which case a linkpath record is emitted. A record with any other key MUST NOT be emitted.
  13. A path exceeding the ustar 100-byte limit MUST be carried by a path record. The ustar prefix field MUST NOT be used to split such a path across prefix and name.
  14. An extended header entry's own name MUST be the containing directory's path, then PaxHeaders.0/, then the base name of the entry it describes. For an entry at the archive root the directory part is absent.

Rules 13 and 14 exist because a tar library given a long path may legitimately choose either encoding, and either choice produces a different byte stream from the same input. Determinism requires the choice be made here rather than by whichever library a producer reached for.

Edit this page