1nbdkit-tmpdisk-plugin(1) NBDKIT nbdkit-tmpdisk-plugin(1)
2
6 nbdkit-tmpdisk-plugin - create a fresh temporary filesystem for each
7 client
8
10 nbdkit tmpdisk [size=]SIZE [type=ext4|xfs|vfat|...] [label=LABEL]
11 nbdkit tmpdisk [size=]SIZE command=COMMAND [VAR=VALUE ...]
13
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 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 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 The command parameter
33 Instead of running mkfs you can run an arbitrary command (a shell
34 script fragment) to create the disk.
35 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 Two special variables are also passed to the shell script fragment:
44 $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 truncate -s $size "$disk"
50 $disk is deleted automatically when the client disconnects.
52 $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 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
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 nbdkit tmpdisk 16G
71 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 Overriding mkfs options
76 Using "command" allows you to easily override any mkfs option, for
77 example:
78 nbdkit tmpdisk 16G command='
80 truncate -s $size "$disk"
81 mke2fs -F -N 10000 -t ext4 "$disk"
82 '
83 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 nbdkit tmpdisk 16G command=' truncate -s $size "$disk" '
91 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 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 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 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
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 label=LABEL
119 Select the filesystem label. The default is not set.
120 [size=]SIZE
122 Specify the virtual size of the disk image.
123 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 This parameter is required.
129 "size=" is a magic config key and may be omitted in most cases.
131 See "Magic parameters" in nbdkit(1).
132 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
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
144 $plugindir/nbdkit-tmpdisk-plugin.so
145 The plugin.
146 Use "nbdkit --dump-config" to find the location of $plugindir.
148
150 "nbdkit-tmpdisk-plugin" first appeared in nbdkit 1.20.
151
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
160 Richard W.M. Jones
161
163 Copyright Red Hat
164
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 • Redistributions of source code must retain the above copyright
171 notice, this list of conditions and the following disclaimer.
172 • 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 • 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 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.
193nbdkit-1.36.2 2023-11-26 nbdkit-tmpdisk-plugin(1)