NAME

       nbdkit-partitioning-plugin - create virtual disk from partitions

SYNOPSIS

        nbdkit partitioning [file=]part1 [[file=]part2 [file=]part3 ...]
                            [partition-type=mbr|gpt]

DESCRIPTION

       "nbdkit-partitioning-plugin" is a plugin for nbdkit(1) which creates a partitioned virtual
       drive from a list of one or more files each containing single partitions.  The plugin
       concatenates the files together and generates a virtual partition table so that NBD
       clients see a single partitioned disk.

       If you just want to concatenate files together (without adding a partition table) use
       nbdkit-split-plugin(1).  If you want to select a single partition from an existing disk,
       use nbdkit-partition-filter(1).  If you want to create a complete disk with a filesystem,
       look at nbdkit-floppy-plugin(1), nbdkit-iso-plugin(1) or nbdkit-linuxdisk-plugin(1).

       The plugin supports read/write access.  To limit clients to read-only access use the -r
       flag.

   Partition table type
       Using the "partition-type" parameter you can choose either an MBR or a GPT partition
       table.  If this parameter is not present then:

       number of files > 4
           ⇒ GPT

       else, total file size is larger than supported by MBR (approx. 2 TB)
           ⇒ GPT

       otherwise
           ⇒ MBR (for maximum compatibility with clients)

   Type of each partition
       The type of each partition is controlled by a partition type byte (for MBR) or a partition
       type GUID (for GPT).  This can be set using the "mbr-id" or "type-guid" parameters
       respectively and affects the type of all following files.

   Padding and alignment
       Partition sizes are automatically rounded up to a multiple of the 512 byte sector size.

       Padding may be added between partitions to provide the best alignment.  This is controlled
       by the "alignment" parameter, which affects the alignment of all following files.

   Writing to the virtual disk
       NBD clients may read and write freely to partitions.  Writes are propagated through to the
       underlying files.

       NBD clients may read from the virtual partition table, and padding areas of the virtual
       disk.  When reading from padding areas, clients will see zeroes.

       NBD clients will get an I/O error if they try to change the virtual partition table or
       padding areas.

EXAMPLES

       From a bare filesystem stored in a file, create a virtual disk with a single partition
       containing the filesystem:

        nbdkit partitioning ext4fs.img

       Create a virtual disk containing boot, swap and root partitions:

        nbdkit partitioning \
                   boot.img \
                   mbr-id=0x82 swap.img mbr-id=default \
                   root.img

       This will not be bootable since the virtual partition table does not contain a boot sector
       or boot loader.

       Notice that the swap partition is bracketed by "mbr-id=0x82" to set the MBR partition type
       byte to 0x82 (Linux swap) for the swap partition, followed by "mbr-id=default" to set the
       MBR partition type byte back to the default (0x83, Linux filesystem) for the remaining
       partition.

       If file.raw has a size which is a multiple of 512 bytes then this is a no-op because the
       partitioning plugin adds a partition table which is then removed by
       nbdkit-partition-filter(1):

        nbdkit --filter=partition partitioning file.raw partition=1

PARAMETERS

       [file=]FILENAME
           One or more files containing partition data.

           This parameter is required.

           "file=" is a magic config key and may be omitted in most cases.  See "Magic
           parameters" in nbdkit(1).

       partition-type=mbr
           Add an MBR (DOS-style) partition table.  The MBR format is maximally compatible with
           all clients.

           If there are > 4 partitions then the first three files are mapped to primary
           partitions, an extended partition (https://en.wikipedia.org/wiki/Extended_boot_record)
           is created as partition 4, and the files starting from the 4th will appear as
           partition 5 and upwards.

       partition-type=gpt
           Add a GPT partition table.  Note that as well as the virtual primary partition table
           added at the beginning of the disk, a virtual secondary partition table is added at
           the end, as required by GPT.  Also this adds a "protective MBR" as defined by the UEFI
           spec so that old clients which don't understand GPT will ignore the partitions.

       alignment=N
           Set the alignment of all following files to "N" bytes.  The default alignment is 1M
           (2048 sectors).

       mbr-id=0xN
           Set the MBR type byte of all following files to "0xN".  Type bytes are normally
           specified in hexadecimal, and you must use the "0x" prefix to indicate this.

       mbr-id=default
           Set the MBR type byte back to the default, 0x83 which indicates a Linux filesystem.

       type-guid=GUID
           Set the GPT partition type GUID of all following files to "GUID".

       type-guid=default
           Set the GPT partition type GUID back to the default,
           "0FC63DAF-8483-4772-8E79-3D69D8477DE4" which indicates a Linux filesystem.

LIMITS

       Although this plugin can create GPT partition tables containing more than 128 GPT
       partitions (in fact, unlimited numbers of partitions), some clients will not be able to
       handle this.

       Zero length partitions are not allowed and will cause nbdkit to exit with an error when it
       starts up.

       The sector size is fixed at 512 bytes.

FILES

       $plugindir/nbdkit-partitioning-plugin.so
           The plugin.

           Use "nbdkit --dump-config" to find the location of $plugindir.

VERSION

       "nbdkit-partitioning-plugin" first appeared in nbdkit 1.8.

SEE ALSO

       nbdkit(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1), nbdkit-iso-plugin(1),
       nbdkit-linuxdisk-plugin(1), nbdkit-partition-filter(1), nbdkit-split-plugin(1),
       nbdkit-plugin(3).

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright Red Hat

LICENSE

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

       •   Redistributions of source code must retain the above copyright notice, this list of
           conditions and the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright notice, this list of
           conditions and the following disclaimer in the documentation and/or other materials
           provided with the distribution.

       •   Neither the name of Red Hat nor the names of its contributors may be used to endorse
           or promote products derived from this software without specific prior written
           permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS
       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.