---
title: 'GeeseFS'
sidebar_label: 'GeeseFS'
sidebar_position: 9
description: 'Как настроить GeeseFS и монтировать бакет на устройство'
---

import Formbricks from '@theme/MDXComponents/Formbricks'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import {TabItemLabel} from '@selectel/docux/components'
import GrantAccess from '@site/docs/_partials/s3/grant-access.mdx'

# GeeseFS

GeeseFS — это программа, с помощью которой можно примонтировать бакет на устройство или сервер и работать с ним как с обычной папкой.
GeeseFS подходит для работы с большим количеством объектов, объем которых до 1 МБ у каждого.
С GeeseFS можно работать на Linux, Windows и macOS.

## Настроить GeeseFS \{#configure-geesefs}

1. [Настройте доступ к S3](#configure-s3-access).
2. [Установите клиент](#install-client).
3. [Создайте конфигурацию](#create-configuration).

### 1. Настроить доступ к S3 \{#configure-s3-access}

<GrantAccess />

### 2. Установить клиент \{#install-client}

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

    1. Убедитесь, что утилиты для работы с FUSE установлены по умолчанию:

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

    2. Если утилиты не установлены, установите их:

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

    3. Скачайте и установите 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. Если у вас не установлен [WinFSP](https://github.com/winfsp/winfsp), скачайте и установите его.

    2. Скачайте файл [geesefs-win-x64.exe](https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-win-x64.exe), но не устанавливайте его.

    3. Опционально: для удобства переименуйте файл в `geesefs.exe`.

    4. Создайте папку `geesefs`.

    5. Перенесите файл `geesefs.exe` в папку `geesefs`.

    6. Добавьте папку `geesefs` в переменную `PATH`:

       6.1. В поиске Windows введите **Изменение системных переменных среды**.

       6.2. Нажмите **Переменные среды**.

       6.3. Выберите параметр `PATH`.

       6.4. Нажмите **Изменить** → **Создать**.

       6.5. Добавьте путь к папке в список.

       6.6. Нажмите **ОК** → **ОК**.

    7. Чтобы настройки переменных сред применились, перезагрузите устройство.
  </TabItem>

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

    1. Подготовьте и установите пакет macFUSE:

       1.1. Установка macFUSE требует вмешательства в настройки безопасности macOS, для этого используйте инструкцию [Getting Started](https://github.com/macfuse/macfuse/wiki/Getting-Started#enabling-support-for-third-party-kernel-extensions-apple-silicon-macs) на Github.

       1.2. Установите пакет [macFUSE](https://osxfuse.github.io/).

    2. Откройте Terminal.

    3. Установите 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-configuration}

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

    1. Откройте CLI.

    2. Создайте директорию, в которой будет хранится файл с S3-ключом:

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

    3. Создайте файл `credentials`:

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

    4. Добавьте S3-ключ:

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

       Укажите:

       * `<access_key>` — значение поля **Access key** из [S3-ключа](#configure-s3-access);
       * `<secret_key>` — значение поля **Secret key** из S3-ключа.

    5. Нажмите **Ctrl + X** → **Y** → **Enter**.
  </TabItem>

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

    1. Откройте PowerShell.

    2. Создайте файл `credentials`:

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

    3. Добавьте S3-ключ:

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

       Укажите:

       * `<access_key>` — значение поля **Access key** из [S3-ключа](#configure-s3-access);
       * `<secret_key>` — значение поля **Secret key** из S3-ключа.

    4. Нажмите **Файл** → **Сохранить**

    5. Если файл сохранился с расширением `.txt`, удалите расширение:

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

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

    1. Откройте Terminal.

    2. Создайте директорию, в которой будет хранится файл с S3-ключом:

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

    3. Создайте файл `credentials`:

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

    4. Добавьте S3-ключ:

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

       Укажите:

       * `<access_key>` — значение поля **Access key** из [S3-ключа](#configure-s3-access);
       * `<secret_key>` — значение поля **Secret key** из S3-ключа.

    5. Нажмите **Control + X** → **Y** → **Enter**.
  </TabItem>
</Tabs>

## Монтировать бакет \{#mount-bucket}

<Tabs queryString="mount-bucket">
  <TabItem value="one-time-mount" default>
    <TabItemLabel>
      Разовое монтирование
    </TabItemLabel>

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

        1. Создайте папку для монтирования:

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

           Укажите `<folder_name>` — имя папки, к которой будет примонтирован бакет.

        2. Монтируйте бакет:

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

           Укажите:

           * `<s3_domain>` — [домен S3 API](/s3/manage/domains.mdx#s3-api-domains) в зависимости от пула, в котором находится бакет;
           * `<pool>` — [пул](/infrastructure/locations.mdx#pool), в котором находится бакет;
           * `<bucket_name>` — имя бакета, который будет монтирован;
           * `<profile_name>` — имя профиля, по умолчанию `default`;
           * `<folder_name>` — имя папки, которую вы создали на шаге 1.

        3. Убедитесь, что бакет монтирован:

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

           Укажите `<folder_name>` — имя папки, которую вы создали на шаге 1.
      </TabItem>

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

        1. Откройте PowerShell.
        2. Монтируйте бакет:

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

           Укажите:

           * `<s3_domain>` — [домен S3 API](/s3/manage/domains.mdx#s3-api-domains) в зависимости от пула, в котором находится бакет;
           * `<pool>` — [пул](/infrastructure/locations.mdx#pool), в котором находится бакет;
           * `<bucket_name>` — имя бакета, который будет монтирован;
           * `<destination>` — имя нового диска или путь до папки в Windows, куда будет монтирован бакет. Чтобы монтировать бакет:

             * как диск — используйте значение вида `S:`;
             * как папку — используйте путь до папки в кавычках, например `"C:\Data\GeeseFS"`.
      </TabItem>

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

        После монтирования папка будет подключена в Finder как внешний диск.

        1. Откройте Finder или Terminal.

        2. Создайте папку для монтирования:

           ```bash
           mkdir -p "<local_folder>"
           ```

           Укажите `<local_folder>` – путь до папки.

        3. Скопируйте и сохраните путь к папке.

        4. Монтируйте бакет:

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

           Укажите:

           * `<volume_name>` — имя внешнего диска в Finder, в качестве которого будет отображаться монтированный бакет;
           * `<bucket_name>` — имя бакета, который будет монтирован;
           * `<local_folder>` — путь до папки, которую вы создали на шаге 2;
           * `<s3_domain>` — [домен S3 API](/s3/manage/domains.mdx#s3-api-domains) в зависимости от пула, в котором находится бакет;
           * `<pool>` — [пул](/infrastructure/locations.mdx#pool), в котором находится бакет;
           * `<profile_name>` — имя профиля, по умолчанию `default`.

           При успешном монтировании вернется ответ:

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

        5. Если у вас возник конфликт из-за сертификата, удалите его:

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

  <TabItem value="auto-mount">
    <TabItemLabel>
      Автоматическое монтирование
    </TabItemLabel>

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

        1. Откройте файл `/etc/fstab`:

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

        2. Добавьте команду для автоматического монтирования бакета:

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

           Укажите:

           * `<bucket_name>` — имя бакета, который будет монтирован;
           * `<folder_name>` — имя папки, к которой будет монтирован бакет;
           * `<s3_domain>` — [домен S3 API](/s3/manage/domains.mdx#s3-api-domains) в зависимости от пула, в котором находится бакет;
           * `<pool>` — [пул](/infrastructure/locations.mdx#pool), в котором находится бакет;
           * `<profile_name>` — имя профиля, по умолчанию `default`;

        3. Примените настройки:

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

        4. Убедитесь, что бакет примонтирован:

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

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

        1. Откройте PowerShell.

        2. Создайте службу Windows, которая будет запускаться вместе с ОС:

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

           Укажите:

           * `<folder_name>` — имя папки в профиле, где будут храниться `.cmd` и логи;
           * `<task_name>` — имя задачи, которая будет монтировать бакет;
           * `<s3_domain>` — [домен S3 API](/s3/manage/domains.mdx#s3-api-domains) в зависимости от пула, в котором находится бакет;
           * `<pool>` — [пул](/infrastructure/locations.mdx#pool), в котором находится бакет;
           * `<bucket_name>` — имя бакета, который будет монтирован;
           * `<destination>` — имя нового диска или путь до папки в Windows, куда будет монтирован бакет. Чтобы монтировать бакет:

             * как диск — используйте значение вида `S:`;
             * как папку — используйте путь до папки в кавычках, например "`C:\Data\GeeseFS"`;
           * `<task_name>` — имя для задачи в службе Windows, которая будет запускать монтирование бакета при запуске системы.

        3. Убедитесь, что бакет монтирован:

           ```bash
           schtasks /Run /TN "<task_name>"
           ```

           Укажите `<task_name>` — имя задачи в службе Windows, которая запускает монтирование бакета при запуске системы.

        4. Перезагрузите устройство.
      </TabItem>

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

        1. Откройте Finder или Terminal.

        2. Создайте папку для монтирования:

           ```bash
           mkdir -p "<local_folder>"
           ```

           Укажите `<local_folder>` – путь до папки.

        3. Скопируйте и сохраните путь к папке.

        4. Скопируйте путь к GeeseFS:

           ```bash
           which geesefs
           ```

        5. Создайте файл конфигурации агента автозапуска:

           ```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"
           ```

           Укажите:

           * `<agent_name>` — имя файла для агента автозапуска;
           * `<geesefs_path>` — путь к GeeseFS, который вы скопировали на шаге 4;
           * `<volume_name>` — имя смонтированного бакета, который будет отображаться в Finder как внешний диск. Может совпадать с `<local_folder>` или отличаться;
           * `<s3_domain>` — [домен S3 API](/s3/manage/domains.mdx#s3-api-domains) в зависимости от пула, в котором находится бакет;
           * `<pool>` — [пул](/infrastructure/locations.mdx#pool), в котором находится бакет;
           * `<local_folder>` — путь до папки, которую вы создали на шаге 2;
           * `<profile_name>` — имя профиля AWS, по умолчанию `default`;
           * `<bucket_name>` — имя бакета, который будет монтирован к устройству;
           * `<username>` — имя пользователя в системе macOS.

        6. Запустите агент:

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

           Укажите `<agent_name>` — имя файла с агентом автозапуска, который вы создали на шаге 5;

        7. Убедитесь, что бакет монтирован:

           ```bash
           mount | grep geesefs || echo "Пока не смонтировано"
           open "<local_folder>"
           ```

           Укажите `<local_folder>` — путь до папки, которую вы создали на шаге 2.
      </TabItem>
    </Tabs>
  </TabItem>
</Tabs>

## Отмонтировать бакет \{#unmount-bucket}

Способ отмонтирования зависит от того, как был монтирован бакет — разово или автоматически.

<Tabs queryString="unmount-bucket">
  <TabItem value="one-time" default>
    <TabItemLabel>
      Разовое монтирование
    </TabItemLabel>

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

        Отмонтируйте бакет:

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

        Укажите `<local_folder>` — путь до папки, к которой монтирован бакет.
      </TabItem>

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

        1. Откройте PowerShell.
        2. Нажмите **Ctrl + C**.
        3. Убедитесь, что в командой строке появился ответ:

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

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

        1. Откройте Terminal.
        2. Отмонтируйте бакет:

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

           Укажите `<local_folder>` — путь до папки, к которой монтирован бакет.
      </TabItem>
    </Tabs>
  </TabItem>

  <TabItem value="auto-mount">
    <TabItemLabel>
      Автоматическое монтирование
    </TabItemLabel>

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

        1. Проверьте список монтирований:

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

        2. В строке нужного монтирования скопируйте значение столбца `UNIT`.

        3. Отключите автоматическое монтирование:

           ```bash
           sudo systemctl disable mnt-<folder_name>.mount
           ```

           Укажите `<folder_name>` — имя папки, к которой был примонтирован бакет.

        4. Убедитесь, что бакет отмонтирован:

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

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

        1. Откройте PowerShell.

        2. Удалите службу с автоматическим монтированием бакета:

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

           Укажите `<task_name>` — имя задачи в службе Windows, которая запускает монтирование бакета при запуске системы.

        3. Перезагрузите устройство.

        4. Убедитесь, что бакет больше не монтируется автоматически.
      </TabItem>

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

        1. Откройте Terminal.

        2. Проверьте точку монтирования:

           ```bash
           mount | grep geesefs
           ```

        3. Скопируйте адрес точки монтирования.

        4. Принудительно отмонтируйте бакет:

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

           Укажите `<folder_path>` – путь до папки.

        5. Остановите агент монтирования и удалите конфигурацию:

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

           Укажите `<agent_name>` — имя файла с агентом автозапуска.

        6. Убедитесь, что в Finder смонтированный бакет не отображается как диск.
      </TabItem>
    </Tabs>
  </TabItem>
</Tabs>

<Formbricks />