.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "2019-01-26" "nbdkit-1.10.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 \s-1NBD\s0 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) or
\&\fBnbdkit\-iso\-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"
You can choose either an \s-1MBR\s0 partition table, which is limited to 4
partitions, or a \s-1GPT\s0 partition table.  In theory \s-1GPT\s0 supports an
unlimited number of partitions.
.PP
The rule for selecting the partition table type is:
.ie n .IP """partition\-type=mbr"" parameter on the command line" 4
.el .IP "\f(CWpartition\-type=mbr\fR parameter on the command line" 4
.IX Item "partition-type=mbr parameter on the command line"
⇒ \s-1MBR\s0 is selected
.ie n .IP """partition\-type=gpt"" parameter on the command line" 4
.el .IP "\f(CWpartition\-type=gpt\fR parameter on the command line" 4
.IX Item "partition-type=gpt parameter on the command line"
⇒ \s-1GPT\s0 is selected
.IP "else, number of files > 4" 4
.IX Item "else, number of files > 4"
⇒ \s-1GPT\s0
.IP "else, total file size is larger than supported by \s-1MBR\s0 (approx. 2 \s-1TB\s0)" 4
.IX Item "else, total file size is larger than supported by MBR (approx. 2 TB)"
⇒ \s-1GPT\s0
.IP "otherwise" 4
.IX Item "otherwise"
⇒ \s-1MBR\s0 (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
\&\s-1MBR\s0) or a partition type \s-1GUID\s0 (for \s-1GPT\s0).  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"
\&\s-1NBD\s0 clients may read and write freely to partitions.  Writes are
propagated through to the underlying files.
.PP
\&\s-1NBD\s0 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
\&\s-1NBD\s0 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=0x83 \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 \s-1MBR\s0 partition type byte to \f(CW0x82\fR (Linux swap) for the swap
partition, followed by \f(CW\*(C`mbr\-id=0x83\*(C'\fR to set the \s-1MBR\s0 partition type
byte back to \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\s-1FILENAME\s0" 4
.IX Item "file=FILENAME"
One or more files containing partition data.
.Sp
This parameter is required.
.Sp
\&\f(CW\*(C`file=\*(C'\fR may be omitted.  To ensure that the filename does not end up
being parsed accidentally as \f(CW\*(C`key=value\*(C'\fR, prefix relative paths with
\&\f(CW\*(C`./\*(C'\fR (absolute paths do not need modification).
.IP "\fBpartition\-type=mbr\fR" 4
.IX Item "partition-type=mbr"
Add an \s-1MBR\s0 (DOS-style) partition table.  The \s-1MBR\s0 format is maximally
compatible with all clients, but only supports up to 4 partitions.
.IP "\fBpartition\-type=gpt\fR" 4
.IX Item "partition-type=gpt"
Add a \s-1GPT\s0 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 \s-1GPT.\s0
Also this adds a \*(L"protective \s-1MBR\*(R"\s0 as defined by the \s-1UEFI\s0 spec so that
old clients which don't understand \s-1GPT\s0 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 \s-1MBR\s0 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.  The default is \f(CW0x83\fR which indicates a
Linux filesystem.
.IP "\fBtype\-guid=\fR\s-1GUID\s0" 4
.IX Item "type-guid=GUID"
Set the \s-1GPT\s0 partition type \s-1GUID\s0 of all following files to \f(CW\*(C`GUID\*(C'\fR.
The default is \f(CW\*(C`0FC63DAF\-8483\-4772\-8E79\-3D69D8477DE4\*(C'\fR which indicates
a Linux filesystem.
.SH "LIMITS"
.IX Header "LIMITS"
This plugin only supports \fBprimary\fR \s-1MBR\s0 partitions, hence the limit
of 4 partitions with \s-1MBR.\s0  This might be increased in future if we
implement support for logical/extended \s-1MBR\s0 partitions.
.PP
Although this plugin can create \s-1GPT\s0 partition tables containing more
than 128 \s-1GPT\s0 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 "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\-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 (C) 2018 Red Hat Inc.
.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
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0