From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id A31AE1FF15C for ; Wed, 26 Mar 2025 15:22:10 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 9170639530; Wed, 26 Mar 2025 15:21:50 +0100 (CET) From: Max Carrara To: pve-devel@lists.proxmox.com Date: Wed, 26 Mar 2025 15:20:59 +0100 Message-Id: <20250326142059.261938-9-m.carrara@proxmox.com> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20250326142059.261938-1-m.carrara@proxmox.com> References: <20250326142059.261938-1-m.carrara@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.074 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_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: [pve-devel] [PATCH v1 pve-storage 8/8] pluginbase: document import and export methods X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" Adapt the previous description, slightly rewording it and formatting it for POD under the IMPORTS AND EXPORTS section. Also add docstrings for the following methods: - volume_export - volume_export_formats - volume_import - volume_import_formats Signed-off-by: Max Carrara Co-authored-by: Maximiliano Sandoval --- src/PVE/Storage/PluginBase.pm | 134 ++++++++++++++++++++++++++-------- 1 file changed, 105 insertions(+), 29 deletions(-) diff --git a/src/PVE/Storage/PluginBase.pm b/src/PVE/Storage/PluginBase.pm index a1bfc8d..cfa5087 100644 --- a/src/PVE/Storage/PluginBase.pm +++ b/src/PVE/Storage/PluginBase.pm @@ -1345,55 +1345,131 @@ sub prune_backups { =head2 IMPORTS AND EXPORTS +Any path-based storage is assumed to support C and C streams, so +the default implementations in C> will return this if +C<< $scfg->{path} >> is set (thereby mimicking the old C<< PVE::Storage::storage_migrate() >> +function). + +Plugins may fall back to methods like C, C, etc. +of C> in case the format doesn't match their +specialized implementations to reuse the C/C code. + +=head3 FORMATS + +The following formats are all prefixed with image information in the form of a +64 bit little endian unsigned integer (C<< pack('Q\<') >>) in order to be able +to preallocate the image on storages which require it. + +=over + +=item * C<< raw+size >> (image files only) + +A raw binary data stream as produced via C<< dd if=$IMAGE_FILE >>. + +=item * C<< qcow2+size >>, C<< vmdk >> (image files only) + +A raw C/C/... file as produced via C<< dd if=some_file.qcow2 >> +for files which are already in C format, or via C. + +B These formats are only valid with C<$with_snapshots> being true (C<1>). + +=item * C<< tar+size >> (subvolumes only) + +A GNU C stream containing just the inner contents of the subvolume. This +does not distinguish between the contents of a privileged or unprivileged +container. In other words, this is from the root user namespace's point of view +with no uid-mapping in effect. As produced via e.g. +C<< tar -C vm-100-disk-1.subvol -cpf output_file.dat . >> + +=back + =cut -# Import/Export interface: -# Any path based storage is assumed to support 'raw' and 'tar' streams, so -# the default implementations will return this if $scfg->{path} is set, -# mimicking the old PVE::Storage::storage_migrate() function. -# -# Plugins may fall back to PVE::Storage::Plugin::volume_{export,import}... -# functions in case the format doesn't match their specialized -# implementations to reuse the raw/tar code. -# -# Format specification: -# The following formats are all prefixed with image information in the form -# of a 64 bit little endian unsigned integer (pack('Q<')) in order to be able -# to preallocate the image on storages which require it. -# -# raw+size: (image files only) -# A raw binary data stream such as produced via `dd if=TheImageFile`. -# qcow2+size, vmdk: (image files only) -# A raw qcow2/vmdk/... file such as produced via `dd if=some.qcow2` for -# files which are already in qcow2 format, or via `qemu-img convert`. -# Note that these formats are only valid with $with_snapshots being true. -# tar+size: (subvolumes only) -# A GNU tar stream containing just the inner contents of the subvolume. -# This does not distinguish between the contents of a privileged or -# unprivileged container. In other words, this is from the root user -# namespace's point of view with no uid-mapping in effect. -# As produced via `tar -C vm-100-disk-1.subvol -cpf TheOutputFile.dat .` +=head3 $plugin->volume_export(\%scfg, $storeid, $fh, $volname, $format [, $snapshot, $base_snapshot, $with_snapshots]) + +=head3 $plugin->volume_export(...) + +Exports a volume or a volume's C<$snapshot> into a file handle C<$fh> as a +stream with a desired export C<$format>. See L for all import/export +formats. + +Optionally, C<$snapshot> (if provided) may have a C<$base_snapshot>, and +C<$with_snapshots> states whether the volume has snapshots overall. + +Cs in order to abort the export if there are (grave) problems, if the +given C<$format> is not supported, or if exporting volumes is not supported as +a whole. + +=cut -# Export a volume into a file handle as a stream of desired format. sub volume_export { my ($class, $scfg, $storeid, $fh, $volname, $format, $snapshot, $base_snapshot, $with_snapshots) = @_; croak "implement me in sub-class\n"; } +=head3 $plugin->volume_export_formats(\%scfg, $storeid, $volname [, $snapshot, $base_snapshot, $with_snapshot]) + +=head3 $plugin->volume_export_formats(...) + +B May be implemented in a storage plugin. + +Returns a list of supported export formats for the given volume or snapshot. + +Optionally, C<$snapshot> (if provided) may have a C<$base_snapshot>, and +C<$with_snapshots> states whether the volume has snapshots overall. + +If the storage does not support exporting volumes at all, and empty list should +be returned. + +=cut + sub volume_export_formats { my ($class, $scfg, $storeid, $volname, $snapshot, $base_snapshot, $with_snapshots) = @_; croak "implement me in sub-class\n"; } -# Import data from a stream, creating a new or replacing or adding to an existing volume. +=head3 $plugin->volume_import(\%scfg, $storeid, $fh, $volname, $format [, $snapshot, $base_snapshot, $with_snapshots, $allow_rename]) + +=head3 $plugin->volume_import(...) + +B May be implemented in a storage plugin. + +Imports data with the given C<$format> from a stream / filehandle C<$fh>, +creating a new volume, or replacing or adding to an existing one. Returns the +volume ID of the imported volume. + +Optionally, C<$snapshot> (if provided) may have a C<$base_snapshot>, and +C<$with_snapshots> states whether the volume has snapshots overall. Renaming an +existing volume may also optionally be allowed via C<$allow_rename> + +Cs if the import fails, if the given C<$format> is not supported, or if +importing volumes is not supported as a whole. + +=cut + sub volume_import { my ($class, $scfg, $storeid, $fh, $volname, $format, $snapshot, $base_snapshot, $with_snapshots, $allow_rename) = @_; croak "implement me in sub-class\n"; } +=head3 $plugin->volume_import_formats(\%scfg, $storeid, $volname [, $snapshot, $base_snapshot, $with_snapshot]) + +=head3 $plugin->volume_import_formats(...) + +B May be implemented in a storage plugin. + +Returns a list of supported import formats for the given volume or snapshot. + +Optionally, C<$snapshot> (if provided) may have a C<$base_snapshot>, and +C<$with_snapshots> states whether the volume has snapshots overall. + +If the storage does not support importing volumes at all, and empty list should +be returned. + +=cut + sub volume_import_formats { my ($class, $scfg, $storeid, $volname, $snapshot, $base_snapshot, $with_snapshots) = @_; croak "implement me in sub-class\n"; } - 1; -- 2.39.5 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel