.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.36.3 (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-ondemand-plugin 1"
.TH nbdkit-ondemand-plugin 1 2024-01-17 nbdkit-1.36.3 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\-ondemand\-plugin \- create filesystems on demand
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& nbdkit ondemand dir=EXPORTSDIR [size=]SIZE [wait=true]
\&                 { [type=ext4|xfs|vfat|...] [label=LABEL]
\&                   | command=COMMAND [VAR=VALUE ...] }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is a plugin for \fBnbdkit\fR\|(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.
.PP
Each filesystem is locked while it is in use by a client, preventing
two clients from accessing the same filesystem (which would cause
corruption).
.PP
Similar plugins include \fBnbdkit\-file\-plugin\fR\|(1) which can serve a
predefined set of exports (clients cannot create more),
\&\fBnbdkit\-tmpdisk\-plugin\fR\|(1) which creates a fresh temporary filesystem
for each client, and \fBnbdkit\-linuxdisk\-plugin\fR\|(1) which exports a
single filesystem from a local directory on the server.
.SS "Export names"
.IX Subsection "Export names"
When a new export name is requested by a client, a sparse file of the
same name is created in \f(CW\*(C`dir=EXPORTSDIR\*(C'\fR on the server.  The file
will be formatted with \fBmkfs\fR\|(8).  The size of the file is currently
fixed by the \f(CW\*(C`size=SIZE\*(C'\fR parameter, but we intend to make this
client-configurable in future.  The filesystem type and label may also
be specified, otherwise \f(CW\*(C`ext4\*(C'\fR and no label is used.
.PP
Export names must be ≤ \f(CW\*(C`NAME_MAX\*(C'\fR (usually 255) bytes in length
and must not contain certain characters including \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`/\*(C'\fR and \f(CW\*(C`:\*(C'\fR.
There may be other limitations added in future.  Client requests which
do not obey these restrictions are rejected.  As a special case,
export name \f(CW""\fR is mapped to the file name \fIdefault\fR.
.SS "Security considerations"
.IX Subsection "Security considerations"
You should \fBonly\fR 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
\&\fBnbdkit\-ip\-filter\fR\|(1), firewalls, or TLS client certificates.
.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 filesystems and
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.  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:
.Sp
.Vb 1
\& truncate \-s $size "$disk"
.Ve
.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.
.SH EXAMPLE
.IX Header "EXAMPLE"
Run the server like this:
.PP
.Vb 2
\& mkdir /var/tmp/exports
\& nbdkit ondemand dir=/var/tmp/exports 1G
.Ve
.PP
Clients can connect and create 1G ext4 filesystems on demand using
commands such as these (note the different export names):
.PP
.Vb 2
\& nbd\-client server /dev/nbd0 \-N export1
\& mount /dev/nbd0 /mnt
.Ve
.PP
.Vb 1
\& guestfish \-\-format=raw \-a nbd://localhost/export2 \-m /dev/sda
.Ve
.PP
.Vb 1
\& qemu\-img info nbd:localhost:10809:exportname=export2
.Ve
.PP
On the server you would see two filesystems created:
.PP
.Vb 3
\& $ 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
.Ve
.PP
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).
.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 \fBdir=\fREXPORTSDIR 4
.IX Item "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.
.Sp
This parameter is required.
.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 all of the filesystems.
.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.
.IP \fBwait=true\fR 4
.IX Item "wait=true"
If set, if two clients try to connect at the same time to the same
export then the second client will wait for the first to disconnect.
The default behaviour is to reject the second client with the error
message:
.Sp
.Vb 1
\& filesystem is locked by another client
.Ve
.Sp
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-effect of using \f(CW\*(C`guestfish \-\-ro\*(C'\fR which opens two NBD
connections in quick succession.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$plugindir\fR\fI/nbdkit\-ondemand\-plugin.so\fR 4
.el .IP \fR\f(CI$plugindir\fR\fI/nbdkit\-ondemand\-plugin.so\fR 4
.IX Item "$plugindir/nbdkit-ondemand-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\-ondemand\-plugin\*(C'\fR first appeared in nbdkit 1.22.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\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\-tmpdisk\-plugin\fR\|(1),
\&\fBnbdkit\-tls\fR\|(1),
\&\fBmkfs\fR\|(8),
\&\fBmke2fs\fR\|(8).
.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.