Cloudfuse - An S3 and Azure Storage FUSE driver

Cloudfuse provides the ability to mount a cloud bucket in your local filesystem on Linux and Windows. With Cloudfuse you can easily read and write to the cloud, and connect programs on your computer to the cloud even if they're not cloud-aware. Cloudfuse uses file caching to provide the performance of local storage, or you can use streaming mode to efficiently access small parts of large files (e.g. video playback). Cloudfuse is a fork of blobfuse2, and adds S3 support and Windows support. Cloudfuse supports clouds with an S3 or Azure interface.

Table of Contents

• Installation
  • Windows
  • Linux
  • From Archive
  • From Source
• Basic Use
• Health Monitor
• Command Line Interface
• Limitations
• License
• Support
• Contributing

Installation

Windows

Download and run the .exe installer from our latest release here. Uncheck the "Launch Cloudfuse" upon finishing the installation. Run the CLI after the install completes.

Linux

Note: Packages from our APT/DNF repositories are built for FUSE 3 only. If your system only supports FUSE 2, install Cloudfuse manually from GitHub Releases.

FUSE Compatibility

• FUSE 3:
  • Ubuntu 20.04 and newer
  • Debian 11 (Bullseye) and newer
  • RHEL 8 and newer
• FUSE 2:
  • Ubuntu 18.04 or older
  • Debian 10 (Buster) or older
  • RHEL 7 or older

Debian /Ubuntu

Using Release on GitHub

Download the .deb file from our latest release here and run the following command in your terminal:

sudo apt-get install ./cloudfuse*.deb

Using APT Repository

1. Add the GPG key for the repository:

   sudo apt-get update
   sudo apt-get install -y curl gpg
   curl -fsSL https://seagate.github.io/cloudfuse/public.key | sudo gpg --dearmor -o /usr/share/keyrings/cloudfuse-archive-keyring.gpg

2. Add the repository to your APT sources:

   echo "deb [signed-by=/usr/share/keyrings/cloudfuse-archive-keyring.gpg] https://seagate.github.io/cloudfuse stable main" | sudo tee /etc/apt/sources.list.d/cloudfuse.list > /dev/null

3. Install cloudfuse:

   sudo apt-get update
   sudo apt-get install cloudfuse

Note: The Cloudfuse APT repository provides only the FUSE 3 build.

Fedora / RHEL

Using Release on GitHub

Download the .rpm file from our latest release here and run the following command in your terminal:

sudo rpm -i ./cloudfuse*.rpm

Using YUM/DNF Repository

1. Add the cloudfuse repository:

   sudo tee /etc/yum.repos.d/cloudfuse.repo <<EOF
   [cloudfuse]
   name=cloudfuse Repository
   baseurl=https://seagate.github.io/cloudfuse/rpm-repo/
   enabled=1
   gpgcheck=1
   gpgkey=https://seagate.github.io/cloudfuse/public.key
   EOF

2. Install cloudfuse:

   sudo dnf install cloudfuse

Note: The Cloudfuse DNF repository provides only the FUSE 3 build.

Enable Running With Systemd

To enable Cloudfuse to run using systemd, see Setup for systemd instructions

From Archive

Download the archive for your platform and architecture from the latest release here. On Windows, you will need to install WinFsp to use Cloudfuse. See this to install WinFSP.

From Source

Please refer to the Installation from source to manually install Cloudfuse.

Basic Use

Basic Use

The following describes how to use the Cloudfuse CLI. If you would like to use a GUI checkout the Cloudfuse GUI repo at https://github.com/Seagate/cloudfuse-gui.

1. Create a basic configuration file (TUI): If you would like an easy way to get started with cloudfuse, run the following to launch a TUI to configure cloudfuse. If you prefer to configure manually, checkout how to write a config file: https://github.com/Seagate/cloudfuse/wiki/Config-File

   cloudfuse config

   The interactive TUI prompts for:

   • Cloud type (S3 / Azure)
   • Bucket / container name
   • Credentials
   • Caching or streaming mode

   It writes an encrypted config file (default: ./config.aes) and asks you for a passphrase. Keep this passphrase safe.

2. Mount using an encrypted (TUI) config: You must provide the same passphrase you used when creating the config, either:

   • Passphrase flag:

     cloudfuse mount <mount-path> --config-file /path/to/config.aes --passphrase "your-passphrase"

   • Environment variable (preferred for scripts/systemd):

     export CLOUDFUSE_SECURE_CONFIG_PASSPHRASE="your-passphrase"
     cloudfuse mount <mount-path> --config-file /path/to/config.aes

3. Prepare a mount point:

   • Linux: directory must already exist.

     mkdir -p /mnt/mybucket

   • Windows: the mount directory must NOT already exist; it will be created.

4. Mount examples: Encrypted (env variable):

   export CLOUDFUSE_SECURE_CONFIG_PASSPHRASE="your-passphrase"
   cloudfuse mount /mnt/mybucket --config-file /path/to/config.aes

   Encrypted (flag):

   cloudfuse mount /mnt/mybucket --config-file /path/to/config.aes --passphrase "your-passphrase"

   Unencrypted:

   cloudfuse mount /mnt/mybucket --config-file /path/to/config.yaml

   Common flags:

   • --foreground (stay in foreground)
   • --read-only (prevent writes)
   • --lazy-write (defer writes until handle close)

5. Verify:

   cloudfuse mount list

   Or list files:

   ls /mnt/mybucket

6. Unmount:

   cloudfuse unmount /mnt/mybucket

   If busy:

   cloudfuse unmount --lazy /mnt/mybucket

Notes:

