#!/usr/bin/perl

use strict;

=head1 NAME

brackup-mount - mount a backup as a filesystem using FUSE

=cut

# Make a friendly error message if Fuse isn't installed
BEGIN {
    eval { require Fuse; };

    if ($@) {
        print STDERR "brackup-mount requires the 'Fuse' library from CPAN\n";
        exit(1);
    }
}

use Brackup::Mount;

my $metafile = shift or usage('No metafile specified');
my $mountpoint = shift or usage('No mountpoint specified');

Brackup::Mount->mount($metafile, $mountpoint);

sub usage {
    my $why = shift || "";
    if ($why) {
        $why =~ s/\s+$//;
        $why = "Error: $why\n\n";
    }
    print STDERR "${why}brackup-mount <metafile> <mountpoint>\n";
    exit(1);

}

=head1 SYNOPSIS

    brackup-mount <metafile> <mountpoint>

=head1 DESCRIPTION

C<brackup-mount> allows you to mount a backup into your filesystem
at a particular mount point. Once it's mounted, you'll have a
read-only view of the directories and files in the backup
at the mountpoint given.

For example:

    brackup-mount somebackup-20080203.brackup /mnt

This might be useful if you need to refer to something from a backup
but you don't want to do a full restore. You can also, if you like, do
something resembling a restore by mounting a backup and copying the
contents into your "real" filesystem.

=head1 PREREQUISITES

Before using this utility, you'll need to install the C<Fuse> library
from CPAN:

    perl -MCPAN -e "install Fuse"

If you're on a Debian-like system then this might be a better idea:

    apt-get install libfuse-perl

=head1 WARNING

This program is EXPERIMENTAL. Do not use it for anything important.

=head1 HOW IT WORKS

C<brackup-mount> reads the metafile it is given and uses the metadata
within to create a filesystem that is exposed via FUSE. All operations
apart from reading from files operate purely on the in-memory data structure
created from the metafile, and so you can C<ls> and C<stat> files to
your heart's content without worrying about expensive calls to your
target.

When a process calls C<open> on a file, the file will be effectively
"restored" from the backup target into a temporary directory, where it
will remain until it is ultimately C<close>d. All C<read> operations
on the file are performed on the temporary file. This means that you
can expect the C<open> call to be the most expensive call against this
filesystem.

If you're paying for data transfer from your target, be aware that
the local copy retrieved on C<open> is thrown away on C<close>, so if you
plan to be opening and closing the same file repeatedly you might
want to force the local copy to be retained for the duration by running
something like C<tail -f filename> in another terminal.

Since Brackup does not retain information about file ownership, all
files in the mounted filesystem will be owned by the user that mounted
the filesystem. The permissions from the brackup metafile are
returned to C<stat> (so you can do C<cp -P>), but aren't enforced on C<open>.

=head1 AUTHOR

Martin Atkins <mart@degeneration.co.uk>

=head1 LICENCE

This program and its associated library are part of the Brackup distribution
and can be disstributed under the same terms as Brackup itself.

=cut