mirror of
https://github.com/google/fuse-archive.git
synced 2026-11-20 16:41:43 +00:00
990 lines
25 KiB
Groff
990 lines
25 KiB
Groff
'\" t
|
||
.\" Automatically generated by Pandoc 3.7.0.2
|
||
.\"
|
||
.TH "fuse\-archive" "1" "August 2026" "fuse\-archive 1.25" "User Manual"
|
||
.PD
|
||
.SH NAME
|
||
\f[B]fuse\-archive\f[R] \- Mount archives as a read\-only FUSE file
|
||
system.
|
||
.PD
|
||
.SH SYNOPSIS
|
||
.IP \(bu 2
|
||
\f[B]fuse\-archive\f[R] [\f[I]options\f[R]] \f[I]archive\f[R]
|
||
[\f[I]mount_point\f[R]]
|
||
.IP \(bu 2
|
||
\f[B]fuse\-archive\f[R] [\f[I]options\f[R]] \f[I]archive\f[R] \&...
|
||
\f[I]mount_point\f[R]
|
||
.PD
|
||
.SH DESCRIPTION
|
||
\f[B]fuse\-archive\f[R] serves one or several archives or compressed
|
||
files (e.g., \f[CR]foo.tar\f[R], \f[CR]foo.tar.gz\f[R],
|
||
\f[CR]foo.xz\f[R], or \f[CR]foo.zip\f[R]) as a read\-only \c
|
||
.UR https://en.wikipedia.org/wiki/Filesystem_in_Userspace
|
||
FUSE
|
||
.UE \c
|
||
\ file system.
|
||
.PD
|
||
.PP
|
||
It is similar to \c
|
||
.UR https://github.com/google/mount-zip
|
||
\f[B]mount\-zip\f[R]
|
||
.UE \c
|
||
\ and \c
|
||
.UR https://bitbucket.org/agalanin/fuse-zip
|
||
\f[B]fuse\-zip\f[R]
|
||
.UE \c
|
||
\ but supports a larger range of archive or compressed file formats.
|
||
.PD
|
||
.PP
|
||
It is similar to \c
|
||
.UR https://github.com/cybernoid/archivemount
|
||
\f[B]archivemount\f[R]
|
||
.UE \c
|
||
\ but can be much faster (see the Performance section below), although
|
||
it can only mount read\-only, not read\-write.
|
||
.PD
|
||
.PP
|
||
\f[B]fuse\-archive\f[R] automatically creates the target mount point if
|
||
needed and automatically removes it when the file system is unmounted.
|
||
If the mount point already existed before \f[B]fuse\-archive\f[R] was
|
||
started, it is not removed.
|
||
.PD
|
||
.PP
|
||
If no mount point is specified, \f[B]fuse\-archive\f[R] uses the name of
|
||
the archive (without its filename extension) as a mount point in the
|
||
current working directory.
|
||
If that directory already exists, it will try to create one with a
|
||
numeric suffix (e.g., \f[CR]archive (1)\f[R]).
|
||
.PD
|
||
.SH OPTIONS
|
||
.PD
|
||
.TP
|
||
\f[B]\-\-help\f[R] or \f[B]\-h\f[R]
|
||
Print help.
|
||
.PD
|
||
.TP
|
||
\f[B]\-\-version\f[R] or \f[B]\-V\f[R]
|
||
Print version info.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o quiet\f[R] or \f[B]\-q\f[R]
|
||
Print fewer log messages.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o verbose\f[R] or \f[B]\-v\f[R]
|
||
Print more log messages.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o redact\f[R]
|
||
Redact file names from log messages.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o force\f[R]
|
||
Continue despite errors.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o maxfilters=N\f[R]
|
||
Maximum number of filters per archive (default is 1).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o precache\f[R]
|
||
Preemptive caching of uncompressed data (default).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o lazycache\f[R]
|
||
Incremental caching of uncompressed data.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nocache\f[R]
|
||
No caching of uncompressed data.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o memcache\f[R]
|
||
Caching in memory (Linux only).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nomerge\f[R]
|
||
Do not merge multiple archives on top of each other.
|
||
Instead, create a subdirectory for each archive inside the mount point.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o notrim\f[R]
|
||
Do not trim the base of the tree.
|
||
Keep all the intermediate directories as specified in the archive(s).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nodirs\f[R]
|
||
No directories.
|
||
Flatten the archive structure by presenting all its files in its root
|
||
directory.
|
||
This might make sense if you\(cqre not interested in the archive tree
|
||
structure, but only in its file data, e.g., for malware scanning.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nospecials\f[R]
|
||
Hide special files (FIFOs, sockets, devices).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nosymlinks\f[R]
|
||
Hide symbolic links.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o noholes\f[R]
|
||
Do not report holes in sparse files.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nohardlinks\f[R]
|
||
Do not report files with multiple hard links.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o noxattrs\f[R]
|
||
Do not report extended attributes.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o nobidding\f[R]
|
||
Do not use libarchive\(cqs format bidding system to detect the archive
|
||
format.
|
||
Instead, strictly rely on the file extension.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o noexternal\f[R]
|
||
Do not use external programs for decompression.
|
||
By default, external programs are allowed but searched for in a
|
||
sanitized \f[CR]PATH\f[R] containing only standard system directories
|
||
(e.g., \f[CR]/usr/bin\f[R], \f[CR]/bin\f[R], \f[CR]/usr/local/bin\f[R])
|
||
to prevent local spoofing attacks.
|
||
Using this option effectively disables external programs by setting
|
||
\f[CR]PATH\f[R] to a safe, non\-directory value (\f[CR]/dev/null\f[R]),
|
||
ensuring that only decompression filters implemented natively or
|
||
statically linked into \f[B]libarchive\f[R] are used.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o unsafe_path\f[R]
|
||
Do not sanitize \f[CR]PATH\f[R] for external programs.
|
||
This option preserves the original \f[CR]PATH\f[R] from the environment
|
||
instead of filtering it.
|
||
Use with caution as it may allow local spoofing attacks if the
|
||
environment is not trusted.
|
||
This option is ignored if \f[CR]\-o noexternal\f[R] is also used.
|
||
.PD
|
||
.TP
|
||
\f[B]\-o dmask=M\f[R]
|
||
Directory permission mask in octal (default is 0022).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o fmask=M\f[R]
|
||
File permission mask in octal (default is 0022).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o uid=N\f[R]
|
||
Set the file owner of all the items in the mounted archive (default is
|
||
the current user).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o gid=N\f[R]
|
||
Set the file group of all the items in the mounted archive (default is
|
||
the current group).
|
||
.PD
|
||
.TP
|
||
\f[B]\-o enforce_permissions\f[R]
|
||
Enforce standard UNIX permissions.
|
||
By default, \f[B]fuse\-archive\f[R] presents all files as being owned by
|
||
the current user and group, with standard read permissions.
|
||
This option instructs \f[B]fuse\-archive\f[R] to use the exact UID, GID,
|
||
and Unix permission bits stored within the archive for each item.
|
||
This includes support for special bits such as \f[CR]SUID\f[R],
|
||
\f[CR]SGID\f[R], and \f[CR]SVTX\f[R] (sticky bit).
|
||
Note that this may result in access denied errors if you are not the
|
||
owner of the files inside the archive.
|
||
.PD
|
||
.TP
|
||
\f[B]\-f\f[R]
|
||
Foreground mode.
|
||
.PD
|
||
.TP
|
||
\f[B]\-d\f[R]
|
||
Foreground mode with debug output.
|
||
.PD
|
||
.SH USAGE EXAMPLES
|
||
Mount a single archive:
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive foobar.tar.gz mnt
|
||
.EE
|
||
.PD
|
||
.PP
|
||
The mounted archive can be explored and read using any application:
|
||
.IP
|
||
.EX
|
||
$ tree mnt
|
||
mnt
|
||
└── foo
|
||
└── bar.txt
|
||
|
||
1 directory, 1 file
|
||
|
||
$ cat mnt/foo/bar.txt
|
||
Hello, world!
|
||
.EE
|
||
.PD
|
||
.PP
|
||
Mount multiple archives into the same mount point (merged view):
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive archive1.zip archive2.tar.bz2 mnt
|
||
.EE
|
||
.PD
|
||
.PP
|
||
Mount multiple archives as separate subdirectories:
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive \-o nomerge archive1.zip archive2.7z mnt
|
||
$ ls mnt
|
||
archive1 archive2
|
||
.EE
|
||
.PD
|
||
.PP
|
||
Consult a GPG\-encrypted file securely without decrypting it to disk:
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive secret.txt.gpg mnt
|
||
Password >
|
||
$ cat mnt/secret.txt
|
||
.EE
|
||
.PD
|
||
.PP
|
||
When finished, unmount the file system:
|
||
.IP
|
||
.EX
|
||
$ umount mnt
|
||
.EE
|
||
.PD
|
||
.SH FEATURES
|
||
.IP \(bu 2
|
||
\f[B]Read\-only view\f[R]: Archives are served as a safe, read\-only
|
||
file system.
|
||
.IP \(bu 2
|
||
\f[B]Wide format support\f[R]: Supports ZIP, 7Z, RAR, TAR, ISO, and many
|
||
other formats through \c
|
||
.UR https://libarchive.org
|
||
\f[B]libarchive\f[R]
|
||
.UE \c
|
||
\&.
|
||
.IP \(bu 2
|
||
\f[B]Encryption\f[R]: Handles both native archive encryption (e.g., ZIP)
|
||
and \c
|
||
.UR https://gnupg.org/
|
||
\f[B]GnuPG\f[R]
|
||
.UE \c
|
||
\ encryption.
|
||
.IP \(bu 2
|
||
\f[B]Flexible Caching\f[R]: Offers pre\-emptive, incremental (lazy), and
|
||
memory\-based caching strategies.
|
||
.IP \(bu 2
|
||
\f[B]Multiple Archives\f[R]: Can mount several archives simultaneously,
|
||
either merging them into a single tree or keeping them separate.
|
||
.IP \(bu 2
|
||
\f[B]Automatic Mount Management\f[R]: Automatically creates and removes
|
||
mount point directories as needed.
|
||
.IP \(bu 2
|
||
\f[B]File System Support\f[R]:
|
||
.RS 2
|
||
.IP \(bu 2
|
||
\f[B]Special Files\f[R]: Supports named sockets, FIFOs, and devices.
|
||
.IP \(bu 2
|
||
\f[B]Links\f[R]: Correctly handles symbolic links and hard links.
|
||
.IP \(bu 2
|
||
\f[B]Sparse Files\f[R]: Detects and exposes \(lqholes\(rq in sparse
|
||
files for efficient reading.
|
||
.IP \(bu 2
|
||
\f[B]Extended Attributes\f[R]: Supports reading xattrs from archives.
|
||
.IP \(bu 2
|
||
\f[B]High\-precision timestamps\f[R]: Supports full nanosecond precision
|
||
for access, modification, and creation times.
|
||
.RE
|
||
.IP \(bu 2
|
||
\f[B]Permissions\f[R]: Honors Unix access modes, ownership (UID/GID),
|
||
and special bits (SUID/SGID/SVTX).
|
||
.IP \(bu 2
|
||
\f[B]Deduplication\f[R]: Gracefully handles name collisions between
|
||
multiple archives or within a single archive.
|
||
.IP \(bu 2
|
||
\f[B]Performance\f[R]: Optimized for speed through efficient caching.
|
||
.PD
|
||
.SH NAME DEDUPLICATION
|
||
In case of name collision, \f[B]fuse\-archive\f[R] adds a number to
|
||
deduplicate the conflicting file name:
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive \-o nomerge archive1.zip archive2.zip mnt
|
||
|
||
$ tree \-F mnt
|
||
mnt
|
||
├── archive1/
|
||
│\ \ ├── file.txt
|
||
│\ \ ├── file (1).txt
|
||
│\ \ └── file (2).txt
|
||
└── archive2/
|
||
├── file.txt
|
||
└── file (1).txt
|
||
|
||
2 directories, 5 files
|
||
.EE
|
||
.PD
|
||
.PP
|
||
Directories are never renamed.
|
||
If a file is colliding with a directory, the file will be the one
|
||
getting renamed.
|
||
.PD
|
||
.SH ARCHIVE FORMATS
|
||
\f[B]fuse\-archive\f[R] is built on top of the \c
|
||
.UR https://libarchive.org
|
||
\f[B]libarchive\f[R]
|
||
.UE \c
|
||
\ library.
|
||
It supports a wide variety of archive formats and compression methods,
|
||
either natively through \f[B]libarchive\f[R] or by invoking external
|
||
filter programs.
|
||
.PD
|
||
.PP
|
||
The exact set of supported formats depends on:
|
||
.IP \(bu 2
|
||
The version and build\-time configuration of the \f[B]libarchive\f[R]
|
||
library.
|
||
.IP \(bu 2
|
||
The availability of external filter programs in the sanitized
|
||
\f[CR]PATH\f[R] (see the \f[CR]\-o noexternal\f[R] and
|
||
\f[CR]\-o unsafe_path\f[R] options).
|
||
.PD
|
||
.PP
|
||
To see the version of \f[B]libarchive\f[R] and other libraries linked
|
||
with your build of \f[B]fuse\-archive\f[R], use the
|
||
\f[CR]\-\-version\f[R] option:
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive \-\-version
|
||
.EE
|
||
.PD
|
||
.SS Filename Extensions
|
||
\f[B]fuse\-archive\f[R] primarily determines an archive\(cqs format from
|
||
its filename extension.
|
||
It recognizes the following:
|
||
.IP \(bu 2
|
||
\f[B]Archive formats\f[R]: \f[CR]7z\f[R], \f[CR]7zip\f[R], \f[CR]a\f[R],
|
||
\f[CR]ar\f[R], \f[CR]cab\f[R], \f[CR]cpio\f[R], \f[CR]deb\f[R],
|
||
\f[CR]iso\f[R], \f[CR]iso9660\f[R], \f[CR]jar\f[R], \f[CR]lha\f[R],
|
||
\f[CR]lzh\f[R], \f[CR]mtree\f[R], \f[CR]rar\f[R], \f[CR]rpm\f[R],
|
||
\f[CR]tar\f[R], \f[CR]war\f[R], \f[CR]warc\f[R], \f[CR]xar\f[R],
|
||
\f[CR]zip\f[R], \f[CR]zipx\f[R].
|
||
.IP \(bu 2
|
||
\f[B]ZIP\-based formats\f[R]: \f[CR]aab\f[R], \f[CR]apk\f[R],
|
||
\f[CR]cbz\f[R], \f[CR]crx\f[R], \f[CR]docx\f[R], \f[CR]epub\f[R],
|
||
\f[CR]ipa\f[R], \f[CR]jar\f[R], \f[CR]odf\f[R], \f[CR]odg\f[R],
|
||
\f[CR]odp\f[R], \f[CR]ods\f[R], \f[CR]odt\f[R], \f[CR]ppsx\f[R],
|
||
\f[CR]pptx\f[R], \f[CR]war\f[R], \f[CR]whl\f[R], \f[CR]xlsx\f[R],
|
||
\f[CR]xpi\f[R], \f[CR]zip\f[R], \f[CR]zipx\f[R].
|
||
.IP \(bu 2
|
||
\f[B]RAR\-based formats\f[R]: \f[CR]rar\f[R], \f[CR]cbr\f[R].
|
||
.IP \(bu 2
|
||
\f[B]Compressed TARs\f[R]: \f[CR]tb2\f[R], \f[CR]tbr\f[R],
|
||
\f[CR]tbz\f[R], \f[CR]tbz2\f[R], \f[CR]tz2\f[R], \f[CR]tgz\f[R],
|
||
\f[CR]tlz\f[R], \f[CR]tlz4\f[R], \f[CR]tlzip\f[R], \f[CR]tlzma\f[R],
|
||
\f[CR]tlrz\f[R], \f[CR]tlzo\f[R], \f[CR]tlzop\f[R], \f[CR]txz\f[R],
|
||
\f[CR]tz\f[R], \f[CR]taz\f[R], \f[CR]tzs\f[R], \f[CR]tzst\f[R],
|
||
\f[CR]tzstd\f[R].
|
||
.IP \(bu 2
|
||
\f[B]Compression filters\f[R]: \f[CR]br\f[R], \f[CR]brotli\f[R],
|
||
\f[CR]bz\f[R], \f[CR]bz2\f[R], \f[CR]bzip2\f[R], \f[CR]grz\f[R],
|
||
\f[CR]grzip\f[R], \f[CR]gz\f[R], \f[CR]gzip\f[R], \f[CR]lrz\f[R],
|
||
\f[CR]lrzip\f[R], \f[CR]lz\f[R], \f[CR]lz4\f[R], \f[CR]lzip\f[R],
|
||
\f[CR]lzma\f[R], \f[CR]lzo\f[R], \f[CR]lzop\f[R], \f[CR]xz\f[R],
|
||
\f[CR]z\f[R], \f[CR]zst\f[R], \f[CR]zstd\f[R].
|
||
.IP \(bu 2
|
||
\f[B]ASCII encoding filters\f[R]: \f[CR]b64\f[R], \f[CR]base64\f[R],
|
||
\f[CR]uu\f[R].
|
||
.IP \(bu 2
|
||
\f[B]Encryption filters\f[R]: \f[CR]asc\f[R], \f[CR]gpg\f[R],
|
||
\f[CR]pgp\f[R].
|
||
.PD
|
||
.PP
|
||
If the filename extension is not recognized, \f[B]fuse\-archive\f[R]
|
||
will attempt to detect the format by examining the file\(cqs byte
|
||
contents.
|
||
This fallback mechanism can be disabled using the
|
||
\f[CR]\-o nobidding\f[R] option, forcing strict reliance on the file
|
||
extension.
|
||
.PD
|
||
.SS External Filter Programs
|
||
For some formats and encodings, \f[B]fuse\-archive\f[R] relies on the
|
||
following external programs being available in the sanitized
|
||
\f[CR]PATH\f[R]:
|
||
.IP \(bu 2
|
||
\f[CR]base64\f[R]: For \f[CR]b64\f[R] and \f[CR]base64\f[R] encodings.
|
||
.IP \(bu 2
|
||
\f[CR]brotli\f[R]: For \f[CR]br\f[R] and \f[CR]brotli\f[R] compression.
|
||
.IP \(bu 2
|
||
\f[CR]compress\f[R]: For \f[CR]z\f[R], \f[CR]taz\f[R], and \f[CR]tz\f[R]
|
||
compression (if not supported natively by \f[B]libarchive\f[R]).
|
||
.IP \(bu 2
|
||
\f[CR]gpg\f[R]: For \f[CR]asc\f[R], \f[CR]gpg\f[R], and \f[CR]pgp\f[R]
|
||
encryption.
|
||
.IP \(bu 2
|
||
\f[CR]lrzip\f[R]: For \f[CR]lrz\f[R] and \f[CR]tlrz\f[R] compression.
|
||
.IP \(bu 2
|
||
\f[CR]lzop\f[R]: For \f[CR]lzo\f[R], \f[CR]lzop\f[R], \f[CR]tlzo\f[R],
|
||
and \f[CR]tlzop\f[R] compression (if not supported natively by
|
||
\f[B]libarchive\f[R]).
|
||
.PD
|
||
.PP
|
||
Other formats, such as \f[CR]uu\f[R] (UUencoded), \f[CR]lzip\f[R],
|
||
\f[CR]xz\f[R], \f[CR]gzip\f[R], and \f[CR]bzip2\f[R], are typically
|
||
handled natively by the \f[B]libarchive\f[R] library and do not require
|
||
external programs.
|
||
.PD
|
||
.SH ARCHIVE TREE STRUCTURE
|
||
By default, \f[B]fuse\-archive\f[R] optimizes the presentation of the
|
||
mounted archives by merging them and trimming redundant top\-level
|
||
directories.
|
||
This behavior can be modified with the \f[CR]\-o nomerge\f[R] and
|
||
\f[CR]\-o notrim\f[R] options.
|
||
.PD
|
||
.SS Merging Multiple Archives
|
||
When mounting several archives, \f[B]fuse\-archive\f[R] merges their
|
||
contents into a single unified directory tree by default.
|
||
If multiple archives contain the same file path, the files are
|
||
deduplicated by adding a numeric suffix (e.g., \f[CR]file (1).txt\f[R]).
|
||
.PD
|
||
.PP
|
||
With the \f[CR]\-o nomerge\f[R] option, \f[B]fuse\-archive\f[R] creates
|
||
a separate subdirectory for each archive at the root of the mount point,
|
||
named after the archive\(cqs filename.
|
||
.PD
|
||
.SS Trimming the Base Tree
|
||
\f[B]fuse\-archive\f[R] automatically \(lqtrims\(rq the common base
|
||
directory of the archive to provide more direct access to its contents.
|
||
For example, if an archive contains only \f[CR]a/b/c/file.txt\f[R], it
|
||
will be presented as \f[CR]file.txt\f[R] at the root of the mount point.
|
||
.PD
|
||
.PP
|
||
The \f[CR]\-o notrim\f[R] option disables this behavior, preserving all
|
||
intermediate directories as they are recorded in the archive.
|
||
.PD
|
||
.SS Interaction Table
|
||
The following table summarizes how these options interact when mounting
|
||
archives \f[CR]arch1.zip\f[R] (containing \f[CR]a/b/c/f1\f[R]) and
|
||
\f[CR]arch2.zip\f[R] (containing \f[CR]a/b/d/f2\f[R]):
|
||
.PD
|
||
.PP
|
||
.TS
|
||
tab(@);
|
||
l l.
|
||
T{
|
||
Option
|
||
T}@T{
|
||
Resulting Structure
|
||
T}
|
||
_
|
||
T{
|
||
(Default)
|
||
T}@T{
|
||
\f[CR]/c/f1\f[R], \f[CR]/d/f2\f[R]
|
||
T}
|
||
T{
|
||
\f[CR]\-o notrim\f[R]
|
||
T}@T{
|
||
\f[CR]/a/b/c/f1\f[R], \f[CR]/a/b/d/f2\f[R]
|
||
T}
|
||
T{
|
||
\f[CR]\-o nomerge\f[R]
|
||
T}@T{
|
||
\f[CR]/arch1/f1\f[R], \f[CR]/arch2/f2\f[R]
|
||
T}
|
||
T{
|
||
\f[CR]\-o nomerge,notrim\f[R]
|
||
T}@T{
|
||
\f[CR]/arch1/a/b/c/f1\f[R], \f[CR]/arch2/a/b/d/f2\f[R]
|
||
T}
|
||
.TE
|
||
.PD
|
||
.SH ENCRYPTION
|
||
\f[B]fuse\-archive\f[R] supports two distinct types of encryption:
|
||
native archive encryption and GPG\-based encryption.
|
||
.PD
|
||
.SS Native Archive Encryption
|
||
Some archive formats (such as ZIP) have native encryption capabilities
|
||
built\-in.
|
||
\f[B]fuse\-archive\f[R] can leverage these when supported by the
|
||
underlying \f[B]libarchive\f[R] library.
|
||
.IP \(bu 2
|
||
\f[B]ZIP\f[R]: Supported (understand legacy ZIP encryption as well as
|
||
AES\-128, AES\-192 and AES\-256).
|
||
.IP \(bu 2
|
||
\f[B]7Z and RAR\f[R]: Native encryption for these formats is currently
|
||
\f[B]not\f[R] supported.
|
||
.PD
|
||
.PP
|
||
When mounting a natively encrypted archive, \f[B]fuse\-archive\f[R] will
|
||
securely prompt for a password in the terminal:
|
||
.IP
|
||
.EX
|
||
$ fuse\-archive encrypted.zip mnt
|
||
Need password for File [1] \(aq/secret.txt\(aq
|
||
Password > Got it!
|
||
Password is Ok
|
||
|
||
$ cat mnt/secret.txt
|
||
This was encrypted.
|
||
.EE
|
||
.PD
|
||
.PP
|
||
For security reasons, \f[B]fuse\-archive\f[R] doesn\(cqt allow the
|
||
password to be specified on the command line.
|
||
However, it is possible to pipe the password to
|
||
\f[B]fuse\-archive\f[R]\(cqs standard input:
|
||
.IP
|
||
.EX
|
||
$ echo password | fuse\-archive encrypted.zip mnt
|
||
.EE
|
||
.PD
|
||
.SS GPG Encryption
|
||
\f[B]fuse\-archive\f[R] also supports archives and individual files
|
||
encrypted with \c
|
||
.UR https://gnupg.org/
|
||
GnuPG
|
||
.UE \c
|
||
\ (e.g., \f[CR]archive.tar.gpg\f[R], \f[CR]archive.7z.pgp\f[R], or
|
||
\f[CR]romeo.txt.asc\f[R]).
|
||
This is handled by invoking the external \f[CR]gpg\f[R] command\-line
|
||
tool.
|
||
.PD
|
||
.PP
|
||
Using GPG encryption is particularly useful for consulting sensitive
|
||
documents without having to store a decrypted copy on the local disk,
|
||
which avoids the risk of leaving confidential data behind in temporary
|
||
folders.
|
||
.PD
|
||
.PP
|
||
When mounting a GPG\-encrypted item, \f[B]fuse\-archive\f[R] leverages
|
||
your existing GnuPG configuration and environment:
|
||
.IP \(bu 2
|
||
\f[B]Passphrase Management\f[R]: It can work with \f[CR]gpg\-agent\f[R]
|
||
to reuse cached passphrases.
|
||
.IP \(bu 2
|
||
\f[B]Secure Prompting\f[R]: It can use \f[CR]pinentry\f[R] to securely
|
||
prompt for passphrases via your preferred method (GUI or terminal).
|
||
.IP \(bu 2
|
||
\f[B]Hardware Support\f[R]: It supports decryption via hardware tokens
|
||
(like YubiKeys) if they are configured in your system\(cqs GnuPG setup.
|
||
.IP \(bu 2
|
||
\f[B]Nested Encodings\f[R]: It can handle multiple layers of compression
|
||
and encryption (e.g., \f[CR]archive.tar.gz.gpg\f[R]).
|
||
Use the \f[CR]\-o maxfilters\f[R] option to support these scenarios.
|
||
.PD
|
||
.PP
|
||
Ensure that the \f[CR]gpg\f[R] program is installed and available in the
|
||
sanitized \f[CR]PATH\f[R].
|
||
.PD
|
||
.SH CACHING
|
||
\f[B]fuse\-archive\f[R] only does the minimum amount of work required to
|
||
serve the requested data.
|
||
It offers several caching strategies and storage options to balance
|
||
performance, mount time, and resource usage.
|
||
.PD
|
||
.SS Caching Strategies
|
||
The following strategies are mutually exclusive.
|
||
If none is specified, pre\-emptive caching is used by default.
|
||
.PD
|
||
.SS Pre\-emptive Caching (\f[CR]\-o precache\f[R], Default)
|
||
By default, \f[B]fuse\-archive\f[R] decompresses and caches the whole
|
||
archive before serving its contents.
|
||
The cost of decompression is incurred upfront at mount time, ensuring
|
||
that subsequent access to any file is instantaneous and supports
|
||
efficient random access.
|
||
.PD
|
||
.SS Incremental Caching (\f[CR]\-o lazycache\f[R])
|
||
With \f[CR]\-o lazycache\f[R], \f[B]fuse\-archive\f[R] decompresses data
|
||
on\-the\-go as it is requested by applications.
|
||
This results in nearly instant mounting for archives that support random
|
||
access to metadata (such as ZIP, 7Z, or RAR).
|
||
Once a section of the archive has been read, it is cached for future
|
||
access.
|
||
.PD
|
||
.PP
|
||
Note that for solidly compressed archives (e.g., \f[CR].tar.gz\f[R],
|
||
\f[CR].tar.xz\f[R]) or encrypted archives, the entire file must still be
|
||
processed at mount time to retrieve the file list, which may take some
|
||
time for very large archives.
|
||
.PD
|
||
.SS No Caching (\f[CR]\-o nocache\f[R])
|
||
The \f[CR]\-o nocache\f[R] option disables long\-term caching.
|
||
\f[B]fuse\-archive\f[R] will use a small rolling buffer in memory to
|
||
serve data.
|
||
This minimizes disk and memory usage but can be significantly slower for
|
||
non\-sequential access patterns or if the same files are read
|
||
repeatedly, as data may need to be re\-decompressed.
|
||
.PD
|
||
.SS Storage Options
|
||
.PD
|
||
.SS Disk Caching (Default)
|
||
By default, decompressed data is cached in an anonymous temporary file
|
||
(in \f[CR]$TMPDIR\f[R] or \f[CR]/tmp\f[R]).
|
||
This cache can use a significant amount of disk space but is
|
||
automatically deleted when the archive is unmounted.
|
||
.PD
|
||
.SS Memory Caching (\f[CR]\-o memcache\f[R])
|
||
The \f[CR]\-o memcache\f[R] option instructs \f[B]fuse\-archive\f[R] to
|
||
store the cache in RAM instead of a temporary file.
|
||
This provides the highest performance but can consume a large amount of
|
||
memory.
|
||
It can be used with both pre\-emptive and incremental caching
|
||
strategies.
|
||
This option is only available on Linux.
|
||
.PD
|
||
.SH ADVANCED OPTIONS
|
||
.PD
|
||
.SS Handling Errors (\f[CR]\-o force\f[R])
|
||
The \f[CR]\-o force\f[R] option allows \f[B]fuse\-archive\f[R] to
|
||
continue mounting an archive even if some errors are encountered.
|
||
This includes:
|
||
.IP \(bu 2
|
||
Wrong or missing decryption passwords.
|
||
.IP \(bu 2
|
||
Unsupported compression or encryption methods.
|
||
.PD
|
||
.PP
|
||
In these cases, files that cannot be correctly processed will still be
|
||
listed in the directory tree, but attempting to read them will result in
|
||
an Input/Output error (EIO).
|
||
.PD
|
||
.SS Nested Encodings (\f[CR]\-o maxfilters=N\f[R])
|
||
Some archives may have multiple layers of compression or encryption
|
||
(e.g., \f[CR]archive.tar.gz.gpg\f[R]).
|
||
By default, \f[B]fuse\-archive\f[R] only processes one layer of
|
||
filtering.
|
||
.PD
|
||
.PP
|
||
To mount archives with nested encodings, you must increase the
|
||
\f[CR]\-o maxfilters\f[R] value (e.g., \f[CR]\-o maxfilters=2\f[R]).
|
||
.PD
|
||
.SS Permissions and Ownership
|
||
By default, \f[B]fuse\-archive\f[R] presents all files as being owned by
|
||
the current user and group, with standard read permissions.
|
||
.PD
|
||
.SS User and Group IDs (\f[CR]\-o uid=N\f[R], \f[CR]\-o gid=N\f[R])
|
||
You can explicitly set the owner and group of all items in the mounted
|
||
archive using the \f[CR]\-o uid\f[R] and \f[CR]\-o gid\f[R] options with
|
||
the desired numerical IDs.
|
||
.PD
|
||
.SS Enforcing Archive Permissions (\f[CR]\-o enforce_permissions\f[R])
|
||
The \f[CR]\-o enforce_permissions\f[R] option instructs
|
||
\f[B]fuse\-archive\f[R] to use the exact UID, GID, and Unix permission
|
||
bits stored within the archive for each item.
|
||
This includes support for special bits such as \f[B]SUID\f[R],
|
||
\f[B]SGID\f[R], and \f[B]SVTX\f[R] (sticky bit).
|
||
Note that this may result in access denied errors if you are not the
|
||
owner of the files inside the archive.
|
||
.PD
|
||
.SS Permission Masks (\f[CR]\-o dmask=M\f[R], \f[CR]\-o fmask=M\f[R])
|
||
You can apply an octal permission mask to directories (\f[CR]dmask\f[R])
|
||
and files (\f[CR]fmask\f[R]).
|
||
For example, \f[CR]\-o fmask=077\f[R] would remove all permissions for
|
||
group and others from files.
|
||
.PD
|
||
.SH LOG MESSAGES
|
||
\f[B]fuse\-archive\f[R] records log messages to the system logger
|
||
(\f[B]syslog\f[R]).
|
||
These messages can help troubleshoot issues, such as I/O errors or
|
||
archives that refuse to mount.
|
||
.PD
|
||
.PP
|
||
To read \f[B]fuse\-archive\f[R]\(cqs log messages on most Linux systems:
|
||
.IP
|
||
.EX
|
||
$ journalctl \-t fuse\-archive
|
||
.EE
|
||
.PD
|
||
.PP
|
||
Alternatively, you can run \f[B]fuse\-archive\f[R] in the foreground
|
||
with the \f[CR]\-f\f[R] option to see log messages directly on your
|
||
terminal.
|
||
.PD
|
||
.PP
|
||
By default, \f[B]fuse\-archive\f[R] writes \f[B]INFO\f[R] and
|
||
\f[B]ERROR\f[R] messages.
|
||
You can decrease the logging level to just \f[B]ERROR\f[R] messages with
|
||
the \f[CR]\-o quiet\f[R] option, or increase it to include
|
||
\f[B]DEBUG\f[R] messages with the \f[CR]\-o verbose\f[R] option.
|
||
.PD
|
||
.SS Redaction
|
||
To prevent sensitive file names from being recorded in the system logs,
|
||
use the \f[CR]\-o redact\f[R] option.
|
||
When enabled, file paths in log messages will be replaced with
|
||
\f[CR](redacted)\f[R].
|
||
.PD
|
||
.SH PERFORMANCE
|
||
Create a single \f[CR].tar.gz\f[R] file that is 256 MiB decompressed and
|
||
255 KiB compressed (the file just contains repeated 0x00 NUL bytes):
|
||
.IP
|
||
.EX
|
||
$ truncate \-\-size=256M zeroes
|
||
$ tar cfz zeroes\-256mib.tar.gz zeroes
|
||
.EE
|
||
.PD
|
||
.PP
|
||
Here are \f[B]fuse\-archive\f[R]\(cqs timings:
|
||
.IP
|
||
.EX
|
||
$ time fuse\-archive zeroes\-256mib.tar.gz mnt
|
||
real 0m0.443s
|
||
|
||
$ dd if=mnt/zeroes of=/dev/null status=progress
|
||
268435456 bytes (268 MB, 256 MiB) copied, 0.836048 s, 321 MB/s
|
||
|
||
$ umount mnt
|
||
.EE
|
||
.PD
|
||
.PP
|
||
For comparison, here are \f[B]archivemount\f[R]\(cqs timings:
|
||
.IP
|
||
.EX
|
||
$ time archivemount zeroes\-256mib.tar.gz mnt
|
||
real 0m0.581s
|
||
|
||
$ dd if=mnt/zeroes of=/dev/null status=progress
|
||
268435456 bytes (268 MB, 256 MiB) copied, 570.146 s, 471 kB/s
|
||
|
||
$ umount mnt
|
||
.EE
|
||
.PD
|
||
.PP
|
||
In this case, \f[B]fuse\-archive\f[R] takes about the same time to load
|
||
the archive as \f[B]archivemount\f[R], but it is \f[B]\(ti700×
|
||
faster\f[R] (0.83s vs.\ 570s) to copy out the decompressed contents.
|
||
This is because \f[B]fuse\-archive\f[R] fully caches the archive and
|
||
does not use \f[B]archivemount\f[R]\(cqs \c
|
||
.UR https://github.com/cybernoid/archivemount/issues/21
|
||
quadratic complexity algorithm
|
||
.UE \c
|
||
\&.
|
||
.PD
|
||
.SH COMPARISON
|
||
.PD
|
||
.PP
|
||
.TS
|
||
tab(@);
|
||
lw(25.0n) cw(16.0n) cw(13.0n) cw(16.0n).
|
||
T{
|
||
Feature
|
||
T}@T{
|
||
\f[B]fuse\-archive\f[R]
|
||
T}@T{
|
||
\f[B]mount\-zip\f[R]
|
||
T}@T{
|
||
\f[B]archivemount\f[R]
|
||
T}
|
||
_
|
||
T{
|
||
Read\-Write Support
|
||
T}@T{
|
||
❌
|
||
T}@T{
|
||
❌
|
||
T}@T{
|
||
✅
|
||
T}
|
||
T{
|
||
Format Support
|
||
T}@T{
|
||
Wide
|
||
T}@T{
|
||
ZIP
|
||
T}@T{
|
||
Wide
|
||
T}
|
||
T{
|
||
GPG Encryption
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Native ZIP Encryption
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}
|
||
T{
|
||
Native 7Z/RAR Encryption
|
||
T}@T{
|
||
❌
|
||
T}@T{
|
||
❌
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Lazy Decompression
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Default Caching
|
||
T}@T{
|
||
Pre\-emptive
|
||
T}@T{
|
||
Lazy
|
||
T}@T{
|
||
N/A
|
||
T}
|
||
T{
|
||
Memory Caching
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Temp File Caching
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Handles Huge Files
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Sparse File Detection
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Linear Complexity
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Precision Timestamps
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}
|
||
T{
|
||
Several Archives
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
Automatic Mount Point
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
T{
|
||
FUSE 3 Support
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
✅
|
||
T}@T{
|
||
❌
|
||
T}
|
||
.TE
|
||
.PD
|
||
.SH RETURN VALUE
|
||
.PD
|
||
.TP
|
||
\f[B]0\f[R]
|
||
Success.
|
||
.PD
|
||
.TP
|
||
\f[B]1\f[R]
|
||
Generic error code for: missing command\-line argument, too many
|
||
command\-line arguments, unknown option, mount point is not empty, etc.
|
||
.PD
|
||
.TP
|
||
\f[B]10\f[R]
|
||
Cannot create the mount point.
|
||
.PD
|
||
.TP
|
||
\f[B]11\f[R]
|
||
Cannot open the archive file.
|
||
.PD
|
||
.TP
|
||
\f[B]12\f[R]
|
||
Cannot create the cache file.
|
||
.PD
|
||
.TP
|
||
\f[B]13\f[R]
|
||
Cannot write to the cache file.
|
||
This is most likely an indication that there is not enough temporary
|
||
space.
|
||
.PD
|
||
.TP
|
||
\f[B]20\f[R]
|
||
The archive contains an encrypted file, but no password was provided.
|
||
.PD
|
||
.TP
|
||
\f[B]21\f[R]
|
||
The archive contains an encrypted file, and the provided password does
|
||
not decrypt it.
|
||
.PD
|
||
.TP
|
||
\f[B]22\f[R]
|
||
The archive contains an encrypted file, and the encryption method is not
|
||
supported.
|
||
.PD
|
||
.TP
|
||
\f[B]30\f[R]
|
||
Cannot recognize the archive format.
|
||
.PD
|
||
.TP
|
||
\f[B]31\f[R]
|
||
Invalid archive header.
|
||
.PD
|
||
.TP
|
||
\f[B]32\f[R]
|
||
Cannot read and extract the archive.
|
||
.PD
|
||
.SH SEE ALSO
|
||
archivemount(1), mount\-zip(1), fuse\-zip(1), fusermount(1), fuse(8),
|
||
umount(8)
|