GeeseFS

Last update: June 04 2026

GeeseFS is a program used to mount a bucket to a device or server, allowing you to work with it as you would with a regular folder. GeeseFS is suitable for working with a large number of objects, each up to 1 MB in size. GeeseFS can be used on Linux, Windows, and macOS.

Configure GeeseFS

1. Configure access to S3.
2. Install the client.
3. Create a configuration.

1. Configure access to S3

Access can be configured by the Account Owner or a user with the iam.admin role.

1. Create a service user with a role with S3 access. If you use a service user with the s3.user, object_storage_user, or s3.bucket.user role, an access policy must be configured for the bucket, and its rules must allow access to this user.
2. Issue an S3 key to the user.

2. Install the client

Linux

1. Ensure that utilities for working with FUSE are installed by default:

   apt list --installed | grep fuse

2. If the utilities are not installed, install them:

   sudo apt-get install fuse

3. Download and install GeeseFS:

   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

Windows

1. If you do not have WinFSP installed, download and install it.

2. Download the geesefs-win-x64.exe file, but do not install it.

3. Optional: for convenience, rename the file to geesefs.exe.

4. Create a geesefs folder.

5. Move the geesefs.exe file to the geesefs folder.

6. Add the geesefs folder to the PATH variable:

   6.1. In the Windows search bar, enter Edit the system environment variables.

   6.2. Click Environment Variables.

   6.3. Select the PATH parameter.

   6.4. Click Edit → New.

   6.5. Add the path to the folder to the list.

   6.6. Click OK → OK.

7. For the environment variable settings to take effect, restart the device.

macOS

1. Prepare and install the macFUSE package:

   1.1. Installing macFUSE requires changing macOS security settings; use the Getting Started guide on GitHub.

   1.2. Install the macFUSE package.

2. Open Terminal.

3. Install GeeseFS:

   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

3. Create a configuration

Linux

1. Open the CLI.

2. Create a directory where the file with the S3 key will be stored:

   mkdir ~/.aws

3. Create a credentials file:

   nano ~/.aws/credentials

4. Add the S3 key:

   [default]
   aws_access_key_id = <access_key>
   aws_secret_access_key = <secret_key>

   Specify:

   • <access_key> — the value of the Access key field from the S3 key;
   • <secret_key> — the value of the Secret key field from the S3 key.

5. Press Ctrl + X → Y → Enter.

Windows

1. Open PowerShell.

2. Create a credentials file:

   New-Item -Type Directory -Path "$env:USERPROFILE\.aws" -Force | Out-Null
   notepad "$env:USERPROFILE\.aws\credentials"

3. Add the S3 key:

   [default]
   aws_access_key_id = <access_key>
   aws_secret_access_key = <secret_key>

   Specify:

   • <access_key> — the value of the Access key field from the S3 key;
   • <secret_key> — the value of the Secret key field from the S3 key.

4. Click File → Save

