Skip to content
Permalink
Browse files

New tmpdisk plugin.

This can be used for exporting temporary disks to thin clients, as a
kind of "remote tmpfs".

See also:
https://www.redhat.com/archives/libguestfs/2020-March/msg00134.html
  • Loading branch information
rwmjones committed Mar 16, 2020
1 parent c9f7250 commit ad5c675dde3088046fdb429af5c60d2a2e528b75
@@ -134,6 +134,7 @@ plugins/*/*.3
/tests/test-split
/tests/test-streaming
/tests/test-tcl
/tests/test-tmpdisk
/tests/test-xz
/tests/test-xz-curl
/test-driver
@@ -86,6 +86,7 @@ non_lang_plugins="\
ssh \
streaming \
tar \
tmpdisk \
vddk \
zero \
"
@@ -1016,6 +1017,7 @@ AC_CONFIG_FILES([Makefile
plugins/streaming/Makefile
plugins/tar/Makefile
plugins/tcl/Makefile
plugins/tmpdisk/Makefile
plugins/vddk/Makefile
plugins/zero/Makefile
filters/Makefile
@@ -269,6 +269,7 @@ L<nbdkit-null-plugin(1)>,
L<nbdkit-partitioning-plugin(1)>,
L<nbdkit-pattern-plugin(1)>,
L<nbdkit-random-plugin(1)>,
L<nbdkit-tmpdisk-plugin(1)>,
L<nbdkit-zero-plugin(1)>,
L<https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl>,
L<https://en.wikipedia.org/wiki/Base64>.
@@ -111,6 +111,7 @@ L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<nbdkit-split-plugin(1)>,
L<nbdkit-partitioning-plugin(1)>,
L<nbdkit-tmpdisk-plugin(1)>,
L<nbdkit-noextents-filter(1)>.

=head1 AUTHORS
@@ -24,7 +24,9 @@ symbolic links, block special devices etc.

To create a FAT-formatted virtual floppy disk, see
L<nbdkit-floppy-plugin(1)>. To create a CD/ISO, see
L<nbdkit-iso-plugin(1)>.
L<nbdkit-iso-plugin(1)>. To create an empty filesystem for each
client that connects (like a "remote tmpfs") use
L<nbdkit-tmpdisk-plugin(1)>.

=head1 EXAMPLES

@@ -184,7 +186,8 @@ L<nbdkit-file-plugin(1)>,
L<nbdkit-floppy-plugin(1)>,
L<nbdkit-iso-plugin(1)>,
L<nbdkit-partition-filter(1)>,
L<nbdkit-partitioning-plugin(1)>.
L<nbdkit-partitioning-plugin(1)>,
L<nbdkit-tmpdisk-plugin(1)>,

=head1 AUTHORS

@@ -103,7 +103,8 @@ L<nbdkit-plugin(3)>,
L<nbdkit-loop(1)>,
L<nbdkit-data-plugin(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-info-plugin(1)>.
L<nbdkit-info-plugin(1)>,
L<nbdkit-tmpdisk-plugin(1)>.

=head1 AUTHORS

@@ -0,0 +1,66 @@
# nbdkit
# Copyright (C) 2017-2020 Red Hat Inc.
#
# 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.

include $(top_srcdir)/common-rules.mk

EXTRA_DIST = nbdkit-tmpdisk-plugin.pod

plugin_LTLIBRARIES = nbdkit-tmpdisk-plugin.la

nbdkit_tmpdisk_plugin_la_SOURCES = \
tmpdisk.c \
$(top_srcdir)/include/nbdkit-plugin.h \
$(NULL)

nbdkit_tmpdisk_plugin_la_CPPFLAGS = \
-I$(top_srcdir)/include \
-I$(top_srcdir)/common/utils \
$(NULL)
nbdkit_tmpdisk_plugin_la_CFLAGS = $(WARNINGS_CFLAGS)
nbdkit_tmpdisk_plugin_la_LDFLAGS = \
-module -avoid-version -shared \
-Wl,--version-script=$(top_srcdir)/plugins/plugins.syms \
$(NULL)
nbdkit_tmpdisk_plugin_la_LIBADD = \
$(top_builddir)/common/utils/libutils.la \
$(NULL)

if HAVE_POD

man_MANS = nbdkit-tmpdisk-plugin.1
CLEANFILES += $(man_MANS)

nbdkit-tmpdisk-plugin.1: nbdkit-tmpdisk-plugin.pod
$(PODWRAPPER) --section=1 --man $@ \
--html $(top_builddir)/html/$@.html \
$<

endif HAVE_POD
@@ -0,0 +1,157 @@
=head1 NAME

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

=head1 SYNOPSIS

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

=head1 DESCRIPTION

This L<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. B<The filesystem is deleted>
when the client disconnects.

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

The size of the disk is chosen using the C<size> parameter. The
filesystem type is C<ext4> but this can be changed using the C<type>
parameter (controlling the I<-t> option of mkfs).

Instead of running mkfs you can run an arbitrary C<command> to create
the disk.

=head2 Example

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

nbdkit tmpdisk 16G

and each thin client would have a file F</etc/rc.d/rc.local>
containing:

nm-online
modprobe nbd
nbd-client server /dev/nbd0
mount /dev/nbd0 /var/scratch

Clients would see a fresh, empty C</var/scratch> directory after boot.

=head2 Security considerations

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

=head1 PARAMETERS

=over 4

=item B<command='>COMMANDB<'>

Instead of running L<mkfs(8)> to create the initial filesystem, run
C<COMMAND> (which usually must be quoted to protect it from the
shell). The following shell variables may be used in C<COMMAND>:

=over 4

=item C<$disk>

The absolute path of the file that the command must initialize. This
file is created by nbdkit before the command runs.

=item C<$label>

The filesystem label (from the C<label> parameter).

=item C<$size>

The virtual size in bytes, which is the same as the file size.

=item C<$type>

The filesystem type (from the C<type> parameter), defaulting to
C<ext4>. (Commands can ignore this if it is not relevant).

=back

=item B<label=>LABEL

Select the filesystem label. The default is not set.

=item [B<size=>]SIZE

Specify the virtual size of the disk image.

This parameter is required.

C<size=> is a magic config key and may be omitted in most cases.
See L<nbdkit(1)/Magic parameters>.

=item B<type=>FS

Select the filesystem type. The default is C<ext4>. Most
non-networked, non-cluster filesystem types supported by the
L<mkfs(8)> command can be used here.

=back

=head1 ENVIRONMENT VARIABLES

=over 4

=item C<TMPDIR>

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

=back

=head1 FILES

=over 4

=item F<$plugindir/nbdkit-tmpdisk-plugin.so>

The plugin.

Use C<nbdkit --dump-config> to find the location of C<$plugindir>.

=back

=head1 VERSION

C<nbdkit-tmpdisk-plugin> first appeared in nbdkit 1.20.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<nbdkit-data-plugin(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-ip-filter(1)>,
L<nbdkit-limit-filter(1)>,
L<nbdkit-linuxdisk-plugin(1)>,
L<nbdkit-memory-plugin(1)>,
L<nbdkit-loop(1)>,
L<nbdkit-tls(1)>,
L<mkfs(8)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright (C) 2018-2020 Red Hat Inc.

0 comments on commit ad5c675

Please sign in to comment.
You can’t perform that action at this time.