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

NAME

6       nbdkit-ondemand-plugin - create filesystems on demand
7

SYNOPSIS

9        nbdkit ondemand dir=EXPORTSDIR [size=]SIZE [wait=true]
10                        { [type=ext4|xfs|vfat|...] [label=LABEL]
11                          | command=COMMAND [VAR=VALUE ...] }
12

DESCRIPTION

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
22       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
26       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
32   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
40       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
46   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
53   The command parameter
54       Instead of running mkfs you can run an arbitrary command (a shell
55       script fragment) to create the disk.
56
57       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
64       Two special variables are also passed to the shell script fragment:
65
66       $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
71            truncate -s $size "$disk"
72
73       $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

EXAMPLE

79       Run the server like this:
80
81        mkdir /var/tmp/exports
82        nbdkit ondemand dir=/var/tmp/exports 1G
83
84       Clients can connect and create 1G ext4 filesystems on demand using
85       commands such as these (note the different export names):
86
87        nbd-client server /dev/nbd0 -N export1
88        mount /dev/nbd0 /mnt
89
90        guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda
91
92        qemu-img info nbd:localhost:10809:exportname=export2
93
94       On the server you would see two filesystems created:
95
96        $ 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
100       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

PARAMETERS

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
110       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
115           This parameter is required.
116
117       label=LABEL
118           Select the filesystem label.  The default is not set.
119
120       [size=]SIZE
121           Specify the virtual size of all of the filesystems.
122
123           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
127           This parameter is required.
128
129           "size=" is a magic config key and may be omitted in most cases.
130           See "Magic parameters" in nbdkit(1).
131
132       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
137       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
143            filesystem is locked by another client
144
145           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

FILES

152       $plugindir/nbdkit-ondemand-plugin.so
153           The plugin.
154
155           Use "nbdkit --dump-config" to find the location of $plugindir.
156

VERSION

158       "nbdkit-ondemand-plugin" first appeared in nbdkit 1.22.
159

SEE ALSO

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

AUTHORS

167       Richard W.M. Jones
168
170       Copyright Red Hat
171

LICENSE

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
177       •   Redistributions of source code must retain the above copyright
178           notice, this list of conditions and the following disclaimer.
179
180       •   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
185       •   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
189       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.
200
201
202
203nbdkit-1.36.2                     2023-11-26         nbdkit-ondemand-plugin(1)
Impressum