1nbdkit-ondemand-plugin(1) NBDKIT nbdkit-ondemand-plugin(1)
2
6 nbdkit-ondemand-plugin - create filesystems on demand
7
9 nbdkit ondemand dir=EXPORTSDIR [size=]SIZE [wait=true]
10 { [type=ext4|xfs|vfat|...] [label=LABEL]
11 | command=COMMAND [VAR=VALUE ...] }
12
14 This is a plugin for nbdkit(1) which creates persistent filesystems on
15 demand. Clients may simply connect to the server, requesting a
16 particular export name, and a new filesystem is created if it does not
17 exist already. Clients can also disconnect and reconnect with the same
18 export name and the same filesystem will still be available.
19 Filesystems are stored in a directory on the server, so they also
20 persist over nbdkit and server restarts.
21 Each filesystem is locked while it is in use by a client, preventing
23 two clients from accessing the same filesystem (which would cause
24 corruption).
25 Similar plugins include nbdkit-file-plugin(1) which can serve a
27 predefined set of exports (clients cannot create more),
28 nbdkit-tmpdisk-plugin(1) which creates a fresh temporary filesystem for
29 each client, and nbdkit-linuxdisk-plugin(1) which exports a single
30 filesystem from a local directory on the server.
31 Export names
33 When a new export name is requested by a client, a sparse file of the
34 same name is created in "dir=EXPORTSDIR" on the server. The file will
35 be formatted with mkfs(8). The size of the file is currently fixed by
36 the "size=SIZE" parameter, but we intend to make this client-
37 configurable in future. The filesystem type and label may also be
38 specified, otherwise "ext4" and no label is used.
39 Export names must be ≤ "NAME_MAX" (usually 255) bytes in length and
41 must not contain certain characters including ".", "/" and ":". There
42 may be other limitations added in future. Client requests which do not
43 obey these restrictions are rejected. As a special case, export name
44 "" is mapped to the file name default.
45 Security considerations
47 You should only use this in an environment where you trust all your
48 clients, since clients can use this plugin to consume arbitrary amounts
49 of disk space by creating unlimited exports. It is therefore best to
50 take steps to limit where clients can connect from using
51 nbdkit-ip-filter(1), firewalls, or TLS client certificates.
52 The command parameter
54 Instead of running mkfs you can run an arbitrary command (a shell
55 script fragment) to create the disk.
56 The other parameters to the plugin are turned into shell variables
58 passed to the command. For example "type" becomes the shell variable
59 $type, etc. Any parameters you want can be passed to the plugin and
60 will be turned into shell variables (not only "type" and "label")
61 making this a very flexible method to create filesystems and disks of
62 all kinds.
63 Two special variables are also passed to the shell script fragment:
65 $disk
67 The absolute path of the disk file. This is partially controlled
68 by the client so you should quote it carefully. This file is not
69 pre-created, the command must create it for example using:
70 truncate -s $size "$disk"
72 $size
74 The virtual size in bytes. This is the "size" parameter, converted
75 to bytes. Note the final size served to the client is whatever
76 disk size "command" creates.
77
79 Run the server like this:
80 mkdir /var/tmp/exports
82 nbdkit ondemand dir=/var/tmp/exports 1G
83 Clients can connect and create 1G ext4 filesystems on demand using
85 commands such as these (note the different export names):
86 nbd-client server /dev/nbd0 -N export1
88 mount /dev/nbd0 /mnt
89 guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda
91 qemu-img info nbd:localhost:10809:exportname=export2
93 On the server you would see two filesystems created:
95 $ ls -l /var/tmp/exports
97 -rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export1
98 -rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export2
99 The plugin does not clean these up. If they are no longer needed then
101 the server admin should delete them (or use a tmp cleaner).
102
104 command='COMMAND'
105 Instead of running mkfs(8) to create the initial filesystem, run
106 "COMMAND" (a shell script fragment which usually must be quoted to
107 protect it from the shell). See "The command parameter" and
108 "EXAMPLES" sections above.
109 dir=EXPORTSDIR
111 The directory where filesystems are saved. When first using this
112 plugin you should point this to an empty directory. When clients
113 connect, filesystems are created here.
114 This parameter is required.
116 label=LABEL
118 Select the filesystem label. The default is not set.
119 [size=]SIZE
121 Specify the virtual size of all of the filesystems.
122 If using "command", this is only a suggested size. The actual size
124 of the resulting disk will be the size of the disk created by
125 "command".
126 This parameter is required.
128 "size=" is a magic config key and may be omitted in most cases.
130 See "Magic parameters" in nbdkit(1).
131 type=FS
133 Select the filesystem type. The default is "ext4". Most non-
134 networked, non-cluster filesystem types supported by the mkfs(8)
135 command can be used here.
136 wait=true
138 If set, if two clients try to connect at the same time to the same
139 export then the second client will wait for the first to
140 disconnect. The default behaviour is to reject the second client
141 with the error message:
142 filesystem is locked by another client
144 This setting is sometimes useful if you are making repeated
146 connections and at the network level the first connection does not
147 fully disconnect before the next connection starts. This can also
148 happen as a side-effect of using "guestfish --ro" which opens two
149 NBD connections in quick succession.
150
152 $plugindir/nbdkit-ondemand-plugin.so
153 The plugin.
154 Use "nbdkit --dump-config" to find the location of $plugindir.
156
158 "nbdkit-ondemand-plugin" first appeared in nbdkit 1.22.
159
161 nbdkit(1), nbdkit-plugin(3), nbdkit-file-plugin(1),
162 nbdkit-ip-filter(1), nbdkit-limit-filter(1),
163 nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
164 nbdkit-tmpdisk-plugin(1), nbdkit-tls(1), mkfs(8), mke2fs(8).
165
167 Richard W.M. Jones
168
170 Copyright Red Hat
171
173 Redistribution and use in source and binary forms, with or without
174 modification, are permitted provided that the following conditions are
175 met:
176 • Redistributions of source code must retain the above copyright
178 notice, this list of conditions and the following disclaimer.
179 • Redistributions in binary form must reproduce the above copyright
181 notice, this list of conditions and the following disclaimer in the
182 documentation and/or other materials provided with the
183 distribution.
184 • Neither the name of Red Hat nor the names of its contributors may
186 be used to endorse or promote products derived from this software
187 without specific prior written permission.
188 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
190 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
191 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
192 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
193 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
194 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
195 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
196 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
197 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
198 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
199 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
200nbdkit-1.36.2 2023-11-26 nbdkit-ondemand-plugin(1)