NAME

       nbdkit-ondemand-plugin - create filesystems on demand

SYNOPSIS

        nbdkit ondemand dir=EXPORTSDIR [size=]SIZE
                        { [type=ext4|xfs|vfat|...] [label=LABEL]
                          | command=COMMAND [VAR=VALUE ...] }

DESCRIPTION

       This is a plugin for nbdkit(1) which creates persistent filesystems on demand.  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 directory on the server, so they also persist over nbdkit and
       server restarts.

       Each filesystem is locked while it is in use by a client, preventing two clients from
       accessing the same filesystem (which would cause corruption).

       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-linuxdisk-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 formatted 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 ≤ "NAME_MAX" (usually 255) bytes in length and must not contain
       certain characters including ".", "/" 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 (a shell script fragment) 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-created, 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.

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 -b 512 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 "COMMAND" (a shell
           script fragment which usually must be quoted to protect it from the shell).  See "The
           command parameter" and "EXAMPLES" sections above.

       dir=EXPORTSDIR
           The directory where filesystems are saved.  When first using this plugin 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.

       [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=" is a magic config key and may be omitted in most cases.  See "Magic
           parameters" in nbdkit(1).

       type=FS
           Select the filesystem type.  The default is "ext4".  Most non-networked, non-cluster
           filesystem types supported by the mkfs(8) command can be used here.

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-plugin(1),
       nbdkit-tmpdisk-plugin(1), nbdkit-tls(1), mkfs(8), mke2fs(8).

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2018-2020 Red Hat Inc.

LICENSE

       Redistribution and use in source and binary forms, with or without modification, 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 notice, this list of
           conditions and the following disclaimer in the documentation 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 EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS
       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 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 DAMAGE.