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

NAME

6       nbdkit-memory-plugin - nbdkit virtual memory (RAM disk) plugin
7

SYNOPSIS

9        nbdkit memory [size=]SIZE [allocator=sparse|malloc|zstd]
10

DESCRIPTION

12       "nbdkit-memory-plugin" is a plugin for nbdkit(1) which stores a single
13       disk image in virtual memory, and discards it when nbdkit exits.  This
14       plugin can be used for testing or where you don't care about the final
15       content of the disk image.
16
17       All nbdkit clients will see the same disk content, initially all
18       zeroes.
19
20       By default the disk image is stored in memory using a sparse array.
21       The allocated parts of the disk image cannot be larger than physical
22       RAM plus swap, less whatever is being used by the rest of the system.
23       Other allocators are available, see "ALLOCATORS" below.  All allocators
24       store the image in memory.  If you want to allocate more space than
25       this use nbdkit-file-plugin(1) backed by a temporary 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 (2⁶³-1 bytes).  This limit
29       is tested when nbdkit is compiled, and it should work on all platforms
30       and architectures supported by nbdkit.
31

EXAMPLES

33       Create a one gigabyte sparse RAM disk:
34
35        nbdkit memory 1G
36
37       If you want to loop mount the above disk, see nbdkit-loop(1).
38
39       Create the largest possible RAM disk:
40
41        nbdkit memory $(( 2**63 - 1 ))
42

PARAMETERS

44       [size=]SIZE
45           Specify the virtual size of the disk image.
46
47           This parameter is required.
48
49           "size=" is a magic config key and may be omitted in most cases.
50           See "Magic parameters" in nbdkit(1).
51
52       allocator=sparse
53       allocator=malloc[,mlock=true]
54       allocator=zstd
55           (nbdkit ≥ 1.22)
56
57           Select the backend allocation strategy.  See "ALLOCATORS" below.
58           The default is sparse.
59

NOTES

61   Preloading small amounts of data
62       If you want an in-memory disk image preinitialized with a small amount
63       of data specified on the command line, look at nbdkit-data-plugin(1)
64       instead.  Note by "small" this does not mean that the virtual disk
65       image must be small, but that the amount of data initially stored
66       sparsely is small enough to specify on the command line.
67
68   Preloading large amounts of data
69       If you want to preload a large amount of data (eg. a disk image) into
70       the memory plugin, use qemu-img(1) or nbdcopy(1):
71
72        $ rm -f pid
73        $ nbdkit -P pid memory 10G
74
75       Wait for nbdkit to become ready to accept connections:
76
77        $ while [ ! -f pid ]; do sleep 1; done
78
79       Preload Fedora disk image using qemu-img:
80
81        $ virt-builder fedora-28 --size=10G
82        $ qemu-img convert -p -n fedora-28.img nbd:localhost:10809
83
84       If you have libnbd ≥ 1.4, you can use nbdcopy(1) as an alternative:
85
86        $ nbdcopy -p fedora-28.img nbd://localhost
87

ALLOCATORS

89       Since nbdkit ≥ 1.22 several allocation strategies are available using
90       the "allocator" parameter.
91
92       allocator=sparse
93           The disk image is stored in memory using a sparse array.  The
94           sparse array uses a simple two level page table with a fixed page
95           size.  The allocated parts of the disk image cannot be larger than
96           physical RAM plus swap, less whatever is being used by the rest of
97           the system.  The aim of the sparse array implementation is to
98           support extremely large images for testing, although it won't
99           necessarily be efficient for that use case.  However it should also
100           be reasonably efficient for normal disk sizes.
101
102           The virtual size of the disk can be as large as you like, up to the
103           maximum supported by nbdkit (2⁶³-1 bytes).
104
105           This is the default, and was the only allocator available before
106           nbdkit 1.22.
107
108       allocator=malloc
109       allocator=malloc,mlock=true
110           The disk image is stored directly in memory allocated using
111           malloc(3) on the heap.  No sparseness is possible: you must have
112           enough memory for the whole disk.  Very large virtual sizes will
113           usually fail.  However this can be faster because the
114           implementation is simpler and the locking strategy allows more
115           concurrency.
116
117           If "mlock=true" is added then additionally the array is locked into
118           RAM using mlock(2) (so it should never be swapped out).  This
119           usually requires you to adjust the ulimit(1) associated with the
120           process and on some operating systems may require you to run nbdkit
121           as root.  (See also the nbdkit(1) --swap option).
122
123           The "mlock=true" feature is only supported on some platforms.  Use
124           "nbdkit memory --dump-plugin" and check that the output contains
125           "mlock=yes".
126
127       allocator=zstd
128           The disk image is stored in a sparse array where each page is
129           compressed using zstd compression.  Assuming a typical 2:1
130           compression ratio, this allows you to store twice as much real data
131           as "allocator=sparse", with the trade-off that the plugin is
132           slightly slower because it has to compress and decompress each
133           page.  Aside from compression, the implementation of this allocator
134           is similar to "allocator=sparse", so in other respects (such as
135           supporting huge virtual disk sizes) it is the same.
136
137           This allocator is only supported if nbdkit was compiled with zstd
138           support.  Use "nbdkit memory --dump-plugin" and check that the
139           output contains "zstd=yes".
140

FILES

142       $plugindir/nbdkit-memory-plugin.so
143           The plugin.
144
145           Use "nbdkit --dump-config" to find the location of $plugindir.
146

VERSION

148       "nbdkit-memory-plugin" first appeared in nbdkit 1.2.
149

SEE ALSO

151       nbdkit(1), nbdkit-plugin(3), nbdkit-loop(1), nbdkit-data-plugin(1),
152       nbdkit-file-plugin(1), nbdkit-info-plugin(1), nbdkit-tmpdisk-plugin(1),
153       mlock(2), malloc(3), qemu-img(1), nbdcopy(1).
154

AUTHORS

156       Richard W.M. Jones
157
159       Copyright Red Hat
160

LICENSE

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