5. If the file was saved with a .txt extension, remove it:

   Rename-Item "$env:USERPROFILE\.aws\credentials.txt"
               "$env:USERPROFILE\.aws\credentials" -Force`

macOS

1. Open Terminal.

2. Create a directory where the file with the S3 key will be stored:

   mkdir ~/.aws

3. Create a credentials file:

   cat ~/.aws/credentials

4. Add the S3 key:

   [default]
   aws_access_key_id = <access_key>
   aws_secret_access_key = <secret_key>

   Specify:

   • <access_key> — the value of the Access key field from the S3 key;
   • <secret_key> — the value of the Secret key field from the S3 key.

5. Press Control + X → Y → Enter.

Mount the bucket

One-time mounting

Linux

1. Create a folder for mounting:

   mkdir /mnt/<folder_name>

   Specify <folder_name> as the name of the folder where the bucket will be mounted.

2. Mount the bucket:

   sudo geesefs
   --endpoint https://<s3_domain>
   --region <pool>
   --profile <profile_name>
   <bucket_name> /mnt/<folder_name>

   Specify:

   • <s3_domain> — the S3 API domain depending on the pool where the bucket is located;
   • <pool> — the pool where the bucket is located;
   • <bucket_name> — the name of the bucket to be mounted;
   • <profile_name> — the profile name, default is default;
   • <folder_name> — the folder name you created in step 1.

3. Ensure that the bucket is mounted:

   df -hT /mnt/<folder_name>

   Specify <folder_name> as the folder name you created in step 1.

Windows

1. Open PowerShell.

2. Mount the bucket:

   geesefs --endpoint <s3_domain> --region <pool>
   <bucket_name> <destination>

   Specify:

   • <s3_domain> — the S3 API domain depending on the pool where the bucket is located;

   • <pool> — the pool where the bucket is located;

   • <bucket_name> — the name of the bucket to be mounted;

   • <destination> — the name of a new disk or the path to a folder in Windows where the bucket will be mounted. To mount the bucket:

     • as a disk — use a value like S:;
     • as a folder — use the path to the folder in quotes, for example "C:\Data\GeeseFS".

macOS

After mounting, the folder will appear in Finder as an external disk.

1. Open Finder or Terminal.

2. Create a folder for mounting:

   mkdir -p "<local_folder>"

   Specify <local_folder> as the path to the folder.

3. Copy and save the path to the folder.

4. Mount the bucket:

   geesefs -o volname="<volume_name>"
       --endpoint https://<s3_domain>
       --region <pool>
       --profile <profile_name>
       <bucket_name> "<local_folder>"

   Specify:

   • <volume_name> — the name of the external disk in Finder as which the mounted bucket will be displayed;
   • <bucket_name> — the name of the bucket to be mounted;
   • <local_folder> — the path to the folder you created in step 2;
   • <s3_domain> — the S3 API domain depending on the pool where the bucket is located;
   • <pool> — the pool where the bucket is located;
   • <profile_name> — the profile name, default is default.

   Upon successful mounting, you will receive the following response:

   main.INFO File system has been successfully mounted

5. If you have a certificate conflict, remove it:

   sed -i '' '/^[[:space:]]*ca_bundle[[:space:]]*=/d' ~/.aws/config

Automatic mounting

Linux

1. Open the /etc/fstab file:

   sudo nano /etc/fstab

2. Add a command for automatic bucket mounting:

   <bucket_name> /mnt/<folder_name> fuse.geesefs _netdev,allow_other,--endpoint=https://<s3_domain>,--region=<pool>,--profile=<profile_name> 0 0

   Specify:

   • <bucket_name> — the name of the bucket to be mounted;
   • <folder_name> — the name of the folder where the bucket will be mounted;
   • <s3_domain> — the S3 API domain depending on the pool where the bucket is located;
   • <pool> — the pool where the bucket is located;
   • <profile_name> — the profile name, default is default;

3. Apply the settings:

   sudo systemctl daemon-reload

4. Ensure that the bucket is mounted:

   sudo mount -a
   df -hT

Windows

1. Open PowerShell.

2. Create a Windows service that will start with the OS:

   $dir = Join-Path $env:USERPROFILE '<folder_name>'
   New-Item -ItemType Directory -Path $dir -Force | Out-Null
   $script = Join-Path $dir '<task_name>.cmd'
   @"
   @echo off
   cd /d "%USERPROFILE%\\\<TASK_FOLDER>"
   geesefs.exe --endpoint https://<s3_domain> --region <pool> <bucket_name> <destination> >> "%USERPROFILE%\\\<task_name>\mount.log" 2>&1
   "@ | Set-Content -Path $script -Encoding ASCII
   
   schtasks /Create /TN "<task_name>" /SC ONLOGON /RL HIGHEST /RU $env:USERNAME /TR "$script" /F

   Specify:

   • <folder_name> — the folder name in the profile where .cmd files and logs will be stored;

   • <task_name> — the task name for the task that will mount the bucket;

   • <s3_domain> — the S3 API domain depending on the pool where the bucket is located;

   • <pool> — the pool where the bucket is located;

   • <bucket_name> — the name of the bucket to be mounted;

   • <destination> — the name of a new disk or the path to a folder in Windows where the bucket will be mounted. To mount the bucket:

     • as a disk — use a value like S:;
     • as a folder — use the path to the folder in quotes, for example " C:\Data\GeeseFS";

   • <task_name> — the name for the task in Windows services that will trigger bucket mounting upon system startup.

3. Ensure that the bucket is mounted:

   schtasks /Run /TN "<task_name>"

   Specify <task_name> as the name of the task in Windows services that triggers bucket mounting upon system startup.

4. Restart the device.

macOS

1. Open Finder or Terminal.

2. Create a folder for mounting:

   mkdir -p "<local_folder>"

   Specify <local_folder> as the path to the folder.

3. Copy and save the path to the folder.

4. Copy the path to GeeseFS:

   which geesefs

5. Create a configuration file for the auto-start agent:

   mkdir -p "$HOME/Library/LaunchAgents"
   cat > "$HOME/Library/LaunchAgents/<agent_name>.plist" <<'PLIST'
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
   <key>Label</key>
   <string><agent_name></string>
   <key>ProgramArguments</key>
   <array>
       <string><geesefs_path></string>
       <string>-o</string><string>volname=<volume_name></string>
       <string>--endpoint</string><string><s3_domain></string>
   <string>--region</string><string><pool></string>
       <string>--profile</string><string><profile_name></string>
       <string><bucket_name></string>
   <string><local_folder></string>
   </array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key>
   <dict>
       <key>NetworkState</key><true/>
   </dict>
   <key>StandardOutPath</key><string>/Users/<username>/Library/Logs/geesefs.out.log</string>
   <key>StandardErrorPath</key><string>/Users/<username>/Library/Logs/geesefs.err.log</string>
   </dict>
   </plist>
   PLIST
   
   chmod 644 "$HOME/Library/LaunchAgents/<agent_name>.plist"
   chmod 700 "$HOME/Library/LaunchAgents"
   plutil -lint "$HOME/Library/LaunchAgents/<agent_name>.plist"

   Specify:

   • <agent_name> — the filename for the auto-start agent;
   • <geesefs_path> — the path to GeeseFS you copied in step 4;
   • <volume_name> — the name of the mounted bucket, which will be displayed in Finder as an external disk. It can be the same as or different from <local_folder>;
   • <s3_domain> — the S3 API domain depending on the pool where the bucket is located;
   • <pool> — the pool where the bucket is located;
   • <local_folder> — the path to the folder you created in step 2;
   • <profile_name> — the AWS profile name, default is default;
   • <bucket_name> — the name of the bucket to be mounted to the device;
   • <username> — your macOS system username.

6. Run the agent:

   launchctl bootstrap gui/$(id -u) "$HOME/Library/LaunchAgents/<agent_name>.plist"
   launchctl enable gui/$(id -u)/<agent_name>
   launchctl kickstart -k gui/$(id -u)/<agent_name>

   Specify <agent_name> as the name of the file with the auto-start agent that you created in step 5.

7. Ensure that the bucket is mounted:

   mount | grep geesefs || echo "Not mounted yet"
   open "<local_folder>"

   Specify <local_folder> as the path to the folder you created in step 2.

Unmount the bucket

The unmounting method depends on how the bucket was mounted: once or automatically.

One-time mounting

Linux

Unmount the bucket:

sudo umount /mnt/<local_folder>

Specify <local_folder> as the path to the folder where the bucket is mounted.

Windows

1. Open PowerShell.

2. Press Ctrl + C.

3. Ensure that the command line returns a response:

   main.INFO Flushing all changes
   main.INFO Successfully exiting

macOS

1. Open Terminal.

2. Unmount the bucket:

   umount "<local_folder>" 2>/dev/null || diskutil unmount force "<local_folder>"

   Specify <local_folder> as the path to the folder where the bucket is mounted.

Automatic mounting

Linux

1. Check the list of mounts:

   systemctl list-units --type=mount

2. In the line for the required mount, copy the value from the UNIT column.

3. Disable automatic mounting:

   sudo systemctl disable mnt-<folder_name>.mount

   Specify <folder_name> as the name of the folder where the bucket was mounted.

4. Ensure that the bucket is unmounted:

   df -hT

Windows

1. Open PowerShell.

2. Remove the service for automatic bucket mounting:

   schtasks /Delete /TN "<task_name>" /F

   Specify <task_name> as the name of the task in Windows services that triggers bucket mounting upon system startup.

3. Restart the device.

4. Ensure that the bucket is no longer mounted automatically.

macOS

1. Open Terminal.

2. Check the mount point:

   mount | grep geesefs

3. Copy the mount point address.

4. Force unmount the bucket:

   diskutil unmount force "<folder_path>"

   Specify <folder_path> as the path to the folder.

5. Stop the mounting agent and remove the configuration:

   launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/<agent_name>.plist"
   rm "$HOME/Library/LaunchAgents/<agent_name>.plist"

   Specify <agent_name> as the name of the auto-start agent file.

6. Ensure that the mounted bucket no longer appears as a disk in Finder.