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
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 -b 512 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

FILES

138       $plugindir/nbdkit-ondemand-plugin.so
139           The plugin.
140
141           Use "nbdkit --dump-config" to find the location of $plugindir.
142

VERSION

144       "nbdkit-ondemand-plugin" first appeared in nbdkit 1.22.
145

SEE ALSO

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

AUTHORS

153       Richard W.M. Jones
154
156       Copyright (C) 2018-2020 Red Hat Inc.
157

LICENSE

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
163       ·   Redistributions of source code must retain the above copyright
164           notice, this list of conditions and the following disclaimer.
165
166       ·   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
171       ·   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
175       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.
186
187
188
189nbdkit-1.24.2                     2021-03-02         nbdkit-ondemand-plugin(1)
Impressum