=head1 NAME

nbdkit-readonly-filter - switch a plugin between read-only and writable

=head1 SYNOPSIS

 nbdkit --filter=readonly PLUGIN

 nbdkit --filter=readonly PLUGIN readonly-file=/tmp/ro

=head1 DESCRIPTION

C<nbdkit-readonly-filter> is an nbdkit filter that has two modes:

=over 4

=item *

When the C<readonly-file> parameter is B<not> used, make the
underlying plugin completely read-only.  This is similar to using the
nbdkit I<-r> option on the command line.

=item *

When the C<readonly-file> parameter is used, make the underlying
plugin read-only when that file is present on disk, but leave it
writable when the file is not present (or if the file is deleted).
This way you can switch a plugin between being writable and
write-protected at run time.

=back

Trying to write to the filter when the filter is enforcing read-only
mode will cause C<EPERM> ("Operation not permitted") to be returned to
the client.

L<nbdkit-protect-filter(1)> is a related filter which can
write-protect parts of a plugin (eg only the boot sector).
L<nbdkit-error-filter(1)> is another filter which can be used for the
same purpose as this filter but is more complicated to use.  See also
the I<-r> option described in the L<nbdkit(1)> manual.

=head1 EXAMPLE

Make a disk read-only 60 seconds after nbdkit is started:

 rm -f /tmp/ro
 nbdkit --filter=readonly file disk.img readonly-file=/tmp/ro
 sleep 60; touch /tmp/ro

=head1 PARAMETERS

=over 4

=item B<readonly-file=>PATHNAME

If this parameter is used, the filter makes the underlying plugin
read-only when F<PATHNAME> exists, otherwise the plugin is writable as
usual.

If this parameter is not used, the filter always makes the underlying
plugin read-only.

=back

=head1 FILES

=over 4

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

The filter.

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

=back

=head1 VERSION

C<nbdkit-readonly-filter> first appeared in nbdkit 1.38.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-error-filter(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-full-plugin(1)>,
L<nbdkit-protect-filter(1)>,
L<nbdkit-filter(3)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
