---
title: "GeeseFS"
sidebar_label: "GeeseFS"
sidebar_position: 9
description: "How to configure GeeseFS and mount a bucket to a device"
---

import Formbricks from '@theme/MDXComponents/Formbricks'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import {TabItemLabel} from 'docs-kit/components'
import GrantAccess from '@site/i18n/en/docusaurus-plugin-content-docs/current/_partials/s3/grant-access.mdx'

# GeeseFS

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

## Configure GeeseFS \{#configure-geesefs}

1. [Configure S3 access](#configure-s3-access).
2. [Install the client](#install-client).
3. [Create a configuration](#create-configuration).

### 1. Configure access to S3 \{#configure-s3-access}

<GrantAccess />

### 2. Install the client \{#install-client}

<Tabs queryString="install-client">
  <TabItem value="linux" default>
    <TabItemLabel>
      Linux
    </TabItemLabel>

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

       ```bash
       apt list --installed | grep fuse
       ```

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

       ```bash
       sudo apt-get install fuse
       ```

    3. 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
       ```
  </TabItem>

  <TabItem value="windows">
    <TabItemLabel>
      Windows
    </TabItemLabel>

    1. If you do not have [WinFSP](https://github.com/winfsp/winfsp) installed, download and install it.

    2. Download the [geesefs-win-x64.exe](https://github.com/yandex-cloud/geesefs/releases/latest/download/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.
  </TabItem>

  <TabItem value="macos">
    <TabItemLabel>
      macOS
    </TabItemLabel>

    1. Prepare and install the macFUSE package:

       1.1. Installing macFUSE requires changing macOS security settings; use the [Getting Started](https://github.com/macfuse/macfuse/wiki/Getting-Started#enabling-support-for-third-party-kernel-extensions-apple-silicon-macs) guide on GitHub.

       1.2. Install the [macFUSE](https://osxfuse.github.io/) package.

    2. Open Terminal.

    3. 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
       ```
  </TabItem>
</Tabs>

### 3. Create a configuration \{#create-configuration}

<Tabs queryString="create-configuration">
  <TabItem value="linux" default>
    <TabItemLabel>
      Linux
    </TabItemLabel>

    1. Open the CLI.

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

       ```bash
       mkdir ~/.aws
       ```

    3. Create a `credentials` file:

       ```bash
       nano ~/.aws/credentials
       ```

    4. Add the S3 key:

       ```bash
       [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](#configure-s3-access);
       * `<secret_key>` — the value of the **Secret key** field from the S3 key.

    5. Press **Ctrl + X** → **Y** → **Enter**.
  </TabItem>

  <TabItem value="windows">
    <TabItemLabel>
      Windows
    </TabItemLabel>

    1. Open PowerShell.

    2. Create a `credentials` file:

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

    3. Add the S3 key:

       ```bash
       [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](#configure-s3-access);
       * `<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:

       ```bash
       Rename-Item "$env:USERPROFILE\.aws\credentials.txt"
                   "$env:USERPROFILE\.aws\credentials" -Force`
       ```
  </TabItem>

  <TabItem value="macos">
    <TabItemLabel>
      macOS
    </TabItemLabel>

    1. Open Terminal.

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

       ```bash
       mkdir ~/.aws
       ```

    3. Create a `credentials` file:

       ```bash
       cat ~/.aws/credentials
       ```

    4. Add the S3 key:

       ```bash
       [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](#configure-s3-access);
       * `<secret_key>` — the value of the **Secret key** field from the S3 key.

    5. Press **Control + X** → **Y** → **Enter**.
  </TabItem>
</Tabs>

## Mount the bucket \{#mount-bucket}

<Tabs queryString="mount-bucket">
  <TabItem value="one-time-mount" default>
    <TabItemLabel>
      One-time mounting
    </TabItemLabel>

    <Tabs queryString="os-one-time-mount">
      <TabItem value="linux" default>
        <TabItemLabel>
          Linux
        </TabItemLabel>

        1. Create a folder for mounting:

           ```bash
           mkdir /mnt/<folder_name>
           ```

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

        2. Mount the bucket:

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

           Specify:

           * `<s3_domain>` — the [S3 API domain](/s3/manage/domains.mdx#s3-api-domains) depending on the pool where the bucket is located;
           * `<pool>` — the [pool](/infrastructure/locations.mdx#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:

           ```bash
           df -hT /mnt/<folder_name>
           ```

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

      <TabItem value="windows">
        <TabItemLabel>
          Windows
        </TabItemLabel>

        1. Open PowerShell.
        2. Mount the bucket:

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

           Specify:

           * `<s3_domain>` — the [S3 API domain](/s3/manage/domains.mdx#s3-api-domains) depending on the pool where the bucket is located;
           * `<pool>` — the [pool](/infrastructure/locations.mdx#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"`.
      </TabItem>

      <TabItem value="macos">
        <TabItemLabel>
          macOS
        </TabItemLabel>

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

        1. Open Finder or Terminal.

        2. Create a folder for mounting:

           ```bash
           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:

           ```bash
           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](/s3/manage/domains.mdx#s3-api-domains) depending on the pool where the bucket is located;
           * `<pool>` — the [pool](/infrastructure/locations.mdx#pool) where the bucket is located;
           * `<profile_name>` — the profile name, default is `default`.

           Upon successful mounting, you will receive the following response:

           ```bash
           main.INFO File system has been successfully mounted
           ```

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

           ```bash
           sed -i '' '/^[[:space:]]*ca_bundle[[:space:]]*=/d' ~/.aws/config
           ```
      </TabItem>
    </Tabs>
  </TabItem>

  <TabItem value="auto-mount">
    <TabItemLabel>
      Automatic mounting
    </TabItemLabel>

    <Tabs queryString="os-auto-mount">
      <TabItem value="linux">
        <TabItemLabel>
          Linux
        </TabItemLabel>

        1. Open the `/etc/fstab` file:

           ```bash
           sudo nano /etc/fstab
           ```

        2. Add a command for automatic bucket mounting:

           ```bash
           <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](/s3/manage/domains.mdx#s3-api-domains) depending on the pool where the bucket is located;
           * `<pool>` — the [pool](/infrastructure/locations.mdx#pool) where the bucket is located;
           * `<profile_name>` — the profile name, default is `default`;

        3. Apply the settings:

           ```bash
           sudo systemctl daemon-reload
           ```

        4. Ensure that the bucket is mounted:

           ```bash
           sudo mount -a
           df -hT
           ```
      </TabItem>

      <TabItem value="windows">
        <TabItemLabel>
          Windows
        </TabItemLabel>

        1. Open PowerShell.

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

           ```bash
           $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](/s3/manage/domains.mdx#s3-api-domains) depending on the pool where the bucket is located;
           * `<pool>` — the [pool](/infrastructure/locations.mdx#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:

           ```bash
           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.
      </TabItem>

      <TabItem value="macos">
        <TabItemLabel>
          macOS
        </TabItemLabel>

        1. Open Finder or Terminal.

        2. Create a folder for mounting:

           ```bash
           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:

           ```bash
           which geesefs
           ```

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

           ```bash
           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](/s3/manage/domains.mdx#s3-api-domains) depending on the pool where the bucket is located;
           * `<pool>` — the [pool](/infrastructure/locations.mdx#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:

           ```bash
           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:

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

           Specify `<local_folder>` as the path to the folder you created in step 2.
      </TabItem>
    </Tabs>
  </TabItem>
</Tabs>

## Unmount the bucket \{#unmount-bucket}

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

<Tabs queryString="unmount-bucket">
  <TabItem value="one-time" default>
    <TabItemLabel>
      One-time mounting
    </TabItemLabel>

    <Tabs queryString="os">
      <TabItem value="linux" default>
        <TabItemLabel>
          Linux
        </TabItemLabel>

        Unmount the bucket:

        ```bash
        sudo umount /mnt/<local_folder>
        ```

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

      <TabItem value="windows">
        <TabItemLabel>
          Windows
        </TabItemLabel>

        1. Open PowerShell.
        2. Press **Ctrl + C**.
        3. Ensure that the command line returns a response:

           ```bash
           main.INFO Flushing all changes
           main.INFO Successfully exiting
           ```
      </TabItem>

      <TabItem value="macos">
        <TabItemLabel>
          macOS
        </TabItemLabel>

        1. Open Terminal.
        2. Unmount the bucket:

           ```bash
           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.
      </TabItem>
    </Tabs>
  </TabItem>

  <TabItem value="auto-mount">
    <TabItemLabel>
      Automatic mounting
    </TabItemLabel>

    <Tabs queryString="os">
      <TabItem value="linux" default>
        <TabItemLabel>
          Linux
        </TabItemLabel>

        1. Check the list of mounts:

           ```bash
           systemctl list-units --type=mount
           ```

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

        3. Disable automatic mounting:

           ```bash
           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:

           ```bash
           df -hT
           ```
      </TabItem>

      <TabItem value="windows">
        <TabItemLabel>
          Windows
        </TabItemLabel>

        1. Open PowerShell.

        2. Remove the service for automatic bucket mounting:

           ```bash
           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.
      </TabItem>

      <TabItem value="macos">
        <TabItemLabel>
          macOS
        </TabItemLabel>

        1. Open Terminal.

        2. Check the mount point:

           ```bash
           mount | grep geesefs
           ```

        3. Copy the mount point address.

        4. Force unmount the bucket:

           ```bash
           diskutil unmount force "<folder_path>"
           ```

           Specify `<folder_path>` as the path to the folder.

        5. Stop the mounting agent and remove the configuration:

           ```bash
           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.
      </TabItem>
    </Tabs>
  </TabItem>
</Tabs>

<Formbricks />