mount-zip.1

'\" t
.\" 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 "MOUNT-ZIP" "1" "April 2024" "mount-zip 1.0" "User Manual"
.hy
.SH NAME
.PP
\f[B]mount-zip\f[R] - Mount a ZIP archive as a FUSE filesystem.
.SH SYNOPSIS
.PP
\f[B]mount-zip\f[R] [\f[I]options\f[R]] \f[I]zip-file\f[R]
[\f[I]mount-point\f[R]]
.SH DESCRIPTION
.PP
\f[B]mount-zip\f[R] is a tool allowing to open, explore and extract ZIP
archives.
.PP
\f[B]mount-zip\f[R] mounts a ZIP archive as a read-only FUSE file
system (https://en.wikipedia.org/wiki/Filesystem_in_Userspace), which
can then be explored and read by any application.
.PP
\f[B]mount-zip\f[R] aspires to be an excellent ZIP mounter.
It starts quickly, uses little memory, decodes encrypted files, and
provides on-the-go decompression and caching for maximum efficiency.
.PP
The mount point should be an empty directory.
If the mount point doesn\[cq]t exist yet, \f[B]mount-zip\f[R] creates it
first.
If no mount point is provided, \f[B]mount-zip\f[R] creates one in the
same directory as the ZIP archive.
.SH OPTIONS
.TP
\f[B]--help\f[R] \f[B]-h\f[R]
print help
.TP
\f[B]--version\f[R]
print version
.TP
\f[B]--quiet\f[R] \f[B]-q\f[R]
print fewer log messages
.TP
\f[B]--verbose\f[R]
print more log messages
.TP
\f[B]--redact\f[R]
redact file names from log messages
.TP
\f[B]--force\f[R]
mount ZIP even if password is wrong or missing, or if the encryption or
compression method is unsupported
.TP
\f[B]--precache\f[R]
preemptively decompress and cache data
.TP
\f[B]--cache=DIR\f[R]
cache directory (default is \f[V]$TMPDIR\f[R] or \f[V]/tmp\f[R])
.TP
\f[B]--memcache\f[R]
cache decompressed data in memory
.TP
\f[B]--nocache\f[R]
no caching of decompressed data
.TP
\f[B]-o encoding=CHARSET\f[R]
original encoding of file names
.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]
hide hard links
.TP
\f[B]-f\f[R]
foreground mode
.TP
\f[B]-d\f[R]
foreground mode with debug output
.SH USAGE
.PP
Mount a ZIP archive:
.IP
.nf
\f[C]
$ mount-zip foobar.zip mnt
\f[R]
.fi
.PP
The mounted ZIP archive can be explored and read using any application:
.IP
.nf
\f[C]
$ tree mnt
mnt
└── foo

0 directories, 1 file

