.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.36.3 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-partitioning-plugin 1"
.TH nbdkit-partitioning-plugin 1 2024-01-17 nbdkit-1.36.3 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-partitioning\-plugin \- create virtual disk from partitions
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& nbdkit partitioning [file=]part1 [[file=]part2 [file=]part3 ...]
\&                     [partition\-type=mbr|gpt]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-partitioning\-plugin\*(C'\fR is a plugin for \fBnbdkit\fR\|(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.
.PP
If you just want to concatenate files together (without adding a
partition table) use \fBnbdkit\-split\-plugin\fR\|(1).  If you want to select
a single partition from an existing disk, use
\&\fBnbdkit\-partition\-filter\fR\|(1).  If you want to create a complete disk
with a filesystem, look at \fBnbdkit\-floppy\-plugin\fR\|(1),
\&\fBnbdkit\-iso\-plugin\fR\|(1) or \fBnbdkit\-linuxdisk\-plugin\fR\|(1).
.PP
The plugin supports read/write access.  To limit clients to read-only
access use the \fI\-r\fR flag.
.SS "Partition table type"
.IX Subsection "Partition table type"
Using the \f(CW\*(C`partition\-type\*(C'\fR parameter you can choose either an MBR or
a GPT partition table.  If this parameter is \fInot\fR present then:
.IP "number of files > 4" 4
.IX Item "number of files > 4"
⇒ GPT
.IP "else, total file size is larger than supported by MBR (approx. 2 TB)" 4
.IX Item "else, total file size is larger than supported by MBR (approx. 2 TB)"
⇒ GPT
.IP otherwise 4
.IX Item "otherwise"
⇒ MBR (for maximum compatibility with clients)
.SS "Type of each partition"
.IX Subsection "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
\&\f(CW\*(C`mbr\-id\*(C'\fR or \f(CW\*(C`type\-guid\*(C'\fR parameters respectively and affects the type
of all following files.
.SS "Padding and alignment"
.IX Subsection "Padding and alignment"
Partition sizes are automatically rounded up to a multiple of the 512
byte sector size.
.PP
Padding may be added between partitions to provide the best alignment.
This is controlled by the \f(CW\*(C`alignment\*(C'\fR parameter, which affects the
alignment of all following files.
.SS "Writing to the virtual disk"
.IX Subsection "Writing to the virtual disk"
NBD clients may read and write freely to partitions.  Writes are
propagated through to the underlying files.
.PP
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.
.PP
NBD clients will get an I/O error if they try to change the virtual
partition table or padding areas.
.SH EXAMPLES
.IX Header "EXAMPLES"
From a bare filesystem stored in a file, create a virtual disk with a
single partition containing the filesystem:
.PP
.Vb 1
\& nbdkit partitioning ext4fs.img
.Ve
.PP
Create a virtual disk containing boot, swap and root partitions:
.PP
.Vb 4
\& nbdkit partitioning \e
\&            boot.img \e
\&            mbr\-id=0x82 swap.img mbr\-id=default \e
\&            root.img
.Ve
.PP
This will not be bootable since the virtual partition table does not
contain a boot sector or boot loader.
.PP
Notice that the swap partition is bracketed by \f(CW\*(C`mbr\-id=0x82\*(C'\fR to set
the MBR partition type byte to \f(CW0x82\fR (Linux swap) for the swap
partition, followed by \f(CW\*(C`mbr\-id=default\*(C'\fR to set the MBR partition type
byte back to the default (\f(CW0x83\fR, Linux filesystem) for the remaining
partition.
.PP
If \fIfile.raw\fR 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 \fBnbdkit\-partition\-filter\fR\|(1):
.PP
.Vb 1
\& nbdkit \-\-filter=partition partitioning file.raw partition=1
.Ve
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP [\fBfile=\fR]FILENAME 4
.IX Item "[file=]FILENAME"
One or more files containing partition data.
.Sp
This parameter is required.
.Sp
\&\f(CW\*(C`file=\*(C'\fR is a magic config key and may be omitted in most cases.
See "Magic parameters" in \fBnbdkit\fR\|(1).
.IP \fBpartition\-type=mbr\fR 4
.IX Item "partition-type=mbr"
Add an MBR (DOS-style) partition table.  The MBR format is maximally
compatible with all clients.
.Sp
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.
.IP \fBpartition\-type=gpt\fR 4
.IX Item "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.
.IP \fBalignment=\fRN 4
.IX Item "alignment=N"
Set the alignment of all following files to \f(CW\*(C`N\*(C'\fR bytes.  The default
alignment is 1M (2048 sectors).
.IP \fBmbr\-id=\fR0xN 4
.IX Item "mbr-id=0xN"
Set the MBR type byte of all following files to \f(CW\*(C`0xN\*(C'\fR.  Type bytes
are normally specified in hexadecimal, and you must use the \f(CW\*(C`0x\*(C'\fR
prefix to indicate this.
.IP \fBmbr\-id=default\fR 4
.IX Item "mbr-id=default"
Set the MBR type byte back to the default, \f(CW0x83\fR which indicates a
Linux filesystem.
.IP \fBtype\-guid=\fRGUID 4
.IX Item "type-guid=GUID"
Set the GPT partition type GUID of all following files to \f(CW\*(C`GUID\*(C'\fR.
.IP \fBtype\-guid=default\fR 4
.IX Item "type-guid=default"
Set the GPT partition type GUID back to the default,
\&\f(CW\*(C`0FC63DAF\-8483\-4772\-8E79\-3D69D8477DE4\*(C'\fR which indicates a Linux
filesystem.
.SH LIMITS
.IX Header "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.
.PP
Zero length partitions are not allowed and will cause nbdkit to exit
with an error when it starts up.
.PP
The sector size is fixed at 512 bytes.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$plugindir\fR\fI/nbdkit\-partitioning\-plugin.so\fR 4
.el .IP \fR\f(CI$plugindir\fR\fI/nbdkit\-partitioning\-plugin.so\fR 4
.IX Item "$plugindir/nbdkit-partitioning-plugin.so"
The plugin.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$plugindir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-partitioning\-plugin\*(C'\fR first appeared in nbdkit 1.8.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-file\-plugin\fR\|(1),
\&\fBnbdkit\-floppy\-plugin\fR\|(1),
\&\fBnbdkit\-iso\-plugin\fR\|(1),
\&\fBnbdkit\-linuxdisk\-plugin\fR\|(1),
\&\fBnbdkit\-partition\-filter\fR\|(1),
\&\fBnbdkit\-split\-plugin\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
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.