From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 0B5FBBC380 for ; Thu, 28 Mar 2024 13:38:43 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 59906A103 for ; Thu, 28 Mar 2024 13:37:51 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS for ; Thu, 28 Mar 2024 13:37:50 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id E41F44170C for ; Thu, 28 Mar 2024 13:37:49 +0100 (CET) From: Christian Ebner To: pbs-devel@lists.proxmox.com Date: Thu, 28 Mar 2024 13:37:04 +0100 Message-Id: <20240328123707.336951-56-c.ebner@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240328123707.336951-1-c.ebner@proxmox.com> References: <20240328123707.336951-1-c.ebner@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.371 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_ASCII_DIVIDERS 0.8 Email that uses ascii formatting dividers and possible spam tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pbs-devel] [PATCH v3 proxmox-backup 55/58] docs: describe file format for split payload files X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 28 Mar 2024 12:38:43 -0000 Signed-off-by: Christian Ebner --- changes since version 2: - not present in previous version docs/file-formats.rst | 32 ++++++++++++++++++++++ docs/meta-format-overview.dot | 50 +++++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/meta-format-overview.dot diff --git a/docs/file-formats.rst b/docs/file-formats.rst index 43ecfefce..292660579 100644 --- a/docs/file-formats.rst +++ b/docs/file-formats.rst @@ -8,6 +8,38 @@ Proxmox File Archive Format (``.pxar``) .. graphviz:: pxar-format-overview.dot +.. _pxar-meta-format: + +Proxmox File Archive Format - Meta (``.mpxar``) +----------------------------------------------- + +.. graphviz:: meta-format-overview.dot + +.. _ppxar-format: + +Proxmox File Archive Format - Payload (``.ppxar``) +-------------------------------------------------- + +The pxar payload contains a concatenation of regular file payloads, +each prefixed by a `PAYLOAD` header. Further, the entries can have +some padding following the actual payload, if a referenced chunk was +not fully reused: + +.. list-table:: + :widths: auto + + * - ``PAYLOAD_START_MARKER`` + - ``[u8; 16]`` + * - ``PAYLOAD`` + - ``header with [u8; 16]`` + * - ``Payload`` + - ``raw regular file payload`` + * - ``Padding`` + - ``none if chunk fully reused`` + * - ``...`` + - ``Further list of header, payload and padding`` + * - ``PAYLOAD_TAIL_MARKER`` + - ``[u8; 16]`` .. _data-blob-format: diff --git a/docs/meta-format-overview.dot b/docs/meta-format-overview.dot new file mode 100644 index 000000000..c3e4869b3 --- /dev/null +++ b/docs/meta-format-overview.dot @@ -0,0 +1,50 @@ +digraph g { +graph [ +rankdir = "LR" +fontname="Helvetica" +]; +node [ +fontsize = "16" +shape = "record" +]; +edge [ +]; + +"archive" [ +label = "archive.mpxar" +shape = "record" +]; + +"rootdir" [ +label = " FORMAT_VERSION | CLI_PARAMS | ENTRY| \{XATTR\}\* extended attribute list\l | \{ACL_USER\}\* USER ACL entries\l | \{ACL_GROUP\}\* GROUP ACL entries\l| \[ACL_GROUP_OBJ\] the ACL_GROUP_OBJ \l| \[ACL_DEFAULT\] the various default ACL fields\l|\{ACL_DEFAULT_USER\}\* USER ACL entries\l|\{ACL_DEFAULT_GROUP\}\* GROUP ACL entries\l|\[FCAPS\] file capability in Linux disk format\l|\[QUOTA_PROJECT_ID\] the ext4/xfs quota project ID\l| { PAYLOAD_REF | SYMLINK | DEVICE | { \{DirectoryEntries\}\* | GOODBYE}}" +shape = "record" +]; + + +"entry" [ +label = " size: u64 = 64\l|type: u64 = ENTRY\l|feature_flags: u64\l|mode: u64\l|flags: u64\l|uid: u64\l|gid: u64\l|mtime: u64\l" +labeljust = "l" +shape = "record" +]; + + + +"direntry" [ +label = " FILENAME |{ENTRY | HARDLINK}" +shape = "record" +]; + +"payloadrefentry" [ +label = " offset: u64 \l| size: u64\l" +shape = "record" +]; + +"archive" -> "rootdir":f0 + +"rootdir":f0 -> "entry":f0 + +"rootdir":de -> "direntry":f0 + +"rootdir":pl -> "payloadrefentry":f0 + +} -- 2.39.2