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
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 -b 512 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
138 $plugindir/nbdkit-ondemand-plugin.so
139 The plugin.
140 Use "nbdkit --dump-config" to find the location of $plugindir.
142
144 "nbdkit-ondemand-plugin" first appeared in nbdkit 1.22.
145
147 nbdkit(1), nbdkit-plugin(3), nbdkit-file-plugin(1),
148 nbdkit-ip-filter(1), nbdkit-limit-filter(1),
149 nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
150 nbdkit-tmpdisk-plugin(1), nbdkit-tls(1), mkfs(8), mke2fs(8).
151
153 Richard W.M. Jones
154
156 Copyright (C) 2018-2020 Red Hat Inc.
157
159 Redistribution and use in source and binary forms, with or without
160 modification, are permitted provided that the following conditions are
161 met:
162 · Redistributions of source code must retain the above copyright
164 notice, this list of conditions and the following disclaimer.
165 · Redistributions in binary form must reproduce the above copyright
167 notice, this list of conditions and the following disclaimer in the
168 documentation and/or other materials provided with the
169 distribution.
170 · Neither the name of Red Hat nor the names of its contributors may
172 be used to endorse or promote products derived from this software
173 without specific prior written permission.
174 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
176 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
177 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
178 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
179 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
180 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
181 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
182 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
183 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
184 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
185 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
186nbdkit-1.24.2 2021-03-02 nbdkit-ondemand-plugin(1)