$ cat mnt/foo
bar
\f[R]
.fi
.PP
When finished, unmount the file system:
.IP
.nf
\f[C]
$ fusermount -u mnt
\f[R]
.fi
.SH FEATURES
.IP \[bu] 2
Read-only view
.IP \[bu] 2
Instant mounting, even with big ZIP archives
.IP \[bu] 2
Compression methods: deflate, bzip2
.IP \[bu] 2
Encryption methods: AES and legacy ZIP encryption
.IP \[bu] 2
Asks for decryption password if necessary
.IP \[bu] 2
Detects file name encoding
.IP \[bu] 2
Converts file names to Unicode UTF-8
.IP \[bu] 2
Deduplicates files in case of name collisions
.IP \[bu] 2
Unpacks files when reading them (on-the-go decompression)
.IP \[bu] 2
Supports all file types, including named sockets, FIFOs, block and
character devices, symbolic links and hard links
.IP \[bu] 2
Supports UNIX access modes and DOS file permissions
.IP \[bu] 2
Supports owner and group information (UID and GID)
.IP \[bu] 2
Supports relative and absolute paths
.IP \[bu] 2
Supports high precision time stamps
.IP \[bu] 2
Works on 32-bit and 64-bit devices
.IP \[bu] 2
Supports ZIP64 extensions, even on 32-bit devices:
.RS 2
.IP \[bu] 2
Supports ZIP archives containing more than 65,535 files
.IP \[bu] 2
Supports ZIP archives and files bigger than 4 GB
.RE
.IP \[bu] 2
Supports ZIP format extensions:
.RS 2
.IP \[bu] 2
000A PKWARE NTFS Extra Field: High-precision timestamps
.IP \[bu] 2
000D PKWARE UNIX Extra Field: File type
.IP \[bu] 2
5455 Extended Timestamp
.IP \[bu] 2
5855 Info-ZIP Unix Extra Field (type 1)
.IP \[bu] 2
7855 Info-ZIP Unix Extra Field (type 2)
.IP \[bu] 2
7875 Info-ZIP New Unix Extra Field: Variable-length UIDs and GIDs
.RE
.SS File Name Encoding
.PP
\f[B]mount-zip\f[R] is fully Unicode compliant.
It converts the file names stored in the ZIP archive from their original
encoding to UTF-8.
.PP
In order to interpret these file names correctly, \f[B]mount-zip\f[R]
needs to determine their original encoding.
By default \f[B]mount-zip\f[R] tries to guess this encoding using the
detection feature provided by the ICU library.
It can automatically recognize the following encodings:
.IP \[bu] 2
UTF-8
.IP \[bu] 2
CP437
.IP \[bu] 2
Shift JIS
.IP \[bu] 2
Big5
.IP \[bu] 2
EUC-JP
.IP \[bu] 2
EUC-KR
.IP \[bu] 2
GB18030
.IP \[bu] 2
ISO-2022-CN
.IP \[bu] 2
ISO-2022-JP
.IP \[bu] 2
ISO-2022-KR
.IP \[bu] 2
KOI8-R
.PP
For example, when mounting a ZIP containing a Shift JIS-encoded file
name, the encoding is correctly detected:
.IP
.nf
\f[C]
$ mount-zip sjis-filename.zip mnt

$ tree mnt
mnt
└── 新しいテキスト ドキュメント.txt

