plugins/ondemand/nbdkit-ondemand-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-ondemand-plugin - create filesystems on demand
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit ondemand dir=EXPORTSDIR [size=]SIZE [wait=true]
   8                  { [type=ext4|xfs|vfat|...] [label=LABEL]
   9                    | command=COMMAND [VAR=VALUE ...] }
  10
  11 =head1 DESCRIPTION
  12
  13 This is a plugin for L<nbdkit(1)> which creates persistent filesystems
  14 on demand.  Clients may simply connect to the server, requesting a
  15 particular export name, and a new filesystem is created if it does not
  16 exist already.  Clients can also disconnect and reconnect with the
  17 same export name and the same filesystem will still be available.
  18 Filesystems are stored in a directory on the server, so they also
  19 persist over nbdkit and server restarts.
  20
  21 Each filesystem is locked while it is in use by a client, preventing
  22 two clients from accessing the same filesystem (which would cause
  23 corruption).
  24
  25 Similar plugins include L<nbdkit-file-plugin(1)> which can serve a
  26 predefined set of exports (clients cannot create more),
  27 L<nbdkit-tmpdisk-plugin(1)> which creates a fresh temporary filesystem
  28 for each client, and L<nbdkit-linuxdisk-plugin(1)> which exports a
  29 single filesystem from a local directory on the server.
  30
  31 =head2 Export names
  32
  33 When a new export name is requested by a client, a sparse file of the
  34 same name is created in C<dir=EXPORTSDIR> on the server.  The file
  35 will be formatted with L<mkfs(8)>.  The size of the file is currently
  36 fixed by the C<size=SIZE> parameter, but we intend to make this
  37 client-configurable in future.  The filesystem type and label may also
  38 be specified, otherwise C<ext4> and no label is used.
  39
  40 Export names must be E<le> C<NAME_MAX> (usually 255) bytes in length
  41 and must not contain certain characters including C<.>, C</> and C<:>.
  42 There may be other limitations added in future.  Client requests which
  43 do not obey these restrictions are rejected.  As a special case,
  44 export name C<""> is mapped to the file name F<default>.
  45
  46 =head2 Security considerations
  47
  48 You should B<only> use this in an environment where you trust all your
  49 clients, since clients can use this plugin to consume arbitrary
  50 amounts of disk space by creating unlimited exports.  It is therefore
  51 best to take steps to limit where clients can connect from using
  52 L<nbdkit-ip-filter(1)>, firewalls, or TLS client certificates.
  53
  54 =head2 The command parameter
  55
  56 Instead of running mkfs you can run an arbitrary command (a shell
  57 script fragment) to create the disk.
  58
  59 The other parameters to the plugin are turned into shell variables
  60 passed to the command.  For example C<type> becomes the shell variable
  61 C<$type>, etc.  Any parameters you want can be passed to the plugin
  62 and will be turned into shell variables (not only C<type> and
  63 C<label>) making this a very flexible method to create filesystems and
  64 disks of all kinds.
  65
  66 Two special variables are also passed to the shell script fragment:
  67
  68 =over 4
  69
  70 =item C<$disk>
  71
  72 The absolute path of the disk file.  This is partially controlled by
  73 the client so you should quote it carefully.  This file is not
  74 pre-created, the command must create it for example using:
  75
  76  truncate -s $size "$disk"
  77
  78 =item C<$size>
  79
  80 The virtual size in bytes.  This is the C<size> parameter, converted
  81 to bytes.  Note the final size served to the client is whatever disk
  82 size C<command> creates.
  83
  84 =back
  85
  86 =head1 EXAMPLE
  87
  88 Run the server like this:
  89
  90  mkdir /var/tmp/exports
  91  nbdkit ondemand dir=/var/tmp/exports 1G
  92
  93 Clients can connect and create 1G ext4 filesystems on demand using
  94 commands such as these (note the different export names):
  95
  96  nbd-client server /dev/nbd0 -N export1
  97  mount /dev/nbd0 /mnt
  98
  99 =for paragraph
 100
 101  guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda
 102
 103 =for paragraph
 104
 105  qemu-img info nbd:localhost:10809:exportname=export2
 106
 107 On the server you would see two filesystems created:
 108
 109  $ ls -l /var/tmp/exports
 110  -rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export1
 111  -rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export2
 112
 113 The plugin does not clean these up.  If they are no longer needed then
 114 the server admin should delete them (or use a tmp cleaner).
 115
 116 =head1 PARAMETERS
 117
 118 =over 4
 119
 120 =item B<command='>COMMANDB<'>
 121
 122 Instead of running L<mkfs(8)> to create the initial filesystem, run
 123 C<COMMAND> (a shell script fragment which usually must be quoted to
 124 protect it from the shell).  See L</The command parameter> and
 125 L</EXAMPLES> sections above.
 126
 127 =item B<dir=>EXPORTSDIR
 128
 129 The directory where filesystems are saved.  When first using this
 130 plugin you should point this to an empty directory.  When clients
 131 connect, filesystems are created here.
 132
 133 This parameter is required.
 134
 135 =item B<label=>LABEL
 136
 137 Select the filesystem label.  The default is not set.
 138
 139 =item [B<size=>]SIZE
 140
 141 Specify the virtual size of all of the filesystems.
 142
 143 If using C<command>, this is only a suggested size.  The actual size
 144 of the resulting disk will be the size of the disk created by
 145 C<command>.
 146
 147 This parameter is required.
 148
 149 C<size=> is a magic config key and may be omitted in most cases.
 150 See L<nbdkit(1)/Magic parameters>.
 151
 152 =item B<type=>FS
 153
 154 Select the filesystem type.  The default is C<ext4>.  Most
 155 non-networked, non-cluster filesystem types supported by the
 156 L<mkfs(8)> command can be used here.
 157
 158 =item B<wait=true>
 159
 160 If set, if two clients try to connect at the same time to the same
 161 export then the second client will wait for the first to disconnect.
 162 The default behaviour is to reject the second client with the error
 163 message:
 164
 165  filesystem is locked by another client
 166
 167 This setting is sometimes useful if you are making repeated
 168 connections and at the network level the first connection does not
 169 fully disconnect before the next connection starts.  This can also
 170 happen as a side-effect of using C<guestfish --ro> which opens two NBD
 171 connections in quick succession.
 172
 173 =back
 174
 175 =head1 FILES
 176
 177 =over 4
 178
 179 =item F<$plugindir/nbdkit-ondemand-plugin.so>
 180
 181 The plugin.
 182
 183 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 184
 185 =back
 186
 187 =head1 VERSION
 188
 189 C<nbdkit-ondemand-plugin> first appeared in nbdkit 1.22.
 190
 191 =head1 SEE ALSO
 192
 193 L<nbdkit(1)>,
 194 L<nbdkit-plugin(3)>,
 195 L<nbdkit-file-plugin(1)>,
 196 L<nbdkit-ip-filter(1)>,
 197 L<nbdkit-limit-filter(1)>,
 198 L<nbdkit-linuxdisk-plugin(1)>,
 199 L<nbdkit-memory-plugin(1)>,
 200 L<nbdkit-tmpdisk-plugin(1)>,
 201 L<nbdkit-tls(1)>,
 202 L<mkfs(8)>,
 203 L<mke2fs(8)>.
 204
 205 =head1 AUTHORS
 206
 207 Richard W.M. Jones
 208
 209 =head1 COPYRIGHT
 210
 211 Copyright Red Hat