1nbdkit-tmpdisk-plugin(1)            NBDKIT            nbdkit-tmpdisk-plugin(1)
2
3
4

NAME

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

SYNOPSIS

10        nbdkit tmpdisk [size=]SIZE [type=ext4|xfs|vfat|...] [label=LABEL]
11
12        nbdkit tmpdisk [size=]SIZE command=COMMAND [VAR=VALUE ...]
13

DESCRIPTION

15       This nbdkit(1) plugin is used for creating temporary filesystems for
16       thin clients.  Each time a client connects it will see a fresh, empty
17       filesystem for its exclusive use.  The filesystem is deleted when the
18       client disconnects.  If you want a persistent filesystem, use
19       nbdkit-ondemand-plugin(1) instead.
20
21       When a new client connects, a blank, sparse file of the required size
22       is created in $TMPDIR (or /var/tmp).  mkfs(8) is then run on the file
23       to create the empty filesystem, and this filesystem is served to the
24       client.  Unlike nbdkit-linuxdisk-plugin(1) each client of this plugin
25       sees a different disk.
26
27       The size of the disk is chosen using the "size" parameter.  The
28       filesystem type is "ext4" but this can be changed using the "type"
29       parameter (controlling the -t option of mkfs).  The filesystem label
30       may be set using "label".
31
32   The command parameter
33       Instead of running mkfs you can run an arbitrary command (a shell
34       script fragment) to create the disk.
35
36       The other parameters to the plugin are turned into shell variables
37       passed to the command.  For example "type" becomes the shell variable
38       $type, etc.  Any parameters you want can be passed to the plugin and
39       will be turned into shell variables (not only "type" and "label")
40       making this a very flexible method to create temporary disks of all
41       kinds.
42
43       Two special variables are also passed to the shell script fragment:
44
45       $disk
46           The absolute path of the disk file.  Note that this is not pre-
47           created, you must create it yourself, for example using:
48
49            truncate -s $size "$disk"
50
51           $disk is deleted automatically when the client disconnects.
52
53       $size
54           The virtual size in bytes.  This is the "size" parameter, converted
55           to bytes.  Note the final size served to the client is whatever
56           disk size "command" creates.
57
58   Security considerations
59       Because each client gets a new disk, the amount of disk space required
60       on the server can be as much as number of clients × size.  It is
61       therefore best to limit the number of clients using
62       nbdkit-limit-filter(1) or take steps to limit where clients can connect
63       from using nbdkit-ip-filter(1), firewalls, or TLS client certificates.
64

EXAMPLES

66   Remote tmpfs
67       One use for this is to create a kind of "remote tmpfs(5)" for thin
68       clients.  On the server you would run (see nbdkit-service(1)):
69
70        nbdkit tmpdisk 16G
71
72       To set up each thin client follow the instructions in nbdkit-client(1).
73       Clients will see a fresh, empty, mounted directory after boot.
74
75   Overriding mkfs options
76       Using "command" allows you to easily override any mkfs option, for
77       example:
78
79        nbdkit tmpdisk 16G command='
80            truncate -s $size "$disk"
81            mke2fs -F -N 10000 -t ext4 "$disk"
82        '
83
84   Serve a fresh blank disk to each client
85       Again using "command", this demonstrates serving any file that you can
86       create locally to the client.  This is different from
87       nbdkit-memory-plugin(1) because the clients all see their own private
88       disk (instead of all seeing the same shared disk):
89
90        nbdkit tmpdisk 16G command=' truncate -s $size "$disk" '
91
92   Serve a fresh operating system to each client
93        nbdkit tmpdisk 16G os=fedora-31 \
94            command=' virt-builder -o "$disk" --size ${size}b "$os" '
95
96   Serve a throwaway snapshot of a base image to each client
97       You could create a base image using mke2fs(8) -d option,
98       virt-builder(1), or similar tools.  Then in the command you could copy
99       and serve different throwaway snapshots to each client:
100
101        truncate -s 1G base.img
102        mke2fs -d initial-content/ -F -t ext4 base.img
103        nbdkit tmpdisk size=0 base=$PWD/base.img \
104            command=' cp --sparse=always "$base" "$disk" '
105
106       The unusual "size=0" parameter is because when using "command", "size"
107       is only a request (but the parameter is required).  In this case the
108       command ignores the requested size.  The final size is the size of
109       $disk created by the cp(1) command.
110

PARAMETERS

112       command='COMMAND'
113           Instead of running mkfs(8) to create the initial filesystem, run
114           "COMMAND" (a shell script fragment which usually must be quoted to
115           protect it from the shell).  See "The command parameter" and
116           "EXAMPLES" sections above.
117
118       label=LABEL
119           Select the filesystem label.  The default is not set.
120
121       [size=]SIZE
122           Specify the virtual size of the disk image.
123
124           If using "command", this is only a suggested size.  The actual size
125           of the resulting disk will be the size of the disk created by
126           "command".
127
128           This parameter is required.
129
130           "size=" is a magic config key and may be omitted in most cases.
131           See "Magic parameters" in nbdkit(1).
132
133       type=FS
134           Select the filesystem type.  The default is "ext4".  Most non-
135           networked, non-cluster filesystem types supported by the mkfs(8)
136           command can be used here.
137

ENVIRONMENT VARIABLES

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

FILES

144       $plugindir/nbdkit-tmpdisk-plugin.so
145           The plugin.
146
147           Use "nbdkit --dump-config" to find the location of $plugindir.
148

VERSION

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

SEE ALSO

153       nbdkit(1), nbdkit-plugin(3), nbdkit-data-plugin(1),
154       nbdkit-eval-plugin(1), nbdkit-file-plugin(1), nbdkit-ip-filter(1),
155       nbdkit-limit-filter(1), nbdkit-linuxdisk-plugin(1),
156       nbdkit-memory-plugin(1), nbdkit-sh-plugin(1), nbdkit-loop(1),
157       nbdkit-tls(1), mkfs(8), mke2fs(8), virt-builder(1).
158

AUTHORS

160       Richard W.M. Jones
161
163       Copyright (C) 2018-2020 Red Hat Inc.
164

LICENSE

166       Redistribution and use in source and binary forms, with or without
167       modification, are permitted provided that the following conditions are
168       met:
169
170       •   Redistributions of source code must retain the above copyright
171           notice, this list of conditions and the following disclaimer.
172
173       •   Redistributions in binary form must reproduce the above copyright
174           notice, this list of conditions and the following disclaimer in the
175           documentation and/or other materials provided with the
176           distribution.
177
178       •   Neither the name of Red Hat nor the names of its contributors may
179           be used to endorse or promote products derived from this software
180           without specific prior written permission.
181
182       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
183       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
184       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
185       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
186       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
187       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
188       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
189       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
190       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
191       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
192       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
193
194
195
196nbdkit-1.28.2                     2021-11-09          nbdkit-tmpdisk-plugin(1)
Impressum