plugins/partitioning/nbdkit-partitioning-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-partitioning-plugin - create virtual disk from partitions
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit partitioning [file=]part1 [[file=]part2 [file=]part3 ...]
   8                      [partition-type=mbr|gpt]
   9
  10 =head1 DESCRIPTION
  11
  12 C<nbdkit-partitioning-plugin> is a plugin for L<nbdkit(1)> which
  13 creates a partitioned virtual drive from a list of one or more files
  14 each containing single partitions.  The plugin concatenates the files
  15 together and generates a virtual partition table so that NBD clients
  16 see a single partitioned disk.
  17
  18 If you just want to concatenate files together (without adding a
  19 partition table) use L<nbdkit-split-plugin(1)>.  If you want to select
  20 a single partition from an existing disk, use
  21 L<nbdkit-partition-filter(1)>.
  22
  23 The plugin supports read/write access.  To limit clients to read-only
  24 access use the I<-r> flag.
  25
  26 =head2 Partition type
  27
  28 You can choose either MBR (limited to 4 partitions) or GPT (limited to
  29 128 partitions) partition table type.
  30
  31 If the C<partition-type> parameter is not supplied then the default is
  32 chosen as follows: If the number of files is E<gt> 4 then GPT is used.
  33 If the total file size is larger than supported by MBR (approximately
  34 2 TB), then GPT is used.  Otherwise MBR is used for maximum
  35 compatibility.
  36
  37 =head2 Padding and alignment
  38
  39 Partition sizes are automatically rounded up to a multiple of the 512
  40 byte sector size.  Padding may be added between partitions to provide
  41 the best alignment.  NBD clients may write to partitions, but will get
  42 an I/O error if they try to change the virtual partition table or any
  43 padding areas of the disk.
  44
  45 =head1 EXAMPLES
  46
  47 Create a virtual disk containing boot, swap and root partitions (note
  48 this will not be bootable since the virtual partition table does not
  49 contain a boot sector or boot loader):
  50
  51  nbdkit partitioning boot.img swap.img root.img
  52
  53 From a bare ext4 filesystem, create a virtual partitioned disk:
  54
  55  nbdkit partitioning ext4fs.img
  56
  57 If the underlying file is a multiple of 512 bytes then this is a
  58 no-op:
  59
  60  nbdkit --filter=partition partitioning file partition=1
  61
  62 =head1 PARAMETERS
  63
  64 =over 4
  65
  66 =item B<file=>FILENAME
  67
  68 One or more files containing partition data.
  69
  70 This parameter is required.
  71
  72 C<file=> may be omitted.  To ensure that the filename does not end up
  73 being parsed accidentally as C<key=value>, prefix relative paths with
  74 C<./> (absolute paths do not need modification).
  75
  76 =item B<partition-type=mbr>
  77
  78 Add an MBR (DOS-style) partition table.  The MBR format is maximally
  79 compatible with clients, but only supports up to 4 partitions.
  80
  81 =item B<partition-type=gpt>
  82
  83 Add a GPT partition table.  This plugin supports up to 128 GPT
  84 partitions.  Note that as well as the virtual primary partition table
  85 added at the beginning of the disk, a virtual secondary partition
  86 table is added at the end, as required by GPT.
  87
  88 =back
  89
  90 =head1 LIMITS
  91
  92 This plugin only supports primary MBR partitions, hence the limit of 4
  93 partitions with MBR.  This might be increased in future if we
  94 implement support for logical/extended partitions.
  95
  96 This plugin only supports 128 GPT partitions.  The GPT format can
  97 support more, but this plugin does not implement that.
  98
  99 Zero length partitions are not allowed and will cause nbdkit to exit
 100 with an error.
 101
 102 The sector size is fixed at 512 bytes.
 103
 104 =head1 SEE ALSO
 105
 106 L<nbdkit(1)>,
 107 L<nbdkit-file-plugin(1)>,
 108 L<nbdkit-partition-filter(1)>,
 109 L<nbdkit-split-plugin(1)>,
 110 L<nbdkit-plugin(3)>.
 111
 112 =head1 AUTHORS
 113
 114 Richard W.M. Jones
 115
 116 =head1 COPYRIGHT
 117
 118 Copyright (C) 2018 Red Hat Inc.