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
   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 The disk image is stored in memory using a sparse array.  The
  20 allocated parts of the disk image cannot be larger than physical RAM
  21 plus swap, less whatever is being used by the rest of the system.  If
  22 you want to allocate more space than this use L<nbdkit-file-plugin(1)>
  23 backed by a temporary file instead.
  24
  25 However the virtual size can be as large as you like, up to the
  26 maximum supported by nbdkit (S<2⁶³-1 bytes>).  This limit is tested
  27 when nbdkit is compiled, and it should work on all platforms and
  28 architectures supported by nbdkit.
  29
  30 =head1 EXAMPLES
  31
  32 Create a one gigabyte sparse RAM disk:
  33
  34  nbdkit memory 1G
  35
  36 If you want to loop mount the above disk, see L<nbdkit-loop(1)>.
  37
  38 Create the largest possible RAM disk:
  39
  40  nbdkit memory $(( 2**63 - 1 ))
  41
  42 =head1 PARAMETERS
  43
  44 =over 4
  45
  46 =item [B<size=>]SIZE
  47
  48 Specify the virtual size of the disk image.
  49
  50 This parameter is required.
  51
  52 C<size=> is a magic config key and may be omitted in most cases.
  53 See L<nbdkit(1)/Magic parameters>.
  54
  55 =back
  56
  57 =head1 NOTES
  58
  59 =head2 Preloading small amounts of data
  60
  61 If you want an in-memory disk image preinitialized with a small amount
  62 of data specified on the command line, look at
  63 L<nbdkit-data-plugin(1)> instead.  Note by "small" this does not mean
  64 that the virtual disk image must be small, but that the amount of data
  65 initially stored sparsely is small enough to specify on the command
  66 line.
  67
  68 =head2 Preloading large amounts of data
  69
  70 If you want to preload a large amount of data (eg. a disk image) into
  71 the memory plugin, use L<qemu-img(1)>:
  72
  73  $ rm -f pid
  74  $ nbdkit -P pid memory 10G
  75
  76  # wait for nbdkit to become ready to accept connections:
  77  $ while [ ! -f pid ]; do sleep 1; done
  78
  79  # preload Fedora disk image:
  80  $ virt-builder fedora-28 --size=10G
  81  $ qemu-img convert -p -n fedora-28.img nbd:localhost:10809
  82
  83 =head1 SEE ALSO
  84
  85 L<nbdkit(1)>,
  86 L<nbdkit-plugin(3)>,
  87 L<nbdkit-loop(1)>,
  88 L<nbdkit-data-plugin(1)>,
  89 L<nbdkit-file-plugin(1)>,
  90 L<nbdkit-reflection-plugin(1)>.
  91
  92 =head1 AUTHORS
  93
  94 Richard W.M. Jones
  95
  96 =head1 COPYRIGHT
  97
  98 Copyright (C) 2017-2018 Red Hat Inc.