=head1 NAME

nbdkit-protect-filter - write-protect parts of a plugin

=head1 SYNOPSIS

 nbdkit --filter=protect plugin protect=START-END [protect=...]

=head1 DESCRIPTION

C<nbdkit-protect-filter> is a filter for L<nbdkit(1)> that lets you
write-protect parts of the underlying plugin.  This prevents clients
from modifying ranges of the plugin, while still allowing the NBD
connection to be writable in general.

One use for this is to prevent clients from adding a phony header to
the data to make it look like a non-raw disk format (like adding a
qcow2 header), since that can be used in some exploits.

To make the whole plugin readonly, use the nbdkit I<-r> option on the
command line, or L<nbdkit-readonly-filter(1)>.  To give selective
access to the server, use L<nbdkit-ip-filter(1)>.  To serve only a
subset of the plugin use L<nbdkit-offset-filter(1)> or
L<nbdkit-partition-filter(1)>.

=head1 EXAMPLES

=head2 Protect the boot sector

Protect the first part of the boot sector from writes, but allow the
MBR partition table to be updated:

 nbdkit --filter=protect file disk.img protect=0-0x1bd

=head2 Protect everything except a single partition

Allow clients to write to a single partition on the disk, but prevent
modifications to the partition table, boot sector, other partitions,
or any other metadata outside the partition:

 $ fdisk -l disk.img
 Device    Boot  Start       End  Sectors Size Id Type
 disk.img1 *      2048  12580863 12578816   6G 83 Linux
 $ start=$((2048*512))
 $ end=$((12580863*512+511))
 $ nbdkit --filter=protect file disk.img protect=~$start-$end

Notes:

=over 4

=item *

Data in other partitions and parts of the disk is still readable.

=item *

The C<'~'> character complements the range protected.  You might need
to escape it from the shell using quotes or backslash.

=item *

This is different from L<nbdkit-partition-filter(1)> — that filter
exposes the partition as a whole device.

=back

=head1 PARAMETERS

=over 4

=item B<protect=>STARTB<->END

Protect the bytes starting at offset C<START> through to offset C<END>
(inclusive).  Reads are permitted.  Writes to the protected range are
only permitted if they do not change the content.  If an attempt is
made to change the content, then the error C<NBD_EPERM> (Operation not
permitted) is returned to the client.

C<START> and C<END> can be expressed in decimal, octal (C<0NN>) or
hexadecimal (C<0xNN>).  If omitted then they default to the start and
end of the underlying plugin respectively.

This parameter can be given multiple times to protect several ranges.

=item B<protect=~>STARTB<->END

This protects the complement of the range C<START> to C<END>.

=back

=head1 FILES

=over 4

=item F<$filterdir/nbdkit-protect-filter.so>

The filter.

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

=back

=head1 VERSION

C<nbdkit-protect-filter> first appeared in nbdkit 1.30.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-ip-filter(1)>,
L<nbdkit-offset-filter(1)>,
L<nbdkit-partition-filter(1)>,
L<nbdkit-readonly-filter(1)>,
L<nbdkit-filter(3)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
