1#!/usr/bin/perl
2
3use strict;
4
5=head1 NAME
6
7brackup-mount - mount a backup as a filesystem using FUSE
8
9=cut
10
11# Make a friendly error message if Fuse isn't installed
12BEGIN {
13    eval { require Fuse; };
14
15    if ($@) {
16        print STDERR "brackup-mount requires the 'Fuse' library from CPAN\n";
17        exit(1);
18    }
19}
20
21use Brackup::Mount;
22
23my $metafile = shift or usage('No metafile specified');
24my $mountpoint = shift or usage('No mountpoint specified');
25
26Brackup::Mount->mount($metafile, $mountpoint);
27
28sub usage {
29    my $why = shift || "";
30    if ($why) {
31        $why =~ s/\s+$//;
32        $why = "Error: $why\n\n";
33    }
34    print STDERR "${why}brackup-mount <metafile> <mountpoint>\n";
35    exit(1);
36
37}
38
39=head1 SYNOPSIS
40
41    brackup-mount <metafile> <mountpoint>
42
43=head1 DESCRIPTION
44
45C<brackup-mount> allows you to mount a backup into your filesystem
46at a particular mount point. Once it's mounted, you'll have a
47read-only view of the directories and files in the backup
48at the mountpoint given.
49
50For example:
51
52    brackup-mount somebackup-20080203.brackup /mnt
53
54This might be useful if you need to refer to something from a backup
55but you don't want to do a full restore. You can also, if you like, do
56something resembling a restore by mounting a backup and copying the
57contents into your "real" filesystem.
58
59=head1 PREREQUISITES
60
61Before using this utility, you'll need to install the C<Fuse> library
62from CPAN:
63
64    perl -MCPAN -e "install Fuse"
65
66If you're on a Debian-like system then this might be a better idea:
67
68    apt-get install libfuse-perl
69
70=head1 WARNING
71
72This program is EXPERIMENTAL. Do not use it for anything important.
73
74=head1 HOW IT WORKS
75
76C<brackup-mount> reads the metafile it is given and uses the metadata
77within to create a filesystem that is exposed via FUSE. All operations
78apart from reading from files operate purely on the in-memory data structure
79created from the metafile, and so you can C<ls> and C<stat> files to
80your heart's content without worrying about expensive calls to your
81target.
82
83When a process calls C<open> on a file, the file will be effectively
84"restored" from the backup target into a temporary directory, where it
85will remain until it is ultimately C<close>d. All C<read> operations
86on the file are performed on the temporary file. This means that you
87can expect the C<open> call to be the most expensive call against this
88filesystem.
89
90If you're paying for data transfer from your target, be aware that
91the local copy retrieved on C<open> is thrown away on C<close>, so if you
92plan to be opening and closing the same file repeatedly you might
93want to force the local copy to be retained for the duration by running
94something like C<tail -f filename> in another terminal.
95
96Since Brackup does not retain information about file ownership, all
97files in the mounted filesystem will be owned by the user that mounted
98the filesystem. The permissions from the brackup metafile are
99returned to C<stat> (so you can do C<cp -P>), but aren't enforced on C<open>.
100
101=head1 AUTHOR
102
103Martin Atkins <mart@degeneration.co.uk>
104
105=head1 LICENCE
106
107This program and its associated library are part of the Brackup distribution
108and can be disstributed under the same terms as Brackup itself.
109
110=cut
111
112
113