Home

Awesome

<div align="center">

Ratarmount Logo

Random Access To Archived Resources (Ratarmount)

Python Version PyPI version Downloads Conda </br> Changelog License Build Status Discord Telegram

</div>

Ratarmount collects all file positions inside a TAR so that it can easily jump to and read from any file without extracting it. It, then, mounts the TAR using fusepy for read access just like archivemount. In contrast to libarchive, on which archivemount is based, random access and true seeking is supported. And in contrast to tarindexer, which also collects file positions for random access, ratarmount offers easy access via FUSE and support for compressed TARs.

Capabilities:

A complete list of supported formats can be found here.

Examples

Table of Contents

  1. Installation
    1. Installation via AppImage
    2. Installation via Package Manager
      1. Arch Linux
    3. System Dependencies for PIP Installation (Rarely Necessary)
    4. PIP Package Installation
  2. Supported Formats
    1. TAR compressions supported for random access
    2. Other supported archive formats
  3. Benchmarks
  4. The Problem
  5. The Solution
  6. Usage
    1. Metadata Index Cache
    2. Bind Mounting
    3. Union Mounting
    4. File versions
    5. Compressed non-TAR files
    6. Xz and Zst Files
    7. Remote Files
    8. Writable Mounting
    9. As a Library
    10. Fsspec Integration
    11. File Joining

Installation

You can install ratarmount either by simply downloading the AppImage or via pip. The latter might require installing additional dependencies.

pip install ratarmount

If you want all features, some of which may possibly result in installation errors on some systems, install with:

pip install ratarmount[full]

Installation via AppImage

The AppImage files are attached under "Assets" on the releases page. They require no installation and can be simply executed like a portable executable. If you want to install it, you can simply copy it into any of the folders listed in your PATH.

appImageName=ratarmount-0.15.0-x86_64.AppImage
wget 'https://github.com/mxmlnkn/ratarmount/releases/download/v0.15.0/$appImageName'
chmod u+x -- "$appImageName"
./"$appImageName" --help  # Simple test run
sudo cp -- "$appImageName" /usr/local/bin/ratarmount  # Example installation

Installation via Package Manager

Packaging status

Arch Linux

Arch Linux's AUR offers ratarmount as stable and development package. Use an AUR helper, like yay or paru, to install one of them:

# stable version
paru -Syu ratarmount
# development version
paru -Syu ratarmount-git

Conda

conda install -c conda-forge ratarmount

System Dependencies for PIP Installation (Rarely Necessary)

Python 3.6+, preferably pip 19.0+, FUSE, and sqlite3 are required. These should be preinstalled on most systems.

On Debian-like systems like Ubuntu, you can install/update all dependencies using:

sudo apt install python3 python3-pip fuse sqlite3 unar libarchive13 lzop gcc liblzo2-dev

On macOS, you have to install macFUSE and other optional dependencies with:

brew install macfuse unar libarchive lrzip lzop lzo

If you are installing on a system for which there exists no manylinux wheel, then you'll have to install further dependencies that are required to build some of the Python packages that ratarmount depends on from source:

sudo apt install \
    python3 python3-pip fuse \
    build-essential software-properties-common \
    zlib1g-dev libzstd-dev liblzma-dev cffi libarchive-dev liblzo2-dev gcc

PIP Package Installation

Then, you can simply install ratarmount from PyPI:

pip install ratarmount

Or, if you want to test the latest version:

python3 -m pip install --user --force-reinstall \
    'git+https://github.com/mxmlnkn/ratarmount.git@develop#egginfo=ratarmountcore&subdirectory=core' \
    'git+https://github.com/mxmlnkn/ratarmount.git@develop#egginfo=ratarmount'

If there are troubles with the compression backend dependencies, you can try the pip --no-deps argument. Ratarmount will work without the compression backends. The hard requirements are fusepy and for Python versions older than 3.7.0 dataclasses.

Supported Formats

TAR compressions supported for random access

Other supported archive formats

Benchmarks

Benchmark comparison between ratarmount, archivemount, and fuse-archive

Reading bandwidth benchmark comparison between ratarmount, archivemount, and fuse-archive

Further benchmarks can be viewed here.

The Problem

You downloaded a large TAR file from the internet, for example the 1.31TB large ImageNet, and you now want to use it but lack the space, time, or a file system fast enough to extract all the 14.2 million image files.

