fuse-archive.1

.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "fuse-archive" "1" "January 2025" "fuse-archive 1.7" "User Manual"
.hy
.SH NAME
.PP
\f[B]fuse-archive\f[R] - Mount an archive or compressed file as a FUSE
file system.
.SH SYNOPSIS
.PP
\f[B]fuse-archive\f[R] [\f[I]options\f[R]] \f[I]archive-file\f[R]
[\f[I]mount-point\f[R]]
.SH DESCRIPTION
.PP
\f[B]fuse-archive\f[R] is a program that serves an archive or compressed
file (e.g.
\f[V]foo.tar\f[R], \f[V]foo.tar.gz\f[R], \f[V]foo.xz\f[R] or
\f[V]foo.zip\f[R]) as a read-only
FUSE (https://en.wikipedia.org/wiki/Filesystem_in_Userspace) file
system.
.PP
It is similar to
\f[B]mount-zip\f[R] (https://github.com/google/mount-zip) and
\f[B]fuse-zip\f[R] (https://bitbucket.org/agalanin/fuse-zip) but speaks
a larger range of archive or compressed file formats.
.PP
It is similar to
\f[B]archivemount\f[R] (https://github.com/cybernoid/archivemount) but
can be much faster (see the Performance section below) although it can
only mount read-only, not read-write.
.SH OPTIONS
.TP
\f[B]--help\f[R] or \f[B]-h\f[R]
Print help
.TP
\f[B]--version\f[R] or \f[B]-V\f[R]
Print version
.TP
\f[B]-o quiet\f[R] or \f[B]-q\f[R]
Print fewer log messages
.TP
\f[B]-o verbose\f[R] or \f[B]-v\f[R]
Print more log messages
.TP
\f[B]-o redact\f[R]
Redact file names from log messages
.TP
\f[B]-o force\f[R]
Continue despite errors
.TP
\f[B]-o nocache\f[R]
No caching of uncompressed data
.TP
\f[B]-o nospecials\f[R]
Hide special files (FIFOs, sockets, devices)
.TP
\f[B]-o nosymlinks\f[R]
Hide symbolic links
.TP
\f[B]-o nohardlinks\f[R]
No files with multiple hard links
.TP
\f[B]-o dmask=M\f[R]
Directory permission mask in octal (default 0022)
.TP
\f[B]-o fmask=M\f[R]
File permission mask in octal (default 0022)
.TP
\f[B]-o uid=N\f[R]
Set the file owner of all the items in the mounted archive (default is
current user)
.TP
\f[B]-o gid=N\f[R]
Set file group of all the items in the mounted archive (default is
current group)
.TP
\f[B]-o default_permissions\f[R]
Use the file owner (UID), group (GID) and permissions stored with each
item in the archive.
.TP
\f[B]-f\f[R]
Foreground mode
.TP
\f[B]-d\f[R]
Foreground mode with debug output
.SH CACHING
.PP
By default, \f[B]fuse-archive\f[R] decompresses and caches the whole
archive before serving its contents.
This ensures that the served files can be accessed in any order without
any performance issue.
.PP
Decompressed data is cached in an anonymous file created in the
\f[V]tmp\f[R] directory (\f[V]$TMPDIR\f[R] or \f[V]/tmp\f[R] by
default).
This cache can use a significant amount of disk space, but it is
automatically deleted when the archive is unmounted.
.PP
If there is not enough temporary space to cache the whole archive,
\f[B]fuse-archive\f[R] can be run with the \f[V]-o nocache\f[R] option.
However, this can cause \f[B]fuse-archive\f[R] to be much slower at
serving files.
.SH PERFORMANCE
.PP
Create a single \f[V].tar.gz\f[R] file that is 256 MiB decompressed and
255 KiB compressed (the file just contains repeated 0x00 NUL bytes):
.IP
.nf
\f[C]
$ truncate --size=256M zeroes
$ tar cfz zeroes-256mib.tar.gz zeroes
\f[R]
.fi
.PP
Here are \f[B]fuse-archive\f[R]\[cq]s timings:
.IP
.nf
\f[C]
$ 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

$ fusermount -u mnt
\f[R]
.fi
.PP
For comparison, here are \f[B]archivemount\f[R]\[cq]s timings:
.IP
.nf
\f[C]
$ 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

$ fusermount -u mnt
\f[R]
.fi
.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]\[ti]700×
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]\[cq]s quadratic complexity
algorithm (https://github.com/cybernoid/archivemount/issues/21).
.SH RETURN VALUE
.TP
\f[B]0\f[R]
Success.
.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.
.TP
\f[B]10\f[R]
Cannot create the mount point.
.TP
\f[B]11\f[R]
Cannot open the archive file.
.TP
\f[B]12\f[R]
Cannot create the cache file.
.TP
\f[B]13\f[R]
Cannot write to the cache file.
This is most likely the indication that there is not enough temp space.
.TP
\f[B]20\f[R]
The archive contains an encrypted file, but no password was provided.
.TP
\f[B]21\f[R]
The archive contains an encrypted file, and the provided password does
not decrypt it.
.TP
\f[B]22\f[R]
The archive contains an encrypted file, and the encryption method is not
supported.
.TP
\f[B]30\f[R]
Cannot recognize the archive format.
.TP
\f[B]31\f[R]
Invalid archive header.
.TP
\f[B]32\f[R]
Cannot read and extract the archive.
.SH SEE ALSO
.PP
archivemount(1), mount-zip(1), fuse-zip(1), fusermount(1), fuse(8),
umount(8)