1nbdkit-memory-plugin(1) NBDKIT nbdkit-memory-plugin(1)
2
6 nbdkit-memory-plugin - nbdkit virtual memory (RAM disk) plugin
7
9 nbdkit memory [size=]SIZE [allocator=sparse|malloc|zstd]
10
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 All nbdkit clients will see the same disk content, initially all
18 zeroes.
19 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 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
33 Create a one gigabyte sparse RAM disk:
34 nbdkit memory 1G
36 If you want to loop mount the above disk, see nbdkit-loop(1).
38 Create the largest possible RAM disk:
40 nbdkit memory $(( 2**63 - 1 ))
42
44 [size=]SIZE
45 Specify the virtual size of the disk image.
46 This parameter is required.
48 "size=" is a magic config key and may be omitted in most cases.
50 See "Magic parameters" in nbdkit(1).
51 allocator=sparse
53 allocator=malloc[,mlock=true]
54 allocator=zstd
55 (nbdkit ≥ 1.22)
56 Select the backend allocation strategy. See "ALLOCATORS" below.
58 The default is sparse.
59
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 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 $ rm -f pid
73 $ nbdkit -P pid memory 10G
74 Wait for nbdkit to become ready to accept connections:
76 $ while [ ! -f pid ]; do sleep 1; done
78 Preload Fedora disk image using qemu-img:
80 $ virt-builder fedora-28 --size=10G
82 $ qemu-img convert -p -n fedora-28.img nbd:localhost:10809
83 If you have libnbd ≥ 1.4, you can use nbdcopy(1) as an alternative:
85 $ nbdcopy -p fedora-28.img nbd://localhost
87
89 Since nbdkit ≥ 1.22 several allocation strategies are available using
90 the "allocator" parameter.
91 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 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 This is the default, and was the only allocator available before
106 nbdkit 1.22.
107 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 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 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 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 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
142 $plugindir/nbdkit-memory-plugin.so
143 The plugin.
144 Use "nbdkit --dump-config" to find the location of $plugindir.
146
148 "nbdkit-memory-plugin" first appeared in nbdkit 1.2.
149
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
156 Richard W.M. Jones
157
159 Copyright (C) 2017-2020 Red Hat Inc.
160
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 • Redistributions of source code must retain the above copyright
167 notice, this list of conditions and the following disclaimer.
168 • 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 • 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 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.
189nbdkit-1.28.2 2021-11-09 nbdkit-memory-plugin(1)