[Yandex Cloud documentation](../../index.md) > [Yandex Object Storage](../index.md) > [Tutorials](index.md) > Backups > Backing up to Object Storage with GeeseFS # Backing up to Object Storage with GeeseFS In this tutorial, you will configure backup of local files to [Yandex Object Storage](../index.md) with [GeeseFS](../tools/geesefs.md). GeeseFS enables mounting a [bucket](../concepts/bucket.md) as a regular folder, so you can use familiar tools for copying and synchronization. Backup essentially involves copying and synchronizing data between the local folder and the bucket as if these are two directories, one hosted in the cloud. The process is optimized with synchronization tools, e.g., `rsync` or `robocopy`, which move only new and updated files. To configure backup using GeeseFS: 1. [Get your cloud ready](#before-begin). 1. [Create a bucket](#create-bucket). 1. [Create a service account](#create-sa). 1. [Create a static access key](#create-static-key). 1. [Set up your environment](#prepare-env). 1. [Mount your bucket](#mount-bucket). 1. [Synchronize the local folder with the bucket](#sync). If you no longer need the resources you created, [delete them](#clear-out). ## Getting started {#before-you-begin} Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md): 1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account. 1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it. If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud). [Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md). ### Required paid resources {#paid-resources} The bucket support cost includes the fee for bucket data storage and data operations (see [Yandex Object Storage pricing](../pricing.md)). ## Create a bucket {#create-bucket} {% note info %} To protect your backups from accidental file deletion, enable [S3 bucket versioning](../operations/buckets/versioning.md). This way, deleted or overwritten files will be saved as previous versions you can [restore](../operations/objects/restore-object-version.md) if needed. For more information about S3 bucket versioning, see [this guide](../concepts/versioning.md). Without versioning, you will not be able to restore files deleted from S3, even if previously copied. {% endnote %} {% list tabs group=instructions %} - Management console {#console} 1. In the [management console](https://console.yandex.cloud), navigate to the relevant folder. 1. Navigate to **Object Storage**. 1. Click **Create bucket**. 1. Enter a name for the bucket in line with the [naming requirements](../concepts/bucket.md#naming). 1. In the **Read objects**, **Read object list**, and **Read settings** fields, select `With authorization`. 1. Click **Create bucket**. - AWS CLI {#cli} 1. If you do not have the AWS CLI yet, [install and configure it](../tools/aws-cli.md). 1. Create a bucket by entering its name consistent with the [naming conventions](../concepts/bucket.md#naming): ```bash aws --endpoint-url=https://storage.yandexcloud.net \ s3 mb s3:// ``` Result: ```text make_bucket: backup-bucket ``` - API {#api} Use the [create](../api-ref/Bucket/create.md) REST API method for the [Bucket](../api-ref/Bucket/index.md) resource, the [BucketService/Create](../api-ref/grpc/Bucket/create.md) gRPC API call, or the [create](../s3/api-ref/bucket/create.md) S3 API method. {% endlist %} ## Create a service account {#create-sa} Create a [service account](../../iam/concepts/users/service-accounts.md) to be used for backups. {% list tabs group=instructions %} - Management console {#console} 1. In the [management console](https://console.yandex.cloud), select the relevant folder. 1. Navigate to **Identity and Access Management**. 1. Click **Create service account**. 1. In the **Name** field, specify `sa-backup-to-s3`. 1. Click ![image](../../_assets/console-icons/plus.svg) **Add role** and select [`storage.editor`](../security/index.md#storage-editor). 1. Click **Create**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id ` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions. 1. Create a service account: ```bash yc iam service-account create --name sa-backup-to-s3 \ --folder-name ``` Result: ```yaml id: ajeab0cnib1p******** folder_id: b0g12ga82bcv******** created_at: "2025-10-03T09:44:35.989446Z" name: sa-backup-to-s3 ``` 1. Assign the `storage.editor` [role](../security/index.md#storage-editor) for the folder to the service account: ```bash yc resource-manager folder add-access-binding \ --service-account-name sa-backup-to-s3 \ --role storage.editor \ --folder-name ``` Result: ```text effective_deltas: - action: ADD access_binding: role_id: storage.editor subject: id: ajeab0cnib1p******** type: serviceAccount ``` - API {#api} 1. Create a service account named `sa-backup-to-s3`. Do it by using the [create](../../iam/api-ref/ServiceAccount/create.md) REST API method for the [ServiceAccount](../../iam/api-ref/ServiceAccount/index.md) resource or the [ServiceAccountService/Create](../../iam/api-ref/grpc/ServiceAccount/create.md) gRPC API call. 1. Assign the `storage.editor` [role](../security/index.md#storage-editor) for the current folder to the the service account. Do it by using the [setAccessBindings](../../resource-manager/api-ref/Folder/setAccessBindings.md) REST API method for the [Folder](../../resource-manager/api-ref/Folder/index.md) resource or the [FolderService/SetAccessBindings](../../resource-manager/api-ref/grpc/Folder/setAccessBindings.md) gRPC API call. {% endlist %} {% note info %} To work with objects in an [encrypted](../concepts/encryption.md) bucket, a user or [service account](../../iam/concepts/users/service-accounts.md) must have the following [roles for the encryption key](../../kms/operations/key-access.md) in addition to the `storage.configurer` [role](../security/index.md#storage-configurer): * `kms.keys.encrypter`: To read the key, [encrypt](../../kms/security/index.md#kms-keys-encrypter) and upload objects. * `kms.keys.decrypter`: To read the key, [decrypt](../../kms/security/index.md#kms-keys-decrypter) and download objects. * `kms.keys.encrypterDecrypter`: This role includes the `kms.keys.encrypter` and `kms.keys.decrypter` [permissions](../../kms/security/index.md#kms-keys-encrypterDecrypter). For more information, see [Key Management Service service roles](../../kms/security/index.md#service-roles). {% endnote %} ## Create a static access key {#create-static-key} {% list tabs group=instructions %} - Management console {#console} 1. In the [management console](https://console.yandex.cloud), select the relevant folder. 1. Navigate to **Identity and Access Management**. 1. In the left-hand panel, select ![FaceRobot](../../_assets/console-icons/face-robot.svg) **Service accounts**. 1. Select the `sa-backup-to-s3` service account. 1. In the top panel, click ![image](../../_assets/console-icons/plus.svg) **Create new key** and select **Create static access key**. 1. Enter a description for the key and click **Create**. 1. Save the ID and secret key for later when you are mounting the bucket. {% note alert %} After you close this dialog, the key value will no longer be available. {% endnote %} - CLI {#cli} 1. Run this command: ```bash yc iam access-key create \ --service-account-name sa-backup-to-s3 ``` Where `--service-account-name` is the name of the service account you are creating the key for. Result: ```text access_key: id: aje726ab18go******** service_account_id: ajecikmc374i******** created_at: "2024-11-28T14:16:44.936656476Z" key_id: YCAJEOmgIxyYa54LY******** secret: YCMiEYFqczmjJQ2XCHMOenrp1s1-yva1******** ``` 1. Save the ID (`key_id`) and secret key (`secret`) for later when you are mounting the bucket. - API {#api} To create an access key, use the [create](../../iam/awscompatibility/api-ref/AccessKey/create.md) REST API method for the [AccessKey](../../iam/awscompatibility/api-ref/AccessKey/index.md) resource or the [AccessKeyService/Create](../../iam/awscompatibility/api-ref/grpc/AccessKey/create.md) gRPC API call. Save the ID (`key_id`) and secret key (`secret`) for later when you are mounting the bucket. {% endlist %} ## Set up your environment {#prepare-env} ### Install GeeseFS {#install-geesefs} {% list tabs group=operating_system %} - Debian/Ubuntu {#linux} 1. Make sure the FUSE utilities are installed in the distribution: ```bash apt list --installed | grep fuse ``` {% note warning %} Many Linux distributions have the utilities for working with FUSE pre-installed by default. Reinstalling or deleting them may lead to OS failures. {% endnote %} 1. If the FUSE utilities are not installed, run this command: ```bash sudo apt-get install fuse ``` 1. 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 ``` - CentOS {#centos} 1. Make sure the FUSE utilities are installed in the distribution: ```bash yum list installed | grep fuse ``` {% note warning %} Many Linux distributions have the utilities for working with FUSE pre-installed by default. Reinstalling or deleting them may lead to OS failures. {% endnote %} 1. If the FUSE utilities are not installed, run this command: ```bash sudo yum install fuse ``` 1. 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 ``` - macOS {#macos} 1. Install the [macFUSE](https://osxfuse.github.io/) package. 1. [Enable](https://github.com/macfuse/macfuse/wiki/Getting-Started#enabling-support-for-third-party-kernel-extensions-apple-silicon-macs) support for third-party core extensions. This step is only required the first time you use MacFUSE on an Apple Silicon Mac. 1. [Allow](https://github.com/macfuse/macfuse/wiki/Getting-Started#allow-the-macfuse-kernel-extension-to-load-apple-silicon-and-intel-macs) loading the MacFUSE core extension (Apple Silicon and Intel Mac). For more information on installing macFUSE, see [this installation guide](https://github.com/osxfuse/osxfuse/wiki/FAQ#2-installuninstall-questions) in the macFUSE GitHub repository. 1. Download and 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 ``` - Windows {#windows} 1. [Download](https://winfsp.dev/rel/) and install WinFSP. 1. [Download](https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-win-x64.exe) the `geesefs-win-x64.exe` file. 1. Rename `geesefs-win-x64.exe` to `geesefs.exe` for convenience. 1. Create a folder named `geesefs` and move the `geesefs.exe` file there. 1. Add `geesefs` to the `PATH` variable: 1. Click **Start** and type **Change system environment variables** in the Windows search bar. 1. Click **Environment Variables...** at the bottom right. 1. In the window that opens, find the `PATH` parameter and click **Edit**. 1. Add your folder path to the list. 1. Click **OK**. {% endlist %} You can also build GeeseFS yourself using its source code. For more information, see [this guide](https://github.com/yandex-cloud/geesefs#installation) in the GeeseFS repository on GitHub. ### Get authenticated in GeeseFS {#auth-geesefs} GeeseFS uses the static access key to Object Storage you [got earlier](#create-static-key). You can set it using one of the following methods: {% list tabs group=operating_system %} - Linux/macOS {#linux} * Using the `credentials` [file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html), which you need to put into the `~/.aws/` folder: 1. Create a directory: ```bash mkdir ~/.aws ``` 1. Create a file named `credentials` with the following contents: ```text [default] aws_access_key_id = aws_secret_access_key = ``` If the key file is located elsewhere, specify its path in the `--shared-config` parameter when mounting the bucket: ```bash geesefs \ --shared-config \ ``` The key file must have the same structure as `~/.aws/credentials`. * Using environment variables: ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= ``` {% note info %} You can run the `geesefs` command with superuser privileges (`sudo`). In this case, make sure to send information about the key either in the `--shared-config` parameter or using environment variables. {% endnote %} - Windows {#windows} * Using the `credentials` [file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html), which you need to put into the `users//.aws/` folder: ```text [default] aws_access_key_id = aws_secret_access_key = ``` If the key file is located elsewhere, specify its path in the `--shared-config` parameter when mounting the bucket: ```cmd geesefs ^ --shared-config ^ ``` The key file must have the same structure as `~/.aws/credentials`. Specify an existing folder as the mount point. * Using environment variables: ```cmd set AWS_ACCESS_KEY_ID= set AWS_SECRET_ACCESS_KEY= ``` {% endlist %} When using GeeseFS on a Compute Cloud VM that has a [linked service account](../../compute/operations/vm-connect/auth-inside-vm.md#link-sa-with-instance), you can enable simplified authentication that does not require a static access key. To do this, use the `--iam` parameter when mounting the bucket. ## Mount a bucket {#mount-bucket} Select the folder or disk where you want to mount the bucket. Make sure you have sufficient permissions to perform this operation. When mounting a bucket, you can also configure GeeseFS settings for system [performance](../tools/geesefs.md#performance) and object access permissions. To view the list of options and their descriptions, run `geesefs --help`. * For one-time bucket mounting: {% list tabs group=operating_system %} - Linux/macOS {#linux} 1. Create a folder for mounting: ```bash mkdir ``` 1. Mount the bucket: ```bash geesefs ``` Specify an existing folder as the mount point. - Windows {#windows} Mount the bucket: ```bash geesefs ``` As the mount point, specify the name of the new folder that will be created when you mount the bucket. You cannot specify the name of an existing folder. Result: ```text 2025/10/06 21:14:27.488504 main.INFO File system has been successfully mounted. The service geesefs has been started. ``` {% endlist %} * To automatically mount a bucket at system startup: {% list tabs group=operating_system %} - Linux {#linux} 1. Create a folder for automatic mounting: ```bash mkdir ``` 1. Open `/etc/fuse.conf`: ```bash sudo nano /etc/fuse.conf ``` 1. Add the following line to it: ```text user_allow_other ``` 1. Open `/etc/fstab`: ```bash sudo nano /etc/fstab ``` 1. Add the following line to the `/etc/fstab` file: ```text /home// fuse.geesefs _netdev,allow_other,--file-mode=0666,--dir-mode=0777,--shared-config=/home//.aws/credentials 0 0 ``` If you had created the `.aws/credentials` file for the `root` user, you do not need to specify the `--shared-config` parameter. {% note info %} For the bucket to be mounted correctly, provide the full absolute path to the mount point and to the key file without `~`, e.g., `/home/user/`. {% endnote %} 1. Reboot your PC and check that the bucket has been mounted to the specified folder. To disable automounting, remove the line with the bucket name from the `/etc/fstab` file. - macOS {#macos} 1. Create a folder for automatic mounting: ```bash mkdir ``` 1. Create a file named `com.geesefs.automount.plist` with the autorun agent configuration: ```bash nano /Users//Library/LaunchAgents/com.geesefs.automount.plist ``` 1. Set the agent configuration by specifying the name of the bucket and the absolute path to the mount point: ```xml Label com.geesefs.automount ProgramArguments /usr/local/bin/geesefs RunAtLoad KeepAlive NetworkState ``` {% note info %} Specify an existing empty folder as the mount point. For the bucket to be mounted correctly, provide the full absolute path to the mount point and to the key file without `~`, e.g., `/home/user/`. {% endnote %} 1. Enable the agent you created: ```bash launchctl load /Users//Library/LaunchAgents/com.geesefs.automount.plist ``` 1. Reboot your PC and check that the bucket has been mounted to the specified folder. To disable agent autorun, use this command: ```bash launchctl unload /Users//Library/LaunchAgents/com.geesefs.automount.plist ``` - Windows {#windows} Create a Windows service that will automatically run at system startup: 1. Run `CMD` as an administrator. 1. Run this command: ```cmd sc create ^ binPath="" ^ DisplayName= "" ^ type=own ^ start=auto ``` Where `binPath` is the path to the `geesefs.exe` file with the required mounting parameters. Here is an example: `C:\geesefs\geesefs.exe `. As the mount point, specify the name of the new folder that will be created when you mount the bucket. You cannot specify the name of an existing folder. Result: ```text [SC] CreateService: Success ``` 1. Click **Start** and start typing `Services` in the Windows search bar. Run the **Services** application as an administrator. 1. In the window that opens, find the service you created earlier, right-click it, and select **Properties**. 1. On the **Log on** tab, select **This account** and specify your Windows account name and password. If necessary, click **Browse** → **Advanced** → **Search** to find the user you need on the computer. 1. Click **OK**. To delete the created service, open `CMD` as an administrator and run the following command: ```cmd sc delete ``` Result: ```text [SC] DeleteService: Success ``` {% endlist %} ## Synchronize the local folder with the bucket {#sync} As the final backup configuration step, set up [manual](#manual-sync) or [automatic](#auto-sync) synchronization between the local folder and the bucket. ### Manual synchronization {#manual-sync} {% list tabs group=operating_system %} - Linux {#linux} For a one-off synchronization, run this command: ```bash rsync -av \ --no-owner \ --no-group \ --no-perms \ --no-times \ --delete \ / \ / ``` Where `--delete` is a flag to delete files from the bucket when they are deleted from the local folder. {% note info %} Specify the full absolute path to folders without using `~`, e.g., `/home/user/`. {% endnote %} This command copies all contents from your local folder to the bucket using the folder mounted with GeeseFS. It only moves new and modified files. The GeeseFS folder is not a proper POSIX-compliant file system, so ownership, permissions, and timestamps are not copied. - Windows {#windows} For a one-off synchronization, use the command line (`CMD`) to run the following: ```bash robocopy "" "" /MIR ``` Where `/MIR` indicates full folder synchronization, including deletion of missing files. {% note info %} Specify the full absolute path to folders without using `~`, e.g., `/home/user/`. {% endnote %} Result: ```text ------------------------------------------------------------------------------- ROBOCOPY :: Robust File Copy for Windows ------------------------------------------------------------------------------- Start : October 6, 2025, 21:16:36 Source : C:\Users\username\geesefs\local\ Target : C:\Users\username\geesefs\mount\ Files: *.* Parameters: *.* /S /E /DCOPY:DA /COPY:DAT /PURGE /MIR /R:1000000 /W:30 ------------------------------------------------------------------------------ 1 C:\Users\username\geesefs\local\ 100% New file 13793 image.PNG ------------------------------------------------------------------------------ TotalCopied SkippedMismatch FAILEDExtras Folders : 1 0 1 0 0 0 Files : 1 1 0 0 0 0 Bytes : 13.4 k 13.4 k 0 0 0 0 Time : 0:00:00 0:00:00 0:00:00 0:00:00 Speed : 13793000 Bytes/sec. Speed : 789.241 MB/min. Ended : October 6, 2025, 21:16:36 ``` {% note tip %} To avoid running the command manually each time, you can create a BAT file: 1. Open **Notepad** and add the following contents: ```text @echo off robocopy "" "" /MIR ``` 1. Save the file, e.g., as `sync_to_s3.bat`. 1. To synchronize folders, run the BAT file. {% endnote %} {% endlist %} ### Automatic synchronization {#auto-sync} {% list tabs group=operating_system %} - Linux {#linux} To automatically synchronize your local folder with the GeeseFS folder: 1. Make sure the user who will schedule the `cron` job has access to both folders. 1. Open the current user's scheduler file by running this command: ```bash crontab -e ``` 1. Add a line to the file to trigger autosync, e.g., every 10 minutes: ```text */10 * * * * rsync -av --no-owner --no-group --no-perms --no-times --delete / / --log-file= ``` Where: * `--delete`: Flag to delete files from the bucket when they are deleted from the local folder. * `--log-file`: Optional parameter for writing logs. Specify the full path. {% note info %} Specify the full absolute path to folders without using `~`, e.g., `/home/user/`. {% endnote %} The job will run at the specified frequency and synchronize the folders. The command in the `cron` job copies all contents from your local folder to the bucket using the folder mounted with GeeseFS. It only moves new and modified files. The GeeseFS folder is not a proper POSIX-compliant file system, so ownership, permissions, and timestamps are not copied. - Windows {#windows} For auto sync, set up a task in the **Task scheduler**: 1. Open the Windows **Task Scheduler**: * **Start Menu** → **Task Scheduler**. * Or start it in **Run** → `taskschd.msc`. 1. Click **Create task...**. 1. In the **Actions** tab, add a new action by specifying the absolute path to the executable script, e.g., a BAT file, under **Program or script**. 1. In the **Triggers** tab, add a schedule. 1. Click **OK**. {% endlist %} ## How to delete the resources you created {#clear-out} To stop paying for the resources you created: 1. [Delete the objects](../operations/objects/delete-all.md) from the bucket. 1. [Delete the bucket](../operations/buckets/delete.md).