GeeseFS

Last update: October 05 2026Open in Markdown

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

Configure GeeseFS

1. Configure S3 access.
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 access to S3. If you use a service user with the s3.user, object_storage_user or s3.bucket.user role, the bucket must have a configured access policy 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 the 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, 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 changes to macOS security settings; follow the Getting Started instructions 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 the 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> — value of the Access key field from the S3 key;
   • <secret_key> — value of the Secret key field from the S3 key.

5. Press Ctrl + X → Y → Enter.

Windows

1. Open PowerShell.

2. Create the 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> — value of the Access key field from the S3 key;
   • <secret_key> — value of the Secret key field from the S3 key.

4. Click File → Save

5. If the file is saved with the .txt extension, remove the extension:

   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 the 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> — value of the Access key field from the S3 key;
   • <secret_key> — 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> — 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> — S3 API domain depending on the pool where the bucket is located;
   • <pool> — pool where the bucket is located;
   • <bucket_name> — name of the bucket to mount;
   • <profile_name> — profile name, default is default;
   • <folder_name> — name of the folder you created in step 1.

3. Ensure that the bucket is mounted:

   df -hT /mnt/<folder_name>

   Specify <folder_name> — the name of the folder 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> — S3 API domain depending on the pool where the bucket is located;

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

   • <bucket_name> — name of the bucket to mount;

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

     • as a drive — use a value like S:;
     • as a folder — use the path to the folder in quotation marks, 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> – 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> — name of the external drive in Finder that the mounted bucket will be displayed as;
   • <bucket_name> — name of the bucket to mount;
   • <local_folder> — path to the folder you created in step 2;
   • <s3_domain> — S3 API domain depending on the pool where the bucket is located;
   • <pool> — pool where the bucket is located;
   • <profile_name> — 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> — name of the bucket to mount;
   • <folder_name> — name of the folder where the bucket will be mounted;
   • <s3_domain> — S3 API domain depending on the pool where the bucket is located;
   • <pool> — pool where the bucket is located;
   • <profile_name> — 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> — name of the folder in the profile where the .cmd file and logs will be stored;

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

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

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

   • <bucket_name> — name of the bucket to mount;

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

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

   • <task_name> — name for the task in the Windows service that will mount the bucket on system startup.

3. Ensure that the bucket is mounted:

   schtasks /Run /TN "<task_name>"

   Specify <task_name> — the name of the task in the Windows service that mounts the bucket on 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> – 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> — file name for the startup agent;
   • <geesefs_path> — path to GeeseFS you copied in step 4;
   • <volume_name> — name of the mounted bucket that will be displayed in Finder as an external drive. It can match <local_folder> or be different;
   • <s3_domain> — S3 API domain depending on the pool where the bucket is located;
   • <pool> — pool where the bucket is located;
   • <local_folder> — path to the folder you created in step 2;
   • <profile_name> — AWS profile name, default is default;
   • <bucket_name> — name of the bucket to mount to the device;
   • <username> — macOS 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> — the name of the file with the startup agent 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> — 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> — 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> — 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 row of the required mount, copy the value of the UNIT column.

3. Disable automatic mounting:

   sudo systemctl disable mnt-<folder_name>.mount

   Specify <folder_name> — 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> — the name of the task in the Windows service that mounts the bucket on 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> – 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> — the name of the file with the startup agent.

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