# TigrisFS

For AI workloads, most runtimes assume data is accessible via a filesystem. By mounting a Tigris bucket as a filesystem, data is no longer limited by local storage nor memory capacity.

We provide [TigrisFS](https://github.com/tigrisdata/tigrisfs) a fork of the original [yandex-cloud/geesefs](https://github.com/yandex-cloud/geesefs) project with optimizations for Tigris. TigrisFS is a FUSE-based filesystem that mounts S3-compatible storage as a local filesystem. You can use TigrisFS to mount any Tigris bucket as if it was a normal Linux filesystem.

note

TigrisFS does not obfuscate the objects in the bucket, and does not require an additional metadata service (unlike JuiceFS). This means you can access the objects directly via the S3-compatible API using the standard S3 SDKs, tools, and libraries, as well as via the TigrisFS filesystem.

## Prerequisites:[​](#prerequisites "Direct link to Prerequisites:")

* A Tigris account
* A bucket you want to mount into your system (`mybucket`)
* A target location you want to mount your bucket to (`~/data`)

note

TigrisFS uses [FUSE](https://www.kernel.org/doc/html/latest/filesystems/fuse.html) to mount buckets into the filesystem. FUSE has limitations involving multiple users accessing the same mountpoint. If you need multiple users (human or service) to access the same bucket, consider creating multiple systemd services mounting the bucket in each user's home directory.

## Installing TigrisFS[​](#installing-tigrisfs "Direct link to Installing TigrisFS")

Download the latest release for your machine from [the list of TigrisFS releases](https://github.com/tigrisdata/tigrisfs/releases)

Debian Linux

You may need to install FUSE utils (fuse3 or fuse RPM/Debian package) first.

```
wget https://github.com/tigrisdata/tigrisfs/releases/download/v1.2.1/tigrisfs_1.2.1_linux_amd64.deb

dpkg -i tigrisfs_1.2.1_linux_amd64.deb
```

MacOS ARM64

You may need to install osxfuse/macfuse first.

```
curl -sL https://github.com/tigrisdata/tigrisfs/releases/download/v1.2.1/tigrisfs_1.2.1_darwin_arm64.tar.gz | sudo tar -xz -C /usr/local/bin
```

## Configure credentials[​](#configure-credentials "Direct link to Configure credentials")

Create a new access key with edit permissions on your target bucket in the [Tigris Dashboard](https://console.storage.dev/). Configure the aws-cli to utilize the credentials as described in the guide [here](https://www.tigrisdata.com/docs/sdks/s3/aws-cli/).

## Mount bucket[​](#mount-bucket "Direct link to Mount bucket")

### Using systemd[​](#using-systemd "Direct link to Using systemd")

When installed from the DEB or RPM package, TigrisFS installs a systemd service to simplify mounting and configuration.

Mount as current user:

```
systemctl --user start tigrisfs@<bucket>
```

Mount as root:

```
systemctl start tigrisfs@<bucket>
```

The bucket is mounted at `$HOME/mnt/tigrisfs/<bucket>` for the current user, or `/mnt/tigrisfs/<bucket>` for root.

To automount the bucket at boot or user login, enable the systemd service:

```
systemctl enable tigrisfs@<bucket> # as root

systemctl --user enable tigrisfs@<bucket> # as current user
```

### Using the command line[​](#using-the-command-line "Direct link to Using the command line")

To mount the bucket using the command line, run the following command:

```
/usr/local/bin/tigrisfs <bucket> <mountpoint>
```

You did it! You now have a performant filesystem backed by bottomless object storage.

## Maximizing performance[​](#maximizing-performance "Direct link to Maximizing performance")

### Cache sizing[​](#cache-sizing "Direct link to Cache sizing")

TigrisFS uses cache for both read buffers when it needs to read data from your Tigris bucket, and write buffers when it needs to write data to Tigris. The cache can be configured using the `--memory-limit` flag when mounting the bucket. The default value is 1GB. You can increase it to 4GB or more, depending on available memory on your machine. For example, below is how to mount a bucket with a 4GB cache:

```
/usr/local/bin/tigrisfs --memory-limit 4096 <bucket> <mountpoint>
```

### Improving write performance[​](#improving-write-performance "Direct link to Improving write performance")

TigrisFS uses a write-back cache to improve write performance. This means that when you write data to the mounted filesystem, it is first written to the cache and then flushed to the Tigris bucket in the background.

As mentioned above, the cache is used for both read and write buffers, so increasing the cache size will also improve write performance.

The other way to improve write performance is to increase the number of flushing threads. By default, TigrisFS uses 16 flushing threads. You can increase this number using the `--max-flushers` flag when mounting the bucket. The recommended value is 32 or more, depending on the number of CPU cores available on your machine.

```
/usr/local/bin/tigrisfs --memory-limit 4096 --max-flushers 64 <bucket> <mountpoint>
```

### Improving performance for small files[​](#improving-performance-for-small-files "Direct link to Improving performance for small files")

Apart from the data cache mentioned above, TigrisFS also uses a metadata cache to improve performance for metadata operations. The metadata cache is enabled by default. For small files, the metadata cache can significantly improve performance, as it reduces the number of requests to the Tigris bucket for metadata operations.

To improve performance for small files, you can increase the TTL of the cached entries in the metadata cache using the `--stat-cache-ttl` flag when mounting the bucket. The default value is 60 seconds. For example, below is how to mount a bucket with a 15 minutes metadata cache TTL:

```
/usr/local/bin/tigrisfs --memory-limit 4096 --max-flushers 64 --stat-cache-ttl 15m <bucket> <mountpoint>
```