=head1 NAME

nbdkit-partitioning-plugin - create virtual disk from partitions

=head1 SYNOPSIS

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

=head1 DESCRIPTION

C<nbdkit-partitioning-plugin> is a plugin for L<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 L<nbdkit-split-plugin(1)>.  If you want to select
a single partition from an existing disk, use
L<nbdkit-partition-filter(1)>.  If you want to create a complete disk
with a filesystem, look at L<nbdkit-floppy-plugin(1)>,
L<nbdkit-iso-plugin(1)> or L<nbdkit-linuxdisk-plugin(1)>.

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

=head2 Partition table type

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

=over 4

=item number of files E<gt> 4

⇒ GPT

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

⇒ GPT

=item otherwise

⇒ MBR (for maximum compatibility with clients)

=back

=head2 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
C<mbr-id> or C<type-guid> parameters respectively and affects the type
of all following files.

=head2 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 C<alignment> parameter, which affects the
alignment of all following files.

=head2 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.

=head1 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 C<mbr-id=0x82> to set
the MBR partition type byte to C<0x82> (Linux swap) for the swap
partition, followed by C<mbr-id=default> to set the MBR partition type
byte back to the default (C<0x83>, Linux filesystem) for the remaining
partition.

If F<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 L<nbdkit-partition-filter(1)>:

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

=head1 PARAMETERS

=over 4

=item [B<file=>]FILENAME

One or more files containing partition data.

This parameter is required.

C<file=> __IS_MAGIC__

=item B<partition-type=mbr>

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

If there are E<gt> 4 partitions then the first three files are mapped
to primary partitions, an extended partition
(L<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.

=item B<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.

=item B<alignment=>N

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

=item B<mbr-id=>0xN

Set the MBR type byte of all following files to C<0xN>.  Type bytes
are normally specified in hexadecimal, and you must use the C<0x>
prefix to indicate this.

=item B<mbr-id=default>

Set the MBR type byte back to the default, C<0x83> which indicates a
Linux filesystem.

=item B<type-guid=>GUID

Set the GPT partition type GUID of all following files to C<GUID>.

=item B<type-guid=default>

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

=back

=head1 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.

=head1 FILES

=over 4

=item F<$plugindir/nbdkit-partitioning-plugin.so>

The plugin.

Use C<nbdkit --dump-config> to find the location of C<$plugindir>.

=back

=head1 VERSION

C<nbdkit-partitioning-plugin> first appeared in nbdkit 1.8.

=head1 SEE ALSO

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

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat