GeeseFS

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

Настроить GeeseFS

Настроить доступ.
Установить клиент.
Создать конфигурацию.

1. Настроить доступ к S3

Настроить доступ может Владелец аккаунта или пользователь с ролью iam_admin.

Создайте сервисного пользователя с ролью с доступом в S3. Если вы используете сервисного пользователя с ролью object_storage_user или s3.bucket.user, в бакете должна быть настроена политика доступа.
Выдайте пользователю S3-ключ.

2. Установить клиент

Linux
Windows
macOS

Убедитесь, что утилиты для работы с FUSE установлены по умолчанию:
```
apt list --installed | grep fuse
```
Если утилиты не установлены, установите их:
```
sudo apt-get install fuse
```

Скачайте и установите 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

Если у вас не установлен WinFSP, скачайте и установите его.
Скачайте файл geesefs-win-x64.exe, но не устанавливайте его.
Опционально: для удобства переименуйте файл в geesefs.exe.
Создайте папку geesefs.
Перенесите файл geesefs.exe в папку geesefs.
Добавьте папку geesefs в переменную PATH:

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

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

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

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

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

6.6. Нажмите ОК → ОК.
Чтобы настройки переменных сред применились, перезагрузите устройство.

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

1.1. Установка macFUSE требует вмешательства в настройки безопасности macOS, для этого используйте инструкцию Getting Started на Github.

1.2. Установите пакет macFUSE.
Откройте Terminal.

Установите 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. Создать конфигурацию

Linux
Windows
macOS

Откройте CLI.
Создайте директорию, в которой будет хранится файл с S3-ключом:
```
mkdir ~/.aws
```
Создайте файл credentials:
```
nano ~/.aws/credentials
```
Добавьте S3-ключ:
```
[default]
aws_access_key_id = <access_key>
aws_secret_access_key = <secret_key>
```
Укажите:
- <access_key> — значение поля Access key из S3-ключа;
- <secret_key> — значение поля Secret key из S3-ключа.
Нажмите Ctrl + X → Y → Enter.

Откройте PowerShell.

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

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

Добавьте S3-ключ:
```
[default]
aws_access_key_id = <access_key>
aws_secret_access_key = <secret_key>
```
Укажите:
- <access_key> — значение поля Access key из S3-ключа;
- <secret_key> — значение поля Secret key из S3-ключа.
Нажмите Файл → Сохранить

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

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

Откройте Terminal.
Создайте директорию, в которой будет хранится файл с S3-ключом:
```
mkdir ~/.aws
```
Создайте файл credentials:
```
cat ~/.aws/credentials
```
Добавьте S3-ключ:
```
[default]
aws_access_key_id = <access_key>
aws_secret_access_key = <secret_key>
```
Укажите:
- <access_key> — значение поля Access key из S3-ключа;
- <secret_key> — значение поля Secret key из S3-ключа.
Нажмите Control + X → Y → Enter.

Монтировать бакет

Разовое монтирование
Автоматическое монтирование

Linux
Windows
macOS

Создайте папку для монтирования:
```
mkdir /mnt/<folder_name>
```
Укажите <folder_name> — имя папки, к которой будет примонтирован бакет.
Монтируйте бакет:
```
sudo geesefs
--endpoint https://<s3_domain>
--region <pool>
--profile <profile_name>
<bucket_name> /mnt/<folder_name>
```
Укажите:
- <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;
- <pool> — пул, в котором находится бакет;
- <bucket_name> — имя бакета, который будет монтирован;
- <profile_name> — имя профиля, по умолчанию default;
- <folder_name> — имя папки, которую вы создали на шаге 1.
Убедитесь, что бакет монтирован:
```
df -hT /mnt/<folder_name>
```
Укажите <folder_name> — имя папки, которую вы создали на шаге 1.

Откройте PowerShell.
Монтируйте бакет:
```
geesefs --endpoint <s3_domain> --region <pool>
<bucket_name> <destination>
```
Укажите:
- <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;
- <pool> — пул, в котором находится бакет;
- <bucket_name> — имя бакета, который будет монтирован;
- <destination> — имя нового диска или путь до папки в Windows, куда будет монтирован бакет. Чтобы монтировать бакет:
  - как диск — используйте значение вида S:;
  - как папку — используйте путь до папки в кавычках, например "C:\Data\GeeseFS".

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

