nbdkit-ondemand-plugin(1) NBDKIT nbdkit-ondemand-plugin(1) NAME nbdkit-ondemand-plugin - create filesystems on demand SYNOPSIS nbdkit ondemand dir=EXPORTSDIR [size=]SIZE [wait=true] [share=true] { [type=ext4|xfs|vfat|...] [label=LABEL] | command=COMMAND [VAR=VALUE ...] } DESCRIPTION This is a plugin for nbdkit(1) which creates persistent filesystems on de- mand. Clients may simply connect to the server, requesting a particular export name, and a new filesystem is created if it does not exist already. Clients can also disconnect and reconnect with the same export name and the same filesystem will still be available. Filesystems are stored in a di- rectory on the server, so they persist over server restarts. By default each export is locked while it is in use by a client, preventing two clients from accessing the same filesystem (which would cause corrup- tion). Similar plugins include nbdkit-file-plugin(1) which can serve a predefined set of exports (clients cannot create more), nbdkit-tmpdisk-plugin(1) which creates a fresh temporary filesystem for each client, and nbdkit-lin- uxdisk-plugin(1) which exports a single filesystem from a local directory on the server. Export names When a new export name is requested by a client, a sparse file of the same name is created in "dir=EXPORTSDIR" on the server. The file will be for- matted with mkfs(8). The size of the file is currently fixed by the "size=SIZE" parameter, but we intend to make this client-configurable in future. The filesystem type and label may also be specified, otherwise "ext4" and no label is used. Export names must be ax "NAME_MAX" (usually 255) bytes in length and must not contain certain characters including "." at the start, and "/". There may be other limitations added in future. Client requests which do not obey these restrictions are rejected. As a special case, export name "" is mapped to the file name default. Security considerations You should only use this in an environment where you trust all your clients, since clients can use this plugin to consume arbitrary amounts of disk space by creating unlimited exports. It is therefore best to take steps to limit where clients can connect from using nbdkit-ip-filter(1), firewalls, or TLS client certificates. The command parameter Instead of running mkfs you can run an arbitrary command or shell script to create the disk. The other parameters to the plugin are turned into shell variables passed to the command. For example "type" becomes the shell variable $type, etc. Any parameters you want can be passed to the plugin and will be turned into shell variables (not only "type" and "label") making this a very flexible method to create filesystems and disks of all kinds. Two special variables are also passed to the shell script fragment: $disk The absolute path of the disk file. This is partially controlled by the client so you should quote it carefully. This file is not pre-cre- ated, the command must create it for example using: truncate -s $size "$disk" $size The virtual size in bytes. This is the "size" parameter, converted to bytes. Note the final size served to the client is whatever disk size "command" creates. Dead client detection Clients which "go away" without disconnecting (such as clients which re- boot) may cause exports to remain locked when they are no longer used. Practically this can cause problems such as the same client being unable to reconnect after a reboot. To avoid this you should enable keepalives to detect dead clients. Use the nbdkit --keepalive option, or for more fine-grained control see the discussion of keepalives in nbdkit-service(1). EXAMPLE Run the server like this: mkdir /var/tmp/exports nbdkit ondemand dir=/var/tmp/exports 1G Clients can connect and create 1G ext4 filesystems on demand using commands such as these (note the different export names): nbd-client server /dev/nbd0 -N export1 mount /dev/nbd0 /mnt guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda qemu-img info nbd:localhost:10809:exportname=export2 On the server you would see two filesystems created: $ ls -l /var/tmp/exports -rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export1 -rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export2 The plugin does not clean these up. If they are no longer needed then the server admin should delete them (or use a tmp cleaner). PARAMETERS command='COMMAND' Instead of running mkfs(8) to create the initial filesystem, run "COM- MAND" (a shell script fragment which usually must be quoted to protect it from the shell). See "The command parameter" above. dir=EXPORTSDIR The directory where filesystems are saved. When first using this plu- gin you should point this to an empty directory. When clients connect, filesystems are created here. This parameter is required. label=LABEL Select the filesystem label. The default is not set. share=true If set, the export is not locked. Two or more clients may connect to the same export. This usually results in filesystem corruption (if us- ing a regular filesystem like ext4), so you have to use some other means to guarantee exclusive access or to ensure sharing is safe. [size=]SIZE Specify the virtual size of all of the filesystems. If using "command", this is only a suggested size. The actual size of the resulting disk will be the size of the disk created by "command". This parameter is required. "size=" prefix may be omitted in most cases. See "Magic parameters" in nbdkit(1). type=FS Select the filesystem type. The default is "ext4". Most non-net- worked, non-cluster filesystem types supported by the mkfs(8) command can be used here. wait=true If set, if two clients try to connect at the same time to the same ex- port then the second client will wait for the first to disconnect. The default behaviour is to reject the second client with the error mes- sage: filesystem is locked by another client This setting is sometimes useful if you are making repeated connections and at the network level the first connection does not fully disconnect before the next connection starts. This can also happen as a side-ef- fect of using "guestfish --ro" which opens two NBD connections in quick succession. If "share=true" then locking is not used and the "wait" parameter has no effect. FILES $plugindir/nbdkit-ondemand-plugin.so The plugin. Use "nbdkit --dump-config" to find the location of $plugindir. VERSION "nbdkit-ondemand-plugin" first appeared in nbdkit 1.22. SEE ALSO nbdkit(1), nbdkit-plugin(3), nbdkit-file-plugin(1), nbdkit-ip-filter(1), nbdkit-limit-filter(1), nbdkit-linuxdisk-plugin(1), nbdkit-memory-plu- gin(1), nbdkit-tmpdisk-plugin(1), nbdkit-service(1), nbdkit-tls(1), mkfs(8), mke2fs(8). AUTHORS Richard W.M. Jones COPYRIGHT Copyright Red Hat LICENSE Redistribution and use in source and binary forms, with or without modifi- cation, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright no- tice, this list of conditions and the following disclaimer in the docu- mentation and/or other materials provided with the distribution. * Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EX- PRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS- CLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DI- RECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SER- VICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL- ITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAM- AGE. nbdkit-1.46.2 2026-08-30 nbdkit-ondemand-plugin(1)
NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | PARAMETERS | FILES | VERSION | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nbdkit-ondemand-plugin&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>