plugins/memory/nbdkit-memory-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-memory-plugin - nbdkit virtual memory (RAM disk) plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit memory [size=]SIZE [allocator=sparse|malloc|zstd]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-memory-plugin> is a plugin for L<nbdkit(1)> which stores a
  12 single disk image in virtual memory, and discards it when nbdkit
  13 exits.  This plugin can be used for testing or where you don't care
  14 about the final content of the disk image.
  15
  16 All nbdkit clients will see the same disk content, initially all
  17 zeroes.
  18
  19 By default the disk image is stored in memory using a sparse array.
  20 The allocated parts of the disk image cannot be larger than physical
  21 RAM plus swap, less whatever is being used by the rest of the system.
  22 Other allocators are available, see L</ALLOCATORS> below.  All
  23 allocators store the image in memory.  If you want to allocate more
  24 space than this use L<nbdkit-file-plugin(1)> backed by a temporary
  25 file instead.
  26
  27 Using the sparse allocator the virtual size can be as large as you
  28 like, up to the maximum supported by nbdkit (S<2⁶³-1 bytes>).  This
  29 limit is tested when nbdkit is compiled, and it should work on all
  30 platforms and architectures supported by nbdkit.
  31
  32 =head1 EXAMPLES
  33
  34 Create a one gigabyte sparse RAM disk:
  35
  36  nbdkit memory 1G
  37
  38 If you want to loop mount the above disk, see L<nbdkit-loop(1)>.
  39
  40 Create the largest possible RAM disk:
  41
  42  nbdkit memory $(( 2**63 - 1 ))
  43
  44 =head1 PARAMETERS
  45
  46 =over 4
  47
  48 =item [B<size=>]SIZE
  49
  50 Specify the virtual size of the disk image.
  51
  52 This parameter is required.
  53
  54 C<size=> is a magic config key and may be omitted in most cases.
  55 See L<nbdkit(1)/Magic parameters>.
  56
  57 =item B<allocator=sparse>
  58
  59 =item B<allocator=malloc>[,B<mlock=true>]
  60
  61 =item B<allocator=zstd>
  62
  63 (nbdkit E<ge> 1.22)
  64
  65 Select the backend allocation strategy.  See L</ALLOCATORS> below.
  66 The default is sparse.
  67
  68 =back
  69
  70 =head1 NOTES
  71
  72 =head2 Preloading small amounts of data
  73
  74 If you want an in-memory disk image preinitialized with a small amount
  75 of data specified on the command line, look at
  76 L<nbdkit-data-plugin(1)> instead.  Note by "small" this does not mean
  77 that the virtual disk image must be small, but that the amount of data
  78 initially stored sparsely is small enough to specify on the command
  79 line.
  80
  81 =head2 Preloading large amounts of data
  82
  83 If you want to preload a large amount of data (eg. a disk image) into
  84 the memory plugin, use L<qemu-img(1)> or L<nbdcopy(1)>:
  85
  86  $ rm -f pid
  87  $ nbdkit -P pid memory 10G
  88
  89 Wait for nbdkit to become ready to accept connections:
  90
  91  $ while [ ! -f pid ]; do sleep 1; done
  92
  93 Preload Fedora disk image using qemu-img:
  94
  95  $ virt-builder fedora-28 --size=10G
  96  $ qemu-img convert -p -n fedora-28.img nbd:localhost:10809
  97
  98 If you have libnbd E<ge> 1.4, you can use L<nbdcopy(1)> as an
  99 alternative:
 100
 101  $ nbdcopy -p fedora-28.img nbd://localhost
 102
 103 =head1 ALLOCATORS
 104
 105 Since nbdkit E<ge> 1.22 several allocation strategies are available
 106 using the C<allocator> parameter.
 107
 108 =over 4
 109
 110 =item B<allocator=sparse>
 111
 112 The disk image is stored in memory using a sparse array.  The sparse
 113 array uses a simple two level page table with a fixed page size.  The
 114 allocated parts of the disk image cannot be larger than physical RAM
 115 plus swap, less whatever is being used by the rest of the system.  The
 116 aim of the sparse array implementation is to support extremely large
 117 images for testing, although it won't necessarily be efficient for
 118 that use case.  However it should also be reasonably efficient for
 119 normal disk sizes.
 120
 121 The virtual size of the disk can be as large as you like, up to the
 122 maximum supported by nbdkit (S<2⁶³-1 bytes>).
 123
 124 This is the default, and was the only allocator available before
 125 S<nbdkit 1.22>.
 126
 127 =item B<allocator=malloc>
 128
 129 =item B<allocator=malloc,mlock=true>
 130
 131 The disk image is stored directly in memory allocated using
 132 L<malloc(3)> on the heap.  No sparseness is possible: you must have
 133 enough memory for the whole disk.  Very large virtual sizes will
 134 usually fail.  However this can be faster because the implementation
 135 is simpler and the locking strategy allows more concurrency.
 136
 137 If C<mlock=true> is added then additionally the array is locked into
 138 RAM using L<mlock(2)> (so it should never be swapped out).  This
 139 usually requires you to adjust the L<ulimit(1)> associated with the
 140 process and on some operating systems may require you to run nbdkit as
 141 root.  (See also the L<nbdkit(1)> I<--swap> option).
 142
 143 The C<mlock=true> feature is only supported on some platforms.  Use
 144 S<C<nbdkit memory --dump-plugin>> and check that the output contains
 145 C<mlock=yes>.
 146
 147 =item B<allocator=zstd>
 148
 149 The disk image is stored in a sparse array where each page is
 150 compressed using L<zstd compression|https://facebook.github.io/zstd/>.
 151 Assuming a typical 2:1 compression ratio, this allows you to store
 152 twice as much real data as C<allocator=sparse>, with the trade-off
 153 that the plugin is slightly slower because it has to compress and
 154 decompress each page.  Aside from compression, the implementation of
 155 this allocator is similar to C<allocator=sparse>, so in other respects
 156 (such as supporting huge virtual disk sizes) it is the same.
 157
 158 This allocator is only supported if nbdkit was compiled with zstd
 159 support.  Use S<C<nbdkit memory --dump-plugin>> and check that the
 160 output contains C<zstd=yes>.
 161
 162 =back
 163
 164 =head1 FILES
 165
 166 =over 4
 167
 168 =item F<$plugindir/nbdkit-memory-plugin.so>
 169
 170 The plugin.
 171
 172 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 173
 174 =back
 175
 176 =head1 VERSION
 177
 178 C<nbdkit-memory-plugin> first appeared in nbdkit 1.2.
 179
 180 =head1 SEE ALSO
 181
 182 L<nbdkit(1)>,
 183 L<nbdkit-plugin(3)>,
 184 L<nbdkit-loop(1)>,
 185 L<nbdkit-data-plugin(1)>,
 186 L<nbdkit-file-plugin(1)>,
 187 L<nbdkit-info-plugin(1)>,
 188 L<nbdkit-tmpdisk-plugin(1)>,
 189 L<mlock(2)>,
 190 L<malloc(3)>,
 191 L<qemu-img(1)>,
 192 L<nbdcopy(1)>.
 193
 194 =head1 AUTHORS
 195
 196 Richard W.M. Jones
 197
 198 =head1 COPYRIGHT
 199
 200 Copyright Red Hat