<details> <summary>Existing Partial Solutions</summary>

Partial Solutions

Archivemount

Archivemount seems to have large performance issues for too many files and large archive for both mounting and file access in version 0.8.7. A more in-depth comparison benchmark can be found here.

Tarindexer

Tarindex is a command line to tool written in Python which can create index files and then use the index file to extract single files from the tar fast. However, it also has some caveats which ratarmount tries to solve:

TAR Browser

I didn't find out about TAR Browser before I finished the ratarmount script. That's also one of it's cons:

Pros:

</details>

The Solution

Ratarmount creates an index file with file names, ownership, permission flags, and offset information. This sidecar is stored at the TAR file's location or in ~/.ratarmount/. Ratarmount can load that index file in under a second if it exists and then offers FUSE mount integration for easy access to the files inside the archive.

Here is a more recent test for version 0.2.0 with the new default SQLite backend:

The reading time for a small file simply verifies the random access by using file seek to be working. The difference between the first read and subsequent reads is not because of ratarmount but because of operating system and file system caches.

<details> <summary>Older test with 1.31 TB Imagenet (Fall 2011 release)</summary>

The test with the first version of ratarmount (50e8dbb), which used the, as of now removed, pickle backend for serializing the metadata index, for the ImageNet data set:

Index loading is relatively slow with 80s because of the pickle backend, which now has been replaced with SQLite and should take less than a second now.

</details>

Usage

Command Line Options

See ratarmount --help or here.

Metadata Index Cache

In order to reduce the mounting time, the created index for random access to files inside the tar will be saved to one of these locations. These locations are checked in order and the first, which works sufficiently, will be used. This is the default location order:

  1. <path to tar>.index.sqlite
  2. ~/.ratarmount/<path to tar: '/' -> '_'>.index.sqlite E.g., ~/.ratarmount/_media_cdrom_programm.tar.index.sqlite

This list of fallback folders can be overwritten using the --index-folders option. Furthermore, an explicitly named index file may be specified using the --index-file option. If --index-file is used, then the fallback folders, including the default ones, will be ignored!

Bind Mounting

The mount sources can be TARs and/or folders. Because of that, ratarmount can also be used to bind mount folders read-only to another path similar to bindfs and mount --bind. So, for:

ratarmount folder mountpoint

all files in folder will now be visible in mountpoint.

Union Mounting

If multiple mount sources are specified, the sources on the right side will be added to or update existing files from a mount source left of it. For example:

ratarmount folder1 folder2 mountpoint

will make both, the files from folder1 and folder2, visible in mountpoint. If a file exists in both multiple source, then the file from the rightmost mount source will be used, which in the above example would be folder2.

If you want to update / overwrite a folder with the contents of a given TAR, you can specify the folder both as a mount source and as the mount point:

ratarmount folder file.tar folder

The FUSE option -o nonempty will be automatically added if such a usage is detected. If you instead want to update a TAR with a folder, you only have to swap the two mount sources:

ratarmount file.tar folder folder

File versions

If a file exists multiple times in a TAR or in multiple mount sources, then the hidden versions can be accessed through special <file>.versions folders. For example, consider:

ratarmount folder updated.tar mountpoint

and the file foo exists both in the folder and as two different versions in updated.tar. Then, you can list all three versions using:

ls -la mountpoint/foo.versions/
    dr-xr-xr-x 2 user group     0 Apr 25 21:41 .
    dr-x------ 2 user group 10240 Apr 26 15:59 ..
    -r-x------ 2 user group   123 Apr 25 21:41 1
    -r-x------ 2 user group   256 Apr 25 21:53 2
    -r-x------ 2 user group  1024 Apr 25 22:13 3

In this example, the oldest version has only 123 bytes while the newest and by default shown version has 1024 bytes. So, in order to look at the oldest version, you can simply do:

cat mountpoint/foo.versions/1

Note that these version numbers are the same as when used with tar's --occurrence=N option.

Prefix Removal

Use ratarmount -o modules=subdir,subdir=<prefix> to remove path prefixes using the FUSE subdir module. Because it is a standard FUSE feature, the -o ... argument should also work for other FUSE applications.

When mounting an archive created with absolute paths, e.g., tar -P cf /var/log/apt/history.log, you would see the whole var/log/apt hierarchy under the mount point. To avoid that, specified prefixes can be stripped from paths so that the mount target directory directly contains history.log. Use ratarmount -o modules=subdir,subdir=/var/log/apt/ to do so. The specified path to the folder inside the TAR will be mounted to root, i.e., the mount point.

