1nbdkit-partitioning-plugin(1) NBDKIT nbdkit-partitioning-plugin(1)
2
6 nbdkit-partitioning-plugin - create virtual disk from partitions
7
9 nbdkit partitioning [file=]part1 [[file=]part2 [file=]part3 ...]
10 [partition-type=mbr|gpt]
11
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 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 The plugin supports read/write access. To limit clients to read-only
27 access use the -r flag.
28 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 number of files > 4
34 ⇒ GPT
35 else, total file size is larger than supported by MBR (approx. 2 TB)
37 ⇒ GPT
38 otherwise
40 ⇒ MBR (for maximum compatibility with clients)
41 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 Padding and alignment
49 Partition sizes are automatically rounded up to a multiple of the 512
50 byte sector size.
51 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 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 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 NBD clients will get an I/O error if they try to change the virtual
65 partition table or padding areas.
66
68 From a bare filesystem stored in a file, create a virtual disk with a
69 single partition containing the filesystem:
70 nbdkit partitioning ext4fs.img
72 Create a virtual disk containing boot, swap and root partitions:
74 nbdkit partitioning \
76 boot.img \
77 mbr-id=0x82 swap.img mbr-id=default \
78 root.img
79 This will not be bootable since the virtual partition table does not
81 contain a boot sector or boot loader.
82 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=default" to set the MBR partition type byte back to
86 the default (0x83, Linux filesystem) for the remaining partition.
87 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 nbdkit --filter=partition partitioning file.raw partition=1
93
95 [file=]FILENAME
96 One or more files containing partition data.
97 This parameter is required.
99 "file=" is a magic config key and may be omitted in most cases.
101 See "Magic parameters" in nbdkit(1).
102 partition-type=mbr
104 Add an MBR (DOS-style) partition table. The MBR format is
105 maximally compatible with all clients.
106 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 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 alignment=N
122 Set the alignment of all following files to "N" bytes. The default
123 alignment is 1M (2048 sectors).
124 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.
129 mbr-id=default
131 Set the MBR type byte back to the default, 0x83 which indicates a
132 Linux filesystem.
133 type-guid=GUID
135 Set the GPT partition type GUID of all following files to "GUID".
136 type-guid=default
138 Set the GPT partition type GUID back to the default,
139 "0FC63DAF-8483-4772-8E79-3D69D8477DE4" which indicates a Linux
140 filesystem.
141
143 Although this plugin can create GPT partition tables containing more
144 than 128 GPT partitions (in fact, unlimited numbers of partitions),
145 some clients will not be able to handle this.
146 Zero length partitions are not allowed and will cause nbdkit to exit
148 with an error when it starts up.
149 The sector size is fixed at 512 bytes.
151
153 $plugindir/nbdkit-partitioning-plugin.so
154 The plugin.
155 Use "nbdkit --dump-config" to find the location of $plugindir.
157
159 "nbdkit-partitioning-plugin" first appeared in nbdkit 1.8.
160
162 nbdkit(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
163 nbdkit-iso-plugin(1), nbdkit-linuxdisk-plugin(1),
164 nbdkit-partition-filter(1), nbdkit-split-plugin(1), nbdkit-plugin(3).
165
167 Richard W.M. Jones
168
170 Copyright Red Hat
171
173 Redistribution and use in source and binary forms, with or without
174 modification, are permitted provided that the following conditions are
175 met:
176 • Redistributions of source code must retain the above copyright
178 notice, this list of conditions and the following disclaimer.
179 • Redistributions in binary form must reproduce the above copyright
181 notice, this list of conditions and the following disclaimer in the
182 documentation and/or other materials provided with the
183 distribution.
184 • Neither the name of Red Hat nor the names of its contributors may
186 be used to endorse or promote products derived from this software
187 without specific prior written permission.
188 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
190 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
191 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
192 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
193 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
194 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
195 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
196 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
197 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
198 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
199 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
200nbdkit-1.34.4 2023-09-26 nbdkit-partitioning-plugin(1)