NAME

       nbdkit-tmpdisk-plugin - create a fresh temporary filesystem for each client

SYNOPSIS

        nbdkit tmpdisk [size=]SIZE [type=ext4|xfs|vfat|...] [label=LABEL]

        nbdkit tmpdisk [size=]SIZE command=COMMAND [VAR=VALUE ...]

DESCRIPTION

       This nbdkit(1) plugin is used for creating temporary filesystems for thin clients.  Each time a client
       connects it will see a fresh, empty filesystem for its exclusive use.  The filesystem is deleted when the
       client disconnects.  If you want a persistent filesystem, use nbdkit-ondemand-plugin(1) instead.

       When a new client connects, a blank, sparse file of the required size is created in $TMPDIR (or
       /var/tmp).  mkfs(8) is then run on the file to create the empty filesystem, and this filesystem is served
       to the client.  Unlike nbdkit-linuxdisk-plugin(1) each client of this plugin sees a different disk.

       The size of the disk is chosen using the "size" parameter.  The filesystem type is "ext4" but this can be
       changed using the "type" parameter (controlling the -t option of mkfs).  The filesystem label may be set
       using "label".

   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 temporary disks of all kinds.

       Two special variables are also passed to the shell script fragment:

       $disk
           The  absolute path of the disk file.  Note that this is not pre-created, you must create it yourself,
           for example using:

            truncate -s $size "$disk"

           $disk is deleted automatically when the client disconnects.

       $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.

   Security considerations
       Because  each  client  gets a new disk, the amount of disk space required on the server can be as much as
       number of clients × size.   It   is   therefore   best   to   limit   the   number   of   clients   using
       nbdkit-limit-filter(1)  or  take steps to limit where clients can connect from using nbdkit-ip-filter(1),
       firewalls, or TLS client certificates.

EXAMPLES

   Remote tmpfs
       One use for this is to create a kind of "remote tmpfs(5)" for thin clients.  On the server you would  run
       (see nbdkit-service(1)):

        nbdkit tmpdisk 16G

       To set up each thin client follow the instructions in nbdkit-client(1).  Clients will see a fresh, empty,
       mounted directory after boot.

   Overriding mkfs options
       Using "command" allows you to easily override any mkfs option, for example:

        nbdkit tmpdisk 16G command='
            truncate -s $size "$disk"
            mke2fs -F -N 10000 -t ext4 "$disk"
        '

   Serve a fresh blank disk to each client
       Again  using  "command",  this  demonstrates  serving any file that you can create locally to the client.
       This is different from nbdkit-memory-plugin(1) because  the  clients  all  see  their  own  private  disk
       (instead of all seeing the same shared disk):

        nbdkit tmpdisk 16G command=' truncate -s $size "$disk" '

   Serve a fresh operating system to each client
        nbdkit tmpdisk 16G os=fedora-31 \
            command=' virt-builder -o "$disk" --size ${size}b "$os" '

   Serve a throwaway snapshot of a base image to each client
       You  could create a base image using mke2fs(8) -d option, virt-builder(1), or similar tools.  Then in the
       command you could copy and serve different throwaway snapshots to each client:

        truncate -s 1G base.img
        mke2fs -d initial-content/ -F -t ext4 base.img
        nbdkit tmpdisk size=0 base=$PWD/base.img \
            command=' cp --sparse=always "$base" "$disk" '

       The unusual "size=0" parameter is because when using  "command",  "size"  is  only  a  request  (but  the
       parameter is required).  In this case the command ignores the requested size.  The final size is the size
       of $disk created by the cp(1) command.

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.

       label=LABEL
           Select the filesystem label.  The default is not set.

       [size=]SIZE
           Specify the virtual size of the disk image.

           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.

ENVIRONMENT VARIABLES

       "TMPDIR"
           The  temporary disks for this plugin are created in this directory, one per connected client.  If not
           set this defaults to /var/tmp.

FILES

       $plugindir/nbdkit-tmpdisk-plugin.so
           The plugin.

           Use "nbdkit --dump-config" to find the location of $plugindir.

VERSION

       "nbdkit-tmpdisk-plugin" first appeared in nbdkit 1.20.

SEE ALSO

       nbdkit(1),   nbdkit-plugin(3),   nbdkit-data-plugin(1),   nbdkit-eval-plugin(1),   nbdkit-file-plugin(1),
       nbdkit-ip-filter(1),    nbdkit-limit-filter(1),    nbdkit-linuxdisk-plugin(1),   nbdkit-memory-plugin(1),
       nbdkit-ondemand-plugin(1),   nbdkit-sh-plugin(3),   nbdkit-loop(1),   nbdkit-service(1),   nbdkit-tls(1),
       mkfs(8), mke2fs(8), virt-builder(1).

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright Red Hat

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.

nbdkit-1.42.2                                      2025-04-02                           nbdkit-tmpdisk-plugin(1)