Compressed non-TAR files

If you want a compressed file not containing a TAR, e.g., foo.bz2, then you can also use ratarmount for that. The uncompressed view will then be mounted to <mountpoint>/foo and you will be able to leverage ratarmount's seeking capabilities when opening that file.

Xz and Zst Files

In contrast to bzip2 and gzip compressed files, true seeking on xz and zst files is only possible at block or frame boundaries. This wouldn't be noteworthy, if both standard compressors for xz and zstd were not by default creating unsuited files. Even though both file formats do support multiple frames and xz even contains a frame table at the end for easy seeking, both compressors write only a single frame and/or block out, making this feature unusable. In order to generate truly seekable compressed files, you'll have to use pixz for xz files. For zstd compressed, you can try with t2sz. The standard zstd tool does not support setting smaller block sizes yet although an issue does exist. Alternatively, you can simply split the original file into parts, compress those parts, and then concatenate those parts together to get a suitable multiframe zst file. Here is a bash function, which can be used for that:

<details> <summary>Bash script: createMultiFrameZstd</summary> 
createMultiFrameZstd()
(
    # Detect being piped into
    if [ -t 0 ]; then
        file=$1
        frameSize=$2
        if [[ ! -f "$file" ]]; then echo "Could not find file '$file'." 1>&2; return 1; fi
        fileSize=$( stat -c %s -- "$file" )
    else
        if [ -t 1 ]; then echo 'You should pipe the output to somewhere!' 1>&2; return 1; fi
        echo 'Will compress from stdin...' 1>&2
        frameSize=$1
    fi
    if [[ ! $frameSize =~ ^[0-9]+$ ]]; then
        echo "Frame size '$frameSize' is not a valid number." 1>&2
        return 1
    fi

    # Create a temporary file. I avoid simply piping to zstd
    # because it wouldn't store the uncompressed size.
    if [[ -d /dev/shm ]]; then frameFile=$( mktemp --tmpdir=/dev/shm ); fi
    if [[ -z $frameFile ]]; then frameFile=$( mktemp ); fi
    if [[ -z $frameFile ]]; then
        echo "Could not create a temporary file for the frames." 1>&2
        return 1
    fi

    if [ -t 0 ]; then
        true > "$file.zst"
        for (( offset = 0; offset < fileSize; offset += frameSize )); do
            dd if="$file" of="$frameFile" bs=$(( 1024*1024 )) \
               iflag=skip_bytes,count_bytes skip="$offset" count="$frameSize" 2>/dev/null
            zstd -c -q -- "$frameFile" >> "$file.zst"
        done
    else
        while true; do
            dd of="$frameFile" bs=$(( 1024*1024 )) \
               iflag=count_bytes count="$frameSize" 2>/dev/null
            # pipe is finished when reading it yields no further data
            if [[ ! -s "$frameFile" ]]; then break; fi
            zstd -c -q -- "$frameFile"
        done
    fi

    'rm' -f -- "$frameFile"
)

In order to compress a file named foo into a multiframe zst file called foo.zst, which contains frames sized 4MiB of uncompressed ata, you would call it like this:

createMultiFrameZstd foo  $(( 4*1024*1024 ))

It also works when being piped to. This can be useful for recompressing files to avoid having to decompress them first to disk.

lbzip2 -cd well-compressed-file.bz2 | createMultiFrameZstd $(( 4*1024*1024 )) > recompressed.zst
</details>

Remote Files

The fsspec API backend adds support for mounting many remote archive or folders. Please refer to the linked respective backend documentation to see the full configuration options, especially for specifying credentials. Some often-used configuration environment variables are copied here for easier viewing.

SymbolDescription
[something]Optional "something"
(one|two)Either "one" or "two"

Many other fsspec-based projects may also work when installed.

This functionality of ratarmount offers a hopefully more-tested and out-of-the-box experience over the experimental fsspec.fuse implementation. And, it also works in conjunction with the other features of ratarmount such as union mounting and recursive mounting.

Index files specified with --index-file can also be compressed and/or be an fsspec (chained) URL, e.g., https://host.org/file.tar.index.sqlite.gz. In such a case, the index file will be downloaded and/or extracted into the default temporary folder. If the default temporary folder has insufficient disk space, it can be changed by setting the RATARMOUNT_INDEX_TMPDIR environment variable.

