nbdkit-partitioning-plugin(1)

1nbdkit-partitioning-plugin(1)       NBDKIT       nbdkit-partitioning-plugin(1)
2
3
4

NAME

6       nbdkit-partitioning-plugin - create virtual disk from partitions
7

SYNOPSIS

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

DESCRIPTION

13       "nbdkit-partitioning-plugin" is a plugin for nbdkit(1) which creates a
14       partitioned virtual drive from a list of one or more files each
15       containing single partitions.  The plugin concatenates the files
16       together and generates a virtual partition table so that NBD clients
17       see a single partitioned disk.
18
19       If you just want to concatenate files together (without adding a
20       partition table) use nbdkit-split-plugin(1).  If you want to select a
21       single partition from an existing disk, use nbdkit-partition-filter(1).
22       If you want to create a complete disk with a filesystem, look at
23       nbdkit-floppy-plugin(1), nbdkit-iso-plugin(1) or
24       nbdkit-linuxdisk-plugin(1).
25
26       The plugin supports read/write access.  To limit clients to read-only
27       access use the -r flag.
28
29   Partition table type
30       Using the "partition-type" parameter you can choose either an MBR or a
31       GPT partition table.  If this parameter is not present then:
32
33       number of files > 4
34           ⇒ GPT
35
36       else, total file size is larger than supported by MBR (approx. 2 TB)
37           ⇒ GPT
38
39       otherwise
40           ⇒ MBR (for maximum compatibility with clients)
41
42   Type of each partition
43       The type of each partition is controlled by a partition type byte (for
44       MBR) or a partition type GUID (for GPT).  This can be set using the
45       "mbr-id" or "type-guid" parameters respectively and affects the type of
46       all following files.
47
48   Padding and alignment
49       Partition sizes are automatically rounded up to a multiple of the 512
50       byte sector size.
51
52       Padding may be added between partitions to provide the best alignment.
53       This is controlled by the "alignment" parameter, which affects the
54       alignment of all following files.
55
56   Writing to the virtual disk
57       NBD clients may read and write freely to partitions.  Writes are
58       propagated through to the underlying files.
59
60       NBD clients may read from the virtual partition table, and padding
61       areas of the virtual disk.  When reading from padding areas, clients
62       will see zeroes.
63
64       NBD clients will get an I/O error if they try to change the virtual
65       partition table or padding areas.
66

EXAMPLES

68       From a bare filesystem stored in a file, create a virtual disk with a
69       single partition containing the filesystem:
70
71        nbdkit partitioning ext4fs.img
72
73       Create a virtual disk containing boot, swap and root partitions:
74
75        nbdkit partitioning \
76                   boot.img \
77                   mbr-id=0x82 swap.img mbr-id=0x83 \
78                   root.img
79
80       This will not be bootable since the virtual partition table does not
81       contain a boot sector or boot loader.
82
83       Notice that the swap partition is bracketed by "mbr-id=0x82" to set the
84       MBR partition type byte to 0x82 (Linux swap) for the swap partition,
85       followed by "mbr-id=0x83" to set the MBR partition type byte back to
86       0x83 (Linux filesystem) for the remaining partition.
87
88       If file.raw has a size which is a multiple of 512 bytes then this is a
89       no-op because the partitioning plugin adds a partition table which is
90       then removed by nbdkit-partition-filter(1):
91
92        nbdkit --filter=partition partitioning file.raw partition=1
93

PARAMETERS

95       [file=]FILENAME
96           One or more files containing partition data.
97
98           This parameter is required.
99
100           "file=" is a magic config key and may be omitted in most cases.
101           See "Magic parameters" in nbdkit(1).
102
103       partition-type=mbr
104           Add an MBR (DOS-style) partition table.  The MBR format is
105           maximally compatible with all clients.
106
107           If there are > 4 partitions then the first three files are mapped
108           to primary partitions, an extended partition
109           (https://en.wikipedia.org/wiki/Extended_boot_record) is created as
110           partition 4, and the files starting from the 4th will appear as
111           partition 5 and upwards.
112
113       partition-type=gpt
114           Add a GPT partition table.  Note that as well as the virtual
115           primary partition table added at the beginning of the disk, a
116           virtual secondary partition table is added at the end, as required
117           by GPT.  Also this adds a "protective MBR" as defined by the UEFI
118           spec so that old clients which don't understand GPT will ignore the
119           partitions.
120
121       alignment=N
122           Set the alignment of all following files to "N" bytes.  The default
123           alignment is 1M (2048 sectors).
124
125       mbr-id=0xN
126           Set the MBR type byte of all following files to "0xN".  Type bytes
127           are normally specified in hexadecimal, and you must use the "0x"
128           prefix to indicate this.  The default is 0x83 which indicates a
129           Linux filesystem.
130
131       type-guid=GUID
132           Set the GPT partition type GUID of all following files to "GUID".
133           The default is "0FC63DAF-8483-4772-8E79-3D69D8477DE4" which
134           indicates a Linux filesystem.
135

LIMITS

137       Although this plugin can create GPT partition tables containing more
138       than 128 GPT partitions (in fact, unlimited numbers of partitions),
139       some clients will not be able to handle this.
140
141       Zero length partitions are not allowed and will cause nbdkit to exit
142       with an error when it starts up.
143
144       The sector size is fixed at 512 bytes.
145

AUTHORS

152       Richard W.M. Jones
153

COPYRIGHT

155       Copyright (C) 2018 Red Hat Inc.
156

LICENSE

158       Redistribution and use in source and binary forms, with or without
159       modification, are permitted provided that the following conditions are
160       met:
161
162       ·   Redistributions of source code must retain the above copyright
163           notice, this list of conditions and the following disclaimer.
164
165       ·   Redistributions in binary form must reproduce the above copyright
166           notice, this list of conditions and the following disclaimer in the
167           documentation and/or other materials provided with the
168           distribution.
169
170       ·   Neither the name of Red Hat nor the names of its contributors may
171           be used to endorse or promote products derived from this software
172           without specific prior written permission.
173
174       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
175       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
176       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
177       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
178       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
179       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
180       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
181       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
182       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
183       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
184       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
185
186
187
188nbdkit-1.12.3                     2019-05-21     nbdkit-partitioning-plugin(1)