[Yandex Cloud documentation](../../index.md) > [Yandex Object Storage](../index.md) > [Tools](index.md) > FUSE > GeeseFS # GeeseFS [GeeseFS](https://github.com/yandex-cloud/geesefs) is a utility for mounting Object Storage buckets using [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace) on Linux, MacOS, and Windows platforms. It was developed by the Yandex Cloud team as a [goofys](goofys.md) branch. It is a high-performance, POSIX-ish file system. ## Features {#features} ### Performance {#performance} Compared to goofys and [s3fs](s3fs.md), GeeseFS handles large amounts of small files (up to 1 MB) much faster and achieves similar or higher performance with large files. For more information about benchmark tests, see the [GeeseFS repository on GitHub](https://github.com/yandex-cloud/geesefs/tree/master/bench). To run faster, GeeseFS implements: * Parallel readahead. * Heuristic readahead for random access: if the size of multiple blocks requested in a row is below the threshold, GeeseFS downloads smaller blocks from the storage for upcoming requests. * Parallel [multipart uploads](../concepts/multipart.md) of objects to the storage. * Optimized object updates: the client and repository only exchange modified object parts. * Background uploads of small object trees and [directories](../concepts/object.md#folder): when a directory is requested, GeeseFS downloads the whole tree per request to the storage. * Asynchronous object write, rename, and delete operations. * Disk cache for reads and writes. ### POSIX compatibility {#posix-compatibility} In addition to the basic functions of the POSIX standards (`open`, `read`, `write`, `close`, and so on), GeeseFS supports the following features: * Read-after-write consistency. * Partial writes (please note that partial writes in buckets with [versioning](../concepts/versioning.md) may result in intermediate object versions). * `fsync`: Synchronization of the contents of an object or directory between the VM memory and storage. * `truncate`: Changing object size arbitrarily. * Soft links (symlinks). * `xattr`: Extended file attributes. * Directory renames. * `readdir`: Reads of directory metadata. ### Partial updating and appending of object data {#patch} GeeseFS supports [partial updating and appending of object data](../concepts/object-patch.md) in Object Storage buckets. To enable partial object updates, use the `--enable-patch` option. Learn more in the GeeseFS repository on GitHub: * [Partial object updates](https://github.com/yandex-cloud/geesefs#partial-object-updates-patch): Description of partial updating and appending of object data. * [Concurrent Updates](https://github.com/yandex-cloud/geesefs#concurrent-patch): Description of a partial object update using multiple concurrent requests. ### Limits {#restrictions} GeeseFS does not support the following: * Working with file and directory access permissions, including the `chmod` and `chown` commands. When mounting the file system, you can specify: * Access permissions to all files or directories in the `--file-mode` and `--dir-mode` option values, respectively. * ID of the owner of all files and directories in the `--uid` option value. * ID of the group all files and directories belong to in the `--gid` option value. Here is an example: ```bash geesefs \ --file-mode=0666 \ --dir-mode=0777 \ --uid=1000 \ ``` * Hard links. * File locking. * Correct time of the last access to the file (`atime`) and the last change of the file's attributes (`ctime`). Both fields always contain the time of the file's last modification: same as in the `mtime` field. * Creating files larger than 1 TB. ## Getting started {#before-you-begin} 1. [Create a service account](../../iam/operations/sa/create.md). 1. [Assign to the service account the roles](../../iam/operations/sa/assign-role-for-sa.md) required for your project, e.g., [storage.editor](../security/index.md#storage-editor) for a bucket (to work with a particular bucket) or a folder (to work with all buckets in this folder). For more information about roles, see [Access management with Yandex Identity and Access Management](../security/index.md). To work with objects in an [encrypted](../concepts/encryption.md) bucket, a user or [service account](../../iam/concepts/users/service-accounts.md) must have the following [roles for the encryption key](../../kms/operations/key-access.md) in addition to the `storage.configurer` [role](../security/index.md#storage-configurer): * `kms.keys.encrypter`: To read the key, [encrypt](../../kms/security/index.md#kms-keys-encrypter) and upload objects. * `kms.keys.decrypter`: To read the key, [decrypt](../../kms/security/index.md#kms-keys-decrypter) and download objects. * `kms.keys.encrypterDecrypter`: This role includes the `kms.keys.encrypter` and `kms.keys.decrypter` [permissions](../../kms/security/index.md#kms-keys-encrypterDecrypter). For more information, see [Key Management Service service roles](../../kms/security/index.md#service-roles). 1. [Create a static access key](../../iam/operations/authentication/manage-access-keys.md#create-access-key). As a result, you will get the static access key data. To authenticate in Object Storage, you will need the following: * `key_id`: Static access key ID * `secret`: Secret key Save `key_id` and `secret`: you will not be able to get the key value again. To access the HTTP API directly, you need static key authentication, which is supported by the tools listed in [Supported tools](index.md). {% note info %} You can [disable using static keys for bucket access](../operations/buckets/disable-statickey-auth.md). Once disabled, access will be denied to all tools using this access option: the AWS CLI, SDK, and third-party applications. Access via [ephemeral keys](../security/ephemeral-keys.md), [temporary Security Token Service access keys](../security/sts.md), and [pre-signed URLs](../security/overview.md#pre-signed) will also be disabled. Only access with an [IAM token](../../iam/concepts/authorization/iam-token.md) or [anonymous access](../security/public-access.md) (if enabled) will remain. {% endnote %} You can use Yandex Lockbox to safely store the static key for access to Object Storage. For more information, see [Using a Yandex Lockbox secret to store a static access key](../tutorials/static-key-in-lockbox/index.md). {% note info %} A service account is only allowed to view a list of buckets in the folder it was created in. A service account can perform actions with objects in buckets that are created in folders different from the service account folder. To enable this, [assign](../../iam/operations/sa/assign-role-for-sa.md) the service account [roles](../security/index.md#service-roles) for the appropriate folder or its bucket. {% endnote %} ## Installation {#installation} {% list tabs group=operating_system %} - Debian/Ubuntu {#linux} 1. Make sure the FUSE utilities are installed in the distribution: ```bash apt list --installed | grep fuse ``` {% note warning %} Many Linux distributions have the utilities for working with FUSE pre-installed by default. Reinstalling or deleting them may lead to OS failures. {% endnote %} 1. If the FUSE utilities are not installed, run this command: ```bash sudo apt-get install fuse ``` 1. Download and install GeeseFS: ```bash wget https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-linux-amd64 chmod a+x geesefs-linux-amd64 sudo cp geesefs-linux-amd64 /usr/bin/geesefs ``` - CentOS {#centos} 1. Make sure the FUSE utilities are installed in the distribution: ```bash yum list installed | grep fuse ``` {% note warning %} Many Linux distributions have the utilities for working with FUSE pre-installed by default. Reinstalling or deleting them may lead to OS failures. {% endnote %} 1. If the FUSE utilities are not installed, run this command: ```bash sudo yum install fuse ``` 1. Download and install GeeseFS: ```bash wget https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-linux-amd64 chmod a+x geesefs-linux-amd64 sudo cp geesefs-linux-amd64 /usr/bin/geesefs ``` - macOS {#macos} 1. Install the [macFUSE](https://osxfuse.github.io/) package. 1. [Enable](https://github.com/macfuse/macfuse/wiki/Getting-Started#enabling-support-for-third-party-kernel-extensions-apple-silicon-macs) support for third-party core extensions. This step is only required the first time you use MacFUSE on an Apple Silicon Mac. 1. [Allow](https://github.com/macfuse/macfuse/wiki/Getting-Started#allow-the-macfuse-kernel-extension-to-load-apple-silicon-and-intel-macs) loading the MacFUSE core extension (Apple Silicon and Intel Mac). For more information on installing macFUSE, see [this installation guide](https://github.com/osxfuse/osxfuse/wiki/FAQ#2-installuninstall-questions) in the macFUSE GitHub repository. 1. Download and install GeeseFS: ```bash platform='arm64' if [[ $(uname -m) == 'x86_64' ]]; then platform='amd64'; fi wget https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-mac-$platform chmod a+x geesefs-mac-$platform sudo cp geesefs-mac-$platform /usr/local/bin/geesefs ``` - Windows {#windows} 1. [Download](https://winfsp.dev/rel/) and install WinFSP. 1. [Download](https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-win-x64.exe) the `geesefs-win-x64.exe` file. 1. Rename `geesefs-win-x64.exe` to `geesefs.exe` for convenience. 1. Create a folder named `geesefs` and move the `geesefs.exe` file there. 1. Add `geesefs` to the `PATH` variable: 1. Click **Start** and type **Change system environment variables** in the Windows search bar. 1. Click **Environment Variables...** at the bottom right. 1. In the window that opens, find the `PATH` parameter and click **Edit**. 1. Add your folder path to the list. 1. Click **OK**. {% endlist %} You can also build GeeseFS yourself using its source code. For more information, see [this guide](https://github.com/yandex-cloud/geesefs#installation) in the GeeseFS repository on GitHub. ## Authentication {#authentication} GeeseFS uses the static access key to Object Storage you [got earlier](#before-you-begin). You can set it using one of the following methods: {% list tabs group=operating_system %} - Linux/macOS {#linux} * Using the `credentials` [file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html), which you need to put into the `~/.aws/` folder: 1. Create a directory: ```bash mkdir ~/.aws ``` 1. Create a file named `credentials` with the following contents: ```text [default] aws_access_key_id = aws_secret_access_key = ``` If the key file is located elsewhere, specify its path in the `--shared-config` parameter when mounting the bucket: ```bash geesefs \ --shared-config \ ``` The key file must have the same structure as `~/.aws/credentials`. * Using environment variables: ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= ``` {% note info %} You can run the `geesefs` command with superuser privileges (`sudo`). In this case, make sure to send information about the key either in the `--shared-config` parameter or using environment variables. {% endnote %} - Windows {#windows} * Using the `credentials` [file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html), which you need to put into the `users//.aws/` folder: ```text [default] aws_access_key_id = aws_secret_access_key = ``` If the key file is located elsewhere, specify its path in the `--shared-config` parameter when mounting the bucket: ```cmd geesefs ^ --shared-config ^ ``` The key file must have the same structure as `~/.aws/credentials`. Specify an existing folder as the mount point. * Using environment variables: ```cmd set AWS_ACCESS_KEY_ID= set AWS_SECRET_ACCESS_KEY= ``` {% endlist %} When using GeeseFS on a Compute Cloud VM that has a [linked service account](../../compute/operations/vm-connect/auth-inside-vm.md#link-sa-with-instance), you can enable simplified authentication that does not require a static access key. To do this, use the `--iam` parameter when mounting the bucket. ## Mounting a bucket {#bucket-mounting} Select the folder or disk where you want to mount the bucket. Make sure you have sufficient permissions to perform this operation. When mounting a bucket, you can also configure GeeseFS settings related to system [performance](#performance) and object access permissions. To view the list of options and their descriptions, run `geesefs --help`. * For one-time bucket mounting: {% list tabs group=operating_system %} - Linux/macOS {#linux} 1. Create a folder for mounting: ```bash mkdir ``` 1. Mount the bucket: ```bash geesefs ``` Specify an existing folder as the mount point. - Windows {#windows} Mount the bucket: ```bash geesefs ``` As the mount point, specify the name of the new folder that will be created when you mount the bucket. You cannot specify the name of an existing folder. Result: ```text 2025/10/06 21:14:27.488504 main.INFO File system has been successfully mounted. The service geesefs has been started. ``` {% endlist %} * To automatically mount a bucket at system startup: {% list tabs group=operating_system %} - Linux {#linux} 1. Create a folder for automatic mounting: ```bash mkdir ``` 1. Open `/etc/fuse.conf`: ```bash sudo nano /etc/fuse.conf ``` 1. Add the following line to it: ```text user_allow_other ``` 1. Open `/etc/fstab`: ```bash sudo nano /etc/fstab ``` 1. Add the following line to the `/etc/fstab` file: ```text /home// fuse.geesefs _netdev,allow_other,--file-mode=0666,--dir-mode=0777,--shared-config=/home//.aws/credentials 0 0 ``` If you had created the `.aws/credentials` file for the `root` user, you do not need to specify the `--shared-config` parameter. {% note info %} For the bucket to be mounted correctly, provide the full absolute path to the mount point and to the key file without `~`, e.g., `/home/user/`. {% endnote %} 1. Reboot your PC and check that the bucket has been mounted to the specified folder. To disable automounting, remove the line with the bucket name from the `/etc/fstab` file. - macOS {#macos} 1. Create a folder for automatic mounting: ```bash mkdir ``` 1. Create a file named `com.geesefs.automount.plist` with the autorun agent configuration: ```bash nano /Users//Library/LaunchAgents/com.geesefs.automount.plist ``` 1. Set the agent configuration by specifying the name of the bucket and the absolute path to the mount point: ```xml Label com.geesefs.automount ProgramArguments /usr/local/bin/geesefs RunAtLoad KeepAlive NetworkState ``` {% note info %} Specify an existing empty folder as the mount point. For the bucket to be mounted correctly, provide the full absolute path to the mount point and to the key file without `~`, e.g., `/home/user/`. {% endnote %} 1. Enable the agent you created: ```bash launchctl load /Users//Library/LaunchAgents/com.geesefs.automount.plist ``` 1. Reboot your PC and check that the bucket has been mounted to the specified folder. To disable agent autorun, use this command: ```bash launchctl unload /Users//Library/LaunchAgents/com.geesefs.automount.plist ``` - Windows {#windows} Create a Windows service that will automatically run at system startup: 1. Run `CMD` as an administrator. 1. Run this command: ```cmd sc create ^ binPath="" ^ DisplayName= "" ^ type=own ^ start=auto ``` Where `binPath` is the path to the `geesefs.exe` file with the required mounting parameters. Here is an example: `C:\geesefs\geesefs.exe `. As the mount point, specify the name of the new folder that will be created when you mount the bucket. You cannot specify the name of an existing folder. Result: ```text [SC] CreateService: Success ``` 1. Click **Start** and start typing `Services` in the Windows search bar. Run the **Services** application as an administrator. 1. In the window that opens, find the service you created earlier, right-click it, and select **Properties**. 1. On the **Log on** tab, select **This account** and specify your Windows account name and password. If necessary, click **Browse** → **Advanced** → **Search** to find the user you need on the computer. 1. Click **OK**. To delete the created service, open `CMD` as an administrator and run the following command: ```cmd sc delete ``` Result: ```text [SC] DeleteService: Success ``` {% endlist %}