src/pxar/mod.rs

   1 //! *pxar* Implementation (proxmox file archive format)
   2 //!
   3 //! This code implements a slightly modified version of the *catar*
   4 //! format used in the [casync](https://github.com/systemd/casync)
   5 //! toolkit (we are not 100\% binary compatible). It is a file archive
   6 //! format defined by 'Lennart Poettering', specially defined for
   7 //! efficient deduplication.
   8
   9 //! Every archive contains items in the following order:
  10 //!  * `ENTRY`              -- containing general stat() data and related bits
  11 //!   * `USER`              -- user name as text, if enabled
  12 //!   * `GROUP`             -- group name as text, if enabled
  13 //!   * `XATTR`             -- one extended attribute
  14 //!   * ...                 -- more of these when there are multiple defined
  15 //!   * `ACL_USER`          -- one `USER ACL` entry
  16 //!   * ...                 -- more of these when there are multiple defined
  17 //!   * `ACL_GROUP`         -- one `GROUP ACL` entry
  18 //!   * ...                 -- more of these when there are multiple defined
  19 //!   * `ACL_GROUP_OBJ`     -- The `ACL_GROUP_OBJ`
  20 //!   * `ACL_DEFAULT`       -- The various default ACL fields if there's one defined
  21 //!   * `ACL_DEFAULT_USER`  -- one USER ACL entry
  22 //!   * ...                 -- more of these when multiple are defined
  23 //!   * `ACL_DEFAULT_GROUP` -- one GROUP ACL entry
  24 //!   * ...                 -- more of these when multiple are defined
  25 //!   * `FCAPS`             -- file capability in Linux disk format
  26 //!   * `QUOTA_PROJECT_ID`  -- the ext4/xfs quota project ID
  27 //!   * `PAYLOAD`           -- file contents, if it is one
  28 //!   * `SYMLINK`           -- symlink target, if it is one
  29 //!   * `DEVICE`            -- device major/minor, if it is a block/char device
  30 //!
  31 //!   If we are serializing a directory, then this is followed by:
  32 //!
  33 //!   * `FILENAME`          -- name of the first directory entry (strictly ordered!)
  34 //!   * `<archive>`         -- serialization of the first directory entry's metadata and contents,
  35 //!  following the exact same archive format
  36 //!   * `FILENAME`          -- name of the second directory entry (strictly ordered!)
  37 //!   * `<archive>`         -- serialization of the second directory entry
  38 //!   * ...
  39 //!   * `GOODBYE`           -- lookup table at the end of a list of directory entries
  40
  41 //!
  42 //! The original format has no way to deal with hardlinks, so we
  43 //! extended the format by a special `HARDLINK` tag, which can replace
  44 //! an `ENTRY` tag. The `HARDLINK` tag contains an 64bit offset which
  45 //! points to the linked `ENTRY` inside the archive, followed by the
  46 //! full path name of that `ENTRY`. `HARDLINK`s may not have further data
  47 //! (user, group, acl, ...) because this is already defined by the
  48 //! linked `ENTRY`.
  49
  50 pub mod catalog;
  51 pub(crate) mod create;
  52 pub(crate) mod dir_stack;
  53 pub(crate) mod extract;
  54 pub(crate) mod metadata;
  55 pub mod fuse;
  56 pub(crate) mod tools;
  57
  58 mod flags;
  59 pub use flags::Flags;
  60
  61 pub use create::{create_archive, PxarCreateOptions};
  62 pub use extract::{extract_archive, ErrorHandler};
  63
  64 /// The format requires to build sorted directory lookup tables in
  65 /// memory, so we restrict the number of allowed entries to limit
  66 /// maximum memory usage.
  67 pub const ENCODER_MAX_ENTRIES: usize = 1024 * 1024;
  68
  69 pub use tools::{format_multi_line_entry, format_single_line_entry};