0 directories, 1 file
\f[R]
.fi
.PP
This system is not foolproof, and doesn\[cq]t recognize a number of
popular encodings.
For example, when mounting a ZIP containing file names encoded in CP866,
they are interpreted as CP437 and rendered as
Mojibake (https://en.wikipedia.org/wiki/Mojibake):
.IP
.nf
\f[C]
$ mount-zip cp866.zip mnt

$ tree mnt
mnt
├── äáΓá
└── ÆѬßΓ«óδ⌐ ñ«¬π¼Ñ¡Γ.txt

0 directories, 2 files
\f[R]
.fi
.PP
In this case, the user needs to explicitly specify the original file
name encoding using the \f[V]-o encoding\f[R] mount option:
.IP
.nf
\f[C]
$ mount-zip -o encoding=cp866 cp866.zip mnt

$ tree mnt
mnt
├── Дата
└── Текстовый документ.txt

0 directories, 2 files
\f[R]
.fi
.SS Name Deduplication
.PP
In case of name collision, \f[B]mount-zip\f[R] adds a number to
deduplicate the conflicting file name:
.IP
.nf
\f[C]
$ unzip -l file-dir-same-name.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
       25  2021-10-29 14:22   pet/cat
       21  2021-10-29 14:22   pet
       30  2021-10-29 14:22   pet/cat/fish
        0  2021-10-29 14:22   pet/cat/fish/
       26  2021-10-29 14:22   pet/cat
       22  2021-10-29 14:22   pet
       31  2021-10-29 14:22   pet/cat/fish
---------                     -------
      155                     7 files

$ mount-zip file-dir-same-name.zip mnt

$ tree -F mnt
mnt
├── pet/
│\ \  ├── cat/
│\ \  │\ \  ├── fish/
│\ \  │\ \  ├── fish (1)
│\ \  │\ \  └── fish (2)
│\ \  ├── cat (1)
│\ \  └── cat (2)
├── pet (1)
└── pet (2)

3 directories, 6 files
\f[R]
.fi
.PP
Directories are never renamed.
If a file name is colliding with a directory name, the file is the one
getting renamed.
.SS Encrypted Archives
.PP
\f[B]mount-zip\f[R] supports encrypted ZIP archives.
It understand both the legacy ZIP encryption scheme, and the more recent
AES encryption schemes.
.PP
When \f[B]mount-zip\f[R] finds an encrypted file while mounting a ZIP
archive, it asks for a password.
If the given password doesn\[cq]t allow to decrypt the file, then
\f[B]mount-zip\f[R] refuses to mount the ZIP archive and returns an
error:
.IP
.nf
\f[C]
$ unzip -l different-encryptions.zip
Archive:  different-encryptions.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
       23  2020-08-28 15:22   ClearText.txt
       32  2020-08-28 15:23   Encrypted AES-128.txt
       32  2020-08-28 15:23   Encrypted AES-192.txt
       32  2020-08-28 15:23   Encrypted AES-256.txt
       34  2020-08-28 15:23   Encrypted ZipCrypto.txt
---------                     -------
      153                     5 files

$ mount-zip different-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES-128.txt\[aq]
Password > Got it!
Use the --force option to mount an encrypted ZIP with a wrong password
Cannot open File [1] \[aq]/Encrypted AES-128.txt\[aq]: Wrong password provided
\f[R]
.fi
.PP
Providing the correct password allows \f[B]mount-zip\f[R] to mount the
ZIP archive and decode the files:
.IP
.nf
\f[C]
$ mount-zip different-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES-128.txt\[aq]
Password > Got it!
Password is Ok

$ tree mnt
mnt
├── ClearText.txt
├── Encrypted AES-128.txt
├── Encrypted AES-192.txt
├── Encrypted AES-256.txt
└── Encrypted ZipCrypto.txt

0 directories, 5 files

$ md5sum mnt/*
7a542815e2c51837b3d8a8b2ebf36490  mnt/ClearText.txt
07c4edd2a55c9d5614457a21fb40aa56  mnt/Encrypted AES-128.txt
e48d57930ef96ff2ad45867202d3250d  mnt/Encrypted AES-192.txt
ca5e064a0835d186f2f6326f88a7078f  mnt/Encrypted AES-256.txt
275e8c5aed7e7ce2f32dd1e5e9ee4a5b  mnt/Encrypted ZipCrypto.txt

$ cat mnt/*
This is not encrypted.
This is encrypted with AES-128.
This is encrypted with AES-192.
This is encrypted with AES-256.
This is encrypted with ZipCrypto.
\f[R]
.fi
.PP
You can force \f[B]mount-zip\f[R] to mount an encrypted ZIP even without
providing the right password by using the \f[V]--force\f[R] option:
.IP
.nf
\f[C]
$ mount-zip --force different-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES-128.txt\[aq]
Password > Got it!
Continuing despite wrong password because of --force option
\f[R]
.fi
.PP
In this case, the files can be listed, but trying to open an encrypted
file for which the given password doesn\[cq]t work results in an I/O
error:
.IP
.nf
\f[C]
$ tree mnt
mnt
├── ClearText.txt
├── Encrypted AES-128.txt
├── Encrypted AES-192.txt
├── Encrypted AES-256.txt
└── Encrypted ZipCrypto.txt

0 directories, 5 files

$ md5sum mnt/*
7a542815e2c51837b3d8a8b2ebf36490  mnt/ClearText.txt
md5sum: \[aq]mnt/Encrypted AES-128.txt\[aq]: Input/output error
md5sum: \[aq]mnt/Encrypted AES-192.txt\[aq]: Input/output error
md5sum: \[aq]mnt/Encrypted AES-256.txt\[aq]: Input/output error
md5sum: \[aq]mnt/Encrypted ZipCrypto.txt\[aq]: Input/output error

$ cat mnt/*
This is not encrypted.
cat: \[aq]mnt/Encrypted AES-128.txt\[aq]: Input/output error
cat: \[aq]mnt/Encrypted AES-192.txt\[aq]: Input/output error
cat: \[aq]mnt/Encrypted AES-256.txt\[aq]: Input/output error
cat: \[aq]mnt/Encrypted ZipCrypto.txt\[aq]: Input/output error
\f[R]
.fi
.PP
For security reasons, \f[B]mount-zip\f[R] doesn\[cq]t allow to specify
the password on the command line.
However, it is possible to pipe the password to
\f[B]mount-zip\f[R]\[cq]s standard input:
.IP
.nf
\f[C]
$ echo password | mount-zip different-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES-128.txt\[aq]
Password is Ok
\f[R]
.fi
.SS Symbolic links
.PP
\f[B]mount-zip\f[R] shows symbolic links recorded in the ZIP archive:
.IP
.nf
\f[C]
$ mount-zip symlink.zip mnt

$ tree mnt
mnt
├── date
└── symlink -> ../tmp/date
\f[R]
.fi
.PP
Note that symbolic links can refer to files located outside the mounted
ZIP archive.
In some circumstances, these links could pose a security risk.
.PP
Symbolic links can be suppressed with the \f[V]-o nosymlinks\f[R]
option:
.IP
.nf
\f[C]
$ mount-zip -o nosymlinks symlink.zip mnt
Skipped Symlink [1] \[aq]/symlink\[aq]

2021-10-28 20:05:01 laptop \[ti]/mount-zip/tests/blackbox/data (intrusive)
$ tree mnt
mnt
└── date

0 directories, 1 file
\f[R]
.fi
.SS Special Files
.PP
\f[B]mount-zip\f[R] shows special files (sockets, FIFOs or pipes,
character and block devices) recorded in the ZIP archive:
.IP
.nf
\f[C]
$ mount-zip pkware-specials.zip mnt

$ ls -n mnt
brw-rw---- 1    0    6 8, 1 Aug  3  2019 block
crw--w---- 1    0    5 4, 0 Aug  3  2019 char
prw-r--r-- 1 1000 1000    0 Aug 15  2019 fifo
-rw-r--r-- 3 1000 1000   32 Aug  9  2019 regular
srw------- 1 1000 1000    0 Aug  3  2019 socket
lrwxrwxrwx 1 1000 1000    7 Aug  3  2019 symlink -> regular
lrwxrwxrwx 1 1000 1000    7 Aug 25  2019 symlink2 -> regular
-rw-r--r-- 3 1000 1000   32 Aug  9  2019 z-hardlink1
-rw-r--r-- 3 1000 1000   32 Aug  9  2019 z-hardlink2
brw-rw---- 1    0    6 8, 1 Aug  3  2019 z-hardlink-block
crw--w---- 1    0    5 4, 0 Aug  3  2019 z-hardlink-char
prw-r--r-- 1 1000 1000    0 Aug 15  2019 z-hardlink-fifo
srw------- 1 1000 1000    0 Aug  3  2019 z-hardlink-socket
lrwxrwxrwx 1 1000 1000    7 Aug  3  2019 z-hardlink-symlink -> regular
\f[R]
.fi
.PP
Special files can be suppressed with the \f[V]-o nospecials\f[R] option:
.IP
.nf
\f[C]
$ mount-zip -o nospecials pkware-specials.zip mnt
Skipped Block Device [0] \[aq]/block\[aq]
Skipped Character Device [1] \[aq]/char\[aq]
Skipped Pipe [2] \[aq]/fifo\[aq]
Skipped Socket [4] \[aq]/socket\[aq]
Skipped Block Device [7] \[aq]/z-hardlink-block\[aq]
Skipped Character Device [8] \[aq]/z-hardlink-char\[aq]
Skipped Pipe [9] \[aq]/z-hardlink-fifo\[aq]
Skipped Socket [10] \[aq]/z-hardlink-socket\[aq]

$ ls -n mnt
-rw-r--r-- 3 1000 1000 32 Aug  9  2019 regular
lrwxrwxrwx 1 1000 1000  7 Aug  3  2019 symlink -> regular
lrwxrwxrwx 1 1000 1000  7 Aug 25  2019 symlink2 -> regular
-rw-r--r-- 3 1000 1000 32 Aug  9  2019 z-hardlink1
-rw-r--r-- 3 1000 1000 32 Aug  9  2019 z-hardlink2
lrwxrwxrwx 1 1000 1000  7 Aug  3  2019 z-hardlink-symlink -> regular
\f[R]
.fi
.SS Hard Links
.PP
\f[B]mount-zip\f[R] shows hard links recorded in the ZIP archive.
.PP
In this example, the three file entries \f[V]0regular\f[R],
\f[V]hlink1\f[R] and \f[V]hlink2\f[R] point to the same inode number (2)
and their reference count is 3:
.IP
.nf
\f[C]
$ mount-zip -o use_ino hlink-chain.zip mnt

$ ls -ni mnt
2 -rw-r----- 3 0 0 10 Aug 14  2019 0regular
2 -rw-r----- 3 0 0 10 Aug 14  2019 hlink1
2 -rw-r----- 3 0 0 10 Aug 14  2019 hlink2

$ md5sum mnt/*
e09c80c42fda55f9d992e59ca6b3307d  mnt/0regular
e09c80c42fda55f9d992e59ca6b3307d  mnt/hlink1
e09c80c42fda55f9d992e59ca6b3307d  mnt/hlink2
\f[R]
.fi
.PP
Some tools can use the inode number to detect duplicated hard links.
In this example, \f[V]du\f[R] only counts the size of the inode (2)
once, even though there are three file entries pointing to it, and only
reports 10 bytes instead of 30 bytes:
.IP
.nf
\f[C]
$ du -b mnt
10      mnt
\f[R]
.fi
.PP
Duplicated hard links can be suppressed with the
\f[V]-o nohardlinks\f[R] option:
.IP
.nf
\f[C]
$ mount-zip -o nohardlinks hlink-chain.zip mnt
Skipped File [1]: Hardlinks are ignored
Skipped File [2]: Hardlinks are ignored

$ ls -ni mnt
2 -rw-r----- 1 0 0 10 Aug 14  2019 0regular
\f[R]
.fi
.SS File Permissions
.PP
\f[B]mount-zip\f[R] shows the Unix file permissions and ownership (UIDs
and GIDs) as recorded in the ZIP archive:
.IP
.nf
\f[C]
$ mount-zip unix-perm.zip mnt

$ ls -n mnt
-rw-r----- 1 1000 1000 0 Jan  5  2014 640
-rw-r---w- 1 1000 1000 0 Jan  5  2014 642
-rw-rw-rw- 1 1000 1000 0 Jan  5  2014 666
-rwsrwsr-x 1 1000 1000 0 Jan  5  2014 6775
-rwxrwxrwx 1 1000 1000 0 Jan  5  2014 777
\f[R]
.fi
.PP
Note that these access permissions are not enforced by default.
In this example, I am able to read the file \f[V]640\f[R] even though I
don\[cq]t own it and I don\[cq]t have the read permission:
.IP
.nf
\f[C]
$ md5sum mnt/*
d41d8cd98f00b204e9800998ecf8427e  mnt/640
d41d8cd98f00b204e9800998ecf8427e  mnt/642
d41d8cd98f00b204e9800998ecf8427e  mnt/666
d41d8cd98f00b204e9800998ecf8427e  mnt/6775
d41d8cd98f00b204e9800998ecf8427e  mnt/777
\f[R]
.fi
.PP
To enforce the access permission check, use the
\f[V]-o default_permissions\f[R] mount option:
.IP
.nf
\f[C]
$ mount-zip -o default_permissions unix-perm.zip mnt

$ md5sum mnt/*
md5sum: mnt/640: Permission denied
md5sum: mnt/642: Permission denied
d41d8cd98f00b204e9800998ecf8427e  mnt/666
d41d8cd98f00b204e9800998ecf8427e  mnt/6775
d41d8cd98f00b204e9800998ecf8427e  mnt/777
\f[R]
.fi
.SS Absolute and Parent-Relative Paths
.PP
\f[B]mount-zip\f[R] supports absolute and parent-relative paths in file
names.
Absolute paths are displayed under the \f[V]ROOT\f[R] directory.
For parent-relative paths, every \f[V]..\f[R] is replaced by
\f[V]UP\f[R].
Finally, ordinary relative paths are placed under the \f[V]CUR\f[R]
directory:
.IP
.nf
\f[C]
$ unzip -l mixed-paths.zip
 Length      Date    Time   Name
--------  ---------- -----  ----
      49  2021-11-02 13:55  normal.txt
      29  2021-11-02 13:55  ../up-1.txt
      30  2021-11-02 13:55  ../../up-2.txt
      40  2021-11-02 13:55  /top.txt
      45  2021-11-02 13:55  /../over-the-top.txt
--------                    -------
     193                    5 files

$ mount-zip mixed-paths.zip mnt
mount-zip[2886935]: Bad file name: \[aq]/../over-the-top.txt\[aq]
mount-zip[2886935]: Skipped File [4]: Cannot normalize path

$ tree mnt
mnt
├── CUR
│\ \  └── normal.txt
├── ROOT
│\ \  └── top.txt
├── UP
│\ \  └── up-1.txt
└── UPUP
    └── up-2.txt

4 directories, 4 files
\f[R]
.fi
.SS Smart Caching
.PP
\f[B]mount-zip\f[R] only does the minimum amount of work required to
serve the requested data.
When reading a compressed file, \f[B]mount-zip\f[R] only decompresses
enough data to serve the reading application.
This is called \f[I]lazy\f[R] or \f[I]on-the-go\f[R] decompression.
.PP
Accessing the beginning of a big compressed file is therefore
instantaneous:
.IP
.nf
\f[C]
$ mount-zip \[aq]Big One.zip\[aq] mnt

$ ls -lh mnt/
-rw-rw-r-- 1 root root 6.4G Mar 26  2020 \[aq]Big One.txt\[aq]

$ time head -4 \[aq]mnt/Big One.txt\[aq]
We\[aq]re going on a bear hunt.
We\[aq]re going to catch a big one.
What a beautiful day!
We\[aq]re not scared.

real    0m0.030s
user    0m0.015s
sys     0m0.014s
\f[R]
.fi
.PP
\f[B]mount-zip\f[R] generally avoids caching decompressed data.
If you read a compressed file several times, it is getting decompressed
each time:
.IP
.nf
\f[C]
$ dd if=\[aq]mnt/Big One.txt\[aq] of=/dev/null status=progress
6777995272 bytes (6.8 GB, 6.3 GiB) copied, 24.9395 s, 272 MB/s

$ dd if=\[aq]mnt/Big One.txt\[aq] of=/dev/null status=progress
6777995272 bytes (6.8 GB, 6.3 GiB) copied, 24.961 s, 272 MB/s
\f[R]
.fi
.PP
But \f[B]mount-zip\f[R] will start caching a file if it detects that
this file is getting read in a non-sequential way (ie the reading
application starts jumping to different positions of the file).
.PP
For example, \f[V]tail\f[R] jumps to the end of the file.
The first time this happens, \f[B]mount-zip\f[R] decompresses the whole
file and caches the decompressed data (in about 13 seconds in this
instance):
.IP
.nf
\f[C]
$ time tail -1 \[aq]mnt/Big One.txt\[aq]
The End

real    0m12.631s
user    0m0.024s
sys     0m0.656s
\f[R]
.fi
.PP
A subsequent call to \f[V]tail\f[R] is instantaneous, because
\f[B]mount-zip\f[R] has now cached the decompressed data:
.IP
.nf
\f[C]
$ time tail -1 \[aq]mnt/Big One.txt\[aq]
The End

real    0m0.032s
user    0m0.018s
sys     0m0.018s
\f[R]
.fi
.PP
Decompressed data is cached in a temporary file located in the cache
directory (\f[V]$TMPDIR\f[R] or \f[V]/tmp\f[R] by default).
The cache directory can be changed with the \f[V]--cache=DIR\f[R]
option.
The cache file is only created if necessary, and automatically deleted
when the ZIP is unmounted.
.PP
Alternatively, the \f[V]--memcache\f[R] option caches the decompressed
data in memory.
Be cautious with this option since it can cause \f[B]mount-zip\f[R] to
use a lot of memory.
.PP
You can preemtively cache data at mount time by using the
\f[V]--precache\f[R] option.
The cost of decompression in incurred upfront, and this ensures that any
subsequent access to the mounted data is fast.
.PP
If \f[B]mount-zip\f[R] cannot create and expand the cache file, or if it
was passed the \f[V]--nocache\f[R] option, it will do its best using a
small rolling buffer in memory.
However, some data access patterns might then result in poor
performance, especially if \f[B]mount-zip\f[R] has to repeatedly extract
the same file.
.SH PERFORMANCE
.PP
On small archives \f[B]mount-zip\f[R] has the same performance as
commonly used virtual filesystems such as KIO, Gnome GVFS, mc vfs,
unpackfs, avfs and fuse-zip.
But on large archives containing many files, \f[B]mount-zip\f[R] is
pretty quick.
.PP
For example on my laptop, a ZIP archive containing more than 70,000
files is mounted in half a second:
.IP
.nf
\f[C]
$ ls -lh linux-5.14.15.zip
-rw-r--r-- 1 fdegros primarygroup 231M Oct 28 15:48 linux-5.14.15.zip

$ time mount-zip linux-5.14.15.zip mnt

real    0m0.561s
user    0m0.344s
sys     0m0.212s

$ tree mnt
mnt
└── linux-5.14.15
    ├── arch
\&...

4817 directories, 72539 files

$ du -sh mnt
1.1G    mnt
\f[R]
.fi
.PP
The full contents of this mounted ZIP, totalling 1.1 GB, can be
extracted with \f[V]cp -R\f[R] in 14 seconds:
.IP
.nf
\f[C]
$ time cp -R mnt out

real    0m13.810s
user    0m0.605s
sys     0m5.356s
\f[R]
.fi
.PP
For comparison, \f[V]unzip\f[R] extracts the contents of the same ZIP in
8.5 seconds:
.IP
.nf
\f[C]
$ time unzip -q -d out linux-5.14.15.zip

real    0m8.411s
user    0m6.067s
sys     0m2.270s
\f[R]
.fi
.PP
Mounting an 8-GB ZIP containing only a few files is instantaneous:
.IP
.nf
\f[C]
$ ls -lh bru.zip
-rw-r----- 1 fdegros primarygroup 7.9G Sep  2 22:37 bru.zip

$ time mount-zip bru.zip mnt

real    0m0.033s
user    0m0.018s
sys     0m0.011s

$ tree -h mnt
mnt
├── [2.0M]  bios
├── [ 25G]  disk
└── [ 64M]  tools

0 directories, 3 files
\f[R]
.fi
.PP
Decompressing and reading the 25-GB file from this mounted ZIP takes
less than two minutes:
.IP
.nf
\f[C]
$ dd if=mnt/disk of=/dev/null status=progress
26843545600 bytes (27 GB, 25 GiB) copied, 104.586 s, 257 MB/s
\f[R]
.fi
.PP
There is no lag when opening and reading the file, and only a moderate
amount of memory is used.
The file is getting lazily decompressed by \f[B]mount-zip\f[R] as it is
getting read by the \f[V]dd\f[R] program.
.SH LOG MESSAGES
.PP
\f[B]mount-zip\f[R] records log messages into
\f[V]/var/log/user.log\f[R].
They can help troubleshooting issues, especially if you are facing I/O
errors when reading files from the mounted ZIP.
.PP
To read \f[B]mount-zip\f[R]\[cq]s log messages:
.IP
.nf
\f[C]
$ grep mount-zip /var/log/user.log | less -S
\f[R]
.fi
.PP
To follow \f[B]mount-zip\f[R]\[cq]s log messages as they are being
written:
.IP
.nf
\f[C]
$ tail -F /var/log/user.log | grep mount-zip
\f[R]
.fi
.PP
Alternatively, you can run \f[B]mount-zip\f[R] in foreground mode with
the \f[V]-f\f[R] option and read all the log messages on the terminal.
.PP
By default, \f[B]mount-zip\f[R] writes INFO and ERROR messages.
You can decrease the logging level to just ERROR messages with the
\f[V]--quiet\f[R] option.
Or you can increase the logging level to include DEBUG messages with the
\f[V]--verbose\f[R] option:
.IP
.nf
\f[C]
$ mount-zip -f --verbose foobar.zip mnt
Indexing \[aq]foobar.zip\[aq]...
Allocating 16 buckets
Detected encoding UTF-8 with 15% confidence
Indexed \[aq]foobar.zip\[aq] in 0 ms
Mounted \[aq]foobar.zip\[aq] on \[aq]mnt\[aq] in 2 ms
Reader 1: Opened File [0]
Reader 1: Closed
Unmounting \[aq]foobar.zip\[aq] from \[aq]mnt\[aq]...
Unmounted \[aq]foobar.zip\[aq] in 0 ms
\f[R]
.fi
.PP
To prevent file names from being recorded in \f[B]mount-zip\f[R]\[cq]s
log messages, use the \f[V]--redact\f[R] option:
.IP
.nf
\f[C]
$ mount-zip -f --verbose --redact bad-crc.zip mnt
Indexing (redacted)...
Allocating 16 buckets
Indexed (redacted) in 0 ms
Mounted (redacted) on (redacted) in 2 ms
Reader 1: Opened File [0]
Cannot read (redacted): Cannot read file: CRC error
Reader 1: Closed
Unmounting (redacted) from (redacted)...
Unmounted (redacted) in 0 ms
\f[R]
.fi
.SH RETURN VALUE
.PP
\f[B]mount-zip\f[R] returns distinct error codes for different error
conditions related the ZIP archive itself:
.TP
\f[B]0\f[R]
Success.
.TP
\f[B]1\f[R]
Generic error code for: missing argument, unknown option, unknown file
name encoding, mount point cannot be created, mount point is not empty,
etc.
.TP
\f[B]11\f[R]
The archive is a multipart ZIP.
.TP
\f[B]15\f[R]
\f[B]mount-zip\f[R] cannot read the ZIP archive.
.TP
\f[B]19\f[R]
\f[B]mount-zip\f[R] cannot find the ZIP archive.
.TP
\f[B]21\f[R]
\f[B]mount-zip\f[R] cannot open the ZIP archive.
.TP
\f[B]23\f[R]
Zlib data error.
This is probably the sign of a wrong password.
Use \f[V]--force\f[R] to bypass the password verification.
.TP
\f[B]26\f[R]
Unsupported compression method.
Use \f[V]--force\f[R] to bypass the compression method verification.
.TP
\f[B]29\f[R]
The archive is not recognized as a valid ZIP.
.TP
\f[B]31\f[R]
The ZIP archive has an inconsistent structure.
.TP
\f[B]34\f[R]
Unsupported encryption method.
Use \f[V]--force\f[R] to bypass the encryption method verification.
.TP
\f[B]36\f[R]
Needs password.
The ZIP archive contains an encrypted file, but no password was
provided.
Use \f[V]--force\f[R] to bypass the password verification.
.TP
\f[B]37\f[R]
Wrong password.
The ZIP archive contains an encrypted file, and the provided password
does not allow to decrypt it.
Use \f[V]--force\f[R] to bypass the password verification.
.TP
\f[B]45\f[R]
Possibly truncated or corrupted ZIP archive.
.SH PROJECT HISTORY
.PP
\f[B]mount-zip\f[R] started as a fork of \f[B]fuse-zip\f[R].
.PP
The original \f[B]fuse-zip\f[R] project was created in 2008 by Alexander
Galanin (http://galanin.nnov.ru/~al/) and is available on
Bitbucket (https://bitbucket.org/agalanin/fuse-zip).
.PP
The \f[B]mount-zip\f[R] project was then forked from \f[B]fuse-zip\f[R]
in 2021 and further developed by François
Degros (https://github.com/fdegros).
The ability to write and modify ZIP archives has been removed, but a
number of optimisations and features have been added:
.PP
.TS
tab(@);
l c c.
T{
Feature
T}@T{
mount-zip
T}@T{
fuse-zip
T}
_
T{
Read-Write Mode
T}@T{
❌
T}@T{
✅
T}
T{
Read-Only Mode
T}@T{
✅
T}@T{
✅
T}
T{
Shows Symbolic Links
T}@T{
✅
T}@T{
✅
T}
T{
Shows Hard Links
T}@T{
✅
T}@T{
✅
T}
T{
Shows Special Files
T}@T{
✅
T}@T{
✅
T}
T{
Shows Precise Timestamps
T}@T{
✅
T}@T{
✅
T}
T{
Allows Random Access
T}@T{
✅
T}@T{
✅
T}
T{
Can Cache in Memory
T}@T{
✅
T}@T{
✅
T}
T{
Can Cache in Temp File
T}@T{
✅
T}@T{
❌
T}
T{
Smart Caching
T}@T{
✅
T}@T{
❌
T}
T{
Decompresses Lazily
T}@T{
✅
T}@T{
❌
T}
T{
Handles Huge Files
T}@T{
✅
T}@T{
❌
T}
T{
Decrypts Encrypted Files
T}@T{
✅
T}@T{
❌
T}
T{
Detects Name Encoding
T}@T{
✅
T}@T{
❌
T}
T{
Deduplicates Names
T}@T{
✅
T}@T{
❌
T}
T{
Can Hide Symlinks
T}@T{
✅
T}@T{
❌
T}
T{
Can Hide Hard Links
T}@T{
✅
T}@T{
❌
T}
T{
Can Hide Special Files
T}@T{
✅
T}@T{
❌
T}
T{
Can Redact Log Messages
T}@T{
✅
T}@T{
❌
T}
T{
Returns Distinct Error Codes
T}@T{
✅
T}@T{
❌
T}
.TE
.SH AUTHORS
.IP \[bu] 2
François Degros (https://github.com/fdegros)
.IP \[bu] 2
Alexander Galanin (http://galanin.nnov.ru/~al/)
.SH LICENSE
.PP
\f[B]mount-zip\f[R] is released under the GNU General Public License
Version 3 or later.
.SH SEE ALSO
.PP
fusermount(1), fuse(8), umount(8)