.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.38.1 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-tmpdisk-plugin 1"
.TH nbdkit-tmpdisk-plugin 1 2024-04-21 nbdkit-1.38.1 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-tmpdisk\-plugin \- create a fresh temporary filesystem for each client
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& nbdkit tmpdisk [size=]SIZE [type=ext4|xfs|vfat|...] [label=LABEL]
.Ve
.PP
.Vb 1
\& nbdkit tmpdisk [size=]SIZE command=COMMAND [VAR=VALUE ...]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This \fBnbdkit\fR\|(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.  \fBThe filesystem is deleted\fR
when the client disconnects.  If you want a persistent filesystem, use
\&\fBnbdkit\-ondemand\-plugin\fR\|(1) instead.
.PP
When a new client connects, a blank, sparse file of the required size
is created in \f(CW$TMPDIR\fR (or \fI/var/tmp\fR).  \fBmkfs\fR\|(8) is then run on
the file to create the empty filesystem, and this filesystem is served
to the client.  Unlike \fBnbdkit\-linuxdisk\-plugin\fR\|(1) each client of
this plugin sees a different disk.
.PP
The size of the disk is chosen using the \f(CW\*(C`size\*(C'\fR parameter.  The
filesystem type is \f(CW\*(C`ext4\*(C'\fR but this can be changed using the \f(CW\*(C`type\*(C'\fR
parameter (controlling the \fI\-t\fR option of mkfs).  The filesystem
label may be set using \f(CW\*(C`label\*(C'\fR.
.SS "The command parameter"
.IX Subsection "The command parameter"
Instead of running mkfs you can run an arbitrary command (a shell
script fragment) to create the disk.
.PP
The other parameters to the plugin are turned into shell variables
passed to the command.  For example \f(CW\*(C`type\*(C'\fR becomes the shell variable
\&\f(CW$type\fR, etc.  Any parameters you want can be passed to the plugin
and will be turned into shell variables (not only \f(CW\*(C`type\*(C'\fR and
\&\f(CW\*(C`label\*(C'\fR) making this a very flexible method to create temporary disks
of all kinds.
.PP
Two special variables are also passed to the shell script fragment:
.ie n .IP $disk 4
.el .IP \f(CW$disk\fR 4
.IX Item "$disk"
The absolute path of the disk file.  Note that this is not
pre-created, you must create it yourself, for example using:
.Sp
.Vb 1
\& truncate \-s $size "$disk"
.Ve
.Sp
\&\f(CW$disk\fR is deleted automatically when the client disconnects.
.ie n .IP $size 4
.el .IP \f(CW$size\fR 4
.IX Item "$size"
The virtual size in bytes.  This is the \f(CW\*(C`size\*(C'\fR parameter, converted
to bytes.  Note the final size served to the client is whatever disk
size \f(CW\*(C`command\*(C'\fR creates.
.SS "Security considerations"
.IX Subsection "Security considerations"
Because each client gets a new disk, the amount of disk space
required on the server can be as much as
\&\fInumber\ of\ clients\fR\ ×\ \fIsize\fR.  It is therefore best to
limit the number of clients using \fBnbdkit\-limit\-filter\fR\|(1) or take
steps to limit where clients can connect from using
\&\fBnbdkit\-ip\-filter\fR\|(1), firewalls, or TLS client certificates.
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS "Remote tmpfs"
.IX Subsection "Remote tmpfs"
One use for this is to create a kind of "remote \fBtmpfs\fR\|(5)" for thin
clients.  On the server you would run (see \fBnbdkit\-service\fR\|(1)):
.PP
.Vb 1
\& nbdkit tmpdisk 16G
.Ve
.PP
To set up each thin client follow the instructions in
\&\fBnbdkit\-client\fR\|(1).  Clients will see a fresh, empty, mounted
directory after boot.
.SS "Overriding mkfs options"
.IX Subsection "Overriding mkfs options"
Using \f(CW\*(C`command\*(C'\fR allows you to easily override any mkfs option, for
example:
.PP
.Vb 4
\& nbdkit tmpdisk 16G command=\*(Aq
\&     truncate \-s $size "$disk"
\&     mke2fs \-F \-N 10000 \-t ext4 "$disk"
\& \*(Aq
.Ve
.SS "Serve a fresh blank disk to each client"
.IX Subsection "Serve a fresh blank disk to each client"
Again using \f(CW\*(C`command\*(C'\fR, this demonstrates serving any file that you
can create locally to the client.  This is different from
\&\fBnbdkit\-memory\-plugin\fR\|(1) because the clients all see their own
private disk (instead of all seeing the same shared disk):
.PP
.Vb 1
\& nbdkit tmpdisk 16G command=\*(Aq truncate \-s $size "$disk" \*(Aq
.Ve
.SS "Serve a fresh operating system to each client"
.IX Subsection "Serve a fresh operating system to each client"
.Vb 2
\& nbdkit tmpdisk 16G os=fedora\-31 \e
\&     command=\*(Aq virt\-builder \-o "$disk" \-\-size ${size}b "$os" \*(Aq
.Ve
.SS "Serve a throwaway snapshot of a base image to each client"
.IX Subsection "Serve a throwaway snapshot of a base image to each client"
You could create a base image using \fBmke2fs\fR\|(8) \fI\-d\fR option,
\&\fBvirt\-builder\fR\|(1), or similar tools.  Then in the command you could
copy and serve different throwaway snapshots to each client:
.PP
.Vb 4
\& truncate \-s 1G base.img
\& mke2fs \-d initial\-content/ \-F \-t ext4 base.img
\& nbdkit tmpdisk size=0 base=$PWD/base.img \e
\&     command=\*(Aq cp \-\-sparse=always "$base" "$disk" \*(Aq
.Ve
.PP
The unusual \f(CW\*(C`size=0\*(C'\fR parameter is because when using \f(CW\*(C`command\*(C'\fR,
\&\f(CW\*(C`size\*(C'\fR 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 \f(CW$disk\fR created by the \fBcp\fR\|(1) command.
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP \fBcommand='\fRCOMMAND\fB'\fR 4
.IX Item "command='COMMAND'"
Instead of running \fBmkfs\fR\|(8) to create the initial filesystem, run
\&\f(CW\*(C`COMMAND\*(C'\fR (a shell script fragment which usually must be quoted to
protect it from the shell).  See "The command parameter" and
"EXAMPLES" sections above.
.IP \fBlabel=\fRLABEL 4
.IX Item "label=LABEL"
Select the filesystem label.  The default is not set.
.IP [\fBsize=\fR]SIZE 4
.IX Item "[size=]SIZE"
Specify the virtual size of the disk image.
.Sp
If using \f(CW\*(C`command\*(C'\fR, this is only a suggested size.  The actual size
of the resulting disk will be the size of the disk created by
\&\f(CW\*(C`command\*(C'\fR.
.Sp
This parameter is required.
.Sp
\&\f(CW\*(C`size=\*(C'\fR is a magic config key and may be omitted in most cases.
See "Magic parameters" in \fBnbdkit\fR\|(1).
.IP \fBtype=\fRFS 4
.IX Item "type=FS"
Select the filesystem type.  The default is \f(CW\*(C`ext4\*(C'\fR.  Most
non-networked, non-cluster filesystem types supported by the
\&\fBmkfs\fR\|(8) command can be used here.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.ie n .IP """TMPDIR""" 4
.el .IP \f(CWTMPDIR\fR 4
.IX Item "TMPDIR"
The temporary disks for this plugin are created in this directory, one
per connected client.  If not set this defaults to \fI/var/tmp\fR.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$plugindir\fR\fI/nbdkit\-tmpdisk\-plugin.so\fR 4
.el .IP \fR\f(CI$plugindir\fR\fI/nbdkit\-tmpdisk\-plugin.so\fR 4
.IX Item "$plugindir/nbdkit-tmpdisk-plugin.so"
The plugin.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$plugindir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-tmpdisk\-plugin\*(C'\fR first appeared in nbdkit 1.20.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBnbdkit\-data\-plugin\fR\|(1),
\&\fBnbdkit\-eval\-plugin\fR\|(1),
\&\fBnbdkit\-file\-plugin\fR\|(1),
\&\fBnbdkit\-ip\-filter\fR\|(1),
\&\fBnbdkit\-limit\-filter\fR\|(1),
\&\fBnbdkit\-linuxdisk\-plugin\fR\|(1),
\&\fBnbdkit\-memory\-plugin\fR\|(1),
\&\fBnbdkit\-sh\-plugin\fR\|(1),
\&\fBnbdkit\-loop\fR\|(1),
\&\fBnbdkit\-tls\fR\|(1),
\&\fBmkfs\fR\|(8),
\&\fBmke2fs\fR\|(8),
\&\fBvirt\-builder\fR\|(1).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
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.