Files

990 lines
25 KiB
Groff
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
'\" 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)