Откройте Finder или Terminal.
Создайте папку для монтирования:
```
mkdir -p "<local_folder>"
```
Укажите <local_folder> — путь до папки.
Скопируйте и сохраните путь к папке.
Монтируйте бакет:
```
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 в зависимости от пула, в котором находится бакет;
- <pool> — пул, в котором находится бакет;
- <profile_name> — имя профиля, по умолчанию default.
При успешном монтировании вернется ответ:
```
main.INFO File system has been successfully mounted
```
Если у вас возник конфликт из-за сертификата, удалите его:
```
sed -i '' '/^[[:space:]]*ca_bundle[[:space:]]*=/d' ~/.aws/config
```

Linux
Windows
macOS

Откройте файл /etc/fstab:
```
sudo nano /etc/fstab
```
Добавьте команду для автоматического монтирования бакета:
```
<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 в зависимости от пула, в котором находится бакет;
- <pool> — пул, в котором находится бакет;
- <profile_name> — имя профиля, по умолчанию default;
Примените настройки:
```
sudo systemctl daemon-reload
```
Убедитесь, что бакет примонтирован:
```
sudo mount -a
df -hT
```

Откройте PowerShell.
Создайте службу Windows, которая будет запускаться вместе с ОС:
```
$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 в зависимости от пула, в котором находится бакет;
- <pool> — пул, в котором находится бакет;
- <bucket_name> — имя бакета, который будет монтирован;
- <destination> — имя нового диска или путь до папки в Windows, куда будет монтирован бакет. Чтобы монтировать бакет:
  - как диск — используйте значение вида S:;
  - как папку — используйте путь до папки в кавычках, например "C:\Data\GeeseFS";
- <task_name> — имя для задачи в службе Windows, которая будет запускать монтирование бакета при запуске системы.
Убедитесь, что бакет монтирован:
```
schtasks /Run /TN "<task_name>"
```
Укажите <task_name> — имя задачи в службе Windows, которая запускает монтирование бакета при запуске системы.
Перезагрузите устройство.

Откройте Finder или Terminal.
Создайте папку для монтирования:
```
mkdir -p "<local_folder>"
```
Укажите <local_folder> — путь до папки.
Скопируйте и сохраните путь к папке.
Скопируйте путь к GeeseFS:
```
which geesefs
```

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

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 в зависимости от пула, в котором находится бакет;
<pool> — пул, в котором находится бакет;
<local_folder> — путь до папки, которую вы создали на шаге 2;
<profile_name> — имя профиля AWS, по умолчанию default;
<bucket_name> — имя бакета, который будет монтирован к устройству;
<username> — имя пользователя в системе macOS.

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

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;

Убедитесь, что бакет монтирован:
```
mount | grep geesefs || echo "Пока не смонтировано"
open "<local_folder>"
```
Укажите <local_folder> — путь до папки, которую вы создали на шаге 2.

Отмонтировать бакет

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

Разовое монтирование
Автоматическое монтирование

Linux
Windows
macOS

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

sudo umount /mnt/<local_folder>

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

Откройте PowerShell.
Нажмите Ctrl + C.
Убедитесь, что в командой строке появился ответ:
```
main.INFO Flushing all changes
main.INFO Successfully exiting
```

Откройте Terminal.
Отмонтируйте бакет:
```
umount "<local_folder>" 2>/dev/null || diskutil unmount force "<local_folder>"
```
Укажите <local_folder> — путь до папки, к которой монтирован бакет.

Linux
Windows
macOS

Проверьте список монтирований:
```
systemctl list-units --type=mount
```
В строке нужного монтирования скопируйте значение столбца UNIT.
Отключите автоматическое монтирование:
```
sudo systemctl disable mnt-<folder_name>.mount
```
Укажите <folder_name> — имя папки, к которой был примонтирован бакет.
Убедитесь, что бакет отмонтирован:
```
df -hT
```

Откройте PowerShell.
Удалите службу с автоматическим монтированием бакета:
```
schtasks /Delete /TN "<task_name>" /F
```
Укажите <task_name> — имя задачи в службе Windows, которая запускает монтирование бакета при запуске системы.
Перезагрузите устройство.
Убедитесь, что бакет больше не монтируется автоматически.

Откройте Terminal.
Проверьте точку монтирования:
```
mount | grep geesefs
```
Скопируйте адрес точки монтирования.
Принудительно отмонтируйте бакет:
```
diskutil unmount force "<folder_path>"
```
Укажите <folder_path> — путь до папки.
Остановите агент монтирования и удалите конфигурацию:
```
launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/<agent_name>.plist"
rm "$HOME/Library/LaunchAgents/<agent_name>.plist"
```
Укажите <agent_name> — имя файла с агентом автозапуска.
Убедитесь, что в Finder смонтированный бакет не отображается как диск.