filters/protect/nbdkit-protect-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-protect-filter - write-protect parts of a plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=protect plugin protect=START-END [protect=...]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-protect-filter> is a filter for L<nbdkit(1)> that lets you
  12 write-protect parts of the underlying plugin.  This prevents clients
  13 from modifying ranges of the plugin, while still allowing the NBD
  14 connection to be writable in general.
  15
  16 One use for this is to prevent clients from adding a phony header to
  17 the data to make it look like a non-raw disk format (like adding a
  18 qcow2 header), since that can be used in some exploits.
  19
  20 To make the whole plugin readonly, use the nbdkit I<-r> option on the
  21 command line.  To give selective access to the server, use
  22 L<nbdkit-ip-filter(1)>.  To serve only a subset of the plugin use
  23 L<nbdkit-offset-filter(1)> or L<nbdkit-partition-filter(1)>.
  24
  25 =head1 EXAMPLES
  26
  27 =head2 Protect the boot sector
  28
  29 Protect the first part of the boot sector from writes, but allow the
  30 MBR partition table to be updated:
  31
  32  nbdkit --filter=protect file disk.img protect=0-0x1bd
  33
  34 =head2 Protect everything except a single partition
  35
  36 Allow clients to write to a single partition on the disk, but prevent
  37 modifications to the partition table, boot sector, other partitions,
  38 or any other metadata outside the partition:
  39
  40  $ fdisk -l disk.img
  41  Device    Boot  Start       End  Sectors Size Id Type
  42  disk.img1 *      2048  12580863 12578816   6G 83 Linux
  43  $ start=$((2048*512))
  44  $ end=$((12580863*512+511))
  45  $ nbdkit --filter=protect file disk.img protect=~$start-$end
  46
  47 Notes:
  48
  49 =over 4
  50
  51 =item *
  52
  53 Data in other partitions and parts of the disk is still readable.
  54
  55 =item *
  56
  57 The C<'~'> character complements the range protected.  You might need
  58 to escape it from the shell using quotes or backslash.
  59
  60 =item *
  61
  62 This is different from L<nbdkit-partition-filter(1)> — that filter
  63 exposes the partition as a whole device.
  64
  65 =back
  66
  67 =head1 PARAMETERS
  68
  69 =over 4
  70
  71 =item B<protect=>STARTB<->END
  72
  73 Protect the bytes starting at offset C<START> through to offset C<END>
  74 (inclusive).  Reads are permitted.  Writes to the protected range are
  75 only permitted if they do not change the content.  If an attempt is
  76 made to change the content, then the error C<NBD_EPERM> (Operation not
  77 permitted) is returned to the client.
  78
  79 C<START> and C<END> can be expressed in decimal, octal (C<0NN>) or
  80 hexadecimal (C<0xNN>).  If omitted then they default to the start and
  81 end of the underlying plugin respectively.
  82
  83 This parameter can be given multiple times to protect several ranges.
  84
  85 =item B<protect=~>STARTB<->END
  86
  87 This protects the complement of the range C<START> to C<END>.
  88
  89 =back
  90
  91 =head1 FILES
  92
  93 =over 4
  94
  95 =item F<$filterdir/nbdkit-protect-filter.so>
  96
  97 The filter.
  98
  99 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 100
 101 =back
 102
 103 =head1 VERSION
 104
 105 C<nbdkit-offset-filter> first appeared in nbdkit 1.30.
 106
 107 =head1 SEE ALSO
 108
 109 L<nbdkit(1)>,
 110 L<nbdkit-file-plugin(1)>,
 111 L<nbdkit-ip-filter(1)>,
 112 L<nbdkit-offset-filter(1)>,
 113 L<nbdkit-partition-filter(1)>,
 114 L<nbdkit-filter(3)>.
 115
 116 =head1 AUTHORS
 117
 118 Richard W.M. Jones
 119
 120 =head1 COPYRIGHT
 121
 122 Copyright Red Hat