• Losing the passphrase makes the encrypted config unusable.
• Prefer CLOUDFUSE_SECURE_CONFIG_PASSPHRASE over putting the passphrase directly in scripts.
• Windows persistent remount requires service commands (see later section).

Command Line Interface

The general format of the Cloudfuse Linux commands is:

cloudfuse [command] [arguments] --[flag-name]=[flag-value]

Available commands:

• help [command] - Displays general help, or help for the specified command
• config - Displays a TUI to easily configure cloudfuse
• mount - Mounts a cloud storage container as a filesystem Example: cloudfuse mount <mount path> --config-file=<config file> Supported container types:
  • S3 Bucket Storage
  • Azure Blob Storage
  • Azure Datalake Storage Gen2
• mount all - Mounts all the containers in an S3 Account or Azure account supported by mount Example: cloudfuse mount all <mount path> --config-file=<config file> On Windows, mounted containers will be remounted on login after a restart.
• mount list - Lists all Cloudfuse filesystems Example: cloudfuse mount list
• unmount - Unmounts the Cloudfuse filesystem Add --lazy (or -z) flag to use lazy unmount (prevents busy errors). Example: cloudfuse unmount --lazy <mount path> On Windows, unmounting a container also stops it from being automatically remounted at login.
• unmount all - Unmounts all Cloudfuse filesystems Add --lazy (or -z) flag to use lazy unmount (prevents busy errors) - Linux only. Example: cloudfuse unmount all --lazy

Remount on Startup (Windows Only)

• cloudfuse service install - Installs the startup process for Cloudfuse which remounts containers on login after a restart.
• cloudfuse service uninstall - Uninstalls the startup process for Cloudfuse and prevents containers from being remounted on login.

Secure Options

To use security options the general format for cloudfuse commands is:

cloudfuse [command] [arguments] --[flag-name]=[flag-value]

• secure decrypt - Decrypts a config file
• secure encrypt - Encrypts a config file
• secure get - Gets value of a config parameter from an encrypted config file
• secure set - Updates value of a config parameter

Find help from your command prompt

To see a list of commands, type cloudfuse -h. To learn about a specific command, just include the name of the command (For example: cloudfuse mount -h).

Verifying Authenticity

Cloudfuse releases are signed keylessly using Cosign. To verify that the checksum file is genuine, use the following command where {tag} is the version of cloudfuse.

cosign verify-blob ./checksums_sha256.txt --bundle ./checksums_sha256.txt.bundle --certificate-identity https://github.com/Seagate/cloudfuse/.github/workflows/publish-release.yml@refs/tags/{tag} --certificate-oidc-is
suer https://token.actions.githubusercontent.com

This command should then print out "Verified OK" is the checksum file is valid. You can then use these checksums to verify that the cloudfuse version downloaded matches the expected checksum.

Health Monitor

Cloudfuse also supports a health monitor. The health monitor allows customers gain more insight into how their Cloudfuse instance is behaving with the rest of their machine. Visit here to set it up.

Limitations

NOTICE

• We have seen some customer issues around files getting corrupted when streaming is used in write mode. Kindly avoid using this feature for write while we investigate and resolve it.

Un-Supported File system operations

• mkfifo : fifo creation is not supported by cloudfuse and this will result in "function not implemented" error
• chown : Change of ownership is not supported by Azure Storage hence Cloudfuse does not support this.
• Creation of device files or pipes is not supported by Cloudfuse.
• Cloudfuse does not support extended-attributes (x-attrs) operations
• Cloudfuse does not support lseek() operation on directory handles. No error is thrown but it will not work as expected.

Un-Supported Scenarios

• Cloudfuse does not support overlapping mount paths. While running multiple instances of Cloudfuse make sure each instance has a unique and non-overlapping mount point.

• Cloudfuse does not support co-existence with NFS on same mount path. Behavior in this case is undefined.

• For Azure block blob accounts, where data is uploaded through other means, Cloudfuse expects special directory marker files to exist in container. In absence of this few file operations might not work. For e.g. if you have a blob 'A/B/c.txt' then special marker files shall exists for 'A' and 'A/B', otherwise opening of 'A/B/c.txt' will fail. Once a 'ls' operation is done on these directories 'A' and 'A/B' you will be able to open 'A/B/c.txt' as well. Possible workaround to resolve this from your container is to either

  create the directory marker files manually through portal or run 'mkdir' command for 'A' and 'A/B' from cloudfuse. Refer here for details on this.

Other Limitations

• In case of Azure BlockBlob accounts, ACLs are not supported by Azure Storage so Cloudfuse will by default return success for 'chmod' operation. However it will work fine for Gen2 (DataLake) accounts. ACLs are not currently supported for S3 accounts.

• When Cloudfuse is mounted on a docker container, SYS_ADMIN privileges are required for it to interact with the fuse driver. If container is created without the privilege, mount will fail. Sample command to spawn a docker container is

  docker run -it --rm --cap-add=SYS_ADMIN --device=/dev/fuse --security-opt apparmor:unconfined <environment variables> <docker image>

License

The Cloudfuse project is licensed under MIT.

Third-Party Notices

See notices for third party license notices.

WinFSP is licensed under the GPLv3 license with a special exception for Free/Libre and Open Source Software, which is available here.

Attribution

WinFsp - Windows File System Proxy, Copyright (C) Bill Zissimopoulos - link

Support

Contact Us

We welcome your questions and feedback! Email us: cloudfuse@seagate.com.

Frequently Asked Questions

A list of FAQs can be found here.

Report Issues and Request Features

Please submit issues and requests here.

Contributing

This project welcomes contributions and suggestions.

This project is governed by the code of conduct. You are expected to follow this as you contribute to the project. Please report all unacceptable behavior to opensource@seagate.com