Writable Mounting

The --write-overlay <folder> option can be used to create a writable mount point. The original archive will not be modified.

This overlay folder can be stored alongside the archive or it can be deleted after unmounting the archive. This is useful when building the executable from a source tarball without extracting. After installation, the intermediary build files residing in the overlay folder can be safely removed.

If it is desired to apply the modifications to the original archive, then the --commit-overlay can be prepended to the original ratarmount call.

Here is an example for applying modifications to a writable mount and then committing those modifications back to the archive:

  1. Mount it with a write overlay and add new files. The original archive is not modified.

    ratarmount --write-overlay example-overlay example.tar example-mount-point
echo "Hello World" > example-mount-point/new-file.txt

  2. Unmount. Changes persist solely in the overlay folder.

    fusermount -u example-mount-point

  3. Commit changes to the original archive.

    ratarmount --commit-overlay --write-overlay example-overlay example.tar example-mount-point

    Output:

    To commit the overlay folder to the archive, these commands have to be executed:

    tar --delete --null --verbatim-files-from --files-from='/tmp/tmp_ajfo8wf/deletions.lst' \
        --file 'example.tar' 2>&1 |
       sed '/^tar: Exiting with failure/d; /^tar.*Not found in archive/d'
    tar --append -C 'zlib-wiki-overlay' --null --verbatim-files-from --files-from='/tmp/tmp_ajfo8wf/append.lst' --file 'example.tar'

Committing is an experimental feature!
Please confirm by entering "commit". Any other input will cancel.
> 
Committed successfully. You can now remove the overlay folder at example-overlay.

  4. Verify the modifications to the original archive.

    tar -tvlf example.tar

    Output:

    -rw-rw-r-- user/user 652817 2022-08-08 10:44 example.txt
-rw-rw-r-- user/user     12 2023-02-16 09:49 new-file.txt

  5. Remove the obsole write overlay folder.

    rm -r example-overlay

As a Library

Ratarmount can also be used as a library. Using ratarmountcore, files inside archives can be accessed directly from Python code without requiring FUSE. For a more detailed description, see the ratarmountcore readme here.

Fsspec Integration

To use all fsspec features, either install via pip install ratarmount[fsspec] or pip install ratarmount[fsspec]. It should also suffice to simply pip install fsspec if ratarmountcore is already installed. The optional fsspec integration is threefold:

  1. Files can be specified on the command line via URLs pointing to remotes as explained in this section.
  2. A ratarmountcore.MountSource wrapping fsspec AbstractFileSystem implementation has been added. A specialized SQLiteIndexedTarFileSystem as a more performant and direct replacement for fsspec.implementations.TarFileSystem has also been added. 
    from ratarmountcore.SQLiteIndexedTarFsspec import SQLiteIndexedTarFileSystem as ratarfs
fs = ratarfs("tests/single-file.tar")
print("Files in root:", fs.ls("/", detail=False))
print("Contents of /bar:", fs.cat("/bar"))
  3. During installation ratarmountcore registers the ratar:// protocol with fsspec via an entrypoint group. This enables usages with fsspec.open. The fsspec URL chaining feature must be used in order for this to be useful. Example for opening the file bar, which is contained inside the file tests/single-file.tar.gz with ratarmountcore: 
    import fsspec
with fsspec.open("ratar://bar::file://tests/single-file.tar.gz") as file:
    print("Contents of file bar:", file.read())
    This also works with pandas: 
    import fsspec
import pandas as pd
with fsspec.open("ratar://bar::file://tests/single-file.tar.gz", compression=None) as file:
    print("Contents of file bar:", file.read())
    The compression=None argument is currently necessary because of this Pandas bug.

File Joining

Files with sequentially numbered extensions can be mounted as a joined file. If it is an archive, then the joined archive file will be mounted. Only one of the files, preferably the first one, should be specified. For example:

base64 /dev/urandom | head -c $(( 1024 * 1024 )) > 1MiB.dat
tar -cjf- 1MiB.dat | split -d --bytes=320K - file.tar.gz.
ls -la
# 320K  file.tar.gz.00
# 320K  file.tar.gz.01
# 138K  file.tar.gz.02
ratarmount file.tar.gz.00 mounted
ls -la mounted
# 1.0M